MQXCLWLN - Navigate Cluster workload records
The MQXCLWLN call is used to navigate through the chains of MQWDR, MQWQR,
and MQWCR records stored in the cluster cache. The cluster cache is an area
of main storage used to store information relating to the cluster.
If the cluster cache is static, it has a fixed size. If you set
it to dynamic, the cluster cache can expand as required, To set the type of
cluster cache to STATIC or DYNAMIC, use:
- The system parameter ClusterCacheType on platforms other than z/OS
- The CLCACHE parameter in the CSQ6SYSP macro on z/OS.
For related information, see the WebSphere MQ System
Setup Guide.
Syntax
- MQXCLWLN (ExitParms, CurrentRecord,
NextOffset, NextRecord, Compcode, Reason)
-
Parameters
The MQ_CLUSTER_WORKLOAD_EXIT call has the following
parameters.
- ExitParms (MQWXP) - input/output
- Exit parameter block.
This structure contains information relating
to the invocation of the exit. The exit sets information in this structure to indicate how the workload
should be managed.
- CurrentRecord (MQPTR) - input
- Address of current record.
This structure contains information relating
to the address of the record currently being examined by the exit. The record must be one of the following
types:
- Cluster workload destination record (MQWDR)
- Cluster workload queue record (MQWQR)
- Cluster workload cluster record (MQWCR)
- NextOffset (MQLONG) - input
- Offset of next record.
This structure contains information relating to the offset of the next
record or structure. NextOffset is the value of the appropriate
offset field in the current record, and must be one of the following fields:
- ChannelDefOffset field in MQWDR
- ClusterRecOffset field in MQWDR
- ClusterRecOffset field in MQWQR
- ClusterRecOffset field in MQWCR
- NextRecord (MQPTR) - output
- Address of next record or structure.
This structure contains information relating to the address
of the next record or structure. If CurrentRecord is
the address of an MQWDR, and NextOffset is the value
of the ChannelDefOffset field, NextRecord is the address of the channel definition structure (MQCD).
If there is no next record or structure, the queue manager sets NextRecord to the null pointer, and the call returns completion
code MQCC_WARNING and reason code MQRC_NO_RECORD_AVAILABLE.
- CompCode (MQLONG) - output
- Completion code.
It
is one of the following:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Warning (partial completion).
- MQCC_FAILED
- Call failed.
- Reason (MQLONG) - output
- Reason code qualifying CompCode
If CompCode is MQCC_OK:
- MQRC_NONE
- (0, X'000) No reason to report.
If CompCode is MQCC_WARNING:
- MQRC_NO_RECORD_AVAILABLE
- (2359, X'0937') No record available. An MQXCLWLN call was issued
from a cluster workload exit to obtain the address of the next record in the
chain, but the current record is the last record in the chain. Corrective
action: None.
If CompCode is MQCC_FAILED:
- MQRC_CURRENT_RECORD_ERROR
- (2357, X'0935') Current-record parameter not valid. An MQXCLWLN
call was issued from a cluster workload exit to obtain the address of the
next record in the chain, but the address specified by the CurrentRecord parameter
is not the address of a valid record. CurrentRecord must be the address of
a destination record (MQWDR), queue record (MQWQR), or cluster record (MQWCR)
residing within the cluster cache. Corrective action: Ensure that the cluster
workload exit passes the address of a valid record residing in the cluster
cache.
- MQRC_ENVIRONMENT_ERROR
- (2012, X'07DC') Call not valid in environment. An MQXCLWLN call was
issued, but not from a cluster workload exit.
- MQRC_NEXT_OFFSET_ERROR
- (2358, X'0936') Next-offset parameter not valid. An MQXCLWLN
call was issued from a cluster workload exit to obtain the address of the
next record in the chain, but the offset specified by the NextOffset parameter
is not valid. NextOffset must be the value of one of the following fields:
- ChannelDefOffset field in MQWDR
- ClusterRecOffset" field in MQWDR
- ClusterRecOffset" field in MQWQR
- ClusterRecOffset" field in MQWCR
Corrective action: Ensure that the value specified for the NextOffset
parameter is the value of one of the fields listed above.
- MQRC_NEXT_RECORD_ERROR
- (2361, X'0939') NextRecord parameter not valid.
- MQRC_WXP_ERROR
- (2356, X'0934') Workload exit parameter structure not valid.
An MQXCLWLN call was issued from a cluster workload exit to obtain the address
of the next record in the chain, but the workload exit parameter structure
ExitParms is not valid, for one of the following reasons:
- The parameter pointer is not valid. (It is not always possible to detect
parameter pointers that are not valid; if not detected, unpredictable results
occur.)
- The StrucId field is not MQWXP_STRUC_ID.
- The Version field is not MQWXP_VERSION_2.
- The Context field does not contain the value passed to the exit by the
queue manager.
Corrective action: Ensure that the parameter specified for ExitParms
is the MQWXP structure that was passed to the exit when the exit was invoked.
For more information on these reason codes, see the WebSphere MQ Application Programming Reference manual.
Usage notes
If the cluster cache is dynamic, the MQXCLWLN call must be used to navigate
through the records; the exit will terminate abnormally if simple pointer-and-offset
arithmetic is used to navigate through the records. If the cluster cache is
static, MQXCLWLN need not be used to navigate through the records. However,
it is recommended that MQXCLWLN be used even when the cache is static, as
this allows migration to a dynamic cache without needing to change the workload
exit.
For more information on dynamic and static cluster caches see CacheType.
C invocation
MQXCLWLN (&ExitParms, CurrentRecord, NextOffset, &NextRecord, &CompCode, &Reason) ;
Declare the parameters as follows:
typedef struct tagMQXCLWLN {
MQWXP ExitParms; /* Exit parameter block */
MQPTR CurrentRecord; /* Address of current record*/
MQLONG NextOffset; /* Offset of next record */
MQPTR NextRecord; /* Address of next record or structure */
MQLONG CompCode; /* Completion code */
MQLONG Reason; /* Reason code qualifying CompCode */
System/390 assembler declaration
CALL MQXCLWLN,(CLWLEXITPARMS,CURRENTRECORD,NEXTOFFSET,NEXTRECORD,COMPCODE,REASON)
Declare the parameters as follows:
CLWLEXITPARMS CMQWXPA, Cluster workload exit parameter block
CURRENTRECORD CMQWDRA, Current record
NEXTOFFSET DS F Next offset
NEXTRECORD DS F Next record
COMPCODE DS F Completion code
REASON DS F Reason code qualifying COMPCODE