MQWXP - Cluster workload exit parameter structure
The MQWXP structure describes the information that is passed to the cluster workload exit.
This structure is supported in the following environments: AIX, Compaq Tru64 UNIX, Compaq OpenVMS Alpha, Compaq NonStop Kernel, HP-UX, Linux, OS/2, z/OS, OS/400, Solaris, and Windows.
Fields
- StrucId (MQCHAR4)
- Structure identifier.
The value is:
- MQWXP_STRUC_ID
- Identifier for cluster workload exit parameter structure.
For the C programming language, the constant MQWXP_STRUC_ID_ARRAY is also defined; this has the same value as MQWXP_STRUC_ID, but is an array of characters instead of a string.
This is an input field to the exit.
- Version (MQLONG)
- Structure version number.
Possible values are:
- MQWXP_VERSION_1
- Version-1 cluster workload exit parameter structure.
- This version is supported in all environments.
- MQWXP_VERSION_2
- Version-2 cluster workload exit parameter structure.
- This version is supported in the following environments: AIX, HP-UX, Linux, OS/400, Solaris and Windows NT.
The following constant specifies the version number of the current version:
- MQWXP_CURRENT_VERSION
- Current version of cluster workload exit parameter structure.
This is an input field to the exit.
- ExitId (MQLONG)
- Type of exit.
This indicates the type of exit being called. The value is:
- MQXT_CLUSTER_WORKLOAD_EXIT
- Cluster workload exit.
This type of exit is supported in the following environments: AIX, Compaq Tru64 UNIX, Compaq OpenVMS Alpha, Compaq NonStop Kernel, HP-UX, Linux, OS/2, z/OS, OS/400, Solaris, and Windows.
This is an input field to the exit.
- ExitReason (MQLONG)
- Reason for invoking exit.
This indicates the reason why the exit is being called. Possible values are:
- MQXR_INIT
- Exit initialization.
This indicates that the exit is being invoked for the first time. It allows the exit to acquire and initialize any resources that it may need (for example: main storage).
- MQXR_TERM
- Exit termination.
This indicates that the exit is about to be terminated. The exit should free any resources that it may have acquired since it was initialized (for example: main storage).
- MQXR_CLWL_OPEN
- Called from MQOPEN processing.
- MQXR_CLWL_PUT
- Called from MQPUT or MQPUT1 processing.
- MQXR_CLWL_MOVE
- Called from MCA when the channel state has changed.
- MQXR_CLWL_REPOS
- Called from MQPUT or MQPUT1 processing for a repository-manager PCF message.
- MQXR_CLWL_REPOS_MOVE
- Called from MCA for a repository-manager PCF message when the channel state has changed.
This is an input field to the exit.
- ExitResponse (MQLONG)
- Response from exit.
This is set by the exit to indicate whether processing of the message should continue. It must be one of the following:
- MQXCC_OK
- Continue normally.
This indicates that processing of the message should continue normally. DestinationChosen identifies the destination to which the message should be sent.
- MQXCC_SUPPRESS_FUNCTION
- Suppress function.
This indicates that processing of the message should be discontinued:
- For MQXR_CLWL_OPEN, MQXR_CLWL_PUT, and MQXR_CLWL_REPOS invocations, the MQOPEN , MQPUT , or MQPUT1 call fails with completion code MQCC_FAILED and reason code MQRC_STOPPED_BY_CLUSTER_EXIT.
- For MQXR_CLWL_MOVE and MQXR_CLWL_REPOS_MOVE invocations, the message is placed on the dead-letter queue.
- MQXCC_SUPPRESS_EXIT
- Suppress exit.
This indicates that processing of the current message should continue normally, but that the exit should not be invoked again until termination of the queue manager. The queue manager processes subsequent messages as if the ClusterWorkloadExit queue-manager attribute were blank. DestinationChosen identifies the destination to which the current message should be sent.
If any other value is returned by the exit, the queue manager processes the message as if MQXCC_SUPPRESS_FUNCTION had been specified.
This is an output field from the exit.
- ExitResponse2 (MQLONG)
Secondary response from exit.
This is set to zero on entry to the exit. It can be set by the exit to provide further information to the queue manager.
When ExitReason has the value MQXR_INIT, the exit can set one of the following values in ExitResponse2:
- MQXR2_STATIC_CACHE
- Exit requires a static cluster cache.
If the exit returns this value, the exit need not use the MQXCLWLN call to navigate the chains of records in the cluster cache, but the cache must be static.
If the exit returns this value and the cluster cache is dynamic, the exit cannot navigate correctly through the records in the cache. In this situation, the queue manager processes the return from the MQXR_INIT call as though the exit had returned MQXCC_SUPPRESS_EXIT in the ExitResponse field.
- MQXR2_DYNAMIC_CACHE
- Exit can operate with either a static or dynamic cache.
If the exit returns this value, the exit must use the MQXCLWLN call to navigate the chains of records in the cluster cache.
If the exit sets neither value, MQXR2_STATIC_CACHE is assumed.
This is an input/output field to the exit.
- Feedback (MQLONG)
- Reserved.
This is a reserved field. The value is zero.
- Reserved (MQLONG)
- Reserved.
This is a reserved field. The value is zero.
- ExitUserArea (MQBYTE16)
- Exit user area.
This is a field that is available for the exit to use. It is initialized to MQXUA_NONE (binary zero) before the first invocation of the exit. Any changes made to this field by the exit are preserved across the invocations of the exit that occur between the MQCONN call and the matching MQDISC call. The field is reset to MQXUA_NONE when the MQDISC call occurs. The first invocation of the exit is indicated by the ExitReason field having the value MQXR_INIT.
The following value is defined:
- MQXUA_NONE
- No user information.
The value is binary zero for the length of the field.
For the C programming language, the constant MQXUA_NONE_ARRAY is also defined; this has the same value as MQXUA_NONE, but is an array of characters instead of a string.
The length of this field is given by MQ_EXIT_USER_AREA_LENGTH. This is an input/output field to the exit.
- ExitData (MQCHAR32)
- Exit data.
This is set on input to the exit routine to the value of the ClusterWorkloadData queue-manager attribute. If no value has been defined for that attribute, this field is all blanks.
The length of this field is given by MQ_EXIT_DATA_LENGTH. This is an input field to the exit.
- MsgDescPtr (PMQMD)
- Address of message descriptor.
This is the address of a copy of the message descriptor (MQMD) for the message being processed. Any changes made to the message descriptor by the exit are ignored by the queue manager.
No message descriptor is passed to the exit if ExitReason has one of the following values:
- MQXR_INIT
- MQXR_TERM
- MQXR_CLWL_OPEN
In these cases, MsgDescPtr is the null pointer.
This is an input field to the exit.
- MsgBufferPtr (PMQVOID)
- Address of buffer containing some or all of the message data.
This is the address of a buffer containing a copy of the first MsgBufferLength bytes of the message data. Any changes made to the message data by the exit are ignored by the queue manager.
No message data is passed to the exit when:
- MsgDescPtr is the null pointer.
- The message has no data.
- The ClusterWorkloadLength queue-manager attribute is zero.
In these cases, MsgBufferPtr is the null pointer.
This is an input field to the exit.
- MsgBufferLength (MQLONG)
- Length of buffer containing message data.
This is the length of the message data passed to the exit. This length is controlled by the ClusterWorkloadLength queue-manager attribute, and may be less than the length of the complete message (see MsgLength).
This is an input field to the exit.
- MsgLength (MQLONG)
- Length of complete message.
The length of the message data passed to the exit (MsgBufferLength) might be less than the length of the complete message. MsgLength is zero if ExitReason is MQXR_INIT, MQXR_TERM, or MQXR_CLWL_OPEN.
This is an input field to the exit.
- QName (MQCHAR48)
- Queue name.
Name of the destination queue; this queue is a cluster queue.
The length of this field is given by MQ_Q_NAME_LENGTH. This is an input field to the exit.
- QMgrName (MQCHAR48)
- Name of local queue manager.
Name of the queue manager that has invoked the cluster workload exit.
The length of this field is given by MQ_Q_MGR_NAME_LENGTH. This is an input field to the exit.
- DestinationCount (MQLONG)
- Number of possible destinations.
This specifies the number of destination records (MQWDR) that describe instances of the destination queue. There is one MQWDR structure for each possible route to each instance of the queue. The MQWDR structures are addressed by an array of pointers (see DestinationArrayPtr).
This is an input field to the exit.
- DestinationChosen (MQLONG)
- Destination chosen.
Number of the MQWDR structure that identifies the route and queue instance to which the message should be sent. The value is in the range 1 through DestinationCount.
On input to the exit, DestinationChosen indicates the route and queue instance that the queue manager has selected. The exit can accept this choice, or choose a different route and queue instance. However, the value returned by the exit must be in the range 1 through DestinationCount. If any other value is returned, the queue manager uses the value of DestinationChosen on input to the exit.
This is an input/output field to the exit.
- DestinationArrayPtr (PPMQWDR)
- Address of an array of pointers to destination records.
This is the address of an array of pointers to destination records (MQWDR). There are DestinationCount destination records.
This is an input field to the exit.
- QArrayPtr (PPMQWQR)
- Address of an array of pointers to queue records.
This is the address of an array of pointers to queue records (MQWQR). If queue records are available, there are DestinationCount of them. If no queue records are available, QArrayPtr is the null pointer.
- Note:
- QArrayPtr can be the null pointer even when DestinationCount is greater than zero.
This is an input field to the exit.
- CacheContext (MQPTR)
- Context information.
This field is reserved for use by the queue manager. The exit must not alter the value of this field.
This is an input field to the exit.
- CacheType (MQLONG)
- Type of cluster cache.
This is the type of the cluster cache. It is one of the following:
- MQCLCT_STATIC
- Cache is static.
If the cache has this type, the size of the cache is fixed, and cannot grow as the queue manager operates. The MQXCLWLN call need not be used to navigate the records in this type of cache.
- MQCLCT_DYNAMIC
- Cache is dynamic.
If the cache has this type, the size of the cache can increase in order to accommodate the varying cluster information. The MQXCLWLN call must be used to navigate the records in this type of cache.
This is an input field to the exit.
C declaration
typedef struct tagMQWXP { MQCHAR4 StrucId; /* Structure identifier */ MQLONG Version; /* Structure version number */ MQLONG ExitId; /* Type of exit */ MQLONG ExitReason; /* Reason for invoking exit */ MQLONG ExitResponse; /* Response from exit */ MQLONG ExitResponse2; /* Reserved */ MQLONG Feedback; /* Reserved */ MQLONG Reserved; /* Reserved */ MQBYTE16 ExitUserArea; /* Exit user area */ MQCHAR32 ExitData; /* Exit data */ PMQMD MsgDescPtr; /* Address of message descriptor */ PMQVOID MsgBufferPtr; /* Address of buffer containing some or all of the message data */ MQLONG MsgBufferLength; /* Length of buffer containing message data */ MQLONG MsgLength; /* Length of complete message */ MQCHAR48 QName; /* Queue name */ MQCHAR48 QMgrName; /* Name of local queue manager */ MQLONG DestinationCount; /* Number of possible destinations */ MQLONG DestinationChosen; /* Destination chosen */ PPMQWDR DestinationArrayPtr; /* Address of an array of pointers to destination records */ PPMQWQR QArrayPtr; /* Address of an array of pointers to queue records */ MQPTR CacheContext; /* Context information */ MQLONG CacheType; /* Type of cluster cache */ } MQWXP;
System/390 assembler declaration
MQWXP DSECT MQWXP_STRUCID DS CL4 Structure identifier MQWXP_VERSION DS F Structure version number MQWXP_EXITID DS F Type of exit MQWXP_EXITREASON DS F Reason for invoking exit MQWXP_EXITRESPONSE DS F Response from exit MQWXP_EXITRESPONSE2 DS F Reserved MQWXP_FEEDBACK DS F Reserved MQWXP_RESERVED DS F Reserved MQWXP_EXITUSERAREA DS XL16 Exit user area MQWXP_EXITDATA DS CL32 Exit data MQWXP_MSGDESCPTR DS F Address of message * descriptor MQWXP_MSGBUFFERPTR DS F Address of buffer containing * some or all of the message * data MQWXP_MSGBUFFERLENGTH DS F Length of buffer containing * message data MQWXP_MSGLENGTH DS F Length of complete message MQWXP_QNAME DS CL48 Queue name MQWXP_QMGRNAME DS CL48 Name of local queue manager MQWXP_DESTINATIONCOUNT DS F Number of possible * destinations MQWXP_DESTINATIONCHOSEN DS F Destination chosen MQWXP_DESTINATIONARRAYPTR DS F Address of an array of * pointers to destination * records MQWXP_QARRAYPTR DS F Address of an array of * pointers to queue records MQWXP_LENGTH EQU *-MQWXP Length of structure ORG MQWXP MQWXP_AREA DS CL(MQWXP_LENGTH)