MQACH - API exit chain header

 

---

The MQACH structure describes the header information that must be present at the start of each exit chain area.

• The address of the first area in the chain in given by the ExitChainAreaPtr field in MQAXP. If there is no chain, ExitChainAreaPtr is the null pointer.

• The address of the next area in the chain is given by the NextChainAreaPtr field in MQACH. For the last area in the chain, NextChainAreaPtr is the null pointer.

Any exit function can create a chain area in dynamically-obtained storage (for example, by using malloc), and add that area to the chain at the desired location (start, middle, or end). The exit function must ensure that it sets all fields in MQACH to valid values.

The exit suite that creates the chain area is responsible for destroying that chain area before termination (the  MQ_TERM_EXIT  function is a convenient point at which to do this). However, adding and removing chain areas from the chain must be done only by an exit function when it is invoked by the queue manager; this restriction is necessary to avoid serialization problems.

Exit chain areas are made available to all exit suites, and must not be used to hold private data. Use ExitUserArea in MQAXP to hold private data.

In general there is no correspondence between the chain of exit functions that are invoked for an API call, and the chain of exit chain areas:

• Some exit functions might not have chain areas.

• Other exit functions might each have multiple chain areas.

• The order of the chain areas might be different from the order of the exit functions that own those chain areas.

 

Fields

The MQACH structure contains the following fields:

 

StrucId (MQCHAR4)

Structure identifier.

The value is:

MQACH_STRUC_ID

Identifier for API exit chain header structure.

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

This initial value of this field is MQACH_STRUC_ID.

 

Version (MQLONG)

Structure version number.

The value is:

MQACH_VERSION_1

Version-1 API exit chain header structure.

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

MQACH_CURRENT_VERSION

Current version of API exit chain header structure.

Note:

When a new version of the MQACH structure is introduced, the layout of the existing part is not changed. The exit function must therefore check that the version number is equal to or greater than the lowest version that contains the fields that the exit function needs to use.

The initial value of this field is MQACH_CURRENT_VERSION.

 

StrucLength (MQLONG)

Length of MQACH structure.

This is the length of the MQACH structure itself; this length excludes the exit-defined data that follows the MQACH structure (see the ChainAreaLength field).

• The exit function that creates the MQACH structure must set this field to the length of the MQACH.

• An exit function that wants to access the exit-defined data should use StrucLength as the offset of the exit-defined data from the start of the MQACH structure.

The following value is defined:

MQACH_LENGTH_1

Length of version-1 MQACH structure.

The following constant specifies the length of the current version:

MQACH_CURRENT_LENGTH

Length of current version of exit chain area header.

The initial value of this field is MQACH_CURRENT_LENGTH.

 

ChainAreaLength (MQLONG)

Total length of chain area.

This is the total length of the chain area. It is equal to the sum of the length of the MQACH plus the length of the exit-defined data that follows the MQACH.

The initial value of this field is zero.

 

ExitInfoName (MQCHAR48)

Exit information name.

This is a name that is used to identify the exit suite to which the chain area belongs.

The length of this field is given by MQ_EXIT_INFO_NAME_LENGTH. The initial value of this field is the null string in C.

 

NextChainAreaPtr (PMQACH)

Address of next MQACH structure in chain.

This is the address of the next chain area in the chain. If the current chain area is the last one in the chain, NextChainAreaPtr is the null pointer.

The initial value of this field is the null pointer.

 

C declaration

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