MQMD (Message descriptor) on IBM i

Overview

Purpose: The MQMD structure contains the control information that accompanies the application data when a message travels between the sending and receiving applications. The structure is an input/output parameter on the MQGET, MQPUT, and MQPUT1 calls.

Version: The current version of MQMD is MDVER2. Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions that follow.

The COPY file provided contains the most recent version of MQMD that is supported by the environment, but with the initial value of the MDVER field set to MDVER1. To use fields that are not present in the version-1 structure, the application must set the MDVER field to the version number of the version required.

A declaration for the version-1 structure is available with the name MQMD1.

Character set and encoding: Data in MQMD must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT. However, if the application is running as an IBM MQ MQI client, the structure must be in the character set and encoding of the client.

If the sending and receiving queue managers use different character sets or encodings, the data in MQMD is converted automatically. It is not necessary for the application to convert the MQMD.

• Use different versions of MQMD
• Message context
• Message expiry
• Fields
• Initial values
• RPG declaration

Use different versions of MQMD

• On the MQPUT and MQPUT1 calls, if the application provides a version-1 MQMD, the application can optionally prefix the message data with an MQMDE, setting the MDFMT field in MQMD to FMMDE to indicate that an MQMDE is present. If the application does not provide an MQMDE, the queue manager assumes default values for the fields in the MQMDE. Note: Several of the fields that exist in the version-2 MQMD but not the version-1 MQMD are input/output fields on the MQPUT and MQPUT1 calls. However, the queue manager does not return any values in the equivalent fields in the MQMDE on output from the MQPUT and MQPUT1 calls; if the application requires those output values, it must use a version-2 MQMD.
• On the MQGET call, if the application provides a version-1 MQMD, the queue manager prefixes the message returned with an MQMDE, but only if one or more of the fields in the MQMDE has a non-default value. The MDFMT field in MQMD will have the value FMMDE to indicate that an MQMDE is present.

When a message is on a transmission queue, some of the fields in MQMD are set to particular values; see MQXQH (Transmission-queue header) on IBM i for details.

Message context

• Identity context relates to the application that originally put the message
• Origin context relates to the application that most recently put the message
• User context relates to the application that originally put the message.

Although identity and origin context usually have the meanings described previously, the content of both types of context fields in MQMD actually depends on the PM* options that are specified when the message is put. As a result, identity context does not necessarily relate to the application that originally put the message, and origin context does not necessarily relate to the application that most recently put the message - it depends on the design of the application suite.

There is one class of application that never alters message context, namely the message channel agent (MCA). MCAs that receive messages from remote queue managers use the context option PMSETA on the MQPUT or MQPUT1 call. This allows the receiving MCA to preserve exactly the message context that travelled with the message from the sending MCA. However, the result is that the origin context does not relate to the application that most recently put the message (the receiving MCA), but instead relates to an earlier application that put the message (possibly the originating application itself).

For more information see Message context.

Message expiry

Messages that have expired on a loaded queue (a queue that has been opened) are automatically removed from the queue within a reasonable period of time after their expiry. Some other new features of this release of IBM MQ can lead to loaded queues being scanned less frequently than in the previous product version, however expired messages on loaded queues are always removed within a reasonable period of their expiry.

Fields

The MQMD structure contains the following fields; the fields are described in alphabetical order:

MDACC (32-byte bit string)

Accounting token.

This is part of the identity context of the message. For more information about message context, see Message context and Controlling context information.

MDACC allows an application to cause work done as a result of the message to be appropriately charged. The queue manager treats this information as a string of bits and does not check its content.

When the queue manager generates this information, it is set as follows:

• The first byte of the field is set to the length of the accounting information present in the bytes that follow; this length is in the range zero through 30, and is stored in the first byte as a binary integer.
• The second and subsequent bytes (as specified by the length field) are set to the accounting information appropriate to the environment.
  • On z/OS® the accounting information is set to:
    • For z/OS batch, the accounting information from the JES JOB card or from a JES ACCT statement in the EXEC card (comma separators are changed to X'FF'). This information is truncated, if necessary, to 31 bytes.
    • For TSO, the user's account number.
    • For CICS®, the LU 6.2 unit of work identifier (UEPUOWDS) (26 bytes).
    • For IMS, the 8-character PSB name concatenated with the 16-character IMS recovery token.
  • On IBM i, the accounting information is set to the accounting code for the job.
  • On HP Integrity NonStop Server, and UNIX, the accounting information is set to the numeric user identifier, in ASCII characters.
  • On Windows, the accounting information is set to a Windows NT security identifier (SID) in a compressed format. The SID uniquely identifies the user identifier stored in the MDUID field. When the SID is stored in the MDACC field, the 6-byte Identifier Authority (located in the third and subsequent bytes of the SID) is omitted. For example, if the Windows NT SID is 28 bytes long, 22 bytes of SID information are stored in the MDACC field.
• The last byte is set to the accounting-token type, one of the following values:

  ATTCIC

  CICS LUOW identifier.

  ATTDOS

  PC DOS default accounting token.

  ATTWNT

  Windows security identifier.

  ATT400

  IBM i accounting token.

  ATTUNX

  UNIX numeric identifier.

  ATTUSR

  User-defined accounting token.

  ATTUNK

  Unknown accounting-token type.

  The accounting-token type is set to an explicit value only in the following environments: AIX , HP-UX, IBM i, Solaris, Windows, plus IBM MQ MQI clients connected to these systems. In other environments, the accounting-token type is set to the value ATTUNK. In these environments the MDPAT field can be used to deduce the type of accounting token received.

• All other bytes are set to binary zero.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETI or PMSETA is specified in the PMO parameter. If neither PMSETI nor PMSETA is specified, this field is ignored on input and is an output-only field. For more information on message context, see Message context and Controlling context information.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the MDACC that was transmitted with the message if it was put to a queue. This will be the value of MDACC that is kept with the message if it is retained (see description of PMRET in MQPMO (Put-message options) on IBM i for more details about retained publications) but is not used as the MDACC when the message is sent as a publication to subscribers since they provide a value to override MDACC in all publications sent to them. If the message has no context, the field is entirely binary zero.

This is an output field for the MQGET call.

This field is not subject to any translation based on the character set of the queue manager-the field is treated as a string of bits, and not as a string of characters.

The queue manager does nothing with the information in this field. The application must interpret the information if it wants to use the information for accounting purposes.

The following special value may be used for the MDACC field:

ACNONE

No accounting token is specified.

The value is binary zero for the length of the field.

The length of this field is given by LNACCT. The initial value of this field is ACNONE.

MDAID (32-byte character string)

Application data relating to identity.

This is part of the identity context of the message. For more information about message context, see Message context and Controlling context information.

MDAID is information that is defined by the application suite, and can be used to provide additional information about the message or its originator. The queue manager treats this information as character data, but does not define the format of it. When the queue manager generates this information, it is entirely blank.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETI or PMSETA is specified in the PMO parameter. If a null character is present, the null and any following characters are converted to blanks by the queue manager. If neither PMSETI nor PMSETA is specified, this field is ignored on input and is an output-only field. For more information on message context, see Message context and Controlling context information.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the MDAID that was transmitted with the message if it was put to a queue. This will be the value of MDAID that is kept with the message if it is retained (see description of PMRET for more details about retained publications) but is not used as the MDAID when the message is sent as a publication to subscribers since they provide a value to override MDAID in all publications sent to them. If the message has no context, the field is entirely blank.

This is an output field for the MQGET call. The length of this field is given by LNAIDD. The initial value of this field is 32 blank characters.

MDAOD (4-byte character string)

Application data relating to origin.

This is part of the origin context of the message. For more information about message context, see Message context and Controlling context information.

MDAOD is information that is defined by the application suite that can be used to provide additional information about the origin of the message. For example, it could be set by applications running with suitable user authority to indicate whether the identity data is trusted.

The queue manager treats this information as character data, but does not define the format of it. When the queue manager generates this information, it is entirely blank.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETA is specified in the PMO parameter. Any information following a null character within the field is discarded. The null character and any following characters are converted to blanks by the queue manager. If PMSETA is not specified, this field is ignored on input and is an output-only field.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the MDAOD that was transmitted with the message if it was put to a queue. This will be the value of MDAOD that is kept with the message if it is retained (see description of PMRET for more details about retained publications) but is not used as the MDAOD when the message is sent as a publication to subscribers since they provide a value to override MDAOD in all publications sent to them. If the message has no context, the field is entirely blank.

This is an output field for the MQGET call. The length of this field is given by LNAORD. The initial value of this field is 4 blank characters.

MDBOC (10-digit signed integer)

Backout counter.

This is a count of the number of times the message has been previously returned by the MQGET call as part of a unit of work, and subsequently backed out. It is provided as an aid to the application in detecting processing errors that are based on message content. The count excludes MQGET calls that specified any of the GMBRW* options.

The accuracy of this count is affected by the HardenGetBackout queue attribute; see Attributes for queues.

This is an output field for the MQGET call. It is ignored for the MQPUT and MQPUT1 calls. The initial value of this field is 0.

MDCID (24-byte bit string)

Correlation identifier.

This is a byte string that the application can use to relate one message to another, or to relate the message to other work that the application is performing. The correlation identifier is a permanent property of the message, and persists across restarts of the queue manager. Because the correlation identifier is a byte string and not a character string, the correlation identifier is not converted between character sets when the message flows from one queue manager to another.

For the MQPUT and MQPUT1 calls, the application can specify any value. The queue manager transmits this value with the message and delivers it to the application that issues the get request for the message.

If the application specifies PMNCID, the queue manager generates a unique correlation identifier which is sent with the message, and also returned to the sending application on output from the MQPUT or MQPUT1 call.

This generated correlation identifier is kept with the message if it is retained and is used as the correlation identifier when the message is sent as a publication to subscribers who specify CINONE in the SDCID field in the MQSD passed on the MQSUB call.

See MQPMO (Put-message options) on IBM i for more details about retained publications

When the queue manager or a message channel agent generates a report message, it sets the MDCID field in the way specified by the MDREP field of the original message, either ROCMTC or ROPCI. Applications which generate report messages should also do this.

For the MQGET call, MDCID is one of the five fields that can be used to select a particular message to be retrieved from the queue. See the description of the MDMID field for details of how to specify values for this field.

Specifying CINONE as the correlation identifier has the same effect as not specifying MOCORI, that is, any correlation identifier will match.

If the GMMUC option is specified in the GMO parameter on the MQGET call, this field is ignored.

On return from an MQGET call, the MDCID field is set to the correlation identifier of the message returned (if any).

The following special values may be used:

CINONE

No correlation identifier is specified.

The value is binary zero for the length of the field.

CINEWS

Message is the start of a new session.

This value is recognized by the CICS bridge as indicating the start of a new session, that is, the start of a new sequence of messages.

For the MQGET call, this is an input/output field. For the MQPUT and MQPUT1 calls, this is an input field if PMNCID is not specified, and an output field if PMNCID is specified. The length of this field is given by LNCID. The initial value of this field is CINONE.

MDCSI (10-digit signed integer)

This specifies the character set identifier of character data in the message.

Note: Character data in MQMD and the other IBM MQ data structures that are parameters on calls must be in the character set of the queue manager. This is defined by the queue manager's CodedCharSetId attribute; see Attributes for the queue manager on IBM i for details of this attribute. The following special values can be used:

CSQM

Queue manager's character set identifier.

Character data in the message is in the queue manager's character set.

On the MQPUT and MQPUT1 calls, the queue manager changes this value in the MQMD sent with the message to the true character-set identifier of the queue manager. As a result, the value CSQM is never returned by the MQGET call.

