Configuring WebSphere MQ to Trigger SAS: An Example

Introduction

SAS Integration Technologies provides two interfaces that can be used to send and receive messages with 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 that runs on Windows XP and uses WebSphere MQ to communicate with a SAS server that runs 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 that starts the SAS server to receive the message and return the requested data set. 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.
For more information about triggering, see the WebSphere MQ Client documentation at www.ibm.com.
The following two sample programs demonstrate the triggering process:
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 that is 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

The trigger samples assume that the following configuration objects have been created on the Windows machine:
  • a queue manager named XPQMGR
  • a local queue named REPLY, with the following settings:
    Configuration Settings for the Local Queue
    Queue Name
    REPLY
    Type
    Local
    Put Messages
    Allowed
    Get Messages
    Allowed
    Default Priority
    0
    Default Persistence
    Not Persistent
    Scope
    Queue Manager
    Usage
    Normal
  • a remote queue named AIX.TRIGQUEUE, with the following settings:
    Configuration Settings for the Remote Queue
    Queue Name
    AIX.TRIGQUEUE
    Type
    Remote
    Put Messages
    Allowed
    Default Priority
    0
    Default Persistence
    Not Persistent
    Scope
    Queue Manager
    Remote Queue Name
    TRIGQUEUE
    Remote Queue Manager Name
    AIX
    Usage
    XMITQ
  • a receiver channel named XPQMGR.CHANNEL, with the following settings:
    Configuration Settings for the Receiver Channel
    Channel Name
    XPQMGR.CHANNEL
    Type
    Receiver
    Transmission Protocol
    TCP/IP
  • a sender channel named AIX.CHANNEL, with the following settings:
    Configuration Settings for the Sender Channel
    Channel Name
    AIX.CHANNEL
    Type
    Sender
    Transmission Protocol
    TCP/IP
    Connection Name
    AIX-machine-name
    Transmission Queue
    XMITQ
  • a process definition named AIX.PROCESS, with the following settings:
    Configuration Settings for the Process Definition
    Process Definition Name
    AIX.PROCESS
    Application Type
    Windows NT
    User Data
    AIX.CHANNEL
  • a transmission queue named XMITQ, with the following settings:
    Configuration Settings for the Transmission Queue
    Queue Name
    XMITQ
    Type
    Local
    Put Messages
    Allowed
    Get Messages
    Allowed
    Default Priority
    0
    Default Persistence
    Not Persistent
    Scope
    Queue Manager
    Usage
    Transmission
    Trigger Control
    On
    Trigger Type
    First
    Trigger Depth
    0
    Trigger Message Priority
    0
    Initiation Queue Name
    CHANNEL.INITQ
    Process Name
    AIX.PROCESS

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:
runmqsc -m AIX -q MY.INITQ