MQSeries support

EGL supports access of 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. For most purposes, however, you use one or the other approach exclusively.

Regardless of your approach, you can control various run-time conditions by customizing options records, which are global basic records that EGL run-time services passes on calls to MQSeries. When you declare an options record as a program variable, you can use an EGL-installed options record part as a typedef; or you can copy the installed part into your own EGL file, customize the part, and use the customized part as a typedef.

Your approach determines how EGL run-time services makes the options records available to MQSeries:

For details on options records and on the values that are passed to MQSeries by default, see Options records for MQ records. For details on MQSeries itself, refer to these documents:

Connections

You connect to a queue manager (called the connecting queue manager) the first time you invoke a statement from the following list:

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, disconnect from the first 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 MQSeries 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 when a commit occurs

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

An MQSeries-related EGL add or get next statement is embedded in a unit of work if the property includeMsgInTransaction is in effect for the MQ record. The generated code includes these options:

For MQGET, MQGMO_SYNCPOINT
For MQPUT, MQPMO_SYNCPOINT

If you do not specify the property includeMsgInTransaction for an MQ record, 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 being 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 MQSeries (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 detected by EGL run-time services.

Customization

If you wish to customize your interaction with MQSeries rather than relying on the default processing of add and get next statements, you need to review the information in this section.

EGL dataTable part

A set of EGL dataTable parts is available to help you interact with MQSeries. Each part allows EGL-supplied functions to retrieve values from memory-based lists at run time. The next section includes details on how data tables are deployed.

Making customization possible

To make customization possible, bring a variety of installed EGL files into your project without changing them in any way. The files are as follows:

records.egl

Contains basic record parts that can be used as typedefs for the options records that are used in your program; also includes structure parts that are used by those records and that give you the flexibility to develop record parts of your own

functions.egl

Contains two sets of functions:

MQSeries command functions, which access MQSeries directly
Initialization functions, which let you 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

Your tasks are as follows:

Using the process for importing files into the workbench, bring those files into an EGL project. The files reside in the following directory:
```
installationDir\egl\eclipse\plugins\
com.ibm.etools.egl.generators_version\MqReusableParts
```
installationDir

The product installation directory, such as C:\Program Files\IBM\RSPD\6.0. If you installed and kept a Rational Developer product before installing the product that you are using now, you may need to specify the directory that was used in the earlier install.

version

The latest version of the plugin; for example, 6.0.0
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.
In your program, declare global variables:
- Declare MQRC, MQRCODE, and MQVALUE, each of which must use as a typedef the dataTable part that has the same name as the variable.
- For each options record that you wish to pass to MQSeries, declare a basic record that uses an options record part as a typedef. For details on each part, see Options records for MQ records.
In your function, initialize the options records that you intend to pass to MQSeries. You can do this easily by invoking the imported EGL initialization function for a given options record. The name of each function is the name of the part that is used as a typedef for the record, followed by _INIT. An example is MQGMO_INIT.
Set values in the options records. In many cases you set a value by assigning an EGL symbol that represents a constant, each of which is based on a symbol described in the MQSeries documentation. You can specify multiple EGL symbols by summing individual ones, as in this example:
```
  MQGMO.GETOPTIONS = MQGMO_LOCK
                     + MQGMO_ACCEPT_TRUNCATED_MSG
                     + MQGMO_BROWSE_FIRST
```
The first time you generate a particular program that uses the customization features of MQSeries support, you also generate the data tables used by that program. To generate all data tables that are used in your program, allow the build descriptor option genTables to default to YES. For additional details, see DataTable part.