CSINHT

Inherit character-set identifier of this structure.

Character data in the message is in the same character set as this structure; this is the queue manager's character set. (For MQMD only, CSINHT has the same meaning as CSQM).

The queue manager changes this value in the MQMD sent with the message to the actual character-set identifier of MQMD. Provided no error occurs, the value CSINHT is not returned by the MQGET call.

CSINHT cannot be used if the value of the MDPAT field in MQMD is ATBRKR.

CSEMBD

Embedded character set identifier.

Character data in the message is in a character set with the identifier that is contained within the message data itself. There can be any number of character-set identifiers embedded within the message data, applying to different parts of the data. This value must be used for PCF messages that contain data in a mixture of character sets. PCF messages have a format name of FMPCF.

Specify this value only on the MQPUT and MQPUT1 calls. If it is specified on the MQGET call, it prevents conversion of the message.

On the MQPUT and MQPUT1 calls, the queue manager changes the values CSQM and CSINHT in the MQMD sent with the message as described previously, but does not change the MQMD specified on the MQPUT or MQPUT1 call. No other check is carried out on the value specified.

Applications that retrieve messages should compare this field against the value the application is expecting; if the values differ, the application may need to convert character data in the message.

If the GMCONV option is specified on the MQGET call, this field is an input/output field. The value specified by the application is the coded character-set identifier to which the message data should be converted if necessary. If conversion is successful or unnecessary, the value is unchanged (except that the value CSQM or CSINHT is converted to the actual value). If conversion is unsuccessful, the value after the MQGET call represents the coded character-set identifier of the unconverted message that is returned to the application.

Otherwise, this is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is CSQM.

MDENC (10-digit signed integer)

Numeric encoding of message data.

This specifies the numeric encoding of numeric data in the message; it does not apply to numeric data in the MQMD structure itself. The numeric encoding defines the representation used for binary integers, packed-decimal integers, and floating-point numbers.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The queue manager does not check that the field is valid. The following special value is defined:

ENNAT

Native machine encoding.

The encoding is the default for the programming language and machine on which the application is running.

Note: The value of this constant depends on the programming language and environment. For this reason, applications must be compiled using the header, macro, COPY, or INCLUDE files appropriate to the environment in which the application will run.

Applications that put messages should normally specify ENNAT. Applications that retrieve messages should compare this field against the value ENNAT; if the values differ, the application may need to convert numeric data in the message. The GMCONV option can be used to request the queue manager to convert the message as part of the processing of the MQGET call.

If the GMCONV option is specified on the MQGET call, this field is an input/output field. The value specified by the application is the encoding to which the message data should be converted if necessary. If conversion is successful or unnecessary, the value is unchanged. If conversion is unsuccessful, the value after the MQGET call represents the encoding of the unconverted message that is returned to the application.

In other cases, this is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is ENNAT.

MDEXP (10-digit signed integer)

Message lifetime.

This is a period of time expressed in tenths of a second, set by the application that puts the message. The message becomes eligible to be discarded if it has not been removed from the destination queue before this period of time elapses.

The value is decremented to reflect the time the message spends on the destination queue, and also on any intermediate transmission queues if the put is to a remote queue. It may also be decremented by message channel agents to reflect transmission times, if these are significant. Likewise, an application forwarding this message to another queue might decrement the value if necessary, if it has retained the message for a significant time. However, the expiration time is treated as approximate, and the value need not be decremented to reflect small time intervals.

When the message is retrieved by an application using the MQGET call, the MDEXP field represents the amount of the original expiry time that still remains.

After a message's expiry time has elapsed, it becomes eligible to be discarded by the queue manager. In the current implementations, the message is discarded when a browse or nonbrowse MQGET call occurs that would have returned the message had it not already expired. For example, a nonbrowse MQGET call with the GMMO field in MQGMO set to MONONE reading from a FIFO ordered queue will cause all the expired messages to be discarded up to the first unexpired message. With a priority ordered queue, the same call will discard expired messages of higher priority and messages of an equal priority that arrived on the queue before the first unexpired message.

A message that has expired is never returned to an application (either by a browse or a non-browse MQGET call), so the value in the MDEXP field of the message descriptor after a successful MQGET call is either greater than zero, or the special value EIULIM.

If a message is put on a remote queue, the message may expire (and be discarded) while it is on an intermediate transmission queue, before the message reaches the destination queue.

A report is generated when an expired message is discarded, if the message specified one of the ROEXP* report options. If none of these options is specified, no such report is generated; the message is assumed to be no longer relevant after this time period (perhaps because a later message has superseded it).

Any other program that discards messages based on expiry time must also send an appropriate report message if one was requested. Note:

1. If a message is put with an MDEXP time of zero, the MQPUT or MQPUT1 call fails with reason code RC2013; no report message is generated in this case.
2. Since a message with an expiry time that has elapsed may not actually be discarded until later, there may be messages on a queue that have passed their expiry time, and which are not therefore eligible for retrieval. These messages nevertheless count towards the number of messages on the queue for all purposes, including depth triggering.
3. An expiration report is generated, if requested, when the message is actually discarded, not when it becomes eligible for discarding.
4. Discarding of an expired message, and the generation of an expiration report if requested, are never part of the application's unit of work, even if the message was scheduled for discarding as a result of an MQGET call operating within a unit of work.
5. If a nearly-expired message is retrieved by an MQGET call within a unit of work, and the unit of work is subsequently backed out, the message may become eligible to be discarded before it can be retrieved again.
6. If a nearly-expired message is locked by an MQGET call with GMLK, the message may become eligible to be discarded before it can be retrieved by an MQGET call with GMMUC; reason code RC2034 is returned on this subsequent MQGET call if that happens.
7. When a request message with an expiry time greater than zero is retrieved, the application can take one of the following actions when it sends the reply message:
   • Copy the remaining expiry time from the request message to the reply message.
   • Set the expiry time in the reply message to an explicit value greater than zero.
   • Set the expiry time in the reply message to EIULIM.
   The action to take depends on the design of the application suite. However, the default action for putting messages to a dead-letter (undelivered-message) queue should be to preserve the remaining expiry time of the message, and to continue to decrement it.
8. Trigger messages are always generated with EIULIM.
9. A message (normally on a transmission queue) which has a MDFMT name of FMXQH has a second message descriptor within the MQXQH. It therefore has two MDEXP fields associated with it. The following additional points should be noted in this case:
   • When an application puts a message on a remote queue, the queue manager places the message initially on a local transmission queue, and prefixes the application message data with an MQXQH structure. The queue manager sets the values of the two MDEXP fields to be the same as that specified by the application.

     If an application puts a message directly on a local transmission queue, the message data must already begin with an MQXQH structure, and the format name must be FMXQH (but the queue manager does not enforce this). In this case the application need not set the values of these two MDEXP fields to be the same. (The queue manager does not check that the MDEXP field within the MQXQH contains a valid value, or even that the message data is long enough to include it.)

   • When a message with a MDFMT name of FMXQH is retrieved from a queue (whether this is a normal or a transmission queue), the queue manager decrements both these MDEXP fields with the time spent waiting on the queue. No error is raised if the message data is not long enough to include the MDEXP field in the MQXQH.
   • The queue manager uses the MDEXP field in the separate message descriptor (that is, not the one in the message descriptor embedded within the MQXQH structure) to test whether the message is eligible for discarding.
   • If the initial values of the two MDEXP fields were different, it is therefore possible for the MDEXP time in the separate message descriptor when the message is retrieved to be greater than zero (so the message is not eligible for discarding), while the time according to the MDEXP field in the MQXQH has elapsed. In this case the MDEXP field in the MQXQH is set to zero.

The following special value is recognized:

EIULIM

Unlimited lifetime.

The message has an unlimited expiration time.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is EIULIM.

MDFB (10-digit signed integer)

Feedback or reason code.

This is used with a message of type MTRPRT to indicate the nature of the report, and is only meaningful with that type of message. The field can contain one of the FB* values, or one of the RC* values. Feedback codes are grouped as follows:

FBNONE

No feedback provided.

FBSFST

Lowest value for system-generated feedback.

FBSLST

Highest value for system-generated feedback.

The range of system-generated feedback codes FBSFST through FBSLST includes the general feedback codes listed later in this section(FB*), and also the reason codes (RC*) that can occur when the message cannot be put on the destination queue.

FBAFST

Lowest value for application-generated feedback.

FBALST

Highest value for application-generated feedback.

Applications that generate report messages should not use feedback codes in the system range (other than FBQUIT), unless they want to simulate report messages generated by the queue manager or message channel agent.

On the MQPUT or MQPUT1 calls, the value specified must either be FBNONE, or be within the system range or application range. This is checked whatever the value of MDMT.

General feedback codes:

FBCOA

Confirmation of arrival on the destination queue (see ROCOA).

FBCOD

Confirmation of delivery to the receiving application (see ROCOD).

FBEXP

Message expired.

Message was discarded because it had not been removed from the destination queue before its expiry time had elapsed.

FBPAN

Positive action notification (see ROPAN).

FBNAN

Negative action notification (see RONAN).

FBQUIT

Application should end.

This can be used by a workload scheduling program to control the number of instances of an application program that are running. Sending an MTRPRT message with this feedback code to an instance of the application program indicates to that instance that it should stop processing. However, adherence to this convention is a matter for the application; it is not enforced by the queue manager.

IMS-bridge feedback codes: When the IMS bridge receives a nonzero IMS-OTMA sense code, the IMS bridge converts the sense code from hexadecimal to decimal, adds the value FBIERR (300), and places the result in the MDFB field of the reply message. This results in the feedback code having a value in the range FBIFST (301) through FBILST (399) when an IMS-OTMA error has occurred.

The following feedback codes can be generated by the IMS bridge:

FBDLZ

Data length zero.

A segment length was zero in the application data of the message.

FBDLN

Data length negative.

A segment length was negative in the application data of the message.

FBDLTB

Data length too big.

A segment length was too big in the application data of the message.

FBBUFO

Buffer overflow.

The value of one of the length fields would cause the data to overflow the message buffer.

FBLOB1

Length in error by one.

The value of one of the length fields was one byte too short.

FBIIH

MQIIH structure not valid or missing.

The MDFMT field in MQMD specifies FMIMS, but the message does not begin with a valid MQIIH structure.

FBNAFI

User ID not authorized for use in IMS.

The user ID contained in the message descriptor MQMD, or the password contained in the IIAUT field in the MQIIH structure, failed the validation performed by the IMS bridge. As a result the message was not passed to IMS.

FBIERR

Unexpected error returned by IMS.

An unexpected error was returned by IMS. Consult the IBM MQ error log on the system on which the IMS bridge resides for more information about the error.

FBIFST

Lowest value for IMS-generated feedback.

IMS-generated feedback codes occupy the range FBIFST (300) through FBILST (399). The IMS-OTMA sense code itself is MDFB minus FBIERR.

FBILST

Highest value for IMS-generated feedback.

CICS-bridge feedback codes: The following feedback codes can be generated by the CICS bridge:

FBCAAB

Application abended.

The application program specified in the message abended. This feedback code occurs only in the DLREA field of the MQDLH structure.

FBCANS

Application cannot be started.

The EXEC CICS LINK for the application program specified in the message failed. This feedback code occurs only in the DLREA field of the MQDLH structure.

FBCBRF

CICS bridge terminated abnormally without completing normal error processing.

FBCCSE

Character set identifier not valid.

FBCIHE

CICS information header structure missing or not valid.

FBCCAE

Length of CICS commarea not valid.

FBCCIE

Correlation identifier not valid.

