SAS 9.1.3 Integration Technologies » Developer's Guide

Application Messaging Overview
Supported Messaging Interface Versions
WebSphere MQ Configuration and Usage
Configuring WebSphere MQ with the WebSphere MQ Explorer
Polling Message Queues from the Object Spawner
Configuring Multiple Clients To Read From a Single Queue
Configuring WebSphere MQ to Trigger SAS
WebSphere MQ Interface
Writing WebSphere MQ Applications
WebSphere MQ Code Samples
WebSphere MQ CALL Routines
MSMQ Interface
Writing MSMQ Applications
MSMQ Code Samples
MSMQ Call Routines
Common Messaging Interface
Writing Applications
Using TIB/Rendezvous with the Common Interface
TIB/Rendezvous Coding Example
TIB/Rendezvous Certified Messaging Coding Example
Using a Repository with Application Messaging
SAS CALL Routines for the Common Interface
Attachment Layout for Websphere MQ and MSMQ Through Common Messaging Interface
Attachment Layout for TIB/Rendezvous
Attachment Error Handling for Common Messaging Interface
Application Messaging

Configuring WebSphere MQ with the WebSphere MQ Explorer

  1. Before you use the WebSphere MQ applications, you must create a queue manager. The queue manager is a system program that is responsible for maintaining the queues and ensuring that the messages in the queues reach their destination. It also performs other functions associated with message queuing.

    A queue is a named destination that applications use to put and get messages. A queue name must be unique within a queue manager. Special queue types can be defined, such as transmission queues and dead letter queues.

    • A transmission queue is a queue that holds messages that will eventually be sent to a remote queue when a communication channel becomes available. Unless otherwise specified, these messages will be transmitted through the default transmission queue.

    • A dead letter queue is a local queue where messages that cannot be delivered are sent, either by the queue manager or an application. Some method should be in place in production environments to monitor and process messages in this queue.

    1. From the WebSphere MQ Explorer window, expand the WebSphere MQ label, then right-click Queue Managers. Select New arrow Queue Manager from the pop-up menu.

      WebSphere MQ Explorer window
    2. Enter the name for your queue manager. The name MYQMGR will be used in the following example. All names in WebSphere MQ are case sensitive. Using all capital letters for names helps avoid confusion. The names in the example are suggestions. You can use different names if you choose. Fill in names for the default transmission queue and dead letter queue. Check the box to make this your default queue manager.

      Create Queue Manager, step 1

      Click Next to continue.

    3. The next screen indicates the type of logging that the queue manager will perform, and the maximum number of log files that can be produced.

      Create Queue Manager, step 2

      Click Next to accept the suggested values and continue.

    4. Verify that Start Queue Manager is checked.

      Create Queue Manager, step 3

      Click Next to continue.

    5. The following step enables the WebSphere MQ applications that are running on your machine to communicate with other machines. Make sure that Create listener configured for TCP/IP is selected, and enter 1414 for the port number. This is the default port number for WebSphere MQ. Check with your system administrator to verify that this is the correct port to use.

      Create Queue Manager, step 4

      Click Finish to create your queue manager. It might take a minute to create and start the queue manager.

  2. Create one or more local queues for exchanging messages on your queue manager. These are the queues that SAS applications will use to exchange messages with other applications. In the tree, find your newly created queue manager and click "+" to expand the menu. Right-click Queues, then select New arrow Local Queue from the popup menu.

    In the Queue Name field, enter the name of the local queue that you want to create. This queue name is specified in any application programs that use WebSphere MQ. On this screen, you might want to change the Default Persistence value from Not Persistent to Persistent. This enables messages to remain in the queue even if the queue manager is shut down. Click the various tabs to see the types of values that can be defined.

    Create Local Queue window

    If you will be using high-volume messaging applications like scoring, you might want to change another default value. Click the Extended tab and increase the Maximum Queue Depth to 100,000 or more. This value represents the maximum number of messages that a queue can hold.

    Create Local Queue window, extended tab

    You can also change the properties after the queue has been defined. Click OK to create the queue. Repeat the process for any additional local queues that you want to create. For example, the REQUEST queue that was previously defined can be used for messages that will be read by a SAS application, while a queue named REPLY could be used by the SAS application to write the response to the request message.

    You should also create the dead letter queue that was defined when you created the queue manager. It is also a local queue. You will need to create the default transmission queue if you will be exchanging messages with queues on other queue managers. See IBM's WebSphere MQ documentation for information about configuring channels and transmission queues.

    At this point, WebSphere MQ has enough information for you to run applications that use message queuing locally within your machine through a single queue manager.

Configuration Required for WebSphere MQ Client Access

IBM also provides a lighter client version of WebSphere MQ that can be installed and used separately from the full WebSphere MQ Base or server installation. The client can be installed on the same machine as the server, or on a separate machine. The client does not have its own queue manager, and must communicate over the network or within a machine to a queue manager that is defined elsewhere.

There are two requirements that must be completed before you can configure the client/server communication.

First, you must define a server connection channel on the queue manager that will provide support to the client. A channel is a definition that enables intercommunication between queue managers, or between clients and queue managers.

To define a server connection channel from the WebSphere MQ Explorer, click MYQMGR arrow Advanced to expand the list. Right-click Channels, select NEW arrow Server Connection Channel and enter the channel name (for example, SERVER.CHANNEL1).

Create Server Connection Channel window

Second, the WebSphere MQ Client must be installed and configured on the client, which might or might not be on the same machine as the server. The client is included as part of the typical installation. Use the MQSERVER Windows environment variable to define the client connection to the server. The following code is an example of how to set this variable in Windows operating environments:

   set MQSERVER=ChannelName/TransportType/ConnectionName

For example:

   set MQSERVER=SERVER.CHANNEL1/TCP/server_address(port)

In this example, server_address is the TCP/IP host name (either the IP address or complete host name) of the server, and port is the number of the TCP/IP port on which the server is listening. The port is defined when you create the queue manager. The default port number is 1414. For example:


Using the Configured Values in a SAS Datastep Application

The queue and queue manager values are required in SAS applications that use the WebSphere MQ functional interface. In the previous examples, the queue manager is named MYQMGR, and the queue is named REQUEST. These values are used as follows in the SAS DATA step application:

   CALL MQCONN(Name, hConn, compCode, reason);

   action = "GEN";
   call mqod(hod, action, rc, parms, objname);

      call mqopen(hconn, hod, options, hobj, compCode, reason);

If a SAS application is running as a WebSphere MQ Client, then you must include the following line of code before making any calls using the WebSphere MQ Functional Interface. This line should be placed at the beginning of the application, before the DATA step. For example:

   data _null_;

Explanations of Common WebSphere MQ Application Error Codes

Reason Code Explanation Suggested Action
2018 Connection handle is invalid. A connection handle that is created by an MQCONN call must be used within the same DATA step where it was created.
2035 User is not authorized to perform the attempted action. Verify that you are connecting to the correct queue and queue manager. Verify that you are authorized to connect to the queue manager. If error is reported to a client connecting to a queue manager, you might need to set the user ID under the MCA tab in the server connection channel definition properties to a user ID that has permission to access the queue manager on the server machine.
2058 Error in Queue Manager Name. Check spelling and case of the queue manager name that is used in the application and is defined in the queue manager.
2059 Queue Manager is not available. Restart the queue manager.
2085 Unknown Object Name. Check spelling and case of the queue name that is used in the application and is defined in the queue manager.
Others   See the Messages book in the WebSphere MQ documentation.