Writing MQSeries Applications

With MQSeries messaging, two or more applications communicate with each other indirectly and asynchronously using message queues. The applications do not have to be running at the same time or even in the same operating environment. An application wishing to communicate with another application simply sends a message to a queue. The receiving application retrieves the message when it is ready.

A typical SAS program using MQSeries services performs the following tasks:

1. The program must first establish a connection to an MQSeries queue manager. The queue manager is responsible for maintaining the queues and for ensuring that the messages in the queues reach their destination. This insulates the application developer from the details of the network. When a successful connection is made, the queue manager issues a connection handle that is used to identify the connection in subsequent function calls.

   Note: A program can have connections to more than one queue manager if the platform supports multiple queue managers running on it.

2. Next, the program must open the desired queue before it can use it. When opening a queue, the program must define how it intends to use it. For example, the program may send (put) messages to the queue, or receive (get) messages from the queue, or it may do both. If a queue is opened using the INQUIRE option, then the queue can be queried for information about the queue itself. Similarly, if the queue is opened using the SET option, then various queue attributes can be set. If the queue is opened successfully, the queue manager issues an object handle that is used to identify the queue in subsequent function calls.

3. A program that opens a queue for sending can put messages on the queue using the SAS CALL routine MQPUT. The queue is identified using the connection handle for the queue manager and the object handle for the queue. In addition, several other functions are available for creating and manipulating the data in the message as well as setting options that help the receiving program locate the message in the queue.

4. A program can also open the same queue (or a different one) for retrieving messages. The program uses the MQGET routine specifying the connection handle to the queue manager and the object handle for the queue from which it wants to retrieve the message. There are a number of options that can set to help identify the message to get from the queue.

5. A program also has the ability to release the resources allocated by a SAS internal handle. These resources are associated with message options and descriptors.

Interface Models

MQSeries provides two Message Queue Interface (MQI) models:

• The program resides on the same machine as the MQSeries Base product and Server (called the Base/Server model)
• The program resides on a different machine from the MQSeries Base product and Server (called the CLIENT model or the MQI Client component)

IBM requires programs to be linked with different libraries according to the model that will be used. The default model that is assumed by SAS is the Base/Server model. If you do not want the default model, you must specify the MQMODEL SAS macro variable and set it to a value of CLIENT. For example,

   %let MQMODEL=CLIENT;

You must set this variable before calling any MQSeries interface function.

If the program is using the client model, it will open a remote queue manager, since MQSeries clients always connect across a network.

If you have licensed Candle's MQSecure product, you can enable its interface by specifying the MQSECURE SAS macro variable and setting it to a value of ENABLE or ON. For example,

   %let MQSECURE=ENABLE;

You must set this variable before calling any MQSeries interface function. MQSecure requires userid/password contexts for signing and encrypting messages. By default, the program will prompt the user for this information at execution time. To override this interactive prompting, set the following macro variables:

   %let MQSIGNEE=userid.passwd - identification of signee
   %let MQENCRYPTID=userid     - userid to whom the message is destined
   %let MQDECRYPTPW=passwd     - password of user to whom the message is destined

Currently, the MQSecure interface can only be enabled while running under the Windows platform.

Data Conversion

If you will be putting or getting messages from heterogeneous systems, then data conversion must be considered. Data conversion is usually categorized as follows:

• Character data conversion
• Numeric data conversion.

The Coded Character Set ID (CCSID) or code page is a number that represents a character translation table to be used between two distinct systems. Encoding is the term generally used to represent how numeric data is represented on a particular system. MQSeries channel communication (Transmission Segment Header and Message Descriptor) data are converted internally by MQSeries, however, the user portion of a message is not. It is the responsibility of the program to convert this data to the native code page and numeric encoding.

Data conversion of this user portion can be handled by either MQSeries conversion exit routines or by SAS using data mapping control. If you want MQSeries to do the data conversion of the user portion of a message, you must adhere to the following protocol:

1. When putting (MQPUT) a message on a queue, you should specify the FORMAT (conversion exit) that the receiver should use to convert the incoming message (see MQMD - message descriptor parameters).
2. Convert a message.
   • MQSeries provides an internal conversion format, "MQSTR", that can be used to convert a message comprised entirely of character data.
   • If the message is not comprised entirely of character data, you will have to create a conversion exit. Refer to MQSeries DQM (Distributed Queuing Guide) for more information about setting up conversion exits.
3. The receiving (MQGET) program must tell MQSeries to do the required data conversion based on the incoming message format and data encoding. The program does this by specifying the CONVERT option on the Get Message Options (see MQGMO - options parameters) which is part of the MQGET call. If you do not want to set up static conversion exit routines, you can let SAS convert the data for you as an alternative solution.

By default, if you do not specify the CONVERT Get Message Option, SAS performs data conversion if required (when incoming message encoding does not match native encoding). If you want to disable or turn off this type of transparent data conversion, specify the MQSASCNV SAS macro variable and set it to a value of DISABLE or OFF. For example,

   %let MQSASCNV=OFF

SAS will perform data conversion based upon the data mapping (MQMAP) being passed to the MQGETPARMS routine. SAS performs origin-to-destination code page translation by using supplied or user-generated translation tables (TRANTAB entries in SASHELP.HOST or SASUSER.PROFILE). To override internal TRANTAB name generation, you can specify the MQSASTBL SAS macro variable and set it to the TRANTAB (translation table) that you want to use.