Configuring WebSphere MQ with the WebSphere MQ Explorer :: Application Messaging with SAS(R) 9.3, Second Edition

Configure a Queue Manager

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 that are associated with message queuing.

A queue is a named destination that applications use to send and receive 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 are 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.

To configure a queue manager, perform the following steps:

From the WebSphere MQ Explorer window, expand the WebSphere MQ node, and then right-click Queue Managers. Select NewQueue Manager from the pop-up menu.
Enter the name for your queue manager. The examples in this section use the name MYQMGR. Fill in names for the default transmission queue and dead letter queue. Select Make this the default queue manager.

Note: All names in WebSphere MQ are case sensitive.

Click Next to continue.
Click Next to accept the default values for the logging options.
Verify that Start Queue Manager is selected.

Click Next to continue.
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.

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

Define Queues

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.

To define a queue, perform the following steps:

In the WebSphere MQ Explorer, locate your queue manager and expand the menu. Right-click Queues, and then select NewLocal Queue from the popup menu. The Create Local Queue window appears.
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. You might also want to change the Default Persistence value from Not Persistent to Persistent. Setting a value of Persistent enables messages to remain in the queue even if the queue manager is shut down. Click each tab to see the types of values that can be defined.
(Optional) If you use high-volume messaging applications like scoring, then select the Extended tab and increase the value of Maximum Queue Depth to 100,000 or more. The value of Maximum Queue Depth represents the maximum number of messages that a queue can hold.
Click OK to create the queue. Repeat the process for any additional local queues that you want to create.

You should also create the dead letter queue that is specified in the queue manager definition. If you will be exchanging messages with queues on other queue managers, then create the default transmission queue. For information about configuring channels and transmission queues, see the IBM WebSphere MQ documentation.

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.

Configuring WebSphere MQ Client Access

Overview of Configuring Client Access

IBM 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.

To configure client access, perform the following steps:

Define a Server Connection Channel

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, perform the following steps:

In WebSphere MQ Explorer, select a queue manager and then select Advanced.
Right-click Channels, and then select NEWServer Connection Channel. The Create Server Connection Channel window appears.
Specify the name of the channel and an optional description, and then click OK to save the channel.

Install the WebSphere MQ Client

The WebSphere MQ Client must be installed and configured on the client machine. The WebSphere MQ Client is included as part of the typical installation.

Define the Queue Manager Connection on the Client Machine

You can use the following methods to define the connection from the client to the queue manager:

Set the MQSERVER environment variable. The following code is an example of how to set this variable on Windows:
```
set
MQSERVER=ChannelName/TransportType/ConnectionName
```
Here is an 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. Here is an example:
```
set
MQSERVER=SERVER.CHANNEL1/TCP/1.2.3.4(1414)
```
Create a client channel definition table, and set the MQCHLLIB and MQCHLTAB environment variables to identify the location of the table.

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

Use the Configured Values in a SAS DATA Step 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:

hConn=0;
Name="MYQMGR";
compCode=0;
reason=0;
CALL MQCONN(Name, hConn, compCode, reason);

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

options="INPUT_SHARED";
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, as shown in the following example:

%let MQMODEL=CLIENT;
data _null_;
...
run;

Common WebSphere MQ Application Error Codes

Reason Code	Explanation	Suggested Action
2018	A 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	The 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	There is an error in the 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	The queue manager is not available.	Restart the queue manager.
2085	The object name is unknown.	Check spelling and case of the queue name that is used in the application and is defined in the queue manager.
Others		See WebSphere MQ Messages at `www.ibm.com`.