Writing Applications Using the Common Messaging Interface

Two general types of programs can use the common messaging interface. One uses the interface to administer information about the message transports. Another uses the interface to send and receive messages between applications. These two types of programs are discussed in the sections below.

Important Note: In Version 9 of the Common Messaging Interface, Version 9 enhanced data sets are the default format for sending and receiving data sets. In order to send and receive Version 8 data sets, you must include the "ATTACH_VERSION=VERSION_8" option in the Dataset option list on the SENDMESSAGE call. If you do not use the "ATTACH_VERSION=VERSION_8" option on the SENDMESSAGE call, received data sets will be stored in the Version 9 format. If you might be sending data sets to another SAS session that is running Release 8.2 or earlier, use this option to exchange data sets in a format that can be interpreted by both applications.

Administrator Programs

SAS programs can utilize the common messaging interface in order to administer the information in the repository for the queues. The goal of such an administrator program is to encapsulate all information about the queues so that all other programs in the application can focus on using the queues rather than configuring them. This not only simplifies the other programs, but also makes the queues easier to administer by having all of this information in one location.

An administrator program performs general functions. For example:

• defining the transport-specific details that are required by the queue. The available transports are: MQSeries (refers to WebSphere MQ), MSMQ, Rendezvous, or Rendezvous-CM.
• setting aliases for new transports and queues and retrieving aliases for existing ones
• retrieving the properties of a queue
• defining and retrieving maps to data descriptors that identify the data type, offset, and length
• setting and retrieving dynamic creation queue models for the MSMQ transport.
• setting and retrieving transport definition models for Rendezvous (optional) and Rendezvous-CM (required).

The following SAS CALL routines are used to administer the information repository:

• SETALIAS
• SETMAP
• SETMODEL
• GETALIAS
• GETMAP
• GETMODEL
• GETQUEUEPROPS

Other functions of the administration process include removing any unneeded information in the repository. This encompasses functions such as the following:

• deleting a transport or queue alias definition
• deleting a data descriptor definition map
• deleting a dynamic or transport model definition.

The following SAS CALL routines are used to administer these aspects of the information repository:

• DELETEALIAS
• DELETEMAP
• DELETEMODEL

User Programs

This section describes how a SAS program can use the common messaging interface in order to access message queues to send and receive messages to other programs. The common interface alleviates the need for these user programs to use transport-specific code. This makes the user programs less vulnerable to changes in the queue's attributes. The programs interact with each queue in a consistent matter, independent of the transport.

User programs perform general functions such as the following:

• initializing the type of transport and obtaining a unique identifier
• opening an existing queue by using a known transport identifier
• sending messages to a queue by using a unique queue identifier
• receiving messages (and possibly attachments) from a queue
• parsing the message
• getting attachments associated with a message (if necessary)
• copying any desired attachment(s) to local storage
• closing all queues upon completion of the program tasks
• terminating transports initialized by the program.

The following SAS CALL routines are the basis for initializing/terminating a transport, opening/closing a queue, and sending/receiving messages and attachments:

• INIT
• TERM
• OPENQUEUE
• CLOSEQUEUE
• SENDMESSAGE
• RECEIVEMESSAGE
• PARSEMESSAGE
• GETATTACHMENT
• ACCEPTATTACHMENT

In addition, user programs can perform transaction processing on transaction queues. Such functions include the following:

• creating a transaction object in order to begin progressing
• committing or aborting work that is performed by using a transaction object
• releasing a transaction object and any resource that is associated with it.

The following SAS CALL routines are provided for applications that require transaction processing:

• BEGINTRANSACTION
• COMMIT
• ABORT
• FREETRANSACTION