MQPSXP - Publish exit data structure
The MQPSXP
structure describes the information that is passed to and returned from the publish exit.
Field | Description |
---|---|
StrucID |
Structure identifier |
Version |
Structure version number |
ExitId |
Type of exit that is being called |
ExitReason |
Reason for calling the exit |
ExitResponse |
Response from the exit |
ExitResponse2 |
Secondary response from exit |
Feedback |
Feedback code |
ExitUserArea |
Exit user area |
ExitData |
Exit data |
QMgrName |
Name of local queue manager |
Hconn |
Connection handle |
MsgDescPtr |
Address of message descriptor (MQMD) |
MsgHandle |
Handle to message properties (MQHMSG) |
MsgInPtr |
Address of input message |
MsgInLength |
Length of input message |
MsgOutPtr |
Address of output message |
MsgOutLength |
Length of output message |
pEntryPoints |
Address of the MQIEP structure |
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 constantMQPSXP_STRUC_ID_ARRAY
is also defined; it has the same value asMQPSXP_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 constantMQPSXP_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. SetMQXCC_OK
in response to any values ofExitReason
. MQXCC_FAILED
- Set
MQXCC_FAILED
to stop the publish operation. The completion codeMQCC_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 setMQXCC_SUPPRESS_FUNCTION
ifExitReason
has the valueMQXR_PUBLICATION
.
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 returnsMQXCC_SUPPRESS_FUNCTION
inExitResponse
.On input to the exit,
Feedback
always has the valueMQFB_NONE
. If the exit returnsMQXCC_SUPPRESS_FUNCTION
, setFeedback
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, ifFeedback
has the original valueMQFB_NONE
, the queue manager setsFeedback
toMQFB_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 separateExitUserArea
. The length ofExitUserArea
is given byMQ_EXIT_USER_AREA_LENGTH
.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 ofExitData
is given byMQ_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 byMQ_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 useHconn
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 theSubType
field of theMQSBC
structure is of valueMQSUBTYPE_PROXY
, theCorrelId
field in the message descriptor must not be changed.No message descriptor is passed to the exit if
ExitReason
isMQXR_INIT
orMQXR_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 useMsgHandle
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 byMsgInPtr
can be modified by the exit; seeMsgOutPtr
.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 byMsgInPtr
.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 byMsgInPtr
, with the length given byMsgInLength
.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 changeMsgOutPtr
andMsgOutLength
. - If the modified data is shorter than the original data, the data can be modified in the buffer addressed by
MsgInPtr
. In this caseMsgOutPtr
must be set to the address of the input message buffer, andMsgOutLength
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 setMsgOutLength
to the length of the new message data. The exit is responsible for freeing the buffer addressed byMsgOutPtr
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 inExitUserArea
, or in a control block that has its address saved inExitUserArea
.MsgOutPtr
is an input/output field to the exit.- If the length of the data does not change, the data can be modified in the buffer addressed by
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 ifMsgOutPtr
is null. SeeMsgOutPtr
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;