Chapter 11 Sending and receiving IBM WebSphere MQ messages

InterSystems IRIS provides an interface for IBM WebSphere MQ that can be used to exchange messages between message queues of InterSystems IRIS and IBM WebSphere MQ. To use this interface, you must have access to the IBM WebSphere MQ server, and the IBM WebSphere MQ client must be running on the same computer as InterSystems IRIS.

This interface consists of the % net.mqsend and % net.mqrecv classes, both subclasses of % net.abstractMQ. These classes use dynamic link libraries automatically installed by InterSystems IRIS on all appropriate platforms. (This is mqInterface.dll on Windows; Other platforms have different file extensions.) . In turn, the InterSystems IRIS dynamic link library requires the IBM WebSphere MQ dynamic link library.

This interface supports only text data, not binary data.

Use the RIS interface of IBM WebSphere MQ

In general, to use the InterSystems IRIS interface of IBM WebSphere MQ, do the following:

  1. Ensure accessIBM WebSphereMQv7.xOr later. Specifically:
  • IBM WebSphere MQThe client must be installed on the same computer as InterSystems IRIS. Please note that the installer will be updated as neededPATHEnvironment variables and add other system variables.
  • Be sure to restart your computer after installing the client so that InterSystems IRIS can recognize the client.
  • The client must be able to access IBMWebSphere MQThe server.
  • The user name that will be used to access the server must have permission to use the queue manager and the queue that you plan to use.
  1. create%Net.MQSendor%Net.MQRecvDepending on whether you want to send or receive messages.
  2. Connect to the IBMWebSphere MQThe server. To do this, you need to provide the following information:
  • Name of the queue manager.
  • The name of the queue to use.
  • The channel that communicates with the queue. You can specify IBMWebSphere MQChannel name, transport mechanism, IP address, and port of the server.

If you are using the authentication capabilities of IBM WebSphere MQ, you can also provide a name and password.

  1. call%Net.MQSendor%Net.MQRecvTo send or receive a message.

Note: To use IBM Websphere MQ on 64-bit Linux platforms, LD_LIBRARY_PATH must be set to include the location of the MQ library. Because a path must be set for any InterSystems IRIS process that uses the MQ interface, if a background process is running, this path must be set before starting InterSystems IRIS and in any UNIX® terminal before running the IRIS terminal.

Get error code

The % net.mqsend and % net.mqrecv methods return 1 on success and 0 on failure. In the case of an error, the %GetLastError() method is called, which returns the last reason code given by IBM WebSphere MQ.

Creating a connection object

Before messages can be sent or received through IBM WebSphere MQ, a Connection object must be created that can establish a Connection to the queue manager, open a channel, and open a queue for use. There are two ways to do this:

  • You can use%InitMethod that takes a parameter specifying all the required information.
  • You can use it after you first set the properties that specify all the required information%ConnectMethods.

Use the %Init() method

To create a connection object using the %Init() method, do the following:

  1. create%Net.MQSend(if a message is to be sent) or%Net.MQRecvInstance if you want to receive messages. This topic refers to this instance as a connection object.

Note: If you receive a

error, the DYNAMIC link LIBRARY is missing and the messages.log file (in the system manager directory) has more details.

  1. Set authentication if requiredConnectionThe following properties of the object:
  • User name – Specifies the user name that is authorized to use this channel.
  • Password – Specifies the password for the given user.
  1. callConnectionThe object’s%Init()Methods. This method takes the following parameters in order.

A. String that specifies the queue name. This should be the valid queue that specifies the queue manager.

B. Specify a string for the queue manager. It should be a valid queue manager on the IBM WebSphere MQ server.

If this parameter is omitted, the system uses the default queue manager configured in IBM WebSphere MQ. Alternatively, if IBM WebSphere MQ has been configured for a queue manager to be determined by the queue name, the system will use the queue manager appropriate to the given queue name.

C. Specify the channel specification character string in the following format:

"channel_name/transport/host_name(port)"
Copy the code

Here, channel_name is the name of the channel to be used, Transport is the Transport used by the channel, Host_name is the name (or IP address) of the server running the IBM WebSphere MQ server, and port is the port that the channel should use.

The transport can be one of the following: TCP, LU62, NETBIOS, or SPX

Such as:

"CHAN_1/TCP/rodan(1401)"
Copy the code
"CHAN_1 / TCP / 127.0.0.1 (1401)."
Copy the code

If this parameter is omitted, the system uses the default channel specification configured in IBM WebSphere MQ. Or, if the system has been configured for channels to be determined by queue names, the system uses channels that are appropriate for a given queue name.

D. An optional string that specifies the log file to which error messages are written. By default, no logging is performed.

  1. check%Init()The value returned by the If this method returns 1, the connection has been successfully established and is ready to useConnectionObject sends or receives messages, depending on the class used.

Use the %Connect() method

In some cases, you might prefer to specify all the details of the connection separately. To do this, use the %Connect() method, as follows:

  1. create%Net.MQSend(if a message is to be sent) or%Net.MQRecvInstance if you want to receive messages. As mentioned earlier, this topic refers to this instance as a connection object.

Note: If you receive a

error, the DYNAMIC link LIBRARY is missing and the messages.log file (in the system manager directory) has more details.

  1. Set up theConnectionThe following properties of the object:
  • QName-(Mandatory) Specify the queue name. This should be the valid queue that specifies the queue manager.
  • QMgr– Specifies the queue manager to use; It should be IBMWebSphere MQValid queue manager on the server.

