MQDLH (Dead-letter header) on IBM i

Overview

Purpose

The MQDLH structure describes the information that prefixes the application message data of messages on the dead-letter (undelivered-message) queue. A message can arrive on the dead-letter queue because the queue manager or message channel agent redirected it to the queue. An application might put the message directly on the queue.

Format name

FMDLH

Character set and encoding

The MQDLH might be at the start of the application message data. If so, the fields in the MQDLH structure are in the character set and encoding given by the MDCSI and MDENC fields. If not, the character set and encoding are set by the MDCSI and MDENC fields in the header structure that precedes the MQDLH.

The character set must be one that has single-byte characters for the characters that are valid in queue names.

Usage

Applications that put messages directly on the dead-letter queue must prefix the message data with an MQDLH structure, and initialize the fields with appropriate values. However, the queue manager does not require that an MQDLH structure is present, or that valid values are specified for the fields. If a message is too long to put on the dead-letter queue, the application must consider doing one of the following things:

• Truncate the message data to fit on the dead-letter queue.
• Record the message on auxiliary storage and place an exception report message on the dead-letter queue indicating the message is too long.
• Discard the message and return an error to its originator. If the message is a critical message. Discard the message only if it is known that the originator still has a copy of the message. For example, a message received by a message channel agent from a communication channel.

Which of the choices is appropriate depends on the design of the application.

The queue manager performs special processing when a message which is a segment is put with an MQDLH structure at the front. See the description of the MQMDE structure for further details.

• Put messages on the dead-letter queue
• Getting messages from the dead-letter queue
• Fields
• Initial values
• RPG declaration

Put messages on the dead-letter queue

• The MDCSI and MDENC fields must be set to whatever character set and encoding are used for fields in the MQDLH structure.
• The MDFMT field must be set to FMDLH to indicate that the data begins with an MQDLH structure.
• The context fields, MDACC, MDAID, MDAOD, MDPAN, MDPAT, MDPD, MDPT, and MDUID must be set by using a context option appropriate to the circumstances:
  • An application putting on the dead-letter queue a message that is not related to any preceding message must use the PMDEFC option. The PMDEFC option causes the queue manager to set all of the context fields in the message descriptor to their default values.
  • A server application putting on the dead-letter queue a message it received must use the PMPASA option, in order to preserve the original context information.
  • A server application putting on the dead-letter queue a reply to message it received must use the PMPASI option. The PMPASI option preserves the identity information but sets the origin information to be that of the server application.
  • A message channel agent putting on the dead-letter queue a message it received from its communication channel must use the PMSETA option. The PMSETA option preserves the original context information.

In the MQDLH structure itself, the fields must be set as follows:

• The DLCSI, DLENC, and DLFMT fields must be set to the values that describe the data that follows the MQDLH structure. These values are typically the values from the original message descriptor.
• The context fields DLPAT, DLPAN, DLPD, and DLPT must be set to values appropriate to the application that is putting the message on the dead-letter queue. These values are not related to the original message.
• Other fields must be set as appropriate.

The application must ensure that all fields have valid values, and that character fields are padded with blanks to the defined length of the field. The character data must not be terminated prematurely by using a null character. The queue manager does not convert the null and subsequent characters to blanks in the MQDLH structure.

Getting messages from the dead-letter queue

Applications that get messages from the dead-letter queue must verify that the messages begin with an MQDLH structure. The application can determine whether an MQDLH structure is present by examining the MDFMT field in the message descriptor MQMD. If the field has the value FMDLH, the message data begins with an MQDLH structure. Messages on the dead-letter queue might be truncated if they were originally too long for the queue they were intended for.

Fields

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

DLCSI (10-digit signed integer)

Character set identifier of data that follows MQDLH.

DLCSI specifies the character set identifier of the data that follows the MQDLH structure. The data is typically from the original message. It does not apply to character data in the MQDLH structure itself.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The following special value can be used:

CSINHT

Inherit character-set identifier of this structure.

Character data in the data following this structure is in the same character set as this structure.

The queue manager changes this value in the structure sent in the message to the actual character-set identifier of the structure. 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.

The initial value of this field is CSUNDF.

DLDM (48-byte character string)

Name of original destination queue manager.

This is the name of the queue manager that was the original destination for the message.

The length of this field is given by LNQMN. The initial value of this field is 48 blank characters.

DLDQ (48-byte character string)

Name of original destination queue.

This is the name of the message queue that was the original destination for the message.

The length of this field is given by LNQN. The initial value of this field is 48 blank characters.

DLENC (10-digit signed integer)

Numeric encoding of data that follows MQDLH.

DLENC specifies the numeric encoding of the data that follows the MQDLH structure. The data is typically from the original message. It does not apply to numeric data in the MQDLH structure itself.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data.

The initial value of this field is 0.

DLFMT (8-byte character string)

Format name of data that follows MQDLH.

This specifies the format name of the data that follows the MQDLH structure (typically the data from the original message).

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The rules for coding this field are the same as the rules for the MDFMT field in MQMD.

The length of this field is given by LNFMT. The initial value of this field is FMNONE.

DLPAN (28-byte character string)

Name of application that put message on dead-letter (undelivered-message) queue.

