Writing WebSphere MQ Applications :: Application Messaging with SAS(R) 9.3, Second Edition

Overview of Writing WebSphere MQ Applications

With WebSphere MQ 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 can communicate with another application by sending a message to a queue. The receiving application retrieves the message when it is ready.

A typical SAS program using WebSphere MQ services performs the following tasks:

Establishes a connection to a WebSphere MQ 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.
Opens the desired queue. When opening a queue, the program must define how it intends to use it. For example, the program can send (put) messages to the queue, receive (get) messages from the queue, or it can do both. If a queue is opened by 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, then the queue manager issues an object handle that is used to identify the queue in subsequent function calls.
(Optional) Puts messages on the queue by 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.
(Optional) Opens 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 be set to help identify the message to get from the queue.
(Optional) Releases the resources allocated by a SAS internal handle. These resources are associated with message options and descriptors.

Interface Models

WebSphere MQ provides two Message Queue Interface (MQI) models:

Base/Server model

runs on the same machine as the WebSphere MQ Base product and WebSphere MQ Server

Client model

runs on a different machine from the WebSphere MQ Base product and WebSphere MQ Server

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, then you must specify the MQMODEL SAS macro variable and set it to a value of CLIENT:

%let
MQMODEL=CLIENT;

You must set this variable before calling any WebSphere MQ interface function.

If the program is using the client model, then it opens a remote queue manager. WebSphere MQ clients always connect across a network. For information about configuring remote access, see Configuring WebSphere MQ Client Access .

Data Conversion

Overview of 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. WebSphere MQ channel communication (Transmission Segment Header and Message Descriptor) data are converted internally by WebSphere MQ. However, the user portion of a message is not. It is the responsibility of the program to convert this data.

Data conversion of this user portion can be handled by either WebSphere MQ conversion exit routines or by SAS.

Converting Data within WebSphere MQ

For WebSphere MQ to perform the data conversion of the user portion of a message, you must perform the following steps:

When putting (MQPUT) a message on a queue, specify the FORMAT (conversion exit) that the receiver should use to convert the incoming message.
Convert a message:
- WebSphere MQ 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, then you must create a conversion exit.
The receiving (MQGET) program must tell WebSphere MQ 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, which is part of the MQGET call. If you do not want to set up static conversion exit routines, then you can let SAS convert the data for you as an alternative solution.

For more information about conversion within WebSphere MQ, see the WebSphere MQ documentation at www.ibm.com.

Converting Data in SAS

By default, if you do not specify the CONVERT Get Message Option, then SAS converts the data conversion to the default encoding for the SAS session. To disable the automatic SAS data conversion, specify the MQSASCNV SAS macro variable and set it to a value of DISABLE or OFF:

%let MQSASCNV=OFF

You can use the KCVT function to convert your data manually. Converting data manually is especially useful for programs that put reply messages on a queue.

For example, your SAS program might use messaging to interact with a Java Web application that uses UTF-8 encoding. When receiving messages, SAS automatically converts the message data to the session encoding. However, you must convert the data back to UTF-8 before sending it to the reply queue. The following code converts the variable TEXT from WLatin1 to UTF-8:

text= kcvt(text, wlatin1, utf8));

For more information, see KCVT Function in SAS National Language Support (NLS): Reference Guide.