MQPSXP - Publish exit data structure

The MQPSXP structure describes the information that is passed to and returned from the publish exit.

Fields

StrucID (MQCHAR4)

StrucID is the structure identifier. The value is as follows:

MQPSXP_STRUCID

MQPSXP_STRUCID is the identifier for the publish exit parameter structure. For the C programming language, the constant MQPSXP_STRUC_ID_ARRAY is also defined; it has the same value as MQPSXP_STRUC_ID, but is an array of characters instead of a string.

StrucID is an input field to the exit.

Version (MQLONG)

Version is the structure version number. The value is as follows:

MQPSXP_VERSION_1

MQPSXP_VERSION_1 is the Version 1 publish exit parameter structure. The constant MQPSXP_CURRENT_VERSION is also defined with the same value.

Version is an input field to the exit.

ExitId (MQLONG)

ExitId is the type of exit that is being called. The value is as follows:

MQXT_PUBLISH_EXIT

Publish exit.

ExitId is an input field to the exit.

ExitReason (MQLONG)

ExitReason is the reason for calling the exit. The possible values are:

MQXR_INIT

The exit for this connection is called for initialization. The exit might acquire and initialize the resources that it needs; for example, main storage.

MQXR_TERM

The exit for this connection is called because the exit is about to be stopped. The exit must free any resources that it has acquired since it was initialized; for example, main storage.

MQXR_PUBLICATION

The exit is called by the queue manager before it puts a publication onto a message queue of a subscriber. The exit can change the message, not put the message on the queue, or halt publication.

ExitReason is an input field to the exit.

ExitResponse (MQLONG)

Set ExitResponse in the exit to specify how processing must continue. ExitResponse is one of the following values:

MQXCC_OK

Set MQXCC_OK to continue processing normally. Set MQXCC_OK in response to any values of ExitReason.

If ExitReason has the value MQXR_PUBLICATION, the DestinationQName and DestinationQMgrName fields of the MQSBC structure identify the destination to which the message is sent.

MQXCC_FAILED

Set MQXCC_FAILED to stop the publish operation. The completion code MQCC_FAILED and reason code 2557 (09FD) (RC2557): MQRC_PUBLISH_EXIT_ERROR is set on return from the exit.

MQXCC_SUPPRESS_FUNCTION

Set MQXCC_SUPPRESS_FUNCTION to stop normal processing of the message. Only set MQXCC_SUPPRESS_FUNCTION if ExitReason has the value MQXR_PUBLICATION.

The message continues to be processed by the queue manager according to the MQRO_DISCARD_MSG option in the Report field in the message descriptor of the message.

• If the MQRO_DISCARD_MSG option is specified, the message is not delivered to the subscriber.
• If the MQRO_DISCARD_MSG option is not specified, the message is placed on the dead-letter queue. If there is no dead-letter queue, or the message cannot be placed successfully on the dead-letter queue, the publication is not delivered to the subscriber. The delivery of the publication to other subscribers depends on the values of the PMSGDLV and NPMSGDLV topic object attributes. For an explanation of these attributes, see the parameter descriptions for the DEFINE TOPIC command.

ExitResponse is an output field from the exit.

ExitResponse2 (MQLONG)

ExitResponse2 is reserved for future use.

Feedback (MQLONG)

Feedback is the feedback code to be used if the exit returns MQXCC_SUPPRESS_FUNCTION in ExitResponse.

On input to the exit, Feedback always has the value MQFB_NONE. If the exit returns MQXCC_SUPPRESS_FUNCTION, set Feedback to the value to be used for the message when the queue manager places it on the dead-letter queue. On return from the exit, if Feedback has the original value MQFB_NONE, the queue manager sets Feedback to MQFB_STOPPED_BY_PUBSUB_EXIT.

Feedback is an input/output field to the exit.

ExitUserArea (MQBYTE16)

ExitUserArea is a field that is available for the exit to use. Each connection has a separate ExitUserArea. The length of ExitUserArea is given by MQ_EXIT_USER_AREA_LENGTH.

The ExitReason field has the value MQXR_INIT on the first invocation of the exit. ExitUserArea is initialized to MQXUA_NONE on the first invocation of the exit for a connection. Subsequent changes to ExitUserArea are preserved across invocations of the exit.

ExitUserArea is an input/output field to the exit.

ExitData (MQCHAR32)

ExitData is fixed exit data defined by the PublishExitData parameter of the stanza in the initialization file of the queue manager. The data is padded with blanks to the full length of the field. If there is no fixed exit data defined in the initialization file, ExitData is blank. The length of ExitData is given by MQ_EXIT_DATA_LENGTH.

