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:

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:

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:

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