Contents Common Messaging Interface Previous Next

SAS CALL Routines for the Common Messaging Interface




SETALIAS

Defines a transport or queue alias in the information repository.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL SETALIAS(type, name, storage, rc, transport <, queue>);

type
Character, input
Specifies the type of alias to be defined. Valid types are:

  • TRANSPORT
  • QUEUE

name
Character, input
Identifies the transport alias or queue alias that will be assigned.

storage
Character, input
Specifies the location for the alias definition. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

transport
Character, input
Identifies the name of the transport. Valid transports are:

  • MQSERIES(trantab=SAS_trantab_override)
  • MQSERIES-C(trantab=SAS_trantab_override)
  • MSMQ
  • RENDEZVOUS

Note: With the MQSeries transport you can optionally specify the SAS trantab to use for application data conversion if SAS is to perform the conversion instead of using an MQSeries conversion exit.

queue
Character, input
Identifies the name of the queue being defined. This parameter is optional.

Note: Valid only if a queue alias is being defined.

Details

An alias provides a level of indirection that simplifies the programmatic interface.

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 footnote.

Example

This example defines an MSMQ queue alias in the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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';

SETMAP

Defines a map data descriptor in the information repository.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL SETMAP(name, storage, rc, descriptor);

name
Character, input
Identifies the map data descriptor that will be assigned.

storage
Character, input
Specifies the location for the map definition. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

