WebSphere MQ message queue access

EGL supports access of WebSphere® MQ (formerly MQSeries®) message queues on any of the target platforms.
You can provide such access in either of the following ways:

You can mix the two approaches in a given program. However, best practice is to use one or the other approach exclusively.

Regardless of your approach, you can control various runtime conditions through options records, which are variables based on specific global BasicRecord parts. EGL passes these variables on calls to WebSphere MQ. EGL provides a number of sample Record parts that you can use as the basis for options records.

Your approach determines how EGL makes the options records available to WebSphere MQ:
For details on options records and on the values that are passed to WebSphere MQ by default, see Options records for MQRecords. For details on WebSphere MQ itself, refer to these documents:

Connections

You connect to a queue manager (called the connecting queue manager) the first time you use one of the following statements:
  • An EGL add or get next statement that accesses a message queue.
  • An invocation of the EGL function MQCONN or MQCONNX.

You can access only one connecting queue manager at a time; however, you can access multiple queues that are under the control of the connecting queue manager. If you wish to connect directly to a queue manager other than the current connecting queue manager, you must disconnect from the first queue manager by invoking MQDISC, then connect to the second queue manager by invoking add, get next, MQCONN, or MQCONNX.

You can also access queues that are under the control of a remote queue manager, which is a queue manager with which the connecting queue manager can interact. Access between the two queue managers is possible only if WebSphere MQ itself is configured to allow for that access.

Access to the connecting queue manager is terminated when you invoke MQDISC or when your code ends.

Include message in transaction

You can embed queue-access statements in a unit of work so that all your changes to the queues are committed or rolled back at a single processing point. If a statement is in a unit of work, the following is true:
  • An EGL get next statement (or an EGL MQGET invocation) removes a message only when a commit occurs
  • The message placed on a queue by an EGL add statement (or an EGL MQPUT invocation) is visible outside the unit of work only after a commit occurs

When queue-access statements are not in a unit of work, each change to a message queue is committed immediately.

An WebSphere MQ-related EGL add or get next statement is embedded in a unit of work if the includeMsgInTransaction property is in effect for the MQRecord. The generated code includes these options:
  • For MQGET, MQGMO_SYNCPOINT
  • For MQPUT, MQPMO_SYNCPOINT
If you do not specify the includeMsgInTransaction property for an MQRecord, the queue-access statements run outside of a unit of work. The generated code includes these options:
  • For MQGET, MQGMO_NO_SYNCPOINT
  • For MQPUT, MQPMO_NO_SYNCPOINT

When your code ends a unit of work, EGL commits or rolls back all recoverable resources that are accessed by your program, including databases, message queues, and recoverable files. This outcome occurs whether you use the system functions (sysLib.commit, sysLib.rollback) or the EGL calls to WebSphere MQ (MQCMIT, MQBACK); the appropriate EGL system function is invoked in either case.

A rollback occurs if an EGL program terminates early because of an error.

Customization

You can customize your interaction with WebSphere MQ rather than relying on the default processing of add and get next statements.

EGL provides a set of DataTable parts to help you interact with WebSphere MQ. Each part allows EGL-supplied functions to retrieve values from memory-based lists at run time. You must bring the following installed EGL files into your project without changing them:
records.egl
Contains BasicRecord parts that are the source for options records; also includes structure parts that those records use and that support your development of custom options records.
functions.egl
Contains two sets of functions:
  • WebSphere MQ command functions, which access WebSphere MQ directly.
  • Initialization functions, which you can use to place initial values in the options records that are used in your program.
mqrcode.egl, mqrc.egl, mqvalue.egl
Contains a set of EGL DataTable parts that are used by the command and initialization functions.

You must carry out the following tasks:

  1. Import the files into an EGL project from the following directory:
    sharedInstallationDir\plugins\
    com.ibm.etools.egl.resources_version\MqReusableParts
    sharedInstallationDir
    The shared product installation directory, such as C:\Program Files\IBM\SDP70Shared. If you installed and kept a Rational® Developer product before installing the product that you are using now, you might need to specify the directory from the earlier installation.
    version
    The latest version of the plugin; for example, "7.0.100.RFB_20080711_1614".
  2. To make the parts more easily available to your program, write one or more EGL import statements in the file that contains your program. If the files to be imported reside in a project other than the one in which you are developing code, make sure that your project references the other project.

    For details, see Import and use statements.

  3. In your program, declare global variables:
    • Include use declarations for the mqrc, mqrcode, and mqvalue DataTables.
    • For each options record that you wish to pass to WebSphere MQ, declare a basic record that uses an options record part as a typedef. For details on each part, see Options records for MQRecords.
  4. In your function, initialize the options records that you intend to pass to WebSphere MQ by invoking the imported EGL initialization function for each record. Each function has the name of a Record part followed by _INIT, for example, MQGMO_INIT.
  5. Set values for the fields in the options records. The mqvalue DataTable contains a single row of fields, each of which corresponds to a symbol that is described in the WebSphere MQ documentation. You can set a value for a field in an option record by using one of the fields in the mqvalue DataTable, as in the following example:
    mqgmo.options = mqvalue.mqgmo_lock[1];
    You can set a numeric field in an option record to a combination of values by adding the values, as in the following example:
      mqgmo.options = mqvalue.mqgmo_lock[1] 
                      + mqvalue.mqgmo_accept_truncated_msg[1] 
                      + mqvalue.mqgmo_browse_first[1];
  6. The details of when you need to generate tables depend on whether your target program language is COBOL or Java™. To generate all the data tables that are used in your program, allow the build descriptor option genTables to default to YES. For more information, see DataTable part.

Features supported only for COBOL

The following WebSphere MQ features are supported only when you are generating a COBOL program:
  • Triggering
  • Distribution lists

Feedback