Writing Applications Using the Common Messaging Interface

Introduction to Writing Applications with 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.
Note: The SAS®9 Common Messaging Interface uses the SAS®9 data set format by default. In order to send and receive SAS Release 8 data sets, you must include the "ATTACH_VERSION=VERSION_8" option in the data set option list on the SENDMESSAGE call. If you do not use the "ATTACH_VERSION=VERSION_8" option on the SENDMESSAGE call, then received data sets are stored in the SAS®9 format. If you might be sending data sets to another SAS session that is running SAS Release 8.2 or earlier, then use the ATTACH_VERSION= option to exchange data sets in a format that can be interpreted by both applications.

Administrator Programs

SAS programs can use 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.
Administrator programs perform general functions, such as the following:
  • defining the transport-specific details that are required by the queue. The available transports are MQSeries (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 that are associated with a message (if necessary)
  • copying any desired attachments to local storage
  • closing all queues upon completion of the program tasks
  • terminating transports that are initialized by the program
The following SAS CALL routines are the basis for initializing or terminating a transport, opening or closing a queue, and sending or 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 canceling 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:
  • BEGINTRANSMISSION
  • COMMIT
  • ABORT
  • FREETRANSACTION