ExitData is an input field to the exit.

QMgrName (MQCHAR48)

QMgrName is the name of the local queue manager. The name is padded with blanks to the full length of the field. The length of this field is given by MQ_Q_MGR_NAME_LENGTH.

QMgrName is an input field to the exit.

Hconn (MQHCONN)

Hconn is the handle representing a connection to the queue manager. Only use Hconn as a parameter to the MQSETMP, MQINQMMP, or MQDLTMP message property function calls to work with message properties.

Hconn is an input field to the exit.

MsgDescPtr (PMQMD)

MsgDescPtr is the address of message descriptor ( MQMD) of the message being processed, and is a copy of the MQMD returned from the MQPUT call. The exit can change the contents of the message descriptor. Any change to the contents of the message descriptor must be done with care. In particular, in the case where the SubType field of the MQSBC structure is of value MQSUBTYPE_PROXY, the CorrelId field in the message descriptor must not be changed.

No message descriptor is passed to the exit if ExitReason is MQXR_INIT or MQXR_TERM ; in these cases, MsgDescPtr is the null pointer.

MsgDescPtr is an input field to the exit.

MsgHandle (MQHMSG)

MsgHandle is the handle to message properties. Only use MsgHandle with the MQSETMP, MQINQMMP, or MQDLTMP message property function calls to work with message properties.

MsgHandle is an input field to the exit.

MsgInPtr (PMQVOID)

MsgInPtr is the address of the input message data. The contents of the buffer addressed by MsgInPtr can be modified by the exit; see MsgOutPtr .

MsgInPtr is an input field to the exit.

MsgInLength (MQLONG)

MsgInLength is the length in bytes of the message data passed to the exit. The address of the data is given by MsgInPtr.

MsgInLength is an input field to the exit.

MsgOutPtr (PMQVOID)

MsgOutPtr is the address of a buffer containing message data that is returned from the exit. On entry to the exit, MsgOutPtr is null. On return from the exit, if the value is still null, the queue manager sends the message specified by MsgInPtr, with the length given by MsgInLength. If the exit modifies the message data, use one of the following procedures:

• If the length of the data does not change, the data can be modified in the buffer addressed by MsgInPtr. In this case, do not change MsgOutPtr and MsgOutLength.
• If the modified data is shorter than the original data, the data can be modified in the buffer addressed by MsgInPtr. In this case MsgOutPtr must be set to the address of the input message buffer, and MsgOutLength set to the new length of the message data.
• If the modified data is, or might be, longer than the original data, the exit must obtain a new message buffer. Copy the modified data into it. Set MsgOutPtr to the address of the new buffer, and set MsgOutLength to the length of the new message data. The exit is responsible for freeing the buffer addressed by MsgOutPtr when the exit is next called.

Note: MsgOutPtr is always the null pointer on input to the exit, and not the address of a previously obtained message buffer. To free the previously obtained buffer, the exit must save its address and length. Save the information either in ExitUserArea, or in a control block that has its address saved in ExitUserArea.

MsgOutPtr is an input/output field to the exit.

MsgOutLength (MQLONG)

MsgOutLength is the length in bytes of the message data returned by the exit. On input to the exit, this field is always zero. On return from the exit, this field is ignored if MsgOutPtr is null. See MsgOutPtr for information about modifying the message data.

MsgOutLength is an input/output field to the exit.

pEntryPoints (PMQIEP)

pEntryPoints is the address of an MQIEP structure through which MQI and DCI calls can be made.

C language declaration - MQPSXP

typedef struct tagMQPSXP {
	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;            /* Feedback code */
	MQBYTE16   ExitUserArea;        /* Exit user area */
	MQCHAR32   ExitData;            /* Exit data */
	MQCHAR48   QMgrName;            /* Name of local queue manager */
	MQHCONN    Hconn;               /* Connection handle */
	MQHMSG     MsgHandle;           /* Handle to message properties */
	PMQMD      MsgDescPtr;          /* Address of message descriptor */
	PMQVOID    MsgInPtr;            /* Address of input message data */
	MQLONG     MsgInLength;         /* Length of input message data */
	PMQVOID    MsgOutPtr;           /* Address of output message data */
	MQLONG     MsgOutLength;        /* Length of output message data */
	/* Ver:1 */
	PMQIEP     pEntryPoints;        /* Address of the MQIEP structure */
	/* Ver:2 */
}	MQPSXP;