Writing Applications Using the Common Messaging Interface

There are two general classes of programs that can use the common messaging Interface. The first type uses the interface to administer information about the message transports. The second type uses the interface to send and receive messages between applications. Both of these types are discussed in the sections below.

Administration Programs

SAS programs can utilize the common messaging interface 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, it also makes the queues easier to administer by having all this information in one location.

An administrator program performs general functions such as:

1. Defining the transport-specific (MQSeries, MSMQ, or Rendezvous) details required by the queue
2. Setting aliases for new transports and queues and retrieving aliases for existing ones
3. Retrieving the properties of a queue
4. Defining and retrieving maps to data descriptors that identify the data type, offset and length
5. Setting and retrieving dynamic creation queue models for the MSMQ transport

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:

1. Deleting a transport or queue alias definition
2. Deleting a data descriptor definition map
3. Deleting a dynamic 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 interface 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 to the queue's attributes. These programs interact with each queue in a consistent matter independent of the transport being used.

These programs perform general functions such as:

1. Initializing the type of transport and obtaining a unique identifier
2. Opening an existing queue using a known transport identifier
3. Sending messages to a queue using a unique queue identifier
4. Receiving messages (and possibly attachments) from a queue
5. Parsing the message
6. Getting attachments associated with a message (if necessary)
7. Copying any desired attachment(s) to local storage
8. Closing all queues upon completion of the program tasks
9. 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, these programs may perform transaction processing on transaction queues. Such functions include:

1. Creating a transaction object to begin progressing
2. Committing or aborting work performed using a transaction object
3. Releasing a transaction object and any resource associated with it

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

• BEGINTRANSACTION
• COMMIT
• ABORT
• FREETRANSACTION