If this parameter is omitted, the system uses the default queue manager configured in IBM WebSphere MQ. Alternatively, if IBM WebSphere MQ has been configured for a queue manager to be determined by the queue name, the system will use the queue manager appropriate to the given queue name.

  1. Or, through SettingsConnectionObject to specify the channel to use:
  • Connection– specify IBMWebSphere MQThe host and port of the server. Such as:"127.0.0.1:1401".
  • Channel– Specifies the name of the channel to use. This must be a valid channel on the IBM WebSphere MQ server.
  • Transport– Specifies the transport used by the channel. This attribute can be one of the following:"TCP"."LU62"."NETBIOS"."SPX"

If these parameters are omitted, the system uses the default channel specification configured in IBM WebSphere MQ. Or, if the system has been configured for channels to be determined by queue names, the system uses channels that are appropriate for a given queue name.

  1. If the channel requires authentication, set itConnectionThe following properties of the object:
  • User name – Specifies the user name that is authorized to use this channel.
  • Password – Specifies the password for the given user.
  1. callConnectionThe object’s%ErrLog()Methods. This method takes a parameter, the name of the log file to be used for this connection object.
  2. check%ErrLog()The value returned by the
  3. callConnectionThe object’s%Connect()Methods.
  4. check%Connect()The value returned by the If this method returns 1, the connection has been successfully established and is ready to useConnectionObject sends or receives messages, depending on the class you use.

Specified Character Set (CCSID)

To set the character set used for message transformation, call the %SetCharSet() method of the Connection object. Specifies the integer coded character set ID(CCSID) used in IBM WebSphere MQ.

  • If messages are being sent, this should be the character set for those messages. If no character set is specified, the MQ system assumes that messages are used asMQDefault character set specified by the client.
  • If you want to retrieve messages, this is the character set to translate those messages into.

To get the CCSID currently in use, call the %charset() method. This method returns the CCSID by reference and returns either 1 or 0 to indicate success.

Specify additional message options

To specify message descriptor options, you can choose to set the following properties of the connection object:

  • ApplIdentityDataSpecifies the application identification message descriptor option.
  • PutApplTypeThe specifiedPUT Application TypeMessage descriptor options.

Send a message

To send a message, do the following:

  1. Follow the instructions in creating a Connection Object to create a connection object. In this case, create%Net.MQSendThe instance.ConnectionObject has a message queue to which messages can be sent.
  2. Call the following methods as needed:
  • %put()– Given a string, this method writes the string to the message queue.
  • %PutStream()– Given an initialized file character stream, this method writes the string to the message queue. Note that the stream must be setFilenameProperty to initialize it. Binary streams are not supported.
  • %SetMsgId()– Given a string, this method uses that string as the message ID for the next message to be sent.
  1. Check the value returned by the called method.
  2. After retrieving the message, callConnectionThe object’s%Close()Method to release a handle to a dynamically linked library.

Example 1: SendString()

The following class method uses the queue manager QM_antigua and a queue channel named S_antigua to send a simple string message to the queue MQtest. The channels are transported using TCP, and the IBM WebSphere MQ server is running on a machine named Antigua and listening on port 1401.

///Method returns reason code from IBM WebSphere MQ
ClassMethod SendString(a) As %Integer
{
 Set send=##class(%Net.MQSend%).New(a)Set queue="mqtest"
 Set qm="QM_antigua"
 Set chan="S_antigua/TCP/antigua(1414)"
 Set logfile="c:\mq-send-log.txt"

 Set check=send.%Init(queue,qm,chan,logfile)
 If 'check Quit send.%GetLastError() //send a unique message Set check=send.%Put("This is a test message "_$h) If 'check  Quit send.%GetLastError()
 Quit check
}
Copy the code

Example 2: SendCharacterStream()

The following class method sends the contents of the file character stream. It uses the same queue as the one used in the previous example:

///Method returns reason code from IBM WebSphere MQ
ClassMethod SendCharacterStream(a) As %Integer
{
 Set send=##class(%Net.MQSend%).New(a)Set queue="mqtest"
 Set qm="QM_antigua"
 Set chan="S_antigua/TCP/antigua(1414)"
 Set logfile="c:\mq-send-log.txt"

 Set check=send.%Init(queue,qm,chan,logfile)
 If 'check Quit send.%GetLastError() //initialize the stream and tell it what file to use Set longmsg=##class(%FileCharacterStream).%New() Set longmsg.Filename="c:\input-sample.txt" Set check=send.%PutStream(longmsg) If 'check  Quit send.%GetLastError()
 Quit check
}
Copy the code

Example 3: Sending a message from a terminal

The following example shows a terminal session that sends a message to an IBM WebSphere MQ queue. This will only run on machines configured with the IBM WebSphere MQ client.

Set MySendQ = ##class(%Net.MQSend%).New(a)Do MySendQ%.Init("Q_1","QM_1","QC_1/TCP/ 127.0.0.1 (1401), ""C: \mq.log")

Do MySendQ%.Put("Hello from tester")

Set MyRecvQ = # #class(%Net.MQRecv%).New(a)Do MyRecvQ%.Init("Q_1","QM_1","QC_1","C: \mq.log")

Do MyRecvQ%.Get(.msg, 10000).Write msg,!
Copy the code