Distribution lists

Not supported in WebSphere MQ for z/OS.

Distribution lists allow you to put a message to multiple destinations in a single MQPUT or MQPUT1 call. Multiple queues can be opened using a single MQOPEN and a message can then be put to each of those queues using a single MQPUT. Some generic information from the MQI structures used for this process can be superseded by specific information relating to the individual destinations included in the distribution list.

When an MQOPEN call is issued, generic information is taken from the Object Descriptor (MQOD). If you specify MQOD_VERSION_2 in the Version field and a value greater than zero in the RecsPresent field, the Hobj can be defined as a handle of a list (of one or more queues) rather than of a queue. In this case, specific information is given through the object records (MQORs), which give details of destination (that is, ObjectName and ObjectQMgrName).

The object handle (Hobj) is passed to the MQPUT call, allowing you to put to a list rather than to a single queue.

When a message is put on the queues (MQPUT), generic information is taken from the Put Message Option structure (MQPMO) and the Message Descriptor (MQMD). Specific information is given in the form of Put Message Records (MQPMRs).

Response Records (MQRR) can receive a completion code and reason code specific to each destination queue.

Figure 5 shows how distribution lists work.

Figure 5. How distribution lists work. This diagram shows that one message is transmitted through the channel and can be put on more than one remote queue.

Opening distribution lists

Use the MQOPEN call to open a distribution list, and use the options of the call to specify what you want to do with the list.

As input to MQOPEN, you must supply:

A connection handle (see Chapter 9, Putting messages on a queue for a description)
Generic information in the Object Descriptor structure (MQOD)
The name of each queue you want to open, using the Object Record structure (MQOR)

The output from MQOPEN is:

An object handle that represents your access to the distribution list
A generic completion code
A generic reason code
Response Records (optional), containing a completion code and reason for each destination

Using the MQOD structure

Use the MQOD structure to identify the queues you want to open. To define a distribution list, you must specify MQOD_VERSION_2 in the Version field, a value greater than zero in the RecsPresent field, and MQOT_Q in the ObjectType field. See WebSphere MQ Application Programming Reference for a description of all the fields of the MQOD structure.

Using the MQOR structure

An MQOR structure must be provided for each destination. The structure contains the destination queue and queue manager names. The ObjectName and ObjectQMgrName fields in the MQOD are not used for distribution lists. There must be one or more object records. If the ObjectQMgrName is left blank, the local queue manager is used. See WebSphere MQ Application Programming Reference for further information about these fields.

You can specify the destination queues in two ways:

By using the offset field ObjectRecOffset.
In this case, the application should declare its own structure containing an MQOD structure, followed by the array of MQOR records (with as many array elements as are needed), and set ObjectRecOffset to the offset of the first element in the array from the start of the MQOD. Care must be taken to ensure that this offset is correct.
Use of built-in facilities provided by the programming language is recommended, if these are available in all of the environments in which the application must run. The following illustrates this technique for the COBOL programming language:
```
 01  MY-OPEN-DATA.
     02 MY-MQOD.
        COPY CMQODV.
     02 MY-MQOR-TABLE OCCURS 100 TIMES.
        COPY CMQORV.
     MOVE LENGTH OF MY-MQOD TO MQOD-OBJECTRECOFFSET.
```
Alternatively, the constant MQOD_CURRENT_LENGTH can be used if the programming language does not support the necessary built-in facilities in all of the environments concerned. The following illustrates this technique:
```
 01  MY-MQ-CONSTANTS.
     COPY CMQV.
 01  MY-OPEN-DATA.
     02 MY-MQOD.
        COPY CMQODV.
     02 MY-MQOR-TABLE OCCURS 100 TIMES.
        COPY CMQORV.
     MOVE MQOD-CURRENT-LENGTH TO MQOD-OBJECTRECOFFSET.
```
However, this will work correctly only if the MQOD structure and the array of MQOR records are contiguous; if the compiler inserts skip bytes between the MQOD and the MQOR array, these must be added to the value stored in ObjectRecOffset.
Using ObjectRecOffset is recommended for programming languages that do not support the pointer data type, or that implement the pointer data type in a way that is not portable to different environments (for example, the COBOL programming language).
By using the pointer field ObjectRecPtr.
In this case, the application can declare the array of MQOR structures separately from the MQOD structure, and set ObjectRecPtr to the address of the array. The following illustrates this technique for the C programming language:
```
MQOD MyMqod;
MQOR MyMqor[100];
MyMqod.ObjectRecPtr = MyMqor;
```
Using ObjectRecPtr is recommended for programming languages that support the pointer data type in a way that is portable to different environments (for example, the C programming language).

