The exit chain area and exit chain area header (MQACH)

If required, an exit function can acquire storage for an exit chain area and set the ExitChainAreaPtr in MQAXP to point to this storage.

Exits (either the same or different exit functions) can acquire multiple exit chain areas and link them together. Exit chain areas must only be added or removed from this list while called from the exit handler. This ensures that there are no serialization issues caused by different threads adding or removing areas from the list at the same time.

An exit chain area must start with an MQACH header structure, the C declaration for which is:

typedef struct tagMQACH {
   MQCHAR4   StrucId;             /* Structure identifier */
   MQLONG    Version;             /* Structure version number */
   MQLONG    StrucLength;         /* Length of the MQACH structure */
   MQLONG    ChainAreaLength;     /* Exit chain area length */
   MQCHAR48  ExitInfoName         /* Exit information name */
   PMQACH    NextChainAreaPtr;    /* Pointer to next exit chain area */
 };

The fields in the exit chain area header are:

StrucId (MQCHAR4) - input

The exit chain area structure identifier, with an initial value, defined by MQACH_DEFAULT, of MQACH_STRUC_ID.

For C programs, the constant MQACH_STRUC_ID_ARRAY is also defined; this has the same value as MQACH_STRUC_ID, but as an array of characters instead of a string.

Version (MQLONG) - input

The structure version number, as follows:

MQACH_VERSION_1: The version number for the exit parameter structure.
MQACH_CURRENT_VERSION: The current version number for the exit context structure.

The initial value of this field, defined by MQACH_DEFAULT, is MQACH_CURRENT_VERSION. Note: If you introduce a new version of this structure, the layout of the existing part does not change. Exit functions must check that the version number is equal to or greater than the lowest version containing the fields that the exit function needs to use.

StrucLength (MQLONG) - input

The length of the MQACH structure. Exits can use this field to determine the start of the exit data, setting it to the length of the structure created by the exit.

The initial value of this field, defined by MQACH_DEFAULT, is MQACH_CURRENT_LENGTH.

ChainAreaLength (MQLONG) - input

The exit chain area length, set to the overall length of the current exit chain area, including the MQACH header.

The initial value of this field, defined by MQACH_DEFAULT, is zero.

ExitInfoName (MQCHAR48) - input

The exit information name.

When an exit creates an MQACH structure, it must initialize this field with its own ExitInfoName, so that later this MQACH structure can be found by either another instance of this exit, or by a cooperating exit.

The initial value of this field, defined by MQACH_DEFAULT, is a zero length string ({""}).

NextChainAreaPtr (PMQACH) - input

A pointer to the next exit chain area with an initial value, defined by MQACH_DEFAULT, of null pointer (NULL ).

Exit functions must release the storage for any exit chain areas that they acquire, and manipulate the chain pointers to remove their exit chain areas from the list. An exit chain area can be constructed as follows:

MQAXP.ExitChainAreaPtr ───┬

  ┌───────────────────────┘

  └──→ ┌─────┬───┬────┬─────┬──────────────────────────────────────────────┬
       │ ACH │ 1 │ 80 │ ──┬ │ First exit's chain area                      │
       └─────┴───┴────┴───│─┴──────────────────────────────────────────────┘

  ┌───────────────────────┘

  └──→ ┌─────┬───┬────┬─────┬───────────────────────────┬
       │ ACH │ 1 │ 64 │ ──┬ │ Second exit's chain area  │
       └─────┴───┴────┴───│─┴───────────────────────────┘

  ┌───────────────────────┘

  └──→ ... etc.