|
|
Application Messaging
Note: For these CALL Routines and CALL documentation, MQSeries refers to WebSphere MQ.
Defines a transport or queue alias in the information repository.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL SETALIAS(type, name, storage, rc, transport <, queue>);
- type
- Character, input
Specifies the type of alias to be defined. The following types are valid:
- name
- Character, input
Identifies the transport alias or queue alias that is assigned.
- storage
- Character, input
Specifies the location for the alias definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine.
If an error occurs, the return code is non-zero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- transport
- Character, input
Identifies the name of the transport. The following transports are valid:
- MQSERIES(trantab=SAS_trantab_override)
- MQSERIES-C(trantab=SAS_trantab_override)
- MSMQ
- RENDEZVOUS
- RENDEZVOUS-CM
Note: With the MQSeries transport, if you use SAS to perform
the conversion instead of using an MQSeries conversion exit, then you can specify which
TRANTAB to use for converting the application data. If the TRANTAB is not specified, SAS will use the session encoding information to convert the data.
- queue
- Character, input
Identifies the name of the queue that is defined. This parameter is optional.
Note: This queue is valid only if a queue alias is being defined.
Details
An alias provides a level of indirection that simplifies
the programming interface by encapsulating information for all other programs. See Writing Applications Using the Common Messaging Interface for details on Administrator Programs.
If you are using Version 8 (TS M1) or later of Integration Technologies
with an LDAP server that was configured with Version 8 or earlier,
please read this Important Note.
Example
This example defines an MSMQ queue alias in the LDAP repository.
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
rc=0;
call setalias('QUEUE', 'MYQUEUE', 'LDAP', rc,
'MSMQ', 'machine_name\queue_name');
if rc ^= 0 then do;
put 'SETALIAS: failed';
msg = sysmsg();
put msg;
end;
else put 'SETALIAS: succeeded';
Defines a map data descriptor in the information repository.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL SETMAP(name, storage, rc, descriptor);
- name
- Character, input
Identifies the map data descriptor that is assigned.
- storage
- Character, input
Specifies the location for the map definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function
SYSMSG() in order to obtain a textual description of the return code.
- descriptor
- Character, input
Describes the layout of the data within a message body. This parameter is a string containing the data type, the offset (optional), and (for character data) the length of each SAS variable, presented in the order in which the data will be passed to a SENDMESSAGE call and returned from a RECEIVEMESSAGE call.
The descriptor has the following format:
"type,offset,length;type,offset,length;..."
where:
- type is the type of data (SHORT, LONG, DOUBLE, or CHAR).
- offset is the offset from the beginning of the message, which is the cursor location in the case of the PARSEMESSAGE routine. This parameter is optional.
- length is the length of the data, which is valid only for the CHAR data type.
Details
A map specifies the layout of the data within a message body. Maps can
be used with the MQSeries, MQSeries-C, MSMQ, Rendezvous, or Rendezvous-CM transport when sending and receiving data.
If you are using Version 8 (TS M1) or later of Integration Technologies with an LDAP server that was configured with Version 8 or earlier, please read this Important Note.
Example
The following example defines a map data descriptor in the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
rc=0;
call setmap('MYMAP', 'LDAP', rc,
'SHORT;LONG,2;SHORT;DOUBLE,6;CHAR,,50');
if rc ^= 0 then do;
put 'SETMAP: failed';
msg = sysmsg();
put msg;
end;
else put 'SETMAP: succeeded';
For the MSMQ transport, defines a dynamic creation queue model. For the Rendezvous transport, the SETMODEL call enables you to change one or more transport attributes from the default values. For the Rendezvous-CM transport, defines a model definition for certified message delivery.
| Transports supported: |
MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL SETMODEL(transport, name, storage, rc, props, value1 <, value2,...>)
- transport
- Character, input
Specifies the transport that is associated with this model. MSMQ, Rendezvous, and Rendezvous-CM are the only valid transports for this CALL routine.
- name
- Character, input
Identifies the dynamic model or transport model that is assigned.
- storage
- Character, input
Specifies the location for the model definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function
SYSMSG() to obtain a textual description of the return code.
- props
- Character, input
Identifies one or more properties that the queue exhibits once created. This parameter is a character
string. Each applicable property is separated by a comma.
You must associate a value with each property that is identified by props.
- values
- Character/numeric, input
Inputs the values for each property that is specified. Use one of the following values for each of the
properties listed in the props parameter.
- For MSMQ, the following creation properties and their values are valid:
-
- AUTHENTICATE
- Character
Specifies whether or not the queue accepts only authenticated messages. The following values are valid:
- "NONE" (Default)
- Specifies the queue accepts either authenticated or nonauthenticated messages.
- "ALWAYS"
- Specifies the queue always requires authenticated messages.
- BASEPRIORITY
- Numeric
Specifies a single base priority for all messages sent to a public queue. Values range from –32768 to 32767, where 32767 is the highest priority and 0 is the default priority.
- JOURNAL
- Character
Specifies whether messages retrieved from the queue are also copied to its journal queue. The following values are valid:
- "NONE" (default)
- Indicates that messages that are removed from the queue are not stored in a journal.
- "ALWAYS"
- Indicates that messages that are removed from the queue are always stored in its journal queue.
- JOURNALQUOTA
- Numeric
Specifies the maximum size (in kilobytes) of the journal queue. The default size is infinite.
- LABEL
- Character
Specifies a description of the queue. The default is a blank label ("").
- PRIVLEVEL
- Character
Specifies the privacy level that is required by the queue. The following values are valid:
- "NONE"
- Specifies that the queue accepts only nonprivate (cleartext) messages.
- "BODY"
- Specifies that the queue accepts only private (encrypted) messages.
- "OPTIONAL" (default)
- Specifies that the queue accepts both private and nonprivate messages.
- QUOTA
- Numeric
Specifies the maximum size (in kilobytes) of the queue. The default size is infinite.
- TRANSACTION
- Character
Specifies whether the queue is a transactional queue or a
nontransactional queue. The following values are valid:
- "NONE" (default)
- Indicates that the queue does not accept transactional operations.
- "ALWAYS"
- Indicates that all messages that are sent to the queue must be done through an MSMQ transaction.
- TYPE
- Binary string
Specifies the type of service that is provided by the queue. The value of the TYPE property is a global unique identifier (GUID) character string that represents binary data. The default is NULL_GUID.
- For Rendezvous and Rendezvous-CM, the following transport properties are valid:
-
- SERVICE
- Character
Specifies the service name or port number. If you specify a null value, the transport creation function looks for the service name "rendezvous" and uses 7500 if "rendezvous" is not found. The TIB/Rendezvous documentation strongly recommends that administrators define "rendezvous" as a service, especially if UDP port 7500 is already in use. For more information, consult the TIB/Rendezvous documentation.
- NETWORK
- Character
Specifies the network name, Host IP, host name, or other identifier of the network. Refer to the TIB/Rendezvous documentation for more details.
- DAEMON
- Character
Specifies the TCP socket number for a local daemon, or the remote host name and socket number for a remote daemon. Refer to the TIB/Rendezvous documentation for more details.
Note: A model is not required if you are using default Rendezvous values.
- For Rendezvous-CM only, the following transport properties are valid:
-
- CMNAME
- Character
Specifies the reusable name of a certified message (CM) transport. This is the CM Correspondent name, which can be omitted if persistent correspondents are not required.
- LEDGER
- Character
Specifies the name of the file in which to store a file-based ledger. This property can be omitted if persistent correspondents are not required.
- RELAYAGENT
- Character
Specifies the name of the relay agent. If you use this property, then it must be configured by the Rendezvous administrator.
- REQUESTOLD
- Character
Indicates whether a persistent correspondent requires delivery of unacknowledged messages that were sent to a previous certified delivery transport with the same CMNAME. Possible types are as follows:
- NO (default)
- Specifies that the new CM transport does not require certified senders to retain unacknowledged messages. Certified senders can delete those messages from their ledgers.
- YES
- Specifies that the new CM transport requires certified senders to retain unacknowledged messages sent to this persistent correspondent. When the new CM transport begins listening to the appropriate subjects, the senders can complete delivery. It is an error to specify YES when CMNAME is null.
- SYNCLEDGER
- Character
Specifies how to synchronize the ledger to its storage medium. Possible types are as follows:
- NO (default)
- Specifies that the operating system writes changes to the storage medium asynchronously.
- YES
- Specifies that the operations updating the ledger file do not return until the changes are written to the storage medium.
Details
Dynamic models for MQSeries are defined within its own configuration.
If you are using Version 8 (TS M1)
or later of Integration Technologies
with an LDAP server that was configured with Version 8 or earlier,
please read this Important Note.
Example
The following example defines an MSMQ model queue in the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
rc=0;
/* private queue model */
call setmodel('MSMQ', 'MYMODEL', 'LDAP', rc,
'AUTHENTICATE,PRIVLEVEL,LABEL', 'ALWAYS',
'BODY', 'Private dynamic queue');
if rc ^= 0 then do;
put 'SETMODEL: failed';
msg = sysmsg();
put msg;
end;
else put 'SETMODEL: succeeded';
Obtains the current definition of a transport alias or
queue alias that is set by the SETALIAS function in the information repository.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL GETALIAS(type, name, storage, rc, transport <, queue>);
- type
- Character, input
Specifies the type of alias. The following types are valid:
- name
- Character, input
Identifies the transport alias or queue alias that is set by the SETALIAS function.
- storage
- Character, input
Specifies the location for the alias definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- transport
- Character, output
Returns the transport name.
- queue
- Character, output
Returns the queue name.
Details
If you are using Version 8 (TS M1) or later of Integration Technologies with an LDAP server that was configured with Version 8 or earlier, please read this Important Note.
Example
The following example obtains a queue alias in the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
length transport queue $ 80;
rc=0;
transport='';
queue='';
call getalias('QUEUE', 'MYQUEUE', 'LDAP',
rc, transport, queue);
if rc ^= 0 then do;
put 'GETALIAS: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'GETALIAS: succeeded';
put 'Transport = ' transport;
put 'Queue = ' queue;
end;
Obtains the current definition of a map data descriptor in the information repository.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL GETMAP(name, storage, rc, descriptor);
- name
- Character, input
Identifies the map data descriptor that is defined by a previous SETMAP function call.
- storage
- Character, input
Specifies the location for the map definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- descriptor
- Character, output
Returns a string that describes the layout of the data. The format of the descriptor is as follows:
"type,offset,length;type,offset,length;..."
where:
- type is the type of data (SHORT, LONG, DOUBLE, CHAR)
- offset is the offset from the beginning of the message which is the cursor
location in the case of the PARSEMESSAGE routine
- length is the length of the data which is valid only for CHAR data type
Details
If you are using Version 8 (TS M1) or later of Integration Technologies with an LDAP server that was configured with Version 8.0 or earlier, please read this Important Note.
Example
The following example obtains a map data descriptor definition in the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
length descriptor $ 80;
rc=0;
descriptor='';
call getmap('MYMAP', 'LDAP', rc, descriptor);
if rc ^= 0 then do;
put 'GETMAP: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'GETMAP: succeeded';
put 'descriptor = ' descriptor;
end;
For MSMQ, obtains a dynamic creation queue model from the information repository. For Rendezvous and Rendezvous-CM, obtains transport attributes.
| Transports supported: |
MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL GETMODEL(transport, name, storage, rc, props, value1, <, value2, value3,...>)
- transport
- Character, input
Specifies the transport that is associated with this model. MSMQ, Rendezvous, and Rendezvous-CM are the only valid transports for this CALL routine.
- name
- Character, input
Identifies the dynamic model.
- storage
- Character, input
Specifies the location for the model definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- props
- Character, input
Identifies one or more properties to be queried.
- values
- Character/numeric, output
Identifies one or more queue properties to be queried. This parameter is a character string with each applicable output variable separated by a comma.
You must associate a variable with each property that is identified by props.
For MSMQ, the following properties are valid:
AUTHENTICATE character
BASEPRIORITY numeric
JOURNAL character
JOURNALQUOTA numeric
LABEL character
PRIVLEVEL character
QUOTA numeric
TRANSACTION character
TYPE binary string
For Rendezvous and Rendezvous-CM, the following transport properties are valid:
DAEMON character
NETWORK character
SERVICE character
For Rendezvous-CM only, the following transport properties are valid:
CMNAME character
LEDGER character
RELAYAGENT character
REQUESTOLD character
SYNCLEDGER character
Details
If you are using Version 8 (TS M1) or later of Integration Technologies with an LDAP server that was configured with Version 8 or earlier, please read this Important Note.
Example
The following example obtains an MSMQ model queue definition in the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
length auth priv $ 10;
length label $ 80;
rc=0;
auth='';
priv='';
label='';
call getmodel('MSMQ', 'MYMODEL', 'LDAP', rc,
'AUTHENTICATE,PRIVLEVEL,LABEL', auth, priv, label);
if rc ^= 0 then do;
put 'GETMODEL: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'GETMODEL: succeeded';
put 'authenticate = ' auth;
put 'privacy level = ' priv;
put 'label = ' label;
end;
Deletes a transport or queue alias definition from the information repository.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL DELETEALIAS(type, name, storage, rc);
- type
- Character, input
Specifies the type of alias that is to be deleted. The following types are valid:
- name
- Character, input
Identifies the transport alias or queue alias that is to be deleted.
- storage
- Character, input
Specifies the location of the alias definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
Details
If you are using Version 8 (TS M1) or later of Integration Technologies with an LDAP server that was configured with Version 8 or earlier, please read this Important Note.
Example
The following example deletes a queue alias from the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
rc=0;
call deletealias('QUEUE', 'MYQUEUE', 'LDAP', rc);
if rc ^= 0 then do;
put 'DELETEALIAS: failed';
msg = sysmsg();
put msg;
end;
else put 'DELETEALIAS: succeeded';
Deletes a map data descriptor definition from the information repository.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL DELETEMAP(name, storage, rc);
- name
- Character, input
Identifies the map data descriptor that is defined by a previous SETMAP function call.
- storage
- Character, input
Specifies the location for the map definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
If you are using Version 8 (TS M1) or later of Integration Technologies with an LDAP server that was configured with Version 8.0 or earlier, please read this Important Note.
Example
The following example deletes a map data descriptor definition from the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
rc=0;
call deletemap('MYMAP', 'LDAP', rc);
if rc ^= 0 then do;
put 'DELETEMAP: failed';
msg = sysmsg();
put msg;
end;
else put 'DELETEMAP: succeeded';
Deletes a dynamic creation queue model from the information repository.
| Transports supported: |
MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL DELETEMODEL(transport, name, storage, rc);
- transport
- Character, input
Specifies the transport that is associated with this model. MSMQ, Rendezvous, and Rendezvous-CM are the only valid transports for this CALL routine.
- name
- Character, input
Identifies the dynamic model.
- storage
- Character, input
Specifies the location for the model definition. The following locations are valid:
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
Details
If you are using Version 8 (TS M1) or later of Integration Technologies with an LDAP server that was configured with Version 8 or earlier, please read this Important Note.
Example
The following example deletes an MSMQ model queue definition from the LDAP repository:
%let ldap_host=mynode.alphalite.com;
%let ldap_port=8001;
%let ldap_base=o=Alphalite Airways,c=US;
length msg $ 200;
length rc 8;
rc=0;
call deletemodel('MSMQ', 'MYMODEL', 'LDAP', rc);
if rc ^= 0 then do;
put 'DELETEMODEL: failed';
msg = sysmsg();
put msg;
end;
else put 'DELETEMODEL: succeeded';
Initializes a particular transport. You must use the TERM CALL routine to terminate the transport after you've completed a session.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL INIT(tid, tname, rc);
- tid
- Numeric, output
Returns the transport handle that is used to open a queue or to begin transaction processing.
- tname
- Character, input
Specifies the name of the transport that is initialized. The following transport names are valid:
- MQSERIES(trantab=SAS_trantab_override)
- MQSERIES-C(trantab=SAS_trantab_override)
- MSMQ
- RENDEZVOUS
- RENDEZVOUS-CM
- alias that is defined in the information repository
Note: With the MQSeries transport, if you use SAS to perform
the conversion instead of using an MQSeries conversion exit, then you can specify which
TRANTAB to use for converting the application data.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
Details
The following transports are valid: MQSeries (MQSeries Base/Server),
MQSeries-C (MQSeries Client), and MSMQ (Microsoft Message Queue),
RENDEZVOUS (TIBCO TIB/Rendezvous), and RENDEZVOUS-CM (TIBCO TIB/Rendezvous Certified Message Delivery).
In addition, you can use a transport alias name that is defined in the information repository to indirectly specify one of the transports.
Example
The following example initializes an MQSeries Base/Server transport:
length msg $ 200;
length tid rc 8;
tid=0;
rc=0;
call init(tid, 'MQSERIES', rc);
if rc ^= 0 then do;
put 'INIT: failed';
msg = sysmsg();
put msg;
end;
else put 'INIT: succeeded';
Terminates a particular transport. If you initiate a transport with the INIT CALL routine, you must use the TERM CALL routine to terminate the transport after you've completed the session.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL TERM(tid, rc);
- tid
- Numeric, input
Specifies the transport handle that is obtained from the INIT function.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
Example
The following example terminates a transport:
length msg $ 200;
length tid rc 8;
rc=0;
call term(tid, rc);
if rc ^= 0 then do;
put 'TERM: failed';
msg = sysmsg();
put msg;
end;
else put 'TERM: succeeded';
Opens a message queue. You must use the CLOSEQUEUE CALL routine to close the message queue.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Note: For Rendezvous Certified Message Delivery (Rendezvous-CM), you must define a model definition for certified message delivery. Use the SETMODEL call to define a model definition.
Syntax
CALL OPENQUEUE(qid, tid, qname, mode, rc <, attr1 <, attr2>>);
- qid
- Numeric, output
Returns the queue handle for the opened queue. This handle is used in subsequent calls to send, receive, and parse messages and
attachments, and close the queue.
- tid
- Numeric, input
Specifies the transport handle that is obtained from the INIT function.
Note: If transport handle is set to 0, then qname is assumed to be a queue alias name that is defined in the information repository, and the transport will be initialized (and terminated at close) automatically.
- qname
- Character, input
Specifies the name of the queue to open.
The syntax for an MQSeries transport is
MQSeries: QMgr:Queue
The syntax for an MSMQ transport is
MSMQ: PathName or FormatName
Rendezvous and Rendezvous-CM: Subject name or inbox name.
- Subject name: Consists of one or more elements separated by dot characters (periods).
The elements can represent a subject name hierarchy. Examples:
RUN.HOME
RUN.for.Elected_office.President
- Inbox name: Generated by the Rendezvous software. Syntax is the same as subject name,
but must begin with _INBOX as the first element.
Notes:
- If an inbox name is specified, the name must have already been created and returned by another call.
For example, a RECEIVEMESSAGE call might have returned an inbox name in its respq attribute.
- When the queue is being opened for sending, wildcard characters ('*' and '>')
are not allowed.
- mode
- Character, input
Identifies the operational mode of the queue that is opened. You can only use one mode to open a queue.
The following modes for the MSMQ and MQSeries transports are valid:
- DELIVERY
- Enables messages to be sent to a queue
- FETCH
- Enables messages to be destructively retrieved
- FETCHX
- The same as FETCH except it ensures exclusive usage
- BROWSE
- Enables messages to be nondestructively retrieved.
The following modes for the Rendezvous and Rendezvous-CM transport are valid:
- DELIVERY
- enables messages to be sent to a queue
- FETCH
- enables messages to be retrieved
- FETCHX
- same as FETCH except used for point-to-point or private messages (using inboxes) instead of broadcast messages (using subject names). The qname property must be left blank ('') on the open call. A private inbox name is generated and associated with the qid. To access this queue, retrieve the inbox name using GETQUEUEPROPS. Use the value returned as the response queue value on send message calls when notifying a partner application of the private inbox name to send responses to. For Rendezvous-CM, if persistent messaging is not required, then you can use the FETCHX mode. The FETCHX mode should not be used with persistent messaging because inbox names do not survive transport invalidation.
- REQUEST
- enables request messages to be sent to a subject (queue) that is being monitored by a remote program serving as an information supplier. The qname parameter should specify the name of the queue to which the request message is to be sent. Any responses received will arrive on the queue specified in the respqueue parameter of the SENDMESSAGE call.
- REQUESTX
- same as REQUEST except used for point-to-point or private messages (using inboxes) instead of broadcast messages (using subject names). The qname parameter should specify the name of the queue on which the request message is to be sent. Any responses received will use the inbox name associated with the qid. This inbox name is created internally by Rendezvous when the respqueue parameter is initialized to null. For Rendezvous-CM, if persistent messaging is not required then you can use the REQUESTX mode. The REQUESTX mode should not be used with persistent messaging because inbox names do not survive transport invalidation.
Note: Before any messages are sent with the Rendezvous transport, the queues that will be receiving the messages must be running and must have a listener (that is, the queues must be opened for FETCH, FETCHX, REQUEST, or REQUESTX). Otherwise, data will be lost. Queues that are opened for REQUEST and REQUESTX automatically have their receiving (response) queues open to listen for incoming messages when the initial request is sent.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- attrs
- Character, input
Specifies one or more attributes to be associated with the queue. Each attribute constitutes a separate parameter in the open call. The following attributes are valid:
- POLL(Timeout=wait_period_in_seconds)
- Allows you to specify how message reception is handled for this queue. By default, the timeout period is set to INFINITE and a receive is blocked until a message arrives. To override the default, specify POLL and the timeout period.
- DYNAMIC(Model=model_name)
- Signifies that the queue is to be dynamically created, and specifies a model name that is defined in the information repository which specifies how to create the queue. For the MQSeries transport, the model is defined in the MQSeries configuration, not in the SAS information repository.
Example
The following example opens a queue for delivery by using an alias name:
length msg $ 200;
length qid tid rc 8;
/* MYQUEUE exists as a queue alias definition
in the SAS information repository. */
rc=0;
qid=0;
tid=0;
call openqueue(qid, tid, 'MYQUEUE',
'DELIVERY', rc, "POLL(Timeout=5)");
if rc ^= 0 then do;
put 'OPENQUEUE: failed';
msg = sysmsg();
put msg;
end;
else put 'OPENQUEUE: succeeded';
Closes a message queue.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL CLOSEQUEUE(qid, rc <, attr>);
- qid
- Numeric, input
Specifies the handle of a queue that is obtained from a previous OPENQUEUE function call.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- attr
- Character, input
Specifies a delete attribute. The following attributes are valid:
- DELETE
- Specifies that the queue is to be deleted after it successfully closes, but only if there are no messages on the queue.
This attribute is supported with MQSeries only. It is not supported with MSMQ because there is no way to programmatically determine the depth of the queue. It is not supported with Rendezvous because Rendezvous handles this function internally.
- DELETE_PURGE
- Causes the queue to be deleted, even if the queue depth is greater than zero. This attribute is supported with MQSeries, MQSeries-C, MSMQ, and Rendezvous-CM. It is not supported with Rendezvous because Rendezvous handles this function
internally.
If you are using Rendezvous Certified Message Delivery, when you close a listener queue the default setting is for the sender to save messages for persistent messaging. If you do not want messages to be saved by the sender or do not want persistent messaging, specify the DELETE_PURGE attribute when you close the queue. Setting the DELETE_PURGE attribute is the same as setting the cancelAgreements argument on TIBRVCM_CANCEL(TRUE).
Example
The following example closes a queue:
length msg $ 200;
length qid rc 8;
rc=0;
call closequeue(qid, rc);
if rc ^= 0 then do;
put 'CLOSEQUEUE: failed';
msg = sysmsg();
put msg;
end;
else put 'CLOSEQUEUE: succeeded';
Sends a message and optional attachments to a queue.
Syntax
CALL SENDMESSAGE(qid, rc, props <, value1, value2,...<, data1, data2,...>>);
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
- qid
- Numeric, input
Specifies the handle of an open queue that is obtained from a previous OPENQUEUE function call.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- props
- Character, input
Identifies one or more message properties that affect the message being sent. This parameter is a character string with each applicable property separated by a comma. All values except MSGID are input to the SENDMESSAGE routine.
The following are valid send message properties for MQSeries:
- ACCOUNTINGTOKEN
- APPLIDENTITYDATA
- APPLORIGINDATA
- CODEDCHARSETID
- ENCODING
- FEEDBACK
- FORMAT
- PUTAPPLNAME
- PUTAPPLTYPE
- PUTDATE
- PUTTIME
- REPORT
- USERID
The following are valid send message properties for MSMQ:
- ACKNOWLEDGE
- ADMINQUEUE
- AUTHENTICATE
- DESCRIPTION
- ENCRYPT
- ENCRYPTALG
- HASHALG
- JOURNAL
- SENDERCERT
The following are valid send message properties for both MQSeries and MSMQ:
- ALLOWREADPROTECT
- ATTACHLIST
- CORRELATIONID
- MAP
- MSGID
- MSGTYPE
- PERSIST
- PRIORITY
- RESPQUEUE
- TIMEOUT
- TRANSACTION
The following are valid send message properties for Rendezvous and Rendezvous-CM:
- ATTACHLIST
- ALLOWREADPROTECT
- MAP
- RESPQUEUE
The following are valid send message properties for Rendezvous-CM only:
- ADDLISTENER
- ALLOWLISTENER
- DISALLOWLISTENER
- RELAYAGENTACTION
- TIMEOUT
- values
- Character/numeric, input/output
Provides values that are associated with the properties specified via the props parameter. You must associate a value with each property that is specified by props. All values except MSGID are input to the routine. For the MQSeries transport,
MSGID is input and output. For the MSMQ transport, MSGID is only output.
Descriptions and values for the send message properties, which are listed above by transport, and the following values for them are valid:
- ACCOUNTINGTOKEN
- Binary string
MQSeries accounting token.
- ACKNOWLEDGE
- Character
MSMQ acknowledgement types. Possible acknowledge types are as follows:
- NONE (Default)
- Specifies that no acknowledgment messages are posted.
- FULL_REACH_QUEUE
- Specifies that positive or negative acknowledgments are posted depending on whether or not the message reaches the queue.
- FULL_RECEIVE
- Specifies that positive or negative acknowledgments are posted depending on whether or not the message is retrieved from the queue.
- NACK_REACH_QUEUE
- Specifies that negative acknowledgments are posted when a message cannot reach the queue.
- NACK_RECEIVE
- Specifies that negative acknowledgments are posted when a message cannot be retrieved from the queue.
- ADDLISTENER
- Character
Identifies one or more certified message names (CMNAMEs) of the listeners. This parameter is a character string with each CMNAME separated by a comma.
Anticipates a listener (or listeners) for certified delivery agreement.
Note: If a listener is added, this feature applies to all future messages within the session.
- ADMINQUEUE
- Character
Specifies the MSMQ administrator queue.
- ALLOWLISTENER
- Character
Identifies one or more certified message names (CMNAMEs) of the listeners. This parameter is a character string with each CMNAME separated by a comma.
Allows listeners on the specified CMNAME to reinstate certified delivery. This feature overrides any DISALLOWLISTENER for listener CMNAME.
Note: If a listener is allowed, this feature applies to all future messages within the session.
- ALLOWREADPROTECT
- Character
value is "YES"
Must be asserted on read-protected data sets in order for that data set to be sent as an attachment. This ensures that the user
realizes that the read password and encryption attributes are not preserved when this data set is sent as a message attachment. If this property is not applied, then the SENDMESSAGE call fails when the user tries to send a read protected data set, and an
error is returned.
Note:This property is supported in Version 8 (TS M1) and later releases. The password and encryption attributes
are not preserved in the intermediate message format when the attachment is on a message queue. Because of this exposure, take care when sending password-protected or encrypted data sets as message attachments.
- APPLIDENTITYDATA
- Character
Specifies the MQSeries application identity data.
- APPLORIGINDATA
- Character
Specifies the MQSeries application origin data.
- ATTACHLIST
- Character
Specifies that a list of attachments is included with message. The format of the list is as follows:
"type,qual1,qual2,options;
type,qual1,qual2,options;..."
where the parameters are defined as follows:
- type
- Is the attachment type, which can be one of the following:
- EXTERNAL_TEXT
- Is an external text file
- EXTERNAL_BIN
- Is an external binary file
- DATASET
- Is a SAS data set
- qual1
- Is a qualifier. For EXTERNAL_TEXT and EXTERNAL_BIN attachment types, this
qualifier specifies the file specification type which can be one of the following:
For the DATASET attachment type, this qualifier specifies the library name.
- qual2
- Is a qualifier. For EXTERNAL_TEXT and EXTERNAL_BIN attachment types, this qualifier specifies the actual filename or fileref. For the DATASET attachment type, this qualifier specifies the member name.
- options
- Specifies optional attachment specifications. Multiple options must be separated by spaces. The following options are valid for all attachment types:
- DESC=attachment description
- MINOR=user specified minor version
- MAJOR=user specified major version
The following options are valid for the Dataset attachment type:
- DATASET_OPTIONS=data set options
- WHERE=where clause
- INDEX=yes|no (default is yes so that indexes are sent)
- IC=yes|no (default is yes so that integrity constraints are sent)
- ATTACH_VERSION=VERSION_8
- If the ATTACH_VERSION option is specified and value=VERSION_8
- then the data set is sent using the column types available in the data sets prior to Version 9. Use this option if you might be sending data sets to another SAS session that is running Release 8.2 or earlier.
- If the ATTACH_VERSION option is omitted or if any other value is specified, then
- the full data set, including all new types, is sent.
- AUTHENTICATE
- Character
Specifies MSMQ authentication enablement. Possible authenticate types are as follows:
- NO (default)
- specifies that no authentication is necessary. The message is not signed.
- YES
- specifies that the message is signed and authenticated by the destination queue manager.
- CODEDCHARSETID
- Numeric
Specifies the MQSeries coded character set.
- CORRELATIONID
- Binary string
Specifies the correlation identifier.
- DESCRIPTION
- Character
Specifies the Message description.
- DISALLOWLISTENER
- Character
Specifies one or more certified message names (CMNAMEs) of the listeners. This parameter is a character string with each CMNAME separated by a comma.
Cancels certified delivery to listeners with the specified CMNAME.
Note: If a listener is disallowed, this feature applies to all future messages within the session.
- ENCODING
- Numeric
Specifies MQSeries data encoding.
- ENCRYPT
- Character
Specifies MSMQ encryption enablement. Possible encryption types are as follows:
- NO (Default)
- specifies that the message is to be sent as clear text.
- YES
- specifies end-to-end encryption of the message body.
- ENCRYPTALG
- Character
Specifies the MSMQ encryption algorithms. The following choices are valid:
- FEEDBACK
- Numeric
Specifies MQSeries feedback code.
- FORMAT
- Character
Specifies MQSeries format name.
- HASHALG
- Character
Specifies MSMQ hash algorithms. Possible hash types are as follows:
- JOURNAL
- Character
Specifies MSMQ journaling. Possible journal types are as follows:
- NO (default)
- specifies that the message is not kept in the originating machine's journal queue.
- YES
- specifies that the message is kept in the originating machine's journal queue.
- DEADLETTER
- specifies that the message is kept in a dead letter queue if it cannot be delivered.
- MAP
- Character
Specifies the data map name.
- MSGID
- Binary string
Specifies the message identifier.
- MSGTYPE
- Numeric
Specifies the message type.
- PERSIST
- Character
Specifies message persistence. Possible persist types are as follows:
- NO
- (default) message is not persistent.
- YES
- message is persistent.
- PRIORITY
- Numeric
Specifies message priority.
- PUTAPPLNAME
- Character
Specifies MQSeries application name.
- PUTAPPLTYPE
- Numeric
Specifies MQSeries application type.
- PUTDATE
- Character
Specifies MQSeries put date.
- PUTTIME
- Character
Specifies MQSeries put time.
- RELAYAGENTACTION
- Character
Specifies the connect and disconnect actions for the relay agent. The following values are valid:
- CONNECT
- Indicates to connect to the relay agent before sending messages and attachments.
- DISCONNECT
- Indicates to disconnect from the relay agent after all messages associated with the call have been processed. The disconnect happens at the end of the call before the call returns to the DATA step.
- BOTH
- Indicates to connect to the relay agent, send all messages, then disconnect from the relay agent. The disconnect happens at the end of the call before the call returns to the DATA step.
- REPORT
- Character
Specifies the MQSeries reporting types. Possible report types are as follows:
- NONE
- specifies that no reports required
- PASS_CORREL_ID
- specifies to pass a correlation identifier
- PASS_MSG_ID
- specifies to pass a message identifier
- COA
- specifies that confirmation-on-arrival reports are required
- COA_WITH_DATA
- specifies that confirmation-on-arrival reports with data are required
- COA_WITH_FULL_DATA
- specifies that confirmation-on-arrival reports with full data are required
- COD
- specifies that confirmation-on-delivery reports are required
- COD_WITH_DATA
- specifies that confirmation-on-delivery reports with data are required
- COD_WITH_FULL_DATA
- specifies that confirmation-on-delivery reports with full data are required
- EXPIRATION
- specifies that expiration reports are required
- EXPIRATION_WITH_DATA
- specifies that expiration reports with data are required
- EXPIRATION_WITH_FULL_DATA
- specifies that expiration reports with full data are required
- EXCEPTION
- specifies that exception reports are required
- EXCEPTION_WITH_DATA
- specifies that exception reports with data are required
- EXCEPTION_WITH_FULL_DATA
- specifies that exception reports with full data required
- DISCARD_MSG
- specifies to discard message if it is undeliverable
- RESPQUEUE
- Character
Specifies the response queue name.
Note: If this attribute is specified with an empty string value ('') when using a Rendezvous or Rendezvous-CM queue that was opened using REQUESTX mode, the generated inbox name will be sent. If another name is specified, it will be used instead.
- SENDERCERT
- Character
Specifies the MSMQ certificate store name that is used in order to search for external certificates. "MY" is typically specified. This results in a search of the current user's certificates with their associated private keys. For example, if "MY" is used, the corresponding registry entry is
HKEY_CURRENT_USER\Software\Microsoft\
SystemCertificates\MY
- TIMEOUT
- Numeric
Specifies the timeout value in seconds.
For Rendezvous-CM, specify this timeout as the length of time this message is to be sent using certified message delivery.
- TRANSACTION
- Numeric
Specifies the transaction object that is obtained from BEGINTRANSACTION.
- USERID
- Character
Specifies the MQSeries user identifier.
- data
- Character/numeric, input
Specifies the individual pieces of data that are sent with
the message.
Details
If you are sending Version 8 data sets, please read this Important Note.
If you intend to send attachments, use a queue that supports transactional processing. In this way, all messages associated with a failed attachment can be backed out if any part of the attachment processing fails. The IBM MQSeries queue manager
supports the syncpoint function. An MSMQ queue is a transactional queue. See Attachment Error Handling for information about exception processing when using attachments.
Before any messages are sent with the TIB/Rendezvous transport, the queues that will be receiving the messages must be running and must have a listener (that is, the queues must be opened for FETCH, FETCHX, REQUEST, or REQUESTX). Otherwise, data will be lost. Queues that are opened for REQUEST and REQUESTX automatically have their receiving (response) queues open to listen for incoming messages.
Note: If you are sending certified messages using Rendezvous-CM, and plan to close the sending queue immediately after sending the message, then you might want to put a sleep() call in to sleep for a couple of seconds to allow the Certified Delivery Agreement to be established between the sending transport and the receiving transport. This delay can also occur when a listener is first opened to receive certified messages.
Example
The following example sends an employee name and ID with records attached:
length msg $ 200;
length qid rc 8;
length msgtype 8 corrid $ 48 alist $ 80;
length employee $ 20 id 8;
rc=0;
/* message properties */
msgtype=1;
corrid='0102030405060708090A0B0C0D0E0F';
alist='DATASET,EMPLOYEE,RECORDS,
DESC=employee records for John Doe';
/* message data */
employee='John Doe ';
id=9999;
call sendmessage(qid, rc,
'MSGTYPE,CORRELATIONID,ATTACHLIST',
msgtype, corrid, alist, employee, id);
if rc ^= 0 then do;
put 'SENDMESSAGE: failed';
msg = sysmsg();
put msg;
end;
else put 'SENDMESSAGE: succeeded';
Receives a message and optional attachments from a queue.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL RECEIVEMESSAGE(qid, rc, event, attchflg, props <, value1, value2,...< data1, data2,...>>);
- qid
- Numeric, input
Specifies the handle of an open queue that is obtained from a previous OPENQUEUE function call.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- event
- Character, output
Contains a description of the event that occurs as a result of the message being received.
Possible event types are
- DELIVERY
- Specifies that the message was delivered
- NO_MESSAGE
- Specifies that no message is on queue
- ERROR
- Specifies that an error has occurred. This event results in a non-zero value for rc.
You need to initialize this parameter to a length of at least 10 before making the call so that there is room for the value to be placed in the string. Otherwise, it could get truncated.
- attchflg
- Numeric, output
Indicates whether an attachment is associated with the received message. Possible return values are as follows:
- 0
- Specifies that no attachments are associated with this message
- 1
- Specifies that attachments are associated with this message. You can call GETATTACHMENT to receive the attachments.
- props
- Character, input
Identifies one or more message properties that are associated with the message that is received. This parameter is a character string. Each property is separated by a comma.
The following receive message properties are valid for MQSeries:
- ACCOUNTINGTOKEN
- APPLIDENTITYDATA
- APPLORIGINDATA
- PUTAPPLNAME
- PUTAPPLTYPE
The following receive message properties are valid for MSMQ:
- ADMINQUEUE
- AUTHENTICATE
- DESCRIPTION
- SENDERCERT
The following receive message properties are valid for both MQSeries and MSMQ:
- CORRELATIONID
- FEEDBACK
- MAP
- MSGID
- MSGTYPE
- OPTIONS
- QUEUEDTIME
- RESPQUEUE
- TRANSACTION
- USERID
The following receive message properties are valid for Rendezvous and Rendezvous-CM:
The following receive message properties are valid for Rendezvous-CM only:
- CERTIFIED
- RELAYAGENTACTION
- SENDERNAME
- values
- Character/numeric
Provides the values that are associated with each property that is specified via the props parameter. You must associate a value with each property that is identified with the props parameter. The property values can be an input, output, or both.
Descriptions and values for the received message properties which are listed above by transport are
- ACCOUNTINGTOKEN
- Binary string, output
Specifies an MQSeries accounting token.
- ADMINQUEUE
- Character, output
Specifies an MSMQ administrator queue.
- APPLIDENTITYDATA
- Character, output
Specifies MQSeries application identity data.
- APPLORIGINDATA
- Character, output
Specifies MQSeries application origin data.
- AUTHENTICATE
- Character, output
Indicates MSMQ authentication enablement. Possible authenticate return values are as follows:
- NO
- Specifies that the message was not authenticated.
- YES
- Specifies that the message was authenticated.
- CORRELATIONID
- Binary string, input/output
Correlation identifier. For MQSeries and MSMQ transports, on input this property can be used for filtering purposes. However, do not try to filter with this property when you are receiving attachment messages. The original CORRELATIONID is not associated with the attachment header message, although the original CORRELATIONID is embedded within the attachment header itself and will be presented accurately. This type of processing is needed because an attachment is made up of multiple messages that must be uniquely identified. A CORRELATIONID that is set by the application is not guaranteed to be unique.
- CERTIFIED
- Character, output
Specifies a Certified Message (CM) indicator. Possible return values are as follows:
- NO
- Specifies that the message was received by the normal transport or the listener has not been certified.
- YES
- Specifies that the message was received within the certified delivery transport.
- DESCRIPTION
- Character, output
Specifies a message description.
- FEEDBACK
- Numeric, output
For MQSeries, it is a feedback code. For MSMQ, it is a class.
- MAP
- Character, input
Specifies a data map name
- MSGID
- Binary string, input/output
Indicates the message identifier. On input, this property can be used for filtering purposes for both MQSeries and MSMQ transports.
- MSGTYPE
- Numeric, output
Indicates the message type.
- OPTIONS
- Character, input
Specifies the receive options. The following options are valid:
- POSITIONFIRST
- (MQSeries/MSMQ)
Indicates to reposition to the first message in the queue.
- CONVERSION_EXIT
- (MQSeries only)
Specifies to use the MQSeries conversion exit. Otherwise, SAS performs all necessary data conversion internally.
- PUTAPPLNAME
- Character, output
Indicates an MQSeries application name.
- PUTAPPLTYPE
- Character, output
Indicates an MQSeries application type.
- QUEUEDTIME
- Character, output
Indicates the time at which the message was queued.
- RELAYAGENTACTION
- Character, input
Specifies connect or disconnect actions for the relay agent. The following values are valid:
- CONNECT
- Indicates to connect to the relay agent before receiving messages and attachments.
- DISCONNECT
- Indicates to disconnect from the relay agent after all messages associated with the call have been processed. If an attachment is received, the disconnect call is issued after the ACCEPTATTACHMENT call has processed all of the messages associated with the attachment and before the call returns to the data step. If ACCEPTATTACHMENT is not called, then the connection is not closed. If a connection was made to the relay agent during the call and an error occurs, then the error causes a disconnect from the relay agent.
- BOTH
- Indicates to connect to the relay agent, receive all messages, then disconnect from the relay agent. If an attachment is received, the disconnect call is issued after the ACCEPTATTACHMENT call has processed all of the messages associated with the attachment and before the call returns to the data step. If ACCEPTATTACHMENT is not called, then the connection is not closed.
If an error occurs in a call, then if a connection was made to the relay agent during the call, an error causes a disconnect from the relay agent.
- RESPQUEUE
- Character, output
Indicates the response queue name.
- SENDERCERT
- Character, output
Indicates the subject within received certificate (MSMQ).
- SENDERNAME
- Character, output
Indicates the name of the certified message (CM) transport used by the sender.
- TRANSACTION
- Numeric, input
Indicates the transaction object obtained from BEGINTRANSACTION.
- USERID
- Character, output
Indicates the user identifier who sent the message.
- data
- Character/numeric, output
When you issue RECEIVEMESSAGE, all data that is associated with a message is placed into an internal buffer. You can parse this data during the RECEIVEMESSAGE call with these optional parameters, or you can call PARSEMESSAGE at a later time to parse the data.
Example
The following example receives a message such as the one sent in the SENDMESSAGE example:
length msg $ 200;
length qid rc attchflg 8 event $ 10;
length msgtype 8 corrid $ 48 map $ 80;
length employee $ 20 id 8;
rc=0;
corrid='';
/* no filtering */
map='employeerecord';
/* data descriptor defined in repository...
for example, "char,,20;double" */
call receivemessage(qid, rc, event, attchflg,
'MSGTYPE,CORRELATIONID,MAP', msgtype, corrid,
map, employee, id);
if rc ^= 0 then do;
put 'RECEIVEMESSAGE: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'RECEIVEMESSAGE: succeeded';
put 'Event = ' event;
if event eq 'DELIVERY' then do;
put 'Message has been delivered';
if attchflg eq 1 then do;
put 'Attachment(s) are associated
with this message';
/* process attachments...*/
end;
put 'employee = ' employee;
put 'id = ' id;
end;
end;
Parses a message body that has been received.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL PARSEMESSAGE(qid, cursor, rc, map, data);
- qid
- Numeric, input
Specifies the handle of an open queue that is obtained from a previous OPENQUEUE function call.
- cursor
- Numeric, input/output
Sets the cursor to zero in order to parse from the beginning. Upon return, the cursor is positioned at the next data location, according to the specified map.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
- map
- Character, input
Specifies the map data descriptor that is defined by a previous SETMAP function call.
- data
- Character/numeric, output
Identifies the data to be parsed from the internal receive buffer.
Example
The following example parses a message:
length msg $ 200;
length qid rc attchflg 8 event $ 10;
length msgtype 8 corrid $ 48 map $ 80;
length employee $ 20 id 8;
rc=0;
map='employeerecord';
/* data descriptor defined in repository...
ie., "char,,20;double" */
cursor=0;
call parsemessage(qid, cursor, rc, map, employee, id);
if rc ^= 0 then do;
put 'PARSEMESSAGE: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'PARSEMESSAGE: succeeded';
put 'employee = ' employee;
put 'id = ' id;
end;
Begins transaction processing by creating a transaction object.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ |
Syntax
CALL BEGINTRANSACTION(transid, tid, rc);
- transid
- Numeric, output
Returns a handle to a transaction object that is generated for committing and aborting transactional processing, as well as freeing the resources that are associated with the transaction object.
- tid
- Numeric, input
Specifies the transport handle that is obtained from the INIT function.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() to obtain a textual description of the return code.
Details
The created transaction object is used to commit or abort prior processing (SENDMESSAGE and RECEIVEMESSAGE calls) that use the transaction object as a message property. Transaction processing is supported only by the MQSeries, MQSeries-C, and MSMQ transports.
Example
The following example begins a transaction:
length msg $ 200;
length transid tid rc 8;
rc=0;
transid=0;
call begintransaction(transid, tid, rc);
if rc ^= 0 then do;
put 'BEGINTRANSACTION: failed';
msg = sysmsg();
put msg;
end;
else put 'BEGINTRANSACTION: succeeded';
Commits prior work that has been done via a transaction object.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ |
Syntax
CALL COMMIT(transid, rc);
- transid
- Numeric, input
Specifies the handle to a transaction object that is obtained from the BEGINTRANSACTION function.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() in order to obtain a textual description of the return code.
Details
For MQSeries, all transactions are associated with a particular queue manager. So when you commit a unit of work that is associated with a particular queue manager, all work that is performed by that particular queue manager under syncpoint control is committed at once. You can associate more than one transaction object with the same queue manager, but it is not a good practice. Under MSMQ, all transaction objects are autonomous.
Example
The following example commits a transactional unit of work for processing:
length msg $ 200;
length transid rc 8;
rc=0;
call commit(transid, rc);
if rc ^= 0 then do;
put 'COMMIT: failed';
msg = sysmsg();
put msg;
end;
else put 'COMMIT: succeeded';
Aborts prior work that has been done via a transaction object.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ |
Syntax
CALL ABORT(transid, rc);
- transid
- Numeric, input
Specifies the handle to a transaction object that is obtained from the BEGINTRANSACTION function.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() in order to obtain a textual description of the return code.
Details
For MQSeries, all transactions are associated with a particular queue manager. So when you abort a unit of work that is associated with a particular queue manager, all work performed by that particular queue manager under syncpoint control is aborted at once. You can associate more than one transaction object with the same queue manager, but it is not a good practice.) Under MSMQ, all transaction objects are autonomous.
Example
The following example aborts the processing of a transactional unit of work:
length msg $ 200;
length transid rc 8;
rc=0;
call abort(transid, rc);
if rc ^= 0 then do;
put 'ABORT: failed';
msg = sysmsg();
put msg;
end;
else put 'ABORT: succeeded';
Frees a transaction object and its associated resources.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ |
Syntax
CALL FREETRANSACTION(transid, rc);
- transid
- Numeric, input
Specifies the handle to a transaction object that is obtained from the BEGINTRANSACTION function.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() in order to obtain a textual description of the return code.
Example
The following example frees the resources that are associated with a transaction object:
length msg $ 200;
length transid rc 8;
rc=0;
call freetransaction(transid, rc);
if rc ^= 0 then do;
put 'FREETRANSACTION: failed';
msg = sysmsg();
put msg;
end;
else put 'FREETRANSACTION: succeeded';
Gets attachment information that is associated with a particular message.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Note: If you send a data set with a SAS 9 or later attachment type to a SAS session running Release 8.2 or earlier, the GETATTACHMENT call fails and returns an error indicating that an unrecognized attachment type was received. See the SENDMESSAGE CALL routine for information about sending SAS 9 attachments in a format for an earlier version.
Syntax
CALL GETATTACHMENT(qid, lastflag, attachid, type, qual1, qual2, rc
<, desc <, minor <, major>>>);
- qid
- Numeric, input
Specifies the handle of an opened queue obtained from a previous OPENQUEUE function call.
- lastflag
- Numeric, output
Indicates whether you have reached the last attachment in a message. Possible values are as follows:
- 0
- Specifies that more attachments are to be presented
- 1
- Specifies that this is the final attachment
- attachid
- Numeric, output
Returns an attachment identifier that is used with the ACCEPTATTACHMENT function call when this attachment is accepted.
- type
- Character, output
Returns the type of attachment. The following types are valid:
- EXTERNAL_TEXT
- EXTERNAL_BIN
- DATASET
- qual1
- Character, output
Returns the first attachment qualifier. If this is an external attachment, then this qualifier designates the file specification that is used to send it (either FILENAME or FILEREF). Otherwise, this qualifier designates the sending library name.
- qual2
- Character, output
Returns the second attachment qualifier. If this is an external attachment, then this qualifier designates the sending filename or fileref. Otherwise, this qualifier designates the sending member name.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() in order to obtain a textual description of the return code.
- desc
- Character, output
Returns a description of the attachment if the sender provides one. This parameter is optional.
- minor
- Numeric, output
Returns a user-specified minor version number. This parameter is optional.
- major
- Numeric, output
Returns a user-specified major version number. This parameter is optional.
Details
You can repeatedly call this function until the final attachment has been presented.
Note: To receive an attachment from outside of the SAS environment, you must know the layout of an attachment.
- For MQSeries (now known as WebSphere MQ) or MSMQ queue, see the attachment layout for more information.
- For TIB/Rendezvous or TIB/Rendezvous-CM, see the attachment layout for more
information.
Example
The following example gets all of the attachment information from a message:
length msg $ 200;
length qid lastflag attachid rc 8;
length type $ 13;
length qual1 qual2 $ 80;
length desc $ 80;
length minor major 8;
next:
rc=0;
lastflag=0;
attachid=0;
type='';
qual1='';
qual2='';
desc='';
minor=0;
major=0;
call getattachment(qid, lastflag, attachid, type,
qual1, qual2, rc, desc, minor, major);
if rc ^= 0 then do;
put 'GETATTACHMENT: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'GETATTACHMENT: succeeded';
put 'Attachment type is ' type;
if type eq 'EXTERNAL_TEXT' OR type eq
'EXTERNAL_BIN' then do;
put "Sender's " qual1 " was " qual2;
/* process external file... */
end;
else do;
put "Sender's library name was ' qual1;
put "Sender's member name was ' qual2;
/* process library member... */
end;
if lastflag eq 0 then goto next;
Accepts an attachment by recreating it on the local machine.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL ACCEPTATTACHMENT(qid, attachid, qual1, qual2, rc);
- qid
- Numeric, input
Specifies the handle of an open queue that is obtained from a previous OPENQUEUE function call.
- attachid
- Numeric, input
Specifies an attachment identifier that is obtained from a previous GETATTACHMENT function call.
- qual1
- Character, input
Specifies the first attachment qualifier. If this is an external file attachment, then this qualifier designates the file
specification that is used to receive it (either FILENAME or FILEREF). Otherwise, this qualifier designates the receiving library name.
- qual2
- Character, input
Specifies the second attachment qualifier. If this is an external file attachment, then this qualifier designates the receiving
filename or fileref. Otherwise, this qualifier designates the receiving member name.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() in order to obtain a textual description of the return code.
Details
See Attachment Error Handling for information about exception processing when you use attachments.
Example
This example accepts attachments from a message and stores them in the file d:\myexternalfile.tmp.
length msg $ 200;
length qid lastflag attachid rc 8;
length type $ 13;
length qual1 qual2 $ 80;
length desc $ 80;
length minor major 8;
next:
rc=0;
lastflag=0;
attachid=0;
type='';
qual1='';
qual2='';
desc='';
minor=0;
major=0;
call getattachment(qid, lastflag, attachid, type,
qual1, qual2, rc, desc, minor, major);
if rc ^= 0 then do;
put 'GETATTACHMENT: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'GETATTACHMENT: succeeded';
put 'Attachment type is ' type;
if type eq 'EXTERNAL_TEXT' OR type eq
'EXTERNAL_BIN' then do;
put "Sender's " qual1 " was " qual2;
/* accept/receive the external attachment */
call acceptattachment(qid, attachid, 'filename',
'd:\myexternalfile.tmp', rc);
if rc ^= 0 then do;
put 'ACCEPTATTACHMENT: failed';
msg = sysmsg();
put msg;
end;
else
put 'ACCEPTATTACHMENT: succeeded';
end;
else do;
put "Sender's library name was ' qual1;
put "Sender's member name was ' qual2;
/* accept/receive the library/member */
libname tmp 'd:\tmp';
call acceptattachment(qid, attachid,
'tmp', 'test', rc);
end;
if lastflag eq 0 then goto next;
Gets information pertaining to a queue's properties and security.
| Transports supported: |
MQSeries, MQSeries-C, MSMQ, Rendezvous, Rendezvous-CM |
Syntax
CALL GETQUEUEPROPS(qid, rc, ttype, pmask, depth, maxdepth, maxmsgl, ctime, desc<, inbox>);
- qid
- Numeric, input
Specifies the handle to an open queue that is obtained from a previous OPENQUEUE function call.
- rc
- Numeric, output
Provides the return code from the CALL routine. If an error occurs, the return code is nonzero. You can use the SAS function SYSMSG() in order to obtain a textual description of the return code.
- ttype
- Character, output
Identifies the transport type of the queue. Possible values are as follows:
- MQSeries
- MQSeries-C
- MSMQ
- Rendezvous
- Rendezvous-CM
- pmask
- Numeric, output
Returns the property assertion mask that the queue accepts. This property is valid only for the MQSeries, MQSeries-C, and MSMQ transports. Possible values are as follows:
- bit 0
- In MSMQ, specifies that the queue only accepts authenticated messages.
- bit 1
- In MSMQ, specifies that the queue only accepts private messages.
- bit 2
- In MSMQ, specifies that the queue only accepts public messages.
- bit 4
- In MSMQ, specifies that the queue only accepts transactional messages. In MQSeries, bit 4 specifies that the QMgr supports syncpoint.
- depth
- Numeric, output
Returns the current depth of the queue.
- maxdepth
- Numeric, output
Returns the maximum depth that is configured for the queue. This property is valid only for the MQSeries, MQSeries-C, and MSMQ transports.
- maxmsgl
- Numeric, output
Returns the maximum length that is configured for the queue. This property is valid only for the MQSeries, MQSeries-C, and MSMQ transports.
- ctime
- Character, output
Returns the queue creation time stamp. This property is valid only for the MQSeries, MQSeries-C, and MSMQ transports.
- desc
- Character, output
Returns a description of the queue. This property is valid only for the MQSeries, MQSeries-C, and MSMQ transports.
- inbox
- Character, output
Returns the name of the private inbox created for a session opened with FETCHX. This property is valid only for the Rendezvous transports. This parameter is optional.
Details
If a transport does not support a particular property, then the routine returns -2 for numeric property values but does not change character property values.
Example
The following example obtains the properties of a queue:
length msg $ 200;
length qid rc 8;
length ttype $ 13;
length pmask depth maxdepth maxmsgl 8;
length ctime desc $ 80;
rc=0;
ttype='';
pmask=0;
depth=0;
maxdepth=0;
maxmsgl=0;
ctime='';
desc='';
call getqueueprops(qid, rc, ttype, pmask, depth,
maxdepth, maxmsgl, ctime, desc);
if rc ^= 0 then do;
put 'GETQUEUEPROPS: failed';
msg = sysmsg();
put msg;
end;
else do;
put 'GETQUEUEPROPS: succeeded';
put 'transport type = ' ttype;
if ttype eq 'MQSERIES' then do;
if pmask='1...'b then put 'Syncpoint is enabled';
else put 'Syncpoint is disabled';
end;
else if ttype eq 'MSMQ' then do;
if pmask='1'b then put 'Authenticated
messages are required';
if pmask='1.'b then put 'Private
messages are required';
else if pmask='1..'b then put 'Public
messages are required';
else put 'Privacy is optional';
if pmask='1...'b then put 'Transactional
messages are required';
else put 'Transactional messages
are not permitted';
end;
put 'depth = ' depth;
put 'maxdepth = ' maxdepth;
put 'maxmsgl = ' maxmsgl;
put 'creation time = ' ctime;
put 'description = ' desc;
end;
|
