Fields in MQWXP - Cluster workload exit parameter structure

Description of the fields in the MQWXP - Cluster workload exit parameter structure

    StrucId (MQCHAR4) - input
    The structure identifier for the cluster workload exit parameter structure.

    • The StrucId value is MQWXP_STRUC_ID.
    • For the C programming language, the constant MQWXP_STRUC_ID_ARRAY is also defined. It has the same value as MQWXP_STRUC_ID. It is an array of characters instead of a string.

    Version (MQLONG) - input
    Indicates the structure version number. Version takes one of the following values:

      MQWXP_VERSION_1
      Version-1 cluster workload exit parameter structure.
      MQWXP_VERSION_1 is supported in all environments.

      MQWXP_VERSION_2
      Version-2 cluster workload exit parameter structure.
      MQWXP_VERSION_2 is supported in the following environments:

      • AIX
      • IBM i
      • Linux
      • Windows

      MQWXP_VERSION_3
      Version-3 cluster workload exit parameter structure.
      MQWXP_VERSION_3 is supported in the following environments:

      • AIX
      • IBM i
      • Linux
      • Windows

      MQWXP_VERSION_4
      Version-4 cluster workload exit parameter structure.
      MQWXP_VERSION_4 is supported in the following environments:

      • AIX
      • IBM i
      • Linux
      • Windows

      MQWXP_CURRENT_VERSION
      Current version of cluster workload exit parameter structure.

    ExitId (MQLONG) - input
    Indicates the type of exit being called. The cluster workload exit is the only supported exit.

    • The ExitId value must be MQXT_CLUSTER_WORKLOAD_EXIT

    ExitReason (MQLONG) - input
    Indicates the reason for invoking the cluster workload exit. ExitReason takes one of the following values:

      MQXR_INIT
      Indicates that the exit is being invoked for the first time.
      Acquire and initialize any resources that the exit might need, such as main storage.

      MQXR_TERM
      Indicates that the exit is about to be terminated.
      Free any resources that the exit might have acquired since it was initialized, such as main storage.

      MQXR_CLWL_OPEN
      Called by MQOPEN.

      MQXR_CLWL_PUT
      Called by MQPUT or MQPUT1.

      MQXR_CLWL_MOVE
      Called by MCA when the channel state has changed.

      MQXR_CLWL_REPOS
      Called by MQPUT or MQPUT1 for a repository-manager PCF message.

      MQXR_CLWL_REPOS_MOVE
      Called by MCA for a repository-manager PCF message if the channel state has changed.

    ExitResponse (MQLONG) - output
    Set ExitResponse to indicate whether processing of the message continues. It must be one of the following values:

      MQXCC_OK
      Continue processing the message normally.

      • DestinationChosen identifies the destination to which the message is to be sent.

      MQXCC_SUPPRESS_FUNCTION
      Discontinue processing the message.

      • The actions taken by the queue manager depend on the reason the exit was invoked:

        ExitReason Action taken

        • MQXR_CLWL_OPEN
        • MQXR_CLWL_REPOS
        • MQXR_CLWL_PUT

        		MQOPEN, MQPUT, or MQPUT1 call fail with completion code MQCC_FAILED and reason code MQRC_STOPPED_BY_CLUSTER_EXIT.

        • MQXR_CLWL_MOVE
        • MQXR_CLWL_REPOS_MOVE

        		The message is placed on the dead-letter queue.

      MQXCC_SUPPRESS_EXIT
      Continue processing the current message normally. Do not invoke the exit again until the queue manager shuts down.
      The queue manager processes subsequent messages as if the ClusterWorkloadExit queue manager attribute is blank. DestinationChosen identifies the destination to which the current message is sent.

      Any other value
      Process the message as if MQXCC_SUPPRESS_FUNCTION is specified.

    ExitResponse2 (MQLONG) - input/output
    Set ExitResponse2 to provide the queue manager with more information.

    • MQXR2_STATIC_CACHE is the default value, and is set on entry to the exit.
    • When ExitReason has the value MQXR_INIT, the exit can set one of the following values in ExitResponse2:

        MQXR2_STATIC_CACHE
        The exit requires a static cluster cache.

        • If the cluster cache is static, the exit need not use the MQXCLWLN call to navigate the chains of records in the cluster cache.
        • If the cluster cache is dynamic, the exit cannot navigate correctly through the records in the cache. Note: 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
        The 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.

    Feedback (MQLONG) - input
    A reserved field. The value is zero.

    Flags (MQLONG) - input
    Indicates information about the message being put.

    • The value of Flags is MQWXP_PUT_BY_CLUSTER_CHL. The message originates from a cluster channel, rather than locally or from a non-cluster channel. In other words, the message has come from another cluster queue manager.

    Reserved (MQLONG) - input
    A reserved field. The value is zero.

    ExitUserArea (MQBYTE16) - input/output
    Set ExitUserArea to communicate between calls to the exit.

    • ExitUserArea is initialized to 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 binary zero when the MQDISC call occurs.
    • The first invocation of the exit is indicated by the ExitReason field having the value MQXR_INIT.
    • The following constants are defined:

        MQXUA_NONE - string

        MQXUA_NONE_ARRAY - character array
        No user information. Both constants are binary zero for the length of the field.

        MQ_EXIT_USER_AREA_LENGTH
        The length of ExitUserArea.

    ExitData (MQCHAR32) - input
    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 ExitData is given by MQ_EXIT_DATA_LENGTH.

    MsgDescPtr (PMQMD) - input
    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.
    • If ExitReason has one of the following values MsgDescPtr is set to the null pointer, and no message descriptor is passed to the exit:

      • MQXR_INIT
      • MQXR_TERM
      • MQXR_CLWL_OPEN

    MsgBufferPtr (PMQVOID) - input
    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.

    MsgBufferLength (MQLONG) - input
    The length of the buffer containing the message data passed to the exit.

    • The length is controlled by the ClusterWorkloadLength queue manager attribute.
    • The length might be less than the length of the complete message, see MsgLength.

    MsgLength (MQLONG) - input
    The length of the complete message 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.

    QName (MQCHAR48) - input
    The name of the destination queue. The queue is a cluster queue.

    • The length of QName is MQ_Q_NAME_LENGTH.

    QMgrName (MQCHAR48) - input
    The name of the local queue manager that has invoked the cluster workload exit.

    • The length of QMgrName is MQ_Q_MGR_NAME_LENGTH.

    DestinationCount (MQLONG) - input
    The number of possible destinations. Destinations are instances of the destination queue and are described by destination records.

    • A destination record is a MQWDR structure. There is one structure for each possible route to each instance of the queue.
    • MQWDR structures are addressed by an array of pointers, see DestinationArrayPtr.

    DestinationChosen (MQLONG) - input/output
    The chosen destination.

    • The number of the MQWDR structure that identifies the route and queue instance where the message is to be sent.
    • The value is in the range 1 - 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.
    • The value set by the exit must be in the range 1 - DestinationCount. If any other value is returned, the queue manager uses the value of DestinationChosen on input to the exit.

    DestinationArrayPtr (PPMQWDR) - input
    The address of an array of pointers to destination records (MQWDR).

    • There are DestinationCount destination records.

    QArrayPtr (PPMQWQR) - input
    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.

    CacheContext (MQPTR) : Version 2 - input
    The CacheContext field is reserved for use by the queue manager. The exit must not alter the value of this field.

    CacheType (MQLONG) : Version 2 - input
    The cluster cache has one of the following types:

      MQCLCT_STATIC
      The cache is static.

      • The size of the cache is fixed, and cannot grow as the queue manager operates.
      • You do not need to use the MQXCLWLN call to navigate the records in this type of cache.

      MQCLCT_DYNAMIC
      The cache is dynamic.

      • The size of the cache can increase in order to accommodate the varying cluster information.
      • We must use the MQXCLWLN call to navigate the records in this type of cache.

    CLWLMRUChannels (MQLONG) : Version 3 - input
    Indicates the maximum number of active outbound cluster channels, to be considered for use by the cluster workload choice algorithm.

    • CLWLMRUChannels is a value 1 - 999 999 999.

    pEntryPoints (PMQIEP) : Version 4
    The address of an MQIEP structure through which MQI and DCI calls can be made.

Parent topic: MQWXP - Cluster workload exit parameter structure


Related reference