The format of the name depends on the DLPAT field. See the description of the MDPAN field in MQMD (Message descriptor) on IBM i.

If it is the queue manager that redirects the message to the dead-letter queue, DLPAN contains the first 28 characters of the queue manager name. The name is padded with blanks if necessary.

The length of this field is given by LNPAN. The initial value of this field is 28 blank characters.

DLPAT (10-digit signed integer)

Type of application that put message on dead-letter (undelivered-message) queue.

This field has the same meaning as the MDPAT field in the message descriptor MQMD (see MQMD (Message descriptor) on IBM i for details).

If it is the queue manager that redirects the message to the dead-letter queue, DLPAT has the value ATQM.

The initial value of this field is 0.

DLPD (8-byte character string)

Date when message was put on dead-letter (undelivered-message) queue.

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 DLPD and DLPT fields, subject to the system clock being set accurately to GMT.

The length of this field is given by LNPDAT. The initial value of this field is eight blank characters.

DLPT (8-byte character string)

Time when message was put on the dead-letter (undelivered-message) queue.

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 later in this topic)

T

tenths of a second (0 through 9)

H

hundredths of a second (0 through 9)

Note: If the system clock is synchronized to an accurate time standard, it is possible for 60 or 61 to be returned for the seconds in DLPT. The extra second occurs when leap seconds are inserted into the global time standard.

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

The length of this field is given by LNPTIM. The initial value of this field is eight blank characters.

DLREA (10-digit signed integer)

Reason message arrived on dead-letter (undelivered-message) queue.

This identifies the reason why the message was placed on the dead-letter queue instead of on the original destination queue. It must be one of the FB* or RC* values (for example, RC2053). See the description of the MDFB field in MQMD (Message descriptor) on IBM i for details of the common FB* values that can occur.

If the value is in the range FBIFST through FBILST, the actual IMS error code can be determined by subtracting FBIERR from the value of the DLREA field.

Some FB* values occur only in this field. They relate to repository messages, trigger messages, or transmission-queue messages that are transferred to the dead-letter queue. These values are:

FBABEG

Application cannot be started.

An application processing a trigger message was unable to start the application named in the TMAI field of the trigger message; see MQTM - Trigger message.

FBATYP

Application type error.

An application processing a trigger message was unable to start the application because the TMAT field of the trigger message is not valid; see MQTM - Trigger message.

FBBOCD

Cluster-receiver channel deleted.

The message was on a cluster transmission queue intended for a cluster queue that was opened with the FBIERR option. The remote cluster-receiver channel to be used to transmit the message to the destination queue was deleted before the message could be sent. Because FBIERR was specified, only the channel selected when the queue was opened can be used to transmit the message. As this channel is not longer available, the message was placed on the dead-letter queue.

FBNARM

Message is not a repository message.

FBSBCX

Message stopped by channel auto-definition exit.

FBSBMX

Message stopped by channel message exit.

FBTM

MQTM structure not valid or missing.

The MDFMT field in MQMD specifies FMTM, but the message does not begin with a valid MQTM structure. For example, the TMSID mnemonic eye-catcher might not be valid. The TMVER might not be recognized. The length of the trigger message might be insufficient to contain the MQTM structure.

FBXQME

Message on transmission queue not in correct format.

A message channel agent found that a message on the transmission queue is not in the correct format. The message channel agent puts the message on the dead-letter queue using this feedback code.

The initial value of this field is RCNONE.

DLSID (4-byte character string)

Structure identifier.

The value must be:

DLSIDV

Identifier for dead-letter header structure.

The initial value of this field is DLSIDV.

DLVER (10-digit signed integer)

Structure version number.

The value must be:

DLVER1

Version number for dead-letter header structure.

The following constant specifies the version number of the current version:

DLVERC

Current version of dead-letter header structure.

The initial value of this field is DLVER1.

Initial values

1. The symbol ¬ represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQDLH Structure
     D*
     D* Structure identifier
     D  DLSID                  1      4    INZ('DLH ')
     D* Structure version number
     D  DLVER                  5      8I 0 INZ(1)
     D* Reason message arrived on dead-letter(undelivered-message) queue
     D  DLREA                  9     12I 0 INZ(0)
     D* Name of original destination queue
     D  DLDQ                  13     60    INZ
     D* Name of original destination queue manager
     D  DLDM                  61    108    INZ
     D* Numeric encoding of data that followsMQDLH
     D  DLENC                109    112I 0 INZ(0)
     D* Character set identifier of data thatfollows MQDLH
     D  DLCSI                113    116I 0 INZ(0)
     D* Format name of data that followsMQDLH
     D  DLFMT                117    124    INZ('        ')
     D* Type of application that put messageon dead-letter
     D* (undelivered-message)queue
     D  DLPAT                125    128I 0 INZ(0)
     D* Name of application that put messageon dead-letter
     D* (undelivered-message)queue
     D  DLPAN                129    156    INZ
     D* Date when message was put ondead-letter (undelivered-message)queue
     D  DLPD                 157    164    INZ
     D* Time when message was put on thedead-letter (undelivered-message)queue
     D  DLPT                 165    172    INZ