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 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 MQMD 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 completing 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 might want to identify differently from those already identified in the MQMD.

For a description of these fields, see MQPMR.

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 1 shows how you can put a message to a distribution list in C.
Figure 1. Putting a message to a distribution list in C. The MQPMO uses pointers to the MQPMR and MQRR structures.
The diagram shows an MQPMO (Put Message Options) data structure. The version number is identified as 2. The structure contains: the number of entries to be found in the dependent MQPMR (Put Message Records) and MQRR (Response Record) structures; a pointer to a separate MQPMR structure; a pointer to a separate MQRR structure. These structures are also shown, and each contains a list with the same number of entries. The number was given in the MQPMO. The MQPMR entries have fields such as MsgId or CorrelId; the precise fields in the MQPMR depend upon another field in the MQPMO. The MQRR entries have fields for Completion Code and Reason Code.
Figure 2 shows how you can put a message to a distribution list in COBOL.
Figure 2. Putting a message to a distribution list in COBOL. The MQPMO uses offsets in COBOL.
The diagram shows an MQPMO (Put Message Options) data structure. The version number is identified as 2. The structure contains two offsets that identify where in the MQPMO the list of MQPMR (Put Message Records) and MQRR (Response Record) values are found. The MQPMR entries have fields such as MsgId or CorrelId; the precise fields in the MQPMR depend upon another field in the MQPMO. The MQRR entries have fields for Completion Code and Reason Code.

Using MQPUT1

If you are using MQPUT1, consider the following points:
  1. The values of the ResponseRecOffset and ResponseRecPtr fields must be null or zero.
  2. The Response Records, if required, must be addressed from the MQOD.