FBCDLQ

Dead-letter queue not available.

The CICS bridge task was unable to copy a reply to this request to the dead-letter queue. The request was backed out.

FBCENE

Encoding not valid.

FBCINE

CICS bridge encountered an unexpected error.

This feedback code occurs only in the DLREA field of the MQDLH structure.

FBCNTA

User identifier not authorized or password not valid.

This feedback code occurs only in the DLREA field of the MQDLH structure.

FBCUBO

Unit of work backed out. The unit of work was backed out, for one of the following reasons:

• A failure was detected while processing another request within the same unit of work.
• A CICS abend occurred while the unit of work was in progress.

FBCUWE

Unit-of-work control field CIUOW not valid.

MQ reason codes: For exception report messages, MDFB contains an MQ reason code. Among possible reason codes are:

RC2051

(2051, X'803') Put calls inhibited for the queue.

RC2053

(2053, X'805') Queue already contains maximum number of messages.

RC2035

(2035, X'7F3') Not authorized for access.

RC2056

(2056, X'808') No space available on disk for queue.

RC2048

(2048, X'800') Queue does not support persistent messages.

RC2031

(2031, X'7EF') Message length greater than maximum for queue manager.

RC2030

(2030, X'7EE') Message length greater than maximum for queue.

This is an output field for the MQGET call, and an input field for MQPUT and MQPUT1 calls. The initial value of this field is FBNONE.

MDFMT (8-byte character string)

Format name of message data.

This is a name that the sender of the message may use to indicate to the receiver the nature of the data in the message. Any characters that are in the queue manager's character set may be specified for the name, but it is recommended that the name be restricted to the following:

• Uppercase A through Z
• Numeric digits 0 through 9

If other characters are used, it may not be possible to translate the name between the character sets of the sending and receiving queue managers.

The name should be padded with blanks to the length of the field, or a null character used to terminate the name before the end of the field; the null and any subsequent characters are treated as blanks. Do not specify a name with leading or embedded blanks. For the MQGET call, the queue manager returns the name padded with blanks to the length of the field.

The queue manager does not check that the name complies with the recommendations described previously.

Names beginning "MQ" in upper, lower, and mixed case have meanings that are defined by the queue manager; you should not use names beginning with these letters for your own formats. The queue manager built-in formats are:

FMNONE

No format name.

The nature of the data is undefined. This means that the data cannot be converted when the message is retrieved from a queue using the GMCONV option.

If GMCONV is specified on the MQGET call, and the character set or encoding of data in the message differs from that specified in the MSGDSC parameter, the message is returned with the following completion and reason codes (assuming no other errors):

• Completion code CCWARN and reason code RC2110 if the FMNONE data is at the beginning of the message.
• Completion code CCOK and reason code RCNONE if the FMNONE data is at the end of the message (that is, preceded by one or more MQ header structures). The MQ header structures are converted to the requested character set and encoding in this case.

FMADMN

Command server request/reply message.

The message is a command-server request or reply message in programmable command format (PCF). Messages of this format can be converted if the GMCONV option is specified on the MQGET call. For more information about using programmable command format messages, see Use Programmable Command Formats.

FMCICS

CICS information header.

The message data begins with the CICS information header MQCIH, which is followed by the application data. The format name of the application data is given by the CIFMT field in the MQCIH structure.

FMCMD1

Type 1 command reply message.

The message is an MQSC command-server reply message containing the object count, completion code, and reason code. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMCMD2

Type 2 command reply message.

The message is an MQSC command-server reply message containing information about the object(s) requested. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMDLH

Dead-letter header.

The message data begins with the dead-letter header MQDLH. The data from the original message immediately follows the MQDLH structure. The format name of the original message data is given by the DLFMT field in the MQDLH structure; see MQDLH (Dead-letter header) on IBM i for details of this structure. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

COA and COD reports are not generated for messages which have a MDFMT of FMDLH.

FMDH

Distribution-list header.

The message data begins with the distribution-list header MQDH; this includes the arrays of MQOR and MQPMR records. The distribution-list header may be followed by additional data. The format of the additional data (if any) is given by the DHFMT field in the MQDH structure; see MQDH (Distribution header) on IBM i for details of this structure. Messages with format FMDH can be converted if the GMCONV option is specified on the MQGET call.

FMEVNT

Event message.

The message is an MQ event message that reports an event that occurred. Event messages have the same structure as programmable commands; for more information about this structure, see Structures for commands and responses. For information about events, see Event monitoring.

Version-1 event messages can be converted if the GMCONV option is specified on the MQGET call.

FMIMS

IMS information header.

The message data begins with the IMS information header MQIIH, which is followed by the application data. The format name of the application data is given by the IIFMT field in the MQIIH structure. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMIMVS

IMS variable string. The message is an IMS variable string, which is a string of the form llzzccc, where:

ll

is a 2-byte length field specifying the total length of the IMS variable string item. This length is equal to the length of ll (2 bytes), plus the length of zz (2 bytes), plus the length of the character string itself. ll is a 2-byte binary integer in the encoding specified by the MDENC field.

zz

is a 2-byte field containing flags that are significant to IMS. zz is a byte string consisting of two 1-byte bit string fields, and is transmitted without change from sender to receiver (that is, zz is not subject to any conversion).

ccc

is a variable-length character string containing ll-4 characters. ccc is in the character set specified by the MDCSI field.

Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMMDE

Message-descriptor extension.

The message data begins with the message-descriptor extension MQMDE, and is optionally followed by other data (usually the application message data). The format name, character set, and encoding of the data which follows the MQMDE is given by the MEFMT, MECSI, and MEENC fields in the MQMDE. See MQMDE (Message descriptor extension) on IBM i for details of this structure. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMPCF

User-defined message in programmable command format (PCF).

The message is a user-defined message that conforms to the structure of a programmable command format (PCF) message. Messages of this format can be converted if the GMCONV option is specified on the MQGET call. See Use Programmable Command Formats for more information about using programmable command format messages.

FMRMH

Reference message header.

The message data begins with the reference message header MQRMH, and is optionally followed by other data. The format name, character set, and encoding of the data is given by the RMFMT, RMCSI, and RMENC fields in the MQRMH. See MQRMH (Reference message header) on IBM i for details of this structure. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMRFH

Rules and formatting header.

The message data begins with the rules and formatting header MQRFH, and is optionally followed by other data. The format name, character set, and encoding of the data (if any) is given by the RFFMT, RFCSI, and RFENC fields in the MQRFH. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMRFH2

Rules and formatting header version 2.

The message data begins with the version-2 rules and formatting header MQRFH2, and is optionally followed by other data. The format name, character set, and encoding of the optional data (if any) is given by the RF2FMT, RF2CSI, and RF2ENC fields in the MQRFH2. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMSTR

Message consisting entirely of characters.

The application message data can be either an SBCS string (single-byte character set), or a DBCS string (double-byte character set). Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMTM

Trigger message.

The message is a trigger message, described by the MQTM structure; see MQTM - Trigger message for details of this structure. Messages of this format can be converted if the GMCONV option is specified on the MQGET call.

FMWIH

Work information header.

The message data begins with the work information header MQWIH, which is followed by the application data. The format name of the application data is given by the WIFMT field in the MQWIH structure.

FMXQH

Transmission queue header.

The message data begins with the transmission queue header MQXQH. The data from the original message immediately follows the MQXQH structure. The format name of the original message data is given by the MDFMT field in the MQMD structure which is part of the transmission queue header MQXQH. See MQXQH (Transmission-queue header) on IBM i for details of this structure.

COA and COD reports are not generated for messages which have a MDFMT of FMXQH.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The length of this field is given by LNFMT. The initial value of this field is FMNONE.

MDGID (24-byte bit string)

Group identifier.

This is a byte string that is used to identify the particular message group or logical message to which the physical message belongs. MDGID is also used if segmentation is allowed for the message. In all of these cases, MDGID has a non-null value, and one or more of the following flags is set in the MDMFL field:

• MFMIG
• MFLMIG
• MFSEG
• MFLSEG
• MFSEGA

If none of these flags is set, MDGID has the special null value GINONE. This field need not be set by the application on the MQPUT or MQGET call if:

• On the MQPUT call, PMLOGO is specified.
• On the MQGET call, MOGRPI is not specified.

Consider using these calls for messages that are not report messages. However, if the application requires more control, or the call is MQPUT1, the application must ensure that MDGID is set to an appropriate value. Message groups and segments can be processed correctly only if the group identifier is unique. For this reason, applications should not generate their own group identifiers ; instead, applications should do one of the following:

• If PMLOGO is specified, the queue manager automatically generates a unique group identifier for the first message in the group or segment of the logical message, and uses that group identifier for the remaining messages in the group or segments of the logical message, so the application does not need to take any special action. Consider using this procedure.
• If PMLOGO is not specified, the application should request the queue manager to generate the group identifier, by setting MDGID to GINONE on the first MQPUT or MQPUT1 call for a message in the group or segment of the logical message. The group identifier returned by the queue manager on output from that call should then be used for the remaining messages in the group or segments of the logical message. If a message group contains segmented messages, the same group identifier must be used for all segments and messages in the group.

  When PMLOGO is not specified, messages in groups and segments of logical messages can be put in any order (for example, in reverse order), but the group identifier must be allocated by the first MQPUT or MQPUT1 call that is issued for any of those messages.

On input to the MQPUT and MQPUT1 calls, the queue manager uses the value detailed in PMOPT. On output from the MQPUT and MQPUT1 calls, the queue manager sets this field to the value that was sent with the message if the object opened is a single queue and not a distribution list, but leaves it unchanged if the object opened is a distribution list. In the latter case, if the application needs to know the group identifiers generated, the application must provide MQPMR records containing the PRGID field.

On input to the MQGET call, the queue manager uses the value detailed in Table 1. On output from the MQGET call, the queue manager sets this field to the value for the message retrieved.

The following special value is defined:

GINONE

No group identifier specified.

The value is binary zero for the length of the field. This is the value that is used for messages that are not in groups, not segments of logical messages, and for which segmentation is not allowed.

The length of this field is given by LNGID. The initial value of this field is GINONE. This field is ignored if MDVER is less than MDVER2.

MDMFL (10-digit signed integer)

Message flags.

These are flags that specify attributes of the message, or control its processing. The flags are divided into the following categories:

• Segmentation flag
• Status flags

These are described in turn.

Segmentation flags: When a message is too big for a queue, an attempt to put the message on the queue usually fails. Segmentation is a technique whereby the queue manager or application splits the message into smaller pieces called segments, and places each segment on the queue as a separate physical message. The application which retrieves the message can either retrieve the segments one by one, or request the queue manager to reassemble the segments into a single message which is returned by the MQGET call. The latter is achieved by specifying the GMCMPM option on the MQGET call, and supplying a buffer that is big enough to accommodate the complete message. (See MQGMO (Get-message options) on IBM i for details of the GMCMPM option.) Segmentation of a message can occur at the sending queue manager, at an intermediate queue manager, or at the destination queue manager.

We can specify one of the following to control the segmentation of a message:

MFSEGI

Segmentation inhibited.

This option prevents the message being broken into segments by the queue manager. If specified for a message that is already a segment, this option prevents the segment being broken into smaller segments.

The value of this flag is binary zero. This is the default.

MFSEGA

Segmentation allowed.

This option allows the message to be broken into segments by the queue manager. If specified for a message that is already a segment, this option allows the segment to be broken into smaller segments. MFSEGA can be set without either MFSEG or MFLSEG being set.