Whichever technique is chosen, one of ObjectRecOffset and ObjectRecPtr must be used; the call fails with reason code MQRC_OBJECT_RECORDS_ERROR if both are zero, or both are nonzero.

Using the MQRR structure

These structures are destination specific as each Response Record contains a CompCode and Reason field for each queue of a distribution list. You must use this structure to enable you to distinguish where any problems lie.

For example, if you receive a reason code of MQRC_MULTIPLE_REASONS and your distribution list contains five destination queues, you will not know which queues the problems apply to if you do not use this structure. However, if you have a completion code and reason code for each destination, you can locate the errors more easily.

See WebSphere MQ Application Programming Reference for further information about the MQRR structure.

Figure 6 shows how you can open a distribution list in C.

Figure 6. Opening a distribution list in C. The MQOD uses pointers to the MQOR and MQRR structures.

Figure 7 shows how you can open a distribution list in COBOL.

Figure 7. Opening a distribution list in COBOL. The MQOD uses offsets in COBOL.

The diagram shows an MQOD (Object Descriptor) data structure. The version number is identified as 2. The structure contains two offsets that identify where in the MQOD the list of MQOR (Object Record) and MQRR (Response Record) values are found. The MQOR entries have fields for destination queue name and queue manager name. The MQRR entries have fields for Completion Code and Reason Code.

Using the MQOPEN options

The following options can be specified when opening a distribution list:

MQOO_OUTPUT
MQOO_FAIL_IF_QUIESCING (optional)
MQOO_ALTERNATE_USER_AUTHORITY (optional)
MQOO_*_CONTEXT (optional)

See Chapter 8, Opening and closing objects for a description of these options.

Putting messages to a distribution list

To put messages to a distribution list, you can use MQPUT or MQPUT1. As input, you must supply:

A connection handle (see Chapter 9, Putting messages on a queue for a description).
An object handle. If a distribution list is opened using MQOPEN, the Hobj allows you only to put to the list.
A message descriptor structure (MQMD). See WebSphere MQ Application Programming Reference for a description of this structure.
Control information in the form of a put-message option structure (MQPMO). See Specifying options using the MQPMO structure for information about filling in the fields of the MQPMO structure.
Control information in the form of Put Message Records (MQPMR).
The length of the data contained within the message (MQLONG).
The message data itself.

The output is:

A completion code
A reason code
Response Records (optional)

Using the MQPMR structure

This structure is optional and gives destination-specific information for some fields that you may want to identify differently from those already identified in the MQMD. For a description of these fields, see WebSphere MQ Application Programming Reference.

The content of each record depends on the information given in the PutMsgRecFields field of the MQPMO. For example, in the sample program AMQSPTL0.C (see The Distribution List sample program for a description) showing the use of distribution lists, the sample chooses to provide values for MsgId and CorrelId in the MQPMR. This section of the sample program looks like this:

  typedef struct
  {
  MQBYTE24 MsgId;
  MQBYTE24 CorrelId;
  } PutMsgRec;...
  /**********************
  MQLONG PutMsgRecFields=MQPMRF_MSG_ID | MQPMRF_CORREL_ID;

This implies that MsgId and CorrelId are provided for each destination of a distribution list. The Put Message Records are provided as an array.

Figure 8 shows how you can put a message to a distribution list in C.

Figure 8. Putting a message to a distribution list in C. The MQPMO uses pointers to the MQPMR and MQRR structures.

Figure 9 shows how you can put a message to a distribution list in COBOL.

Figure 9. Putting a message to a distribution list in COBOL. The MQPMO uses offsets in COBOL.

Using MQPUT1

If you are using MQPUT1, consider the following:

The values of the ResponseRecOffset and ResponseRecPtr fields must be null or zero.
The Response Records, if required, must be addressed from the MQOD.