Reading from and writing to message queues

Write to message queues with the EGL add statement; read with get next.

The first time you use an EGL statement with an MQ record during a program, EGL checks to see if there is an active connection to a queue manager. If not, it creates one.

After you have read from or written to a message queue you may need to commit or roll back your changes.

Connecting to queue managers

You can connect to only one queue manager at a time in an EGL program.

EGL automatically connects to the queue manager on the first add or get next statement in a program, using the queue manager name specified in the system resource name associated with the message queue record. If the queue manager name is not specified, the queue manager is the default queue manager defined for your system. EGL automatically disconnects from the queue manager when the program ends, closing any open files and committing the current unit of work if it is still open.

EGL provides sample functions named MQCONN and MQDISC that call the MQCONN and MQDISC routines from the WebSphere® MQ API. Use these functions in the following circumstances:
  • If the connection queue manager and the queue manager to which the queue belongs are different, use an MQCONN function call to connect before issuing the add or get next statement in the program. Otherwise the add or the get next statement will use the current open connection instead of attempting to connect to the queue manager specified in the system resource name.
  • If you want a long running program to disconnect from the queue manager before the program ends, use an MQCONN function call to do the initial connection and an MQDISC function call to disconnect after all queue access is complete.

For more information on MQCONN and MQDISC, see Using direct WebSphere MQ API calls. In workstation environments (Windows NT™, OS/2®, AIX®, Solaris, and HP), WebSphere® MQ provides different runtime libraries for WebSphere® MQ programs depending on whether the program is running on the same system as the message queue manager or whether the program is running as an WebSphere® MQ client communicating with a manager on a server system. On AIX® and HP systems, different libraries are provided for threaded and non-threaded environments as well.

Writing messages to queues

Write messages to queues using the add statement with the message queue record as the I/O object. EGL performs the following actions:
  1. Establishes the connection to the queue.
  2. Opens the connection to the queue.
  3. Puts the message on the queue.
You must use a local definition of the remote queue on the currently connected queue manager if both of the following circumstances are true:
  • You are writing messages to a queue on another Queue Manager using the add statement.
  • You previously wrote a message to a queue using the add statement.

EGL saves the connection handle for future add statements.

You must use the close statement after an add statement to close the connection to the queue in any of the following circumstances:
  • Before using the get next statement.
  • To release the queue for access by another program.
  • To release the queue if you have a long running program and have completed work with the queue.

EGL automatically closes the connection to the queue on program termination.

Reading messages from queues

Read messages from queues using the get next statement with the message queue record as the I/O object.When you use the get next statement, EGL performs the following actions:
  1. Connects to the queue manager, if the queue manager is not already connected.
  2. Opens the queue, if the queue is not already open.
  3. Gets the next message from the queue.
You must use a local definition of the remote queue on the currently connected queue manager if both of the following circumstances are true:
  • You are reading messages from a queue on another Queue Manager using the get next statement.
  • You previously read a message from a queue using the get next statement.
You must use the close statement after a get next statement to close the connection to the queue in any of the following circumstances:
  • Before using the add statement.
  • To release the queue for access by another program.
  • To release the queue if you have a long running program and have completed work with the queue.

EGL automatically closes the connection to the queue on program termination.

Committing or rolling back messages

When you combine messages in a transaction that defines a unit of work, the messages can be committed or rolled back as a group. When a unit of work is committed, everything included in the transaction is finalized. When a unit of work is rolled back, everything included in the transaction is removed.

The methods used for commits and rollbacks depend on your environment. The following environments handle commits and rollbacks independently of MQ:
  • AS/400®
  • CICS® for MVS/ESA™
  • CICS® for VSE/ESA™
  • IMS™

In these transaction environments, message queue commits and rollbacks are coordinated with commits and rollbacks for other recoverable resources, like DB2® databases, using a two-phase commit protocol.

In other environments, the resources for different managers are committed independently from one another. EGL automatically issues the appropriate MQ calls for commits and rollbacks when you use sysLib.commit() and sysLib.rollback().