descriptor
Character, input
Describes the layout of the data within a message body. The descriptor 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 (cursor location in the case of the PARSEMESSAGE routine). This parameter is optional.
  • Length is the length of the data (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, MSMQ, or Rendezvous 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.0 or earlier, please read this footnote.

Example

This example defines a map data descriptor in the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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';

SETMODEL

For the MSMQ transport, defines a dynamic creation queue model. For the Rendezvous transport, changes the attributes of the transport from the defaults.

Transports supported: MSMQ, Rendezvous

Syntax

CALL SETMODEL(transport, name, storage, rc, props, value1 <, value2,...>)

transport
Character, input
Specifies the transport associated with this model. MSMQ and Rendezvous are the only valid transports for this CALL routine.

name
Character, input
Identifies the dynamic model or transport model that will be assigned.

storage
Character, input
Specifies the location for the model definition. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

props
Character, input
Identifies one or more properties that the queue will exhibit once created. This parameter is a character string with each applicable property separated by a comma.

For each property identified by props, you must have a property value associated with it in order to set its value.

values
Character/numeric, input
Inputs the values to use for each property specified. Use one of the values listed or described above for each of the properties used.

For MSMQ, valid creation properties and values are:

AUTHENTICATE
Character
Specifies whether or not the queue only accepts authenticated messages. Valid values are:

"NONE" (Default)
Specifies the queue will except either authenticated or non-authenticated 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. Valid values are:

"NONE" (default)
Messages removed from the queue are not stored in a journal.

"ALWAYS"
Messages 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. Valid values are:

"NONE"
The queue accepts only non-private (cleartext) messages.

"BODY"
The queue accepts only private (encrypted) messages.

"OPTIONAL" (default)
The queue accepts both private and non-private 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 non-transactional queue. Valid values are:

"NONE" (default)
The queue does not accept transactional operations.

"ALWAYS"
All messages sent to the queue must always be done through an MSMQ transaction.

TYPE
Binary string
Specifies the type of service provided by the queue. The value of the TYPE property is a globally unique identifier (GUID) character string representing binary data. The default is NULL_GUID.

For Rendezvous, valid transport properties are:

SERVICE
Character
Specifies the service name or port number to be used. 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 to be used. 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.

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.0 or earlier, please read this footnote.

Example

This example defines an MSMQ model queue in the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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';

GETALIAS

Obtains the current definition of a transport alias or queue alias set by the SETALIAS function in the information repository.

Transports supported: MQSeries, MSMQ, Rendezvous

Syntax

CALL GETALIAS(type, name, storage, rc, transport <, queue>);

type
Character, input
Specifies the type of alias. Valid types are:

  • TRANSPORT
  • QUEUE

name
Character, input
Identifies the transport alias or queue alias set by the SETALIAS function.

storage
Character, input
Specifies the location for the alias definition. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

transport
Character, output
Returns the transport name.

queue
Character, output
Returns the queue name.

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 footnote.

Example

This example obtains a queue alias in the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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;

GETMAP

Obtains the current definition of a map data descriptor in the information repository.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL GETMAP(name, storage, rc, descriptor);

name
Character, input
Identifies the map data descriptor defined by a previous SETMAP function call.

storage
Character, input
Specifies the location for the map definition. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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 (cursor location in the case of the PARSEMESSAGE routine)
  • Length is the length of the data (valid only for CHAR data type)

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 footnote.

Example

This example obtains a map data descriptor definition in the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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;

GETMODEL

For MSMQ, obtains a dynamic creation queue model from the information repository. For Rendezvous, obtains transport attributes.

Transports supported: MSMQ, Rendezvous

Syntax

CALL GETMODEL(transport, name, storage, rc, props, value1, <, value2, value3,...>)

transport
Character, input
Specifies the transport associated with this model. MSMQ and RENDEZVOUS 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. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

props
Character, input
Identifies one or more properties.

values
Character/numeric, output
Identifies one or more queue properties to be queried. This parameter is a character string with each applicable property separated by a comma.

For each property identified by props, you must have an associated property value.

For MSMQ, valid properties are: 

       AUTHENTICATE         character
       BASEPRIORITY         numeric
       JOURNAL              character
       JOURNALQUOTA         numeric
       LABEL                character
       PRIVLEVEL            character
       QUOTA                numeric
       TRANSACTION          character
       TYPE                 binary string

For Rendezvous, valid transport properties are: 

       DAEMON               character
       NETWORK              character
       SERVICE              character

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 footnote.

Example

This example obtains an MSMQ model queue definition in the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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;

DELETEALIAS

Deletes a transport or queue alias definition from the information repository.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL DELETEALIAS(type, name, storage, rc);

type
Character, input
Specifies the type of alias to be deleted. Valid types are:

  • TRANSPORT
  • QUEUE

name
Character, input
Identifies the transport alias or queue alias that will be deleted.

storage
Character, input
Specifies the location of the alias definition. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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 footnote.

Example

This example deletes a queue alias from the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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';

DELETEMAP

Deletes a map data descriptor definition from the information repository.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL DELETEMAP(name, storage, rc);

name
Character, input
Identifies the map data descriptor defined by a previous SETMAP function call.

storage
Character, input
Specifies the location for the map definition. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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 footnote.

Example

This example deletes a map data descriptor definition from the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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';

DELETEMODEL

Deletes a dynamic creation queue model from the information repository.

Transports supported: MSMQ, Rendezvous

Syntax

CALL DELETEMODEL(transport, name, storage, rc);

transport
Character, input
Specifies the transport associated with this model. MSMQ and Rendezvous 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. Valid locations are:

  • REGISTRY
  • LDAP

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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 footnote.

Example

This example deletes a MSMQ model queue definition from the LDAP repository. 

   %let ldap_host=mynode.alpine.com;
   %let ldap_port=8001;
   %let ldap_base=o=Alpine 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';

INIT

Initializes a particular transport.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL INIT(tid, tname, rc);

tid
Numeric, output
Returns the transport handle used to open a queue or begin transaction processing.

tname
Character, input
Specifies the name of the transport to initialize. Valid transport names are:

  • MQSERIES(trantab=SAS_trantab_override)
  • MQSERIES-C(trantab=SAS_trantab_override)
  • MSMQ
  • RENDEZVOUS
  • Alias defined in the information repository

Note: With the MQSeries transport you can optionally specify the SAS trantab to use for application data conversion if SAS is to perform the conversion instead of using an MQSeries conversion exit.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Details

Valid transports are as follows: MQSeries (MQSeries Base/Server), MQSeries-C (MQSeries Client), MSMQ (Microsoft Message Queue), and RENDEZVOUS (TIBCO TIB/Rendezvous). A transport alias name that is defined in the information repository can also be used to indirectly specify one of the transports.

Example

This 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';

TERM

Terminates a particular transport.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL TERM(tid, rc);

tid
Numeric, input
Specifies the transport handle obtained from the INIT function.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This 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';

OPENQUEUE

Opens a message queue.

Transports supported: MSMQ, MQSeries, Rendezvous

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.

tid
Numeric, input
Specifies the transport handle 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 each transport is as follows:

MQSeries: QMgr:Queue

MSMQ: PathName or FormatName

  • PathName representations are:

    • machineName\QueueName (public queue)
    • machineName\QueueName;Journal (public queue's journal)
    • machineName\PRIVATE$\QueueName (private queue)
    • machineName\PRIVATE$\QueueName;Journal (private queue's journal)
    • machineName\Journal (machine journal queue)
    • machineName\DeadLetter (machine deadletter queue)
    • machineName\DeadXACT (machine transaction deadletter queue)

      Note: machineName can be substituted with '.' to designate the local machine.

  • FormatName representations are:

    • PUBLIC=QueueGUID (public queue)
    • PUBLIC=QueueGUID;Journal (public queue's journal)
    • PRIVATE=machineGUID\QueueNumber (private queue)
    • PRIVATE=machineGUID\QueueNumber;Journal (private queue's journal)
    • DIRECT=AddressSpecification\QueueName (direct format for public queue)
    • DIRECT=AddressSpecification\PRIVATE$\QueueName (direct format for private queue)

    where AddressSpecification is protocol:address (For example, tcp:10.26.1.177)

    Notes:
    • Direct format can only be used in certain situations. Consult MSMQ documentation for details.
    • A queue alias name defined in the information repository can also be used as the qname parameter.

Rendezvous: 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 may 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 being opened. Each applicable mode is separated by a comma.

Valid modes for the MSNQ and MQSeries transports are:

  • DELIVERY - enables messages to be sent to a queue
  • FETCH - enables messages to be destructively retrieved
  • FETCHX - same as FETCH except ensures exclusive usage
  • BROWSE - enables messages to be non-destructively retrieved.

Valid modes for the Rendezvous transport are:

  • DELIVERY - enables messages to be sent to a queue

  • FETCH - enables messages to be destructively 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 (''). The private inbox name will be generated and associated with the qid.

  • 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.

    Notes:

    • Each Rendezvous session, except for a request type transaction, can support communication in only one direction (either SEND or RECEIVE).

    • 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.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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. Valid attributes are:

POLL(Timeout=wait_period_in_seconds)
Allows you to specify how message reception will be 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 an optional timeout period.

DYNAMIC(Model=model_name)
Signifies that the queue is to be dynamically created and optionally 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 the SAS information repository.

Example

This example opens a queue for delivery using an alias name. 

   length msg $ 200;
   length qid tid rc 8;

   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';

CLOSEQUEUE

Closes a message queue.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL CLOSEQUEUE(qid, rc <, attr>);

qid
Numeric, input
Specifies the handle of a queue obtained from a previous OPENQUEUE function call.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

attr
Character, input
Specifies a delete attribute. Valid attributes are:

DELETE
Specifies the queue is to be deleted after it successfully closes, 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
Specifying this attribute causes the queue to be deleted even if the queue depth is greater than zero. This attribute is supported with MSMQ and MQSeries only. It is not supported with Rendezvous because Rendezvous handles this function internally.

Example

This 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';

SENDMESSAGE

Sends a message and optional attachments to a queue.

Syntax

CALL SENDMESSAGE(qid, rc, props <, value1, value2,...<, data1, data2,...>>);

Transports supported: MSMQ, MQSeries, Rendezvous

qid
Numeric, input
Specifies the handle of an open queue obtained from a previous OPENQUEUE function call.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

props
Character, input
Identifies one or more message properties that affects the message being sent. This parameter is a character string with each applicable property separated by a comma. All values are inputs to the SENDMESSAGE routine except MSGID.

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:

  • ATTACHLIST
  • ALLOWREADPROTECT
  • MAP
  • RESPQUEUE

values
Character/numeric, input/output
Provides values associated with the properties specified via the props parameter. For each property specified by props, you must have a property value associated with it in order to set its value. All values are input to the routine except MSGID. For the MQSeries transport, MSGID is input and output. For the MSMQ transport, MSGID is only output.

A description for the send message properties listed above and valid values for them are as follows:

ACCOUNTINGTOKEN
Binary string
MQSeries accounting token.

ACKNOWLEDGE
Character
MSMQ acknowledgement types. Possible acknowledge types are:

NONE (Default)
Specifies no acknowledgment messages are posted

FULL_REACH_QUEUE
Specifies that positive/negative acknowledgments are posted depending whether or not the message reaches the queue.

FULL_RECEIVE
Specifies positive/negative acknowledgments are posted depending 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.

ADMINQUEUE
Character
MSMQ administrator queue.

ALLOWREADPROTECT
Character - value of "YES"
This property is supported in Version 8 (TS M1) and later releases. Please take note that 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 and/or encrypted datasets as message attachments. The ALLOWREADPROTECT property must be asserted on read protected data sets in order for that dataset to be sent as an attachment. This ensures that the user realizes that the read password and encryption attributes will not be preserved when this dataset is sent as a message attachment. If this property is not applied, then the sendmessage call will fail when trying to send a read protected data set and an error will be returned.

APPLIDENTITYDATA
Character
MQSeries application identity data.

APPLORIGINDATA
Character
MQSeries application origin data.

ATTACHLIST
Character
List of attachments to be 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 - external text file
  • EXTERNAL_BIN - external binary file
  • DATASET - SAS dataset

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:

  • FILENAME
  • FILEREF

For all other attachment types, 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
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=dataset 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)

AUTHENTICATE
Character
MSMQ authentication enablement. Possible authenticate types are:

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
MQSeries coded character set identifier.

CORRELATIONID
Binary string
Correlation identifier.

DESCRIPTION
Character
Message description.

ENCODING
Numeric
MQSeries data encoding.

ENCRYPT
Character
MSMQ encryption enablement. Possible encryption types are:

NO (Default)
Specifies the message is to be sent as clear text.

YES
Specifies end-to-end encryption of the message body.

ENCRYPTALG
Character
MSMQ encryption algorithms. Valid choices are:

  • RC2 (default)
  • RC4

FEEDBACK
Numeric
MQSeries feedback code.

FORMAT
Character
MQSeries format name.

HASHALG
Character
MSMQ hash algorithms. Possible hash types are:

  • MD2
  • MD4
  • MD5 (default)

JOURNAL
Character
MSMQ journaling. Possible journal types are:

NO (default)
Specifies the message is not kept in the originating machine's journal queue.

YES
Specifies the message is kept in the originating machine's journal queue.

DEADLETTER
Specifies the message is kept in a dead letter queue if it cannot be delivered.

MAP
Character
Data map name.

MSGID
Binary string
Message identifier.

MSGTYPE
Numeric
Message type.

PERSIST
Character
Message persistence. Possible persist types are:

  • NO - (default) message is not persistent.
  • YES - message is persistent.

PRIORITY
Numeric
Message priority.

PUTAPPLNAME
Character
MQSeries application name.

PUTAPPLTYPE
Numeric
MQSeries application type.

PUTDATE
Character
MQSeries put date.

PUTTIME
Character
MQSeries put time.

REPORT
Character
MQSeries reporting types. Possible report types are:

  • NONE (no reports required)
  • PASS_CORREL_ID (pass correlation identifier)
  • PASS_MSG_ID (pass message identifier)
  • COA (confirmation-on-arrival reports required)
  • COA_WITH_DATA (confirmation-on-arrival reports with data required)
  • COA_WITH_FULL_DATA (confirmation-on-arrival reports with full data required)
  • COD (confirmation-on-delivery reports required)
  • COD_WITH_DATA (confirmation-on-delivery reports with data required)
  • COD_WITH_FULL_DATA (confirmation-on-delivery reports with full data required)
  • EXPIRATION (expiration reports required)
  • EXPIRATION_WITH_DATA (expiration reports with data required)
  • EXPIRATION_WITH_FULL_DATA (expiration reports with full data required)
  • EXCEPTION (exception reports required)
  • EXCEPTION_WITH_DATA (exception reports with data required)
  • EXCEPTION_WITH_FULL_DATA (exception reports with full data required)
  • DISCARD_MSG (discard message if undeliverable)

RESPQUEUE
Character
Response queue name.

Note: If this attribute is specified with an empty string value ('') when using a Rendezvous 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
MSMQ certificate store name 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
Timeout value (seconds).

TRANSACTION
Numeric
Transaction object obtained from BEGINTRANSACTION.

USERID
Character
MQSeries user identifier.

data
Character/numeric, input
The data parameters are individual pieces of data to be sent with the message.

Details

If you intend to send attachments, it is recommended that the queue support transactional processing so that 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 on 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.

Example

This 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';

RECEIVEMESSAGE

Receives a message and optional attachments from a queue.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL RECEIVEMESSAGE(qid, rc, event, attchflg, props <, value1, value2,...< data1, data2,...>>);

qid
Numeric, input
Specifies the handle of an open queue obtained from a previous OPENQUEUE function call.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

event
Character, output
Contains a description of the event that occurred as a result of the message being received.

Possible event types are:

  • DELIVERY - message was delivered
  • NO_MESSAGE - no message on queue
  • ERROR - error has occurred

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 there is an attachment associated with the received message. Possible return values:

  • 0 - no attachments are associated with this message
  • 1 - attachment(s) are associated with this message. You may call GETATTACHMENT to receive the attachment(s).

props
Character, input
Identifies one or more message properties associated with the message being received. This parameter is a character string with each property separated by a comma.

The valid receive message properties for MQSeries are:

  • ACCOUNTINGTOKEN
  • APPLIDENTITYDATA
  • APPLORIGINDATA
  • PUTAPPLNAME
  • PUTAPPLTYPE

The valid receive message properties for MSMQ are:

  • 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 valid receive message properties for Rendezvous are:

  • MAP
  • RESPQUEUE

values
Character/numeric
Provides the values associated with each property specified via the props parameter. For each property identified with the props parameter, you must have a property value associated with it. The property values can be an input, output, or both.

A description for the received message properties listed above and valid values for them are as follows:

ACCOUNTINGTOKEN
Binary string, output
MQSeries accounting token.

ADMINQUEUE
Character, output
MSMQ administrator queue.

APPLIDENTITYDATA
Character, output
MQSeries application identity data.

APPLORIGINDATA
Character, output
MQSeries application origin data.

AUTHENTICATE
Character, output
MSMQ authentication enablement. Possible authenticate return values are:

  • NO - message was not authenticated.
  • YES - 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 filtering with this property when receiving attachment messages because the original CORRELATIONID will not be 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 since an attachment is made up of multiple messages that need to be uniquely identified and a correlationid that is set by the application when sending a message is not guaranteed to be unique by any means.

DESCRIPTION
Character, output
Message description.

FEEDBACK
Numeric, output
For MQSeries, it is a feedback code. For MSMQ, it is a class.

MAP
Character, input
Data map name

MSGID
Binary string, input/output
Message identifier. On input, this property can be used for filtering purposes for both MQSeries and MSMQ transports.

MSGTYPE
Numeric, output
Message type.

OPTIONS
Character, input
Receive options. Valid options are:

POSITIONFIRST
(MQSeries/MSMQ)
Reposition to the first message in the queue.

CONVERSION_EXIT
(MQSeries only)
Specifies to use the MQSeries conversion exit. Otherwise, SAS will perform all necessary data conversion internally.

PUTAPPLNAME
Character, output
MQSeries application name.

PUTAPPLTYPE
Character, output
MQSeries application type.

QUEUEDTIME
Character, output
Time at which the message was queued.

RESPQUEUE
Character, output
Response queue name.

SENDERCERT
Character, output
(MSMQ) Subject within received certificate.

TRANSACTION
Numeric, input
Transaction object obtained from BEGINTRANSACTION.

USERID
Character, output
User identifier who sent the message.

data
Character/numeric, output
When you issue RECEIVEMESSAGE, all data 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 may call PARSEMESSAGE at a later time to parse the data.

Example

This 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... i.e.., "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;

PARSEMESSAGE

Parses a message body that has been received.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL PARSEMESSAGE(qid, cursor, rc, map, data);

qid
Numeric, input
Specifies handle of an open queue obtained from a previous OPENQUEUE function call.

cursor
Numeric, input/output
Sets the cursor to zero to parse from the beginning. Upon return, the cursor will be 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 occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

map
Character, input
Specifies the map data descriptor defined by a previous SETMAP function call.

data
Character/numeric, output
Identifies the data to be parsed from the internal receive buffer.

Example

This 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;

BEGINTRANSACTION

Begins transaction processing by creating a transaction object.

Transports supported: MSMQ, MQSeries

Syntax

CALL BEGINTRANSACTION(transid, tid, rc);

transid
Numeric, output
Returns a handle to a transaction object generated for committing and aborting transactional processing, as well as freeing the resources associated with the transaction object.

tid
Numeric, input
Specifies the transport handle obtained from the INIT function.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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 only supported by the MQSeries and MSMQ transports.

Example

This 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';

Commit

Commits prior work that has been done via a transaction object.

Transports supported: MSMQ, MQSeries

Syntax

CALL COMMIT(transid, rc);

transid
Numeric, input
Specifies the handle to a transaction object obtained from the BEGINTRANSACTION function.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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 performed by that particular queue manager under syncpoint control is committed at once. (You could have more than one transaction object associated with the same queue manager, although it is a better practice to create only one transaction object per queue manager.) Under MSMQ, all transaction objects are autonomous.

Example

This 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';

Abort

Aborts prior work that has been done via a transaction object.

Transports supported: MSMQ, MQSeries

Syntax

CALL ABORT(transid, rc);

transid
Numeric, input
Specifies the handle to a transaction object obtained from the BEGINTRANSACTION function.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used 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 could have more than one transaction object associated with the same queue manager, although it is a better practice to create only one transaction object per queue manager.) Under MSMQ, all transaction objects are autonomous.

Example

This 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';

FREETRANSACTION

Frees a transaction object and its associated resources.

Transports supported: MSMQ, MQSeries

Syntax

CALL FREETRANSACTION(transid, rc);

transid
Numeric, input
Specifies the handle to a transaction object obtained from the BEGINTRANSACTION function.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example frees the resources 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';

GETATTACHMENT

Gets attachment information associated with a particular message.

Transports supported: MSMQ, MQSeries, Rendezvous

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:

  • 0 - more attachments to be presented
  • 1 - last attachment

attachid
Numeric, output
Returns an attachment identifier to use with the ACCEPTATTACHMENT function call when accepting this attachment.

type
Character, output
Returns the type of attachment. Valid types are:

  • 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 was 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 occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

desc
Character, output
Returns a description of the attachment (if the sender provided one). This parameter is optional.

minor
Numeric, output
Returns an optional user specified minor version number.

major
Numeric, output
Returns an optional user specified major version number.

Details

You can repeatedly call this function until the last attachment has been presented.

Note: To receive an attachment from an MQSeries or MSMQ queue outside of the SAS environment, you need to know the layout of an attachment. See attachment layout, for more information.

Example

This example Gets all the attachments 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;

ACCEPTATTACHMENT

Accepts an attachment by recreating it on the local machine.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL ACCEPTATTACHMENT(qid, attachid, qual1, qual2, rc);

qid
Numeric, input
Specifies the handle of an open queue obtained from a previous OPENQUEUE function call.

attachid
Numeric, input
Specifies an attachment identifier 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 will be 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 occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Details

See Attachment Error Handling for information on exception processing when using 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;

GETQUEUEPROPS

Gets information pertaining to a queue's properties and security.

Transports supported: MSMQ, MQSeries, Rendezvous

Syntax

CALL GETQUEUEPROPS(qid, rc, ttype, pmask, depth, maxdepth, maxmsgl, ctime, desc);

qid
Numeric, input
Specifies the handle to an open queue obtained from a previous OPENQUEUE function call. This property is valid only for the MSMQ and MQSeries transports.

rc
Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code. This property is valid only for the MSMQ and MQSeries transports.

ttype
Character, output
Identifies the transport type of the queue. Possible values are:

  • MQSeries
  • MSMQ
  • Rendezvous

pmask
Numeric, output
Returns the property assertion mask that the queue accepts. This property is valid only for the MSMQ and MQSeries transports.

  • bit 0 - (MSMQ) Queue only accepts authenticated messages.
  • bit 1 - (MSMQ) Queue only accepts private messages.
  • bit 2 - (MSMQ) Queue only accepts public messages.
  • bit 4 - (MSMQ) Queue only accepts transactional messages. (MQSeries) QMgr supports syncpoint.

depth
Numeric, output
Returns the current depth of the queue. This property is valid only for the MSMQ and MQSeries transports.

maxdepth
Numeric, output
Returns the maximum depth configured for the queue. This property is valid only for the MSMQ and MQSeries transports.

maxmsgl
Numeric, output
Returns the maximum length configured for the queue. This property is valid only for the MSMQ and MQSeries transports.

ctime
Character, output
Returns the queue creation time stamp. This property is valid only for the MSMQ and MQSeries transports.

desc
Character, output
Returns a description of the queue. This property is valid only for the MSMQ and MQSeries transports.

Details

If a transport does not support a particular property, then the routine returns -2 for numeric property values and character property values are not changed.

Example

This example obtains the properties of a queue. 

   length msg $ 200;
   length qid rc 8;
   length ttype $ 10;
   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;

Contents Common Messaging Interface Previous Next

Copyright © 2025 SAS Institute Inc. All Rights Reserved.