When the queue manager segments a message, the queue manager turns on the MFSEG flag in the copy of the MQMD that is sent with each segment, but does not alter the settings of these flags in the MQMD provided by the application on the MQPUT or MQPUT1 call. For the last segment in the logical message, the queue manager also turns on the MFLSEG flag in the MQMD that is sent with the segment.

Note: Care is needed when messages are put with MFSEGA but without PMLOGO. If the message is:

• Not a segment, and
• Not in a group, and
• Not being forwarded,

the application must remember to reset the MDGID field to GINONE before each MQPUT or MQPUT1 call, in order to cause a unique group identifier to be generated by the queue manager for each message. If this is not done, unrelated messages could inadvertently end up with the same group identifier, which might lead to incorrect processing subsequently. See the descriptions of the MDGID field and the PMLOGO option for more information about when the MDGID field must be reset. The queue manager splits messages into segments as necessary in order to ensure that the segments (plus any header data that may be required) fit on the queue. However, there is a lower limit for the size of a segment generated by the queue manager, and only the last segment created from a message can be smaller than this limit. (The lower limit for the size of an application-generated segment is one byte.) Segments generated by the queue manager may be of unequal length. The queue manager processes the message as follows:

• User-defined formats are split on boundaries which are multiples of 16 bytes. This means that the queue manager will not generate segments that are smaller than 16 bytes (other than the last segment).
• Built-in formats other than FMSTR are split at points appropriate to the nature of the data present. However, the queue manager never splits a message in the middle of an MQ header structure. This means that a segment containing a single MQ header structure cannot be split further by the queue manager, and as a result the minimum possible segment size for that message is greater than 16 bytes. The second or later segment generated by the queue manager will begin with one of the following:
  • An MQ header structure
  • The start of the application message data
  • Part-way through the application message data
• FMSTR is split without regard for the nature of the data present (SBCS, DBCS, or mixed SBCS/DBCS). When the string is DBCS or mixed SBCS/DBCS, this may result in segments which cannot be converted from one character set to another. The queue manager never splits FMSTR messages into segments that are smaller than 16 bytes (other than the last segment).
• The MDFMT, MDCSI, and MDENC fields in the MQMD of each segment are set by the queue manager to describe correctly the data present at the start of the segment; the format name will be either the name of a built-in format, or the name of a user-defined format.
• The MDREP field in the MQMD of segments with MDOFF greater than zero are modified as follows:
  • For each report type, if the report option is RO*D, but the segment cannot possibly contain any of the first 100 bytes of user data (that is, the data following any MQ header structures that may be present), the report option is changed to RO*.

The queue manager follows the previously rules, but otherwise splits messages unpredictably; do not make assumptions about where a message is split For persistent messages, the queue manager can perform segmentation only within a unit of work:

• If the MQPUT or MQPUT1 call is operating within a user-defined unit of work, that unit of work is used. If the call fails partway through the segmentation process, the queue manager removes any segments that were placed on the queue as a result of the failing call. However, the failure does not prevent the unit of work being committed successfully.
• If the call is operating outside a user-defined unit of work, and there is no user-defined unit of work in existence, the queue manager creates a unit of work just for the duration of the call. If the call is successful, the queue manager commits the unit of work automatically (the application does not need to do this). If the call fails, the queue manager backs out the unit of work.
• If the call is operating outside a user-defined unit of work, but a user-defined unit of work does exist, the queue manager is unable to perform segmentation. If the message does not require segmentation, the call can still succeed. But if the message does require segmentation, the call fails with reason code RC2255.

For nonpersistent messages, the queue manager does not require a unit of work to be available in order to perform segmentation.

Special consideration must be given to data conversion of messages which may be segmented:

• If data conversion is performed only by the receiving application on the MQGET call, and the application specifies the GMCMPM option, the data-conversion exit will be passed the complete message for the exit to convert, and the fact that the message was segmented will not be apparent to the exit.
• If the receiving application retrieves one segment at a time, the data-conversion exit will be invoked to convert one segment at a time. The exit must therefore be capable of converting the data in a segment independently of the data in any of the other segments.

  If the nature of the data in the message is such that arbitrary segmentation of the data on 16-byte boundaries may result in segments which cannot be converted by the exit, or the format is FMSTR and the character set is DBCS or mixed SBCS/DBCS, the sending application should itself create and put the segments, specifying MFSEGI to suppress further segmentation. In this way, the sending application can ensure that each segment contains sufficient information to allow the data-conversion exit to convert the segment successfully.

• If sender conversion is specified for a sending message channel agent (MCA), the MCA converts only messages which are not segments of logical messages; the MCA never attempts to convert messages which are segments.

This flag is an input flag on the MQPUT and MQPUT1 calls, and an output flag on the MQGET call. On the latter call, the queue manager also echoes the value of the flag to the GMSEG field in MQGMO.

The initial value of this flag is MFSEGI.

Status flags: These are flags that indicate whether the physical message belongs to a message group, is a segment of a logical message, both, or neither. One or more of the following can be specified on the MQPUT or MQPUT1 call, or returned by the MQGET call:

MFMIG

Message is a member of a group.

MFLMIG

Message is the last logical message in a group.

If this flag is set, the queue manager turns on MFMIG in the copy of MQMD that is sent with the message, but does not alter the settings of these flags in the MQMD provided by the application on the MQPUT or MQPUT1 call.

It is valid for a group to consist of only one logical message. If this is the case, MFLMIG is set, but the MDSEQ field has the value one.

MFSEG

Message is a segment of a logical message.

When MFSEG is specified without MFLSEG, the length of the application message data in the segment ( excluding the lengths of any MQ header structures that may be present) must be at least one. If the length is zero, the MQPUT or MQPUT1 call fails with reason code RC2253.

MFLSEG

Message is the last segment of a logical message.

If this flag is set, the queue manager turns on MFSEG in the copy of MQMD that is sent with the message, but does not alter the settings of these flags in the MQMD provided by the application on the MQPUT or MQPUT1 call.

It is valid for a logical message to consist of only one segment. If this is the case, MFLSEG is set, but the MDOFF field has the value zero.

When MFLSEG is specified, it is permissible for the length of the application message data in the segment ( excluding the lengths of any header structures that may be present) to be zero.

The application must ensure that these flags are set correctly when putting messages. If PMLOGO is specified, or was specified on the preceding MQPUT call for the queue handle, the settings of the flags must be consistent with the group and segment information retained by the queue manager for the queue handle. The following conditions apply to successive MQPUT calls for the queue handle when PMLOGO is specified:

• If there is no current group or logical message, all of these flags (and combinations of them) are valid.
• Once MFMIG has been specified, it must remain on until MFLMIG is specified. The call fails with reason code RC2241 if this condition is not satisfied.
• Once MFSEG has been specified, it must remain on until MFLSEG is specified. The call fails with reason code RC2242 if this condition is not satisfied.
• Once MFSEG has been specified without MFMIG, MFMIG must remain off until after MFLSEG has been specified. The call fails with reason code RC2242 if this condition is not satisfied.

Table 1 shows the valid combinations of the flags, and the values used for various fields.

These flags are input flags on the MQPUT and MQPUT1 calls, and output flags on the MQGET call. On the latter call, the queue manager also echoes the values of the flags to the GMGST and GMSST fields in MQGMO.

Default flags: The following can be specified to indicate that the message has default attributes:

MFNONE

No message flags (default message attributes).

This inhibits segmentation, and indicates that the message is not in a group and is not a segment of a logical message. MFNONE is defined to aid program documentation. It is not intended that this flag be used with any other, but as its value is zero, such use cannot be detected.

The MDMFL field is partitioned into subfields; for details see Report options and message flags on IBM i.

The initial value of this field is MFNONE. This field is ignored if MDVER is less than MDVER2.

MDMID (24-byte bit string)

Message identifier.

This is a byte string that is used to distinguish one message from another. Generally, no two messages should have the same message identifier, although this is not disallowed by the queue manager. The message identifier is a permanent property of the message, and persists across restarts of the queue manager. Because the message identifier is a byte string and not a character string, the message identifier is not converted between character sets when the message flows from one queue manager to another.

For the MQPUT and MQPUT1 calls, if MINONE or PMNMID is specified by the application, the queue manager generates a unique message identifier ¹ when the message is put, and places it in the message descriptor sent with the message. The queue manager also returns this message identifier in the message descriptor belonging to the sending application. The application can use this value to record information about particular messages, and to respond to queries from other parts of the application.

If the message is being put to a topic, the queue manager generates unique message identifiers as necessary for each message published. If PMNMID is specified by the application, the queue manager generates a unique message identifier to return on output. If MINONE is specified by the application, the value of the MDMID field in the MQMD is unchanged on return from the call.

See the description of PMRET in PMOPT for more details about retained publications.

If the message is being put to a distribution list, the queue manager generates unique message identifiers as necessary, but the value of the MDMID field in MQMD is unchanged on return from the call, even if MINONE or PMNMID was specified. If the application needs to know the message identifiers generated by the queue manager, the application must provide MQPMR records containing the PRMID field.

The sending application can also specify a particular value for the message identifier, other than MINONE; this stops the queue manager generating a unique message identifier. An application that is forwarding a message can use this facility to propagate the message identifier of the original message.

The queue manager does not itself make any use of this field except to:

• Generate a unique value if requested, as described previously
• Deliver the value to the application that issues the get request for the message
• Copy the value to the MDCID field of any report message that it generates about this message (depending on the MDREP options)

When the queue manager or a message channel agent generates a report message, it sets the MDMID field in the way specified by the MDREP field of the original message, either RONMI or ROPMI. Applications that generate report messages should also do this.

For the MQGET call, MDMID is one of the five fields that can be used to select a particular message to be retrieved from the queue. Normally the MQGET call returns the next message on the queue, but if a particular message is required, this can be obtained by specifying one or more of the five selection criteria, in any combination; these fields are:

• MDMID
• MDCID
• MDGID
• MDSEQ
• MDOFF

The application sets one or more of these field to the values required, and then sets the corresponding MO* match options in the GMMO field in MQGMO to indicate that those fields should be used as selection criteria. Only messages that have the specified values in those fields are candidates for retrieval. The default for the GMMO field (if not altered by the application) is to match both the message identifier and the correlation identifier.

Normally, the message returned is the first message on the queue that satisfies the selection criteria. But if GMBRWN is specified, the message returned is the next message that satisfies the selection criteria; the scan for this message starts with the message following the current cursor position.

Note: The queue is scanned sequentially for a message that satisfies the selection criteria, so retrieval times will be slower than if no selection criteria are specified, especially if many messages have to be scanned before a suitable one is found.

See Table 1 for more information about how selection criteria are used in various situations.

Specifying MINONE as the message identifier has the same effect as not specifying MOMSGI, that is, any message identifier will match.

This field is ignored if the GMMUC option is specified in the GMO parameter on the MQGET call.

On return from an MQGET call, the MDMID field is set to the message identifier of the message returned (if any).

The following special value may be used:

MINONE

No message identifier is specified.

The value is binary zero for the length of the field.

This is an input/output field for the MQGET, MQPUT, and MQPUT1 calls. The length of this field is given by LNMID. The initial value of this field is MINONE.

MDMT (10-digit signed integer)

Message type.

This indicates the type of the message. Message types are grouped as follows:

MTSFST

Lowest value for system-defined message types.

MTSLST

Highest value for system-defined message types.

The following values are currently defined within the system range:

MTDGRM

Message not requiring a reply.

The message is one that does not require a reply.

MTRQST

Message requiring a reply.

The message is one that requires a reply.

The name of the queue to which the reply should be sent must be specified in the MDRQ field. The MDREP field indicates how the MDMID and MDCID of the reply are to be set.

