Configuring WebSphere MQ to Trigger SAS: An Example

• Introduction
• Configuration on the Windows XP Machine
• Configuration on the AIX Machine
• Notes

Introduction

SAS Integration Technologies provides two interfaces that can be used to send and receive messages using WebSphere MQ, the Common Messaging Interface, and the WebSphere MQ Interface. WebSphere MQ (formerly called MQSeries) enables you to trigger, or start, an application automatically when a message arrives on a message queue. There are many situations where it is useful to have a SAS DATA step application started when a message arrives on a specific queue. However, SAS cannot be started directly by the trigger monitor. An intermediate batch job is started by WebSphere MQ, and this batch job calls SAS. The details of one such configuration and batch job are included here.

The following example shows a SAS client running on Windows XP communicating using WebSphere MQ with a SAS server running on AIX. This SAS client sends a message to a queue and queue manager on AIX. When the message arrives on the queue, it triggers a batch job which starts the SAS server to receive the message and return the requested data set. The details of this example are specific to SAS 9.1. On AIX, the 64-bit WebSphere Client libraries are required by the SAS interfaces. The WebSphere MQ Client can connect to a WebSphere MQ server on any supported platform. WebSphere MQ requires that the trigger monitor and the application to be started be on the same system, but they can be on either the client or the server. The process definition, which defines the application to be triggered, must be defined on the WebSphere MQ server. In this example, the WebSphere MQ Queue Manager (server installation) is on the same AIX system as the WebSphere MQ Client. See IBM's WebSphere MQ Clients manual for more information about how to set up triggering when the client and server are on different systems. Refer to Notes for more details.

The following two sample programs demonstrate the triggering process:

• mqclient.sas
• mqserver.sas

The SAS DATA step mqclient.sas runs on the XP machine and requests a data set. The mqserver.sas program is triggered by the startsas batch program described below. It runs on the AIX machine. The mqserver.sas program reads the message off of the queue and returns the requested data set.

Configuration on the Windows XP Machine

For the sample programs to work, the following objects must be defined for the Windows queue manager, which is called XPQMGR in this example. The windows shown are taken from the IBM WebSphere® MQ Version 5.3 Explorer.

Define the local queue to receive replies from the triggered program.

Define the remote queue definition for the queue on the AIX queue manager that triggers SAS.

Define the receiver channel to listen for incoming messages.

Define the sender channel to send messages to the AIX queue manager.

Define the process definition to start the sender channel.

Define the transmission queue.

Configuration on the AIX Machine

The following code can either be a part of a configuration file, or stanzas that can be entered in the runmqsc tool. Modify the following templates and use the WebSphere MQ tool runmqsc to define the required objects on a queue manager that is named AIX for this example.

   * Local Queue that triggers the batch job to start SAS
   DEFINE QLOCAL(TRIGQUEUE) +
      REPLACE DEFPSIST(YES) DESCR('TRIGQUEUE Queue') +
      INITQ(MY.INITQ) +
      TRIGGER TRIGTYPE(EVERY) PROCESS(TRIGSAS.PROCESS)
   * TRIGTYPE can also be FIRST or DEPTH. EVERY will trigger
   * the batch job every time a message arrives on the queue.

   * Process to start the batch file that starts SAS
   DEFINE PROCESS (TRIGSAS.PROCESS) +
      REPLACE APPLICID('/users/userid/startsas') APPLTYPE(UNIX)

   DEFINE QLOCAL(MY.INITQ)

   * Receiver Channel for AIX Queue Manager
   DEFINE CHANNEL(AIX.CHANNEL) CHLTYPE(RCVR) +
      REPLACE DESCR('Receiver Channel on AIX') +
      TRPTYPE(TCP)

   *--- remote definitions for Windows XP queue manager ---*

   * Remote Queue at XPQMGR
   DEFINE QREMOTE(XPQMGR.REPLY) +
      REPLACE RNAME(REPLY) RQMNAME(XPGMGR) XMITQ(XPQMGR.XMITQ)

   * Transmission Queue
   DEFINE QLOCAL(XPQMGR.XMITQ) +
      REPLACE DESCR('Transmit Queue to XP system') +
      USAGE(XMITQ) TRIGGER TRIGTYPE(FIRST) +
      INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(XPQMGR.PROCESS)

   * Process definition for XMITQ trigger
   DEFINE PROCESS(XPQMGR.PROCESS) +
      REPLACE DESCR('Process definition +
         to start XPQMGR Channel') +
      USERDATA('XPQMGR.CHANNEL')

   * Sender Channel - started automatically
   * when first message written to XMITQ
   DEFINE CHANNEL(XPQMGR.CHANNEL) CHLTYPE(SDR) +
      REPLACE DESCR('Sender Channel to XPQMGR') +
      TRPTYPE(TCP) XMITQ(XPQMGR.XMITQ) +
      CONNAME('XPMACHINE.MYLOCATION.MYCOMPANY.COM')

   *---- Setup Client/Server Server Connection Channel ----*
   DEFINE CHANNEL(MQCLIENT.CHANNEL) +
      CHLTYPE(SVRCONN) TRPTYPE(TCP) +
      REPLACE DESCR('Server connection for client access') +
      MCAUSER(' ')

This example uses /users/userid/startsas as the name of the batch file triggered to run a SAS DATA step. The contents of this file are:

   # Make sure the 64-bit WebSphere MQ client
   # libraries are in your LIBPATH.
   export LIBPATH=/usr/mqm/lib64

   # Define the server that the SAS WebSphere MQ
   # client interface will connect through.
   export MQSERVER=
      MQCLIENT.CHANNEL/TCP/'<server IP address>(port)'

   sas -sysin /users/userid/mqserver.sas

You must also make sure that the trigger monitor has been started on the AIX machine for the proper initiation queue:

   runmqtrm -m AIX -q MY.INITQ

Notes

Note that support of WebSphere MQ 64-bit Client code in SAS requires SAS 9.1, WebSphere MQ Client and Server Version 5.2+PTF U482982, and the MACS Support Pac for MQSeries Client Library support for AIX. WebSphere MQ was not supported on AIX in SAS 9. Client and server support are available in SAS 8.2. The client-specific considerations of this example are not required when using SAS 8.2.