MTRPLY

Reply to an earlier request message.

The message is the reply to an earlier request message (MTRQST). The message should be sent to the queue indicated by the MDRQ field of the request message. The MDREP field of the request should be used to control how the MDMID and MDCID of the reply are set.

Note: The queue manager does not enforce the request-reply relationship; this is an application responsibility.

MTRPRT

Report message.

The message is reporting on some expected or unexpected occurrence, usually related to some other message (for example, a request message was received which contained data that was not valid). The message should be sent to the queue indicated by the MDRQ field of the message descriptor of the original message. The MDFB field should be set to indicate the nature of the report. The MDREP field of the original message can be used to control how the MDMID and MDCID of the report message should be set.

Report messages generated by the queue manager or message channel agent are always sent to the MDRQ queue, with the MDFB and MDCID fields set as described previously.

Other values within the system range may be defined in future versions of the MQI, and are accepted by the MQPUT and MQPUT1 calls without error.

Application-defined values can also be used. They must be within the following range:

MTAFST

Lowest value for application-defined message types.

MTALST

Highest value for application-defined message types.

For the MQPUT and MQPUT1 calls, the MDMT value must be within either the system-defined range or the application-defined range; if it is not, the call fails with reason code RC2029.

This is an output field for the MQGET call, and an input field for MQPUT and MQPUT1 calls. The initial value of this field is MTDGRM.

MDOFF (10-digit signed integer)

Offset of data in physical message from start of logical message.

This is the offset in bytes of the data in the physical message from the start of the logical message of which the data forms part. This data is called a segment. The offset is in the range 0 through 999 999 999. A physical message which is not a segment of a logical message has an offset of zero.

This field need not be set by the application on the MQPUT or MQGET call if:

• On the MQPUT call, PMLOGO is specified.
• On the MQGET call, MOOFFS is not specified.

These are the recommended ways of using these calls for messages that are not report messages. However, if the application does not comply with these conditions, or the call is MQPUT1, the application must ensure that MDOFF is set to an appropriate value. On input to the MQPUT and MQPUT1 calls, the queue manager uses the value detailed in Table 1. On output from the MQPUT and MQPUT1 calls, the queue manager sets this field to the value that was sent with the message.

For a report message reporting on a segment of a logical message, the MDOLN field (provided it is not OLUNDF) is used to update the offset in the segment information retained by the queue manager.

On input to the MQGET call, the queue manager uses the value detailed in Table 1. On output from the MQGET call, the queue manager sets this field to the value for the message retrieved.

The initial value of this field is zero. This field is ignored if MDVER is less than MDVER2.

MDOLN (10-digit signed integer)

Length of original message.

This field is of relevance only for report messages that are segments. It specifies the length of the message segment to which the report message relates; it does not specify the length of the logical message of which the segment forms part, nor the length of the data in the report message.

Note: When generating a report message for a message that is a segment, the queue manager and message channel agent copy into the MQMD for the report message the MDGID, MDSEQ, MDOFF, and MDMFL, fields from the original message. As a result, the report message is also a segment. Applications that generate report messages are recommended to do the same, and to ensure that the MDOLN field is set correctly. The following special value is defined:

OLUNDF

Original length of message not defined.

MDOLN is an input field on the MQPUT and MQPUT1 calls, but the value provided by the application is accepted only in particular circumstances:

• If the message being put is a segment and is also a report message, the queue manager accepts the value specified. The value must be:
  • Greater than zero if the segment is not the last segment
  • Not less than zero if the segment is the last segment
  • Not less than the length of data present in the message
  If these conditions are not satisfied, the call fails with reason code RC2252.
• If the message being put is a segment but not a report message, the queue manager ignores the field and uses the length of the application message data instead.
• In all other cases, the queue manager ignores the field and uses the value OLUNDF instead.

This is an output field on the MQGET call.

The initial value of this field is OLUNDF. This field is ignored if MDVER is less than MDVER2.

MDPAN (28-byte character string)

Name of application that put the message.

This is part of the origin context of the message. For more information about message context, see Message context and Controlling context information.

The format of the MDPAN depends on the value of MDPAT.

When this field is set by the queue manager (that is, for all options except PMSETA), it is set to value which is determined by the environment:

• On z/OS, the queue manager uses:
  • For z/OS batch, the 8-character job name from the JES JOB card
  • For TSO, the 7-character TSO user identifier
  • For CICS, the 8-character applid, followed by the 4-character tranid
  • For IMS, the 8-character IMS system identifier, followed by the 8-character PSB name
  • For XCF, the 8-character XCF group name, followed by the 16-character XCF member name
  • For a message generated by a queue manager, the first 28 characters of the queue manager name
  • For distributed queuing without CICS, the 8-character jobname of the channel initiator followed by the 8-character name of the module putting to the dead-letter queue followed by an 8-character task identifier.
  • For MQSeries® Java language bindings processing with IBM MQ for z/OS the 8-character jobname of the address space created for the UNIX System Services environment. Typically, this will be a TSO user identifier with a single numeric character appended.
  The name or names are each padded to the right with blanks, as is any space in the remainder of the field. Where there is more than one name, there is no separator between them.
• On PC DOS, and Windows systems, the queue manager uses:
  • For a CICS application, the CICS transaction name
  • For a non-CICS application, the rightmost 28 characters of the fully-qualified name of the executable
• On IBM i, the queue manager uses the fully-qualified job name.
• On HP Integrity NonStop Server, the queue manager uses: the rightmost 28 characters of the fully-qualified name of the executable, if this is available to the queue manager, and blanks otherwise
• On UNIX, the queue manager uses:
  • For a CICS application, the CICS transaction name
  • For a non-CICS application, the rightmost 14 characters of the fully-qualified name of the executable if this is available to the queue manager, and blanks otherwise (for example, on AIX )
• On VSE/ESA, the queue manager uses the 8-character applid, followed by the 4-character tranid.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETA is specified in the PMO parameter. Any information following a null character within the field is discarded. The null character and any following characters are converted to blanks by the queue manager. If PMSETA is not specified, this field is ignored on input and is an output-only field.

This is an output field for the MQGET call. The length of this field is given by LNPAN. The initial value of this field is 28 blank characters.

MDPAT (10-digit signed integer)

Type of application that put the message.

This is part of the origin context of the message. For more information about message context, see Message context and Controlling context information.

MDPAT may have one of the following standard types. User-defined types can also be used but should be restricted to values in the range ATUFST through ATULST.

ATAIX

AIX application (same value as ATUNIX).

ATBRKR

Broker.

ATCICS

CICS transaction.

ATCICB

CICS bridge.

ATVSE

CICS/VSE transaction.

ATDOS

IBM MQ MQI client application on PC DOS.

ATDQM

Distributed queue manager agent.

ATGUAR

Tandem Guardian application (same value as ATNSK).

ATIMS

IMS application.

ATIMSB

IMS bridge.

ATJAVA

Java.

ATMVS

MVS or TSO application (same value as ATZOS).

ATNOTE

Lotus Notes® Agent application.

ATNSK

Tandem NonStop Kernel application.

AT390

OS/390® application (same value as ATZOS).

AT400

IBM i application.

ATQM

Queue manager.

ATUNIX

UNIX application.

ATVOS

Stratus VOS application.

ATWIN

16-bit Windows application.

ATWINT

32-bit Windows application.

ATXCF

XCF.

ATZOS

z/OS application.

ATDEF

Default application type.

This is the default application type for the platform on which the application is running.

Note: The value of this constant is environment-specific.

ATUNK

Unknown application type.

This value can be used to indicate that the application type is unknown, even though other context information is present.

ATUFST

Lowest value for user-defined application type.

ATULST

Highest value for user-defined application type.

The following special value can also occur:

ATNCON

No context information present in message.

This value is set by the queue manager when a message is put with no context (that is, the PMNOC context option is specified).

When a message is retrieved, MDPAT can be tested for this value to decide whether the message has context (it is recommended that MDPAT is never set to ATNCON, by an application using PMSETA, if any of the other context fields are nonblank).

ATSIB

Indicates a message originated in another IBM MQ messaging product and arrived via the SIB (Service Integration Bus) bridge.

When the queue manager generates this information as a result of an application put, the field is set to a value that is determined by the environment. Note that on IBM i, it is set to AT400; the queue manager never uses ATCICS on IBM i.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETA is specified in the PMO parameter. If PMSETA is not specified, this field is ignored on input and is an output-only field.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the MDPAT that was transmitted with the message if it was put to a queue. This will be the value of MDPAT that is kept with the message if it is retained (see description of PMRET for more details about retained publications) but is not used as the MDPAT when the message is sent as a publication to subscribers since they provide a value to override MDPAT in all publications sent to them. If the message has no context, the field is set to ATNCON.

This is an output field for the MQGET call. The initial value of this field is ATNCON.

MDPD (8-byte character string)

Date when message was put.

This is part of the origin context of the message. For more information about message context, see Message context and Controlling context information.

The format used for the date when this field is generated by the queue manager is:

• YYYYMMDD

where the characters represent:

YYYY

year (four numeric digits)

MM

month of year (01 through 12)

DD

day of month (01 through 31)

Greenwich Mean Time (GMT) is used for the MDPD and MDPT fields, subject to the system clock being set accurately to GMT.

If the message was put as part of a unit of work, the date is that when the message was put, and not the date when the unit of work was committed.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETA is specified in the PMO parameter. The contents of the field are not checked by the queue manager, except that any information following a null character within the field is discarded. The null character and any following characters are converted to blanks by the queue manager. If PMSETA is not specified, this field is ignored on input and is an output-only field.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the MDPD that was transmitted with the message if it was put to a queue. This will be the value of MDPD that is kept with the message if it is retained (see description of PMRET for more details about retained publications) but is not used as the MDPD when the message is sent as a publication to subscribers since they provide a value to override MDPD in all publications sent to them. If the message has no context, the field is entirely blank.

This is an output field for the MQGET call. The length of this field is given by LNPDAT. The initial value of this field is 8 blank characters.

MDPER (10-digit signed integer)

Message persistence.

This indicates whether the message survives system failures and restarts of the queue manager. For the MQPUT and MQPUT1 calls, the value must be one of the following:

PEPER

Message is persistent.

This means that the message survives system failures and restarts of the queue manager. Once the message has been put, and the putter's unit of work committed (if the message is put as part of a unit of work), the message is preserved on auxiliary storage. It remains there until the message is removed from the queue, and the getter's unit of work committed (if the message is retrieved as part of a unit of work).

When a persistent message is sent to a remote queue, a store-and-forward mechanism is used to hold the message at each queue manager along the route to the destination, until the message is known to have arrived at the next queue manager.

Persistent messages cannot be placed on:

• Temporary dynamic queues
• Shared queues where the coupling facility structure level is less than three, or the coupling facility structure is not recoverable.

Persistent messages can be placed on permanent dynamic queues, predefined queues, and shared queues where the coupling facility structure level is 3, and the coupling facility is recoverable.

PENPER

Message is not persistent.

This means that the message does not normally survive system failures or restarts of the queue manager. This applies even if an intact copy of the message is found on auxiliary storage during restart of the queue manager.

In the special case of shared queues, nonpersistent messages do survive restarts of queue managers in the queue sharing group, but do not survive failures of the coupling facility used to store messages on the shared queues.

PEQDEF

Message has default persistence.

• If the queue is a cluster queue, the persistence of the message is taken from the DefPersistence attribute defined at the destination queue manager that owns the particular instance of the queue on which the message is placed. Usually, all of the instances of a cluster queue have the same value for the DefPersistence attribute, although this is not mandated.

  The value of DefPersistence is copied into the MDPER field when the message is placed on the destination queue. If DefPersistence is changed subsequently, messages that have already been placed on the queue are not affected.

• If the queue is not a cluster queue, the persistence of the message is taken from the DefPersistence attribute defined at the local queue manager, even if the destination queue manager is remote. If there is more than one definition in the queue-name resolution path, the default persistence is taken from the value of this attribute in the first definition in the path. This could be:
  • An alias queue
  • A local queue
  • A local definition of a remote queue
  • A queue manager alias
  • A transmission queue (for example, the DefXmitQName queue)

  The value of DefPersistence is copied into the MDPER field when the message is put. If DefPersistence is changed subsequently, messages that have already been put are not affected.

Both persistent and nonpersistent messages can exist on the same queue.

When replying to a message, applications should normally use for the reply message the persistence of the request message.

For an MQGET call, the value returned is either PEPER or PENPER.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is PEQDEF.

MDPRI (10-digit signed integer)

Message priority.

For the MQPUT and MQPUT1 calls, the value must be greater than or equal to zero; zero is the lowest priority. The following special value can also be used:

PRQDEF

Default priority for queue.

• If the queue is a cluster queue, the priority for the message is taken from the DefPriority attribute as defined at the destination queue manager that owns the particular instance of the queue on which the message is placed. Usually, all of the instances of a cluster queue have the same value for the DefPriority attribute, although this is not mandated.

  The value of DefPriority is copied into the MDPRI field when the message is placed on the destination queue. If DefPriority is changed subsequently, messages that have already been placed on the queue are not affected.

• If the queue is not a cluster queue, the priority for the message is taken from the DefPriority attribute as defined at the local queue manager, even if the destination queue manager is remote. If there is more than one definition in the queue-name resolution path, the default priority is taken from the value of this attribute in the first definition in the path. This could be:
  • An alias queue
  • A local queue
  • A local definition of a remote queue
  • A queue manager alias
  • A transmission queue (for example, the DefXmitQName queue)

  The value of DefPriority is copied into the MDPRI field when the message is put. If DefPriority is changed subsequently, messages that have already been put are not affected.

The value returned by the MQGET call is always greater than or equal to zero; the value PRQDEF is never returned.

If a message is put with a priority greater than the maximum supported by the local queue manager (this maximum is given by the MaxPriority queue manager attribute), the message is accepted by the queue manager, but placed on the queue at the queue manager's maximum priority; the MQPUT or MQPUT1 call completes with CCWARN and reason code RC2049. However, the MDPRI field retains the value specified by the application which put the message.

When replying to a message, applications should normally use for the reply message the priority of the request message. In other situations, specifying PRQDEF allows priority tuning to be carried out without changing the application.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is PRQDEF.

MDPT (8-byte character string)

Time when message was put.

This is part of the origin context of the message. For more information about message context, see Message context and Controlling context information.

The format used for the time when this field is generated by the queue manager is:

• HHMMSSTH

where the characters represent (in order):

HH

hours (00 through 23)

MM

minutes (00 through 59)

SS

seconds (00 through 59; see note )

T

tenths of a second (0 through 9)

H

hundredths of a second (0 through 9)

Note: If the system clock is synchronized to a very accurate time standard, it is possible on rare occasions for 60 or 61 to be returned for the seconds in MDPT. This happens when leap seconds are inserted into the global time standard.

Greenwich Mean Time (GMT) is used for the MDPD and MDPT fields, subject to the system clock being set accurately to GMT.

If the message was put as part of a unit of work, the time is that when the message was put, and not the time when the unit of work was committed.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETA is specified in the PMO parameter. The contents of the field are not checked by the queue manager, except that any information following a null character within the field is discarded. The null character and any following characters are converted to blanks by the queue manager. If PMSETA is not specified, this field is ignored on input and is an output-only field.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the MDPT value that was transmitted with the message if it was put to a queue. This will be the value of MDPT that is kept with the message if it is retained (see description of PMRET for more details about retained publications) but is not used as the MDPT when the message is sent as a publication to subscribers since they provide a value to override MDPT in all publications sent to them. If the message has no context, the field is entirely blank.

This is an output field for the MQGET call. The length of this field is given by LNPTIM. The initial value of this field is 8 blank characters.

MDREP (10-digit signed integer)

Options for report messages.

A report message is a message about another message, used to inform an application about expected or unexpected events that relate to the original message. The MDREP field enables the application sending the original message to specify which report messages are required, whether the application message data is to be included in them, and also (for both reports and replies) how the message and correlation identifiers in the report or reply message are to be set. Any or all (or none) of the following types of report message can be requested:

• Exception
• Expiration
• Confirm on arrival (COA)
• Confirm on delivery (COD)
• Positive action notification (PAN)
• Negative action notification (NAN)

If more than one type of report message is required, or other report options are needed, the values can be added together (do not add the same constant more than once).

The application that receives the report message can determine the reason the report was generated by examining the MDFB field in the MQMD; see the MDFB field for more details.

The use of report options when putting a message to a topic can cause zero, one or many report messages to be generated and sent to the application. This is because the publication message may be sent to zero, one or many subscribing applications.

Exception options: We can specify one of the following options to request an exception report message.

ROACTIVITY

Activity reports required

This report option enables an activity report to be generated, whenever a message with this report option set is processed by supporting applications.

Messages with this report option set must be accepted by any queue manager, even if they do not 'understand' the option. This allows the report option to be set on any user message, even if they are processed by previous queue managers. To achieve this, the report option is placed in the ROAUM subfield.

If a process (either a queue manager or a user process) performs an Activity on a message with ROACT set, it can choose to generate and put an activity report.

The activity report option allows the route of any message to be traced throughout a queue manager network. The report option can be specified on any current user message and instantly they can begin to calculate the route of the message through the network. If the application generating the message cannot enable activity report generation, it can be enabled by using an API crossing exit supplied by queue manager administrators.

Several conditions are applicable to activity reports:

1. The route will be less detailed if there are fewer queue managers in the network which are able to generate activity reports.
2. The activity reports may not be easily 'orderable' in order to determine the route taken.
3. The activity reports may not be able to find a route to their requested destination.

ROEXC

Exception reports required.

This type of report can be generated by a message channel agent when a message is sent to another queue manager and the message cannot be delivered to the specified destination queue. For example, the destination queue or an intermediate transmission queue might be full, or the message might be too big for the queue.

Generation of the exception report message depends on the persistence of the original message, and the speed of the message channel (normal or fast) through which the original message travels:

• For all persistent messages, and for nonpersistent messages traveling through normal message channels, the exception report is generated only if the action specified by the sending application for the error condition can be completed successfully. The sending application can specify one of the following actions to control the disposition of the original message when the error condition arises:
  • RODLQ (this causes the original message to be placed on the dead-letter queue).
  • RODISC (this causes the original message to be discarded).
  If the action specified by the sending application cannot be completed successfully, the original message is left on the transmission queue, and no exception report message is generated.
• For nonpersistent messages traveling through fast message channels, the original message is removed from the transmission queue and the exception report generated even if the specified action for the error condition cannot be completed successfully. For example, if RODLQ is specified, but the original message cannot be placed on the dead-letter queue because (say) that queue is full, the exception report message is generated and the original message discarded.

  See Message persistence for more information about normal and fast message channels.

An exception report is not generated if the application that put the original message can be notified synchronously of the problem by means of the reason code returned by the MQPUT or MQPUT1 call.

Applications can also send exception reports, to indicate that a message that it has received cannot be processed (for example, because it is a debit transaction that would cause the account to exceed its credit limit).

Message data from the original message is not included with the report message.

Do not specify more than one of ROEXC, ROEXCD, and ROEXCF.

ROEXCD

Exception reports with data required.

This is the same as ROEXC, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.

Do not specify more than one of ROEXC, ROEXCD, and ROEXCF.

ROEXCF

Exception reports with full data required.

This is the same as ROEXC, except that all of the application message data from the original message is included in the report message.

Do not specify more than one of ROEXC, ROEXCD, and ROEXCF.

Expiration options: We can specify one of the following options to request an expiration report message.

ROEXP

Expiration reports required.

This type of report is generated by the queue manager if the message is discarded before delivery to an application because its expiry time has passed (see the MDEXP field). If this option is not set, no report message is generated if a message is discarded for this reason (even if one of the ROEXC* options is specified).

Message data from the original message is not included with the report message.

Do not specify more than one of ROEXP, ROEXPD, and ROEXPF.

ROEXPD

Expiration reports with data required.

This is the same as ROEXP, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.

Do not specify more than one of ROEXP, ROEXPD, and ROEXPF.

ROEXPF

Expiration reports with full data required.

This is the same as ROEXP, except that all of the application message data from the original message is included in the report message.

Do not specify more than one of ROEXP, ROEXPD, and ROEXPF.

Confirm-on-arrival options: We can specify one of the following options to request a confirm-on-arrival report message.

ROCOA

Confirm-on-arrival reports required.

This type of report is generated by the queue manager that owns the destination queue, when the message is placed on the destination queue. Message data from the original message is not included with the report message.

If the message is put as part of a unit of work, and the destination queue is a local queue, the COA report message generated by the queue manager becomes available for retrieval only if and when the unit of work is committed.

A COA report is not generated if the MDFMT field in the message descriptor is FMXQH or FMDLH. This prevents a COA report being generated if the message is put on a transmission queue, or is undeliverable and put on a dead-letter queue.

Do not specify more than one of ROCOA, ROCOAD, and ROCOAF.

ROCOAD

Confirm-on-arrival reports with data required.

This is the same as ROCOA, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.

Do not specify more than one of ROCOA, ROCOAD, and ROCOAF.

ROCOAF

Confirm-on-arrival reports with full data required.

This is the same as ROCOA, except that all of the application message data from the original message is included in the report message.

Do not specify more than one of ROCOA, ROCOAD, and ROCOAF.

Discard and expiry options: We can specify the following option to set the expiry time and discard flag for report messages.

ROPDAE

Set report message expiry time and discard flag. This option ensures that report messages and reply messages inherit the expiry time and discard flag (whether to discard or not), from their original messages. With this option set, report and reply messages:

1. Inherit the RODISC flag (if it was set).
2. Inherit the remaining expiry time of the message, if the message is not an expiry report. If the message is an expiry report, the expiry time is set to 60 seconds.

With this option set, the following applies: Note:

1. Report and reply messages are generated with a discard flag and an expiry value, and cannot remain within the system.
2. Trace route messages are prevented from reaching destination queues on non-trace route enabled queue managers.
3. Queues are prevented from being filled with reports that cannot be delivered, if communications links are broken.
4. Command server responses inherit the remaining expiry of the request.

Confirm-on-delivery options: We can specify one of the following options to request a confirm-on-delivery report message.

ROCOD

Confirm-on-delivery reports required.

This type of report is generated by the queue manager when an application retrieves the message from the destination queue in a way that causes the message to be deleted from the queue. Message data from the original message is not included with the report message.

If the message is retrieved as part of a unit of work, the report message is generated within the same unit of work, so that the report is not available until the unit of work is committed. If the unit of work is backed out, the report is not sent.

A COD report is not generated if the MDFMT field in the message descriptor is FMDLH. This prevents a COD report being generated if the message is undeliverable and put on a dead-letter queue.

ROCOD is not valid if the destination queue is an XCF queue.

Do not specify more than one of ROCOD, ROCODD, and ROCODF.

ROCODD

Confirm-on-delivery reports with data required.

This is the same as ROCOD, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.

If GMATM is specified on the MQGET call for the original message, and the message retrieved is truncated, the amount of application message data placed in the report message is the minimum of:

• The length of the original message
• 100 bytes.

ROCODD is not valid if the destination queue is an XCF queue.

Do not specify more than one of ROCOD, ROCODD, and ROCODF.

ROCODF

Confirm-on-delivery reports with full data required.

This is the same as ROCOD, except that all of the application message data from the original message is included in the report message.

ROCODF is not valid if the destination queue is an XCF queue.

Do not specify more than one of ROCOD, ROCODD, and ROCODF.

Action-notification options: We can specify one or both of the following options to request that the receiving application send a positive-action or negative-action report message.

ROPAN

Positive action notification reports required.

This type of report is generated by the application that retrieves the message and acts upon it. It indicates that the action requested in the message has been performed successfully. The application generating the report determines whether any data is to be included with the report.

Other than conveying this request to the application retrieving the message, the queue manager takes no action based upon this option. It is the responsibility of the retrieving application to generate the report if appropriate.

RONAN

Negative action notification reports required.

This type of report is generated by the application that retrieves the message and acts upon it. It indicates that the action requested in the message has not been performed successfully. The application generating the report determines whether any data is to be included with the report. For example, it may be desirable to include some data indicating why the request could not be performed.

Other than conveying this request to the application retrieving the message, the queue manager takes no action based upon this option. It is the responsibility of the retrieving application to generate the report if appropriate.

Determination of which conditions correspond to a positive action and which correspond to a negative action is the responsibility of the application. However, it is recommended that if the request has been only partially performed, a NAN report rather than a PAN report should be generated if requested. It is also recommended that every possible condition should correspond to either a positive action, or a negative action, but not both.

Message-identifier options: We can specify one of the following options to control how the MDMID of the report message (or of the reply message) is to be set.

RONMI

New message identifier.

This is the default action, and indicates that if a report or reply is generated as a result of this message, a new MDMID is to be generated for the report or reply message.

ROPMI

Pass message identifier.

If a report or reply is generated as a result of this message, the MDMID of this message is to be copied to the MDMID of the report or reply message.

The MsgId of a publication message will be different for each subscriber that receives a copy of the publication and therefore the MsgId copied into the report or reply message will be different for each one.

If this option is not specified, RONMI is assumed.

Correlation-identifier options: We can specify one of the following options to control how the MDCID of the report message (or of the reply message) is to be set.

ROCMTC

Copy message identifier to correlation identifier.

This is the default action, and indicates that if a report or reply is generated as a result of this message, the MDMID of this message is to be copied to the MDCID of the report or reply message.

The MsgId of a publication message will be different for each subscriber that receives a copy of the publication and therefore the MsgId copied into the CorrelId of the report or reply message will be different for each one.

ROPCI

Pass correlation identifier.

If a report or reply is generated as a result of this message, the MDCID of this message is to be copied to the MDCID of the report or reply message.

The MDCID of a publication message will be specific to a subscriber unless it uses the SOSCID option and sets the SCDIC field in the MQSD to CINONE. Therefore it is possible that the MDCID copied into the MDCID of the report or reply message will be different for each one.

If this option is not specified, ROCMTC is assumed.

Servers replying to requests or generating report messages are recommended to check whether the ROPMI or ROPCI options were set in the original message. If they were, the servers should take the action described for those options. If neither is set, the servers should take the corresponding default action.

: We can specify one of the following options to control the disposition of the original message when it cannot be delivered to the destination queue. These options apply only to those situations that would result in an exception report message being generated if one had been requested by the sending application. The application can set the disposition options independently of requesting exception reports.

RODLQ

Place message on dead-letter queue. This is the default action, and indicates that the message should be placed on the dead-letter queue, if the message cannot be delivered to the destination queue. This happens in the following situations:

• When the application that put the original message cannot be notified synchronously of the problem by means of the reason code returned by the MQPUT or MQPUT1 call. An exception report message is generated, if one was requested by the sender.
• When the application that put the original message was putting to a topic

An exception report message will be generated, if one was requested by the sender.

RODISC

Discard message. This indicates that the message should be discarded if it cannot be delivered to the destination queue. This happens in the following situations:

• When the application that put the original message cannot be notified synchronously of the problem by means of the reason code returned by the MQPUT or MQPUT1 call. An exception report message is generated, if one was requested by the sender.
• When the application that put the original message was putting to a topic

An exception report message will be generated, if one was requested by the sender.

If it is required to return the original message to the sender, without the original message being placed on the dead-letter queue, the sender should specify RODISC with ROEXCF.

Default option: We can specify the following if no report options are required:

RONONE

No reports required.

This value can be used to indicate that no other options have been specified. RONONE is defined to aid program documentation. It is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.

General information:

1. All report types required must be specifically requested by the application sending the original message. For example, if a COA report is requested but an exception report is not, a COA report is generated when the message is placed on the destination queue, but no exception report is generated if the destination queue is full when the message arrives there. If no MDREP options are set, no report messages are generated by the queue manager or message channel agent (MCA).

   Some report options can be specified even though the local queue manager does not recognize them; this is useful when the option is to be processed by the destination queue manager. See Report options and message flags on IBM i for more details.

   If a report message is requested, the name of the queue to which the report should be sent must be specified in the MDRQ field. When a report message is received, the nature of the report can be determined by examining the MDFB field in the message descriptor.

2. If the queue manager or MCA that generates a report message is unable to put the report message on the reply queue (for example, because the reply queue or transmission queue is full), the report message is placed instead on the dead-letter queue. If that also fails, or there is no dead-letter queue, the action taken depends on the type of the report message:
   • If the report message is an exception report, the message which caused the exception report to be generated is left on its transmission queue; this ensures that the message is not lost.
   • For all other report types, the report message is discarded and processing continues normally. This is done because either the original message has already been delivered safely (for COA or COD report messages), or is no longer of any interest (for an expiration report message).
   Once a report message has been placed successfully on a queue (either the destination queue or an intermediate transmission queue), the message is no longer subject to special processing; it is treated just like any other message.
3. When the report is generated, the MDRQ queue is opened and the report message put using the authority of the MDUID in the MQMD of the message causing the report, except in the following cases:
   • Exception reports generated by a receiving MCA are put with whatever authority the MCA used when it tried to put the message causing the report. The CDPA channel attribute determines the user identifier used.
   • COA reports generated by the queue manager are put with whatever authority was used when the message causing the report was put on the queue manager generating the report. For example, if the message was put by a receiving MCA using the MCA's user identifier, the queue manager puts the COA report using the MCA's user identifier.
   Applications generating reports should normally use the same authority as they would have used to generate a reply; this should normally be the authority of the user identifier in the original message.

   If the report has to travel to a remote destination, senders and receivers can decide whether to accept it, in the same way as they do for other messages.

4. If a report message with data is requested:
   • The report message is always generated with the amount of data requested by the sender of the original message. If the report message is too big for the reply queue, the processing described previously occurs; the report message is never truncated in order to fit on the reply queue.
   • If the MDFMT of the original message is FMXQH, the data included in the report does not include the MQXQH. The report data starts with the first byte of the data beyond the MQXQH in the original message. This occurs whether the queue is a transmission queue.
5. If a COA, COD, or expiration report message is received at the reply queue, it is guaranteed that the original message arrived, was delivered, or expired, as appropriate. However, if one or more of these report messages is requested and is not received, the reverse cannot be assumed, since one of the following may have occurred:
   1. The report message is held up because a link is down.
   2. The report message is held up because a blocking condition exists at an intermediate transmission queue or at the reply queue (for example, the queue is full or inhibited for puts).
   3. The report message is on a dead-letter queue.
   4. When the queue manager was attempting to generate the report message, it was unable to put it on the appropriate queue, and was also unable to put it on the dead-letter queue, so the report message could not be generated.
   5. A failure of the queue manager occurred between the action being reported (arrival, delivery or expiry), and generation of the corresponding report message. (This does not happen for COD report messages if the application retrieves the original message within a unit of work, as the COD report message is generated within the same unit of work.)

   Exception report messages may be held up in the same way for reasons 1, 2, and 3 previously. However, when an MCA is unable to generate an exception report message (the report message cannot be put either on the reply queue or the dead-letter queue), the original message remains on the transmission queue at the sender, and the channel is closed. This occurs irrespective of whether the report message was to be generated at the sending or the receiving end of the channel.

6. If the original message is temporarily blocked (resulting in an exception report message being generated and the original message being put on a dead-letter queue), but the blockage clears and an application then reads the original message from the dead-letter queue and puts it again to its destination, the following may occur:
   • Even though an exception report message has been generated, the original message eventually arrives successfully at its destination.
   • More than one exception report message is generated in respect of a single original message, since the original message may encounter another blockage later.

Report messages when putting to a topic:

1. Reports can be generated when putting a message to a topic. This message will be sent to all subscribers to the topic, which could be zero, one or many. This should be taken into account when choosing to use report options as many report messages could be generated as a result.
2. When putting a message to a topic, there may be many destination queues that are to be given a copy of the message. If some of these destination queues have a problem, such as queue full, then the successful completion of the MQPUT depends on the setting of NPMSGDLV or PMSGDLV (depending on the persistence of the message). If the setting is such that message delivery to the destination queue must be successful (for example, it is a persistent message to a durable subscriber and PMSGDLV is set to ALL or ALLDUR), then success is defined as one of the following criteria being met:
   • Successful put to the subscriber queue
   • Use of RODLQ and a successful put to the Dead-letter queue if the subscriber queue cannot take the message
   • Use of RODISC if the subscriber queue cannot take the message.

Report messages for message segments:

1. Report messages can be requested for messages that have segmentation allowed (see the description of the MFSEGA flag). If the queue manager finds it necessary to segment the message, a report message can be generated for each of the segments that subsequently encounters the relevant condition. Applications should therefore be prepared to receive multiple report messages for each type of report message requested. The MDGID field in the report message can be used to correlate the multiple reports with the group identifier of the original message, and the MDFB field used to identify the type of each report message.
2. If GMLOGO is used to retrieve report messages for segments, be aware that reports of different types may be returned by the successive MQGET calls. For example, if both COA and COD reports are requested for a message that is segmented by the queue manager, the MQGET calls for the report messages may return the COA and COD report messages interleaved in an unpredictable fashion. This can be avoided by using the GMCMPM option (optionally with GMATM). GMCMPM causes the queue manager to reassemble report messages that have the same report type. For example, the first MQGET call might reassemble all of the COA messages relating to the original message, and the second MQGET call might reassemble all of the COD messages. Which is reassembled first depends on which type of report message happens to occur first on the queue.
3. Applications that themselves put segments can specify different report options for each segment. However, the following points should be noted:
   • If the segments are retrieved using the GMCMPM option, only the report options in the first segment are honored by the queue manager.
   • If the segments are retrieved one by one, and most of them have one of the ROCOD* options, but at least one segment does not, it will not be possible to use the GMCMPM option to retrieve the report messages with a single MQGET call, or use the GMASGA option to detect when all of the report messages have arrived.
4. In an MQ network, it is possible for the queue managers to have differing capabilities. If a report message for a segment is generated by a queue manager or MCA that does not support segmentation, the queue manager or MCA will not by default include the necessary segment information in the report message, and this may make it difficult to identify the original message that caused the report to be generated. This difficulty can be avoided by requesting data with the report message, that is, by specifying the appropriate RO*D or RO*F options. However, be aware that if RO*D is specified, less than 100 bytes of application message data may be returned to the application which retrieves the report message, if the report message is generated by a queue manager or MCA that does not support segmentation.

Contents of the message descriptor for a report message: When the queue manager or message channel agent (MCA) generates a report message, it sets the fields in the message descriptor to the following values, and then puts the message in the normal way.

Field in MQMD	Value used
MDSID	MDSIDV
MDVER	MDVER2
MDREP	RONONE
MDMT	MTRPRT
MDEXP	EIULIM
MDFB	As appropriate for the nature of the report (FBCOA, FBCOD, FBEXP, or an RC* value)
MDENC	Copied from the original message descriptor
MDCSI	Copied from the original message descriptor
MDFMT	Copied from the original message descriptor
MDPRI	Copied from the original message descriptor
MDPER	Copied from the original message descriptor
MDMID	As specified by the report options in the original message descriptor
MDCID	As specified by the report options in the original message descriptor
MDBOC	0
MDRQ	Blanks
MDRM	Name of queue manager
MDUID	As set by the PMPASI option
MDACC	As set by the PMPASI option
MDAID	As set by the PMPASI option
MDPAT	ATQM, or as appropriate for the message channel agent
MDPAN	First 28 bytes of the queue manager name or message channel agent name. For report messages generated by the IMS bridge, this field contains the XCF group name and XCF member name of the IMS system to which the message relates.
MDPD	Date when report message is sent
MDPT	Time when report message is sent
MDAOD	Blanks
MDGID	Copied from the original message descriptor
MDSEQ	Copied from the original message descriptor
MDOFF	Copied from the original message descriptor
MDMFL	Copied from the original message descriptor
MDOLN	Copied from the original message descriptor if not OLUNDF, and set to the length of the original message data otherwise

An application generating a report is recommended to set similar values, except for the following:

• The MDRM field can be set to blanks (the queue manager will change this to the name of the local queue manager when the message is put).
• The context fields should be set using the option that would have been used for a reply, normally PMPASI.

Analyzing the report field: The MDREP field contains subfields; because of this, applications that need to check whether the sender of the message requested a particular report should use one of the techniques described in Analyzing the report field on IBM i.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is RONONE.

MDRM (48-byte character string)

Name of reply queue manager.

This is the name of the queue manager to which the reply message or report message should be sent. MDRQ is the local name of a queue that is defined on this queue manager.

If the MDRM field is blank, the local queue manager looks up the MDRQ name in its queue definitions. If a local definition of a remote queue exists with this name, the MDRM value in the transmitted message is replaced by the value of the RemoteQMgrName attribute from the definition of the remote queue, and this value will be returned in the message descriptor when the receiving application issues an MQGET call for the message. If a local definition of a remote queue does not exist, the MDRM that is transmitted with the message is the name of the local queue manager.

If the name is specified, it may contain trailing blanks; the first null character and characters following it are treated as blanks. Otherwise, however, no check is made that the name satisfies the naming rules for queue managers, or that this name is known to the sending queue manager; this is also true for the name transmitted, if the MDRM is replaced in the transmitted message.

If a reply-to queue is not required, it is recommended (although this is not checked) that the MDRM field should be set to blanks; the field should not be left uninitialized.

For the MQGET call, the queue manager always returns the name padded with blanks to the length of the field.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The length of this field is given by LNQMN. The initial value of this field is 48 blank characters.

MDRQ (48-byte character string)

Name of reply queue.

This is the name of the message queue to which the application that issued the get request for the message should send MTRPLY and MTRPRT messages. The name is the local name of a queue that is defined on the queue manager identified by MDRM. This queue should not be a model queue, although the sending queue manager does not verify this when the message is put.

For the MQPUT and MQPUT1 calls, this field must not be blank if the MDMT field has the value MTRQST, or if any report messages are requested by the MDREP field. However, the value specified (or substituted) is passed on to the application that issues the get request for the message, whatever the message type.

If the MDRM field is blank, the local queue manager looks up the MDRQ name in its own queue definitions. If a local definition of a remote queue exists with this name, the MDRQ value in the transmitted message is replaced by the value of the RemoteQName attribute from the definition of the remote queue, and this value will be returned in the message descriptor when the receiving application issues an MQGET call for the message. If a local definition of a remote queue does not exist, MDRQ is unchanged.

If the name is specified, it may contain trailing blanks; the first null character and characters following it are treated as blanks. Otherwise, however, no check is made that the name satisfies the naming rules for queues; this is also true for the name transmitted, if the MDRQ is replaced in the transmitted message. The only check made is that a name has been specified, if the circumstances require it.

If a reply-to queue is not required, it is recommended (although this is not checked) that the MDRQ field should be set to blanks; the field should not be left uninitialized.

For the MQGET call, the queue manager always returns the name padded with blanks to the length of the field.

If a message that requires a report message cannot be delivered, and the report message also cannot be delivered to the queue specified, both the original message and the report message go to the dead-letter (undelivered-message) queue. See the DeadLetterQName attribute described in Attributes for the queue manager on IBM i.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The length of this field is given by LNQN. The initial value of this field is 48 blank characters.

MDSEQ (10-digit signed integer)

Sequence number of logical message within group.

Sequence numbers start at 1, and increase by 1 for each new logical message in the group, up to a maximum of 999 999 999. A physical message which is not in a group has a sequence number of 1.

This field need not be set by the application on the MQPUT or MQGET call if:

• On the MQPUT call, PMLOGO is specified.
• On the MQGET call, MOSEQN is not specified.

These are the recommended ways of using these calls for messages that are not report messages. However, if the application requires more control, or the call is MQPUT1, the application must ensure that MDSEQ is set to an appropriate value. On input to the MQPUT and MQPUT1 calls, the queue manager uses the value detailed in Table 1. On output from the MQPUT and MQPUT1 calls, the queue manager sets this field to the value that was sent with the message.

On input to the MQGET call, the queue manager uses the value detailed in Table 1. On output from the MQGET call, the queue manager sets this field to the value for the message retrieved.

The initial value of this field is one. This field is ignored if MDVER is less than MDVER2.

MDSID (4-byte character string)

Structure identifier.

The value must be:

MDSIDV

Identifier for message descriptor structure.

This is always an input field. The initial value of this field is MDSIDV.

MDUID (12-byte character string)

User identifier.

This is part of the identity context of the message. For more information about message context, see Message context and Controlling context information.

MDUID specifies the user identifier of the application that originated the message. The queue manager treats this information as character data, but does not define the format of it.

After a message has been received, MDUID can be used in the ODAU field of the OBJDSC parameter of a subsequent MQOPEN or MQPUT1 call, so that the authorization check is performed for the MDUID user instead of the application performing the open.

When the queue manager generates this information for an MQPUT or MQPUT1 call, the queue manager uses a user identifier determined from the environment.

When the user identifier is determined from the environment:

• On z/OS, the queue manager uses:
  • For batch, the user identifier from the JES JOB card or started task
  • For TSO, the log on user identifier
  • For CICS, the user identifier associated with the task
  • For IMS, the user identifier depends on the type of application:
    • For:
      • Nonmessage BMP regions
      • Nonmessage IFP regions
      • Message BMP and message IFP regions that have not issued a successful GU call
      the queue manager uses the user identifier from the region JES JOB card or the TSO user identifier. If these are blank or null, it uses the name of the program specification block (PSB).
    • For:
      • Message BMP and message IFP regions that have issued a successful GU call
      • MPP regions
      the queue manager uses one of:
      • The signed-on user identifier associated with the message
      • The logical terminal (LTERM) name
      • The user identifier from the region JES JOB card
      • The TSO user identifier
      • The PSB name
• On IBM i, the queue manager uses the name of the user profile associated with the application job.
• On HP Integrity NonStop Server, the queue manager uses the MQSeries principal that is defined for the Tandem user identifier in the MQSeries principal database.
• On UNIX, the queue manager uses:
  • The application's logon name
  • The effective user identifier of the process if no logon is available
  • The user identifier associated with the transaction, if the application is a CICS transaction
• On VSE/ESA, this is a reserved field.
• On Windows, the queue manager uses the first 12 characters of the logged-on user name.

For the MQPUT and MQPUT1 calls, this is an input/output field if PMSETI or PMSETA is specified in the PMO parameter. Any information following a null character within the field is discarded. The null character and any following characters are converted to blanks by the queue manager. If PMSETI or PMSETA is not specified, this field is ignored on input and is an output-only field.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the MDUID that was transmitted with the message if it was put to a queue. This will be the value of MDUID that is kept with the message if it is retained (see description of PMRET for more details about retained publications) but is not used as the MDUID when the message is sent as a publication to subscribers since they provide a value to override MDUID in all publications sent to them. If the message has no context, the field is entirely blank.

This is an output field for the MQGET call. The length of this field is given by LNUID. The initial value of this field is 12 blank characters.

MDVER (10-digit signed integer)

Structure version number.

The value must be one of the following:

MDVER1

Version-1 message descriptor structure.

MDVER2

Version-2 message descriptor structure.

Note: When a version-2 MQMD is used, the queue manager performs additional checks on any MQ header structures that may be present at the beginning of the application message data; for further details see the usage notes for the MQPUT call.

Fields that exist only in the more-recent version of the structure are identified as such in the descriptions of the fields. The following constant specifies the version number of the current version:

MDVERC

Current version of message descriptor structure.

This is always an input field. The initial value of this field is MDVER1.

Initial values

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D*
     D* MQMD Structure
     D*
     D* Structure identifier
     D  MDSID                  1      4    INZ('MD  ')
     D* Structure version number
     D  MDVER                  5      8I 0 INZ(1)
     D* Options for report messages
     D  MDREP                  9     12I 0 INZ(0)
     D* Message type
     D  MDMT                  13     16I 0 INZ(8)
     D* Message lifetime
     D  MDEXP                 17     20I 0 INZ(-1)
     D* Feedback or reason code
     D  MDFB                  21     24I 0 INZ(0)
     D* Numeric encoding of message data
     D  MDENC                 25     28I 0 INZ(273)
     D* Character set identifier of messagedata
     D  MDCSI                 29     32I 0 INZ(0)
     D* Format name of message data
     D  MDFMT                 33     40    INZ('        ')
     D* Message priority
     D  MDPRI                 41     44I 0 INZ(-1)
     D* Message persistence
     D  MDPER                 45     48I 0 INZ(2)
     D* Message identifier
     D  MDMID                 49     72    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     000000000000')
     D* Correlation identifier
     D  MDCID                 73     96    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     000000000000')
     D* Backout counter
     D  MDBOC                 97    100I 0 INZ(0)
     D* Name of reply queue
     D  MDRQ                 101    148    INZ
     D* Name of reply queue manager
     D  MDRM                 149    196    INZ
     D* User identifier
     D  MDUID                197    208    INZ
     D* Accounting token
     D  MDACC                209    240    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     0000000000000000000000-
     D                                     000000')
     D* Application data relating toidentity
     D  MDAID                241    272    INZ
     D* Type of application that put themessage
     D  MDPAT                273    276I 0 INZ(0)
     D* Name of application that put themessage
     D  MDPAN                277    304    INZ
     D* Date when message was put
     D  MDPD                 305    312    INZ
     D* Time when message was put
     D  MDPT                 313    320    INZ
     D* Application data relating toorigin
     D  MDAOD                321    324    INZ
     D* Group identifier
     D  MDGID                325    348    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     000000000000')
     D* Sequence number of logical messagewithin group
     D  MDSEQ                349    352I 0 INZ(1)
     D* Offset of data in physical messagefrom start of logical message
     D  MDOFF                353    356I 0 INZ(0)
     D* Message flags
     D  MDMFL                357    360I 0 INZ(0)
     D* Length of original message
     D  MDOLN                361    364I 0 INZ(-1)