Publish/subscribe routing exit parameter structure

Home
Publish/subscribe routing exit parameter structure

The MQPXP structure describes the information that is passed to the publish/subscribe routing exit. The exit is invoked each time a broker sends a publication to a subscriber or to another broker. The exit is also invoked when a stream is initialized or terminated.
This structure is supported in the following environments: AIX, HP-UX, Linux, Solaris, and Windows.

Fields

DestinationQMgrName (MQCHAR48)

Name of destination queue manager.
This is the name of the queue manager to which the message is being sent. The name is padded with blanks to the full length of the field. The name can be altered by the exit.
The length of this field is given by MQ_Q_MGR_NAME_LENGTH. This is an input/output field to the exit.

DestinationQName (MQCHAR48)

Name of destination queue.
This is the name of the queue to which the message is being sent. The name is padded with blanks to the full length of the field. The name can be altered by the exit.
The length of this field is given by MQ_Q_NAME_LENGTH. This is an input/output field to the exit.

DestinationType (MQLONG)

Type of destination for message.
This is the type of the destination to which the message is being sent. It is one of the following:

MQDT_APPL

Application.

MQDT_BROKER

Broker.

This is an input field to the exit.

ExitData (MQCHAR32)

Exit data.
This is the fixed exit data defined by the RoutingExitData parameter of the Broker stanza in the queue manager's initialization file. 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, this field is completely blank.
The length of this field is given by MQ_EXIT_DATA_LENGTH. This is an input field to the exit.

ExitId (MQLONG)

Type of exit.
This indicates the type of exit being called. The value is:

MQXT_PUBSUB_ROUTING_EXIT

Publish/subscribe routing exit.

This is an input field to the exit.

ExitNumber (MQLONG)

Exit number.
This is the sequence number of the exit. The value is one.
This is an input field to the exit.

ExitReason (MQLONG)

Reason for invoking exit.
This indicates the reason why the exit is being called. Possible values are:

MQXR_INIT

Exit initialization.
This indicates that the exit for the stream identified by the StreamName field is being invoked for the first time. It allows the exit to acquire and initialize any resources that it might need (for example: main storage).

MQXR_TERM

Exit termination.
This indicates that the exit for the stream identified by the StreamName field is about to be terminated. The exit should free any resources that it has acquired since it was initialized (for example: main storage).

MQXR_MSG

Process a message.
This indicates that the exit is being invoked to process a message.

This is an input field to the exit.

ExitResponse (MQLONG)

Response from exit.
This is set by the exit to indicate how processing should continue. It must be one of the following:

MQXCC_OK

Continue normally.
This indicates that processing should continue normally. It is valid for all values of ExitReason.
When ExitReason has the value MQXR_MSG, DestinationQName and DestinationQMgrName identify the destination to which the message should be sent.

MQXCC_SUPPRESS_FUNCTION

Suppress function.
This indicates that the normal processing of the message should be discontinued. It is valid only when ExitReason has the value MQXR_MSG.
The processing performed on the message is determined by the MQRO_DISCARD_MSG option in the Report field of the message descriptor of the message:

If the exit specifies MQRO_DISCARD_MSG, the message is discarded.
If the exit does not specify MQRO_DISCARD_MSG, the message is placed on the dead-letter queue (undelivered-message queue). If there is no dead-letter queue, or the message cannot be placed successfully on the dead-letter queue:

The message is discarded if the Persistence field in the message descriptor has the value MQPER_NOT_PERSISTENT and the DiscardNonPersistentPublication parameter in the queue manager's initialization file has the value yes.
In all other cases, the message is retried intermittently.

MQXCC_SUPPRESS_EXIT

Suppress exit.
This indicates that the exit should not be invoked again until termination of the stream. It is valid only when ExitReason has the value MQXR_INIT or MQXR_MSG.
The broker processes subsequent messages as if no publish/subscribe routing exit were defined. Processing of the current message (if there is one) continues normally; DestinationQName and DestinationQMgrName identify the destination to which the current message should be sent.

If any other value is returned by the exit, the broker processes the message as if MQXCC_OK had been specified.
This is an output field from the exit.

ExitResponse2 (MQLONG)

Reserved.
This is a reserved field. The value is zero.

ExitUserArea (MQBYTE16)

Exit user area.
This is a field that is available for the exit to use. It is initialized to MQXUA_NONE (binary zero) on the first invocation of the exit for the stream, and thereafter any changes made to this field by the exit are preserved across invocations of the exit. The first invocation of the exit is indicated by the ExitReason field having the value MQXR_INIT. There is a separate ExitUserArea for each stream.
The following value is defined:

MQXUA_NONE

No user information.
The value is binary zero for the length of the field.
For the C programming language, the constant MQXUA_NONE_ARRAY is also defined; this has the same value as MQXUA_NONE, but is an array of characters instead of a string.

The length of this field is given by MQ_EXIT_USER_AREA_LENGTH. This is an input/output field to the exit.

Feedback (MQLONG)

Feedback code.
This is the feedback code to be used if the exit returns MQXCC_SUPPRESS_FUNCTION in the ExitResponse field.
On input to the exit, this field always has the value MQFB_NONE. If the exit decides to return MQXCC_SUPPRESS_FUNCTION, the exit should set Feedback to the value to be used for the message when the broker places it on the dead-letter queue.
If MQXCC_SUPPRESS_FUNCTION is returned by the exit, but Feedback still has the value MQFB_NONE, the following feedback code is used:

MQFB_STOPPED_BY_PUBSUB_EXIT

Message stopped by publish/subscribe routing exit.

This is an input/output field to the exit.

HeaderLength (MQLONG)

Reserved.
This is a reserved field. The value is zero.
This is an input field to the exit.

MsgDescPtr (PMQMD)

Address of message descriptor.
This is the address of the message descriptor (MQMD) of the message being processed. The exit can change the contents of the message descriptor, so use it with care. In particular:

If DestinationType has the value MQDT_BROKER, 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.
This is an input field to the exit.

MsgInLength (MQLONG)

Length of input message data.
This is the length in bytes of the message data passed to the exit. The address of the data is given by MsgInPtr.
This is an input field to the exit.

MsgInPtr (PMQVOID)

Address of input message data.
This is the address of a buffer containing the message data that is input to the exit. The contents of this buffer can be modified by the exit; see MsgOutPtr.
This is an input field to the exit.

MsgOutLength (MQLONG)

Length of output message data.
This is the length in bytes of the message data returned by the exit. On input to the exit, this field is always zero. On output from the exit, this field is ignored if MsgOutPtr is the null pointer. See the description of the MsgOutPtr field for information about modifying the message data.
This is an input/output field to the exit.

MsgOutPtr (PMQVOID)

Address of output message data.
This is the address of a buffer containing the message data that is output from the exit. On input to the exit, this field is always the null pointer. On output from the exit, if the value is still the null pointer, the broker sends the message specified by MsgInPtr, with the length given by MsgInLength.
If the exit needs to modify 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 buffer of the required size and copy the modified data into it. In this case MsgOutPtr must be set to the address of the new buffer, and MsgOutLength set to the new length of the message data. The exit is responsible for freeing the buffer on a subsequent invocation of the exit.
Note:
Because MsgOutPtr is always the null pointer on input to the exit, the exit must save the address of the buffer it obtains, either in ExitUserArea, or in a control block whose address is saved in ExitUserArea.

This is an input/output field to the exit.

QMgrName (MQCHAR48)

Name of local queue manager.
This 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. This is an input field to the exit.

StreamName (MQCHAR48)

Name of stream.
This is the name of the stream to which the message belongs. The name is padded with blanks to the full length of the field.
The length of this field is given by MQ_OBJECT_NAME_LENGTH. This is an input field to the exit.

StrucId (MQCHAR4)

Structure identifier.
Possible values are:

MQPXP_STRUC_ID

Identifier for publish/subscribe routing-exit parameter structure.
For the C programming language, the constant MQPXP_STRUC_ID_ARRAY is also defined; this has the same value as MQPXP_STRUC_ID, but is an array of characters instead of a string.

This is an input field to the exit.

V(MQLONG)

Structure version number.
The value is:

MQPXP_VERSION_1

Version-1 publish/subscribe routing-exit parameter structure.

MQPXP_CURRENT_VERSION

Current version of publish/subscribe routing-exit parameter structure.

This is an input field to the exit.

C declaration
typedef struct tagMQPXP {
  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 */
  MQLONG    ExitNumber;           /* Exit number */
  MQBYTE16  ExitUserArea;         /* Exit user area */
  MQCHAR32  ExitData;             /* Exit data */
  MQLONG    HeaderLength;         /* Reserved */
  MQLONG    MsgInLength;          /* Length of input message data */
  MQLONG    MsgOutLength;         /* Length of output message data */
  MQLONG    DestinationType;      /* Type of destination for message */
  PMQMD     MsgDescPtr;           /* Address of message descriptor */
  PMQVOID   MsgInPtr;             /* Address of input message data */
  PMQVOID   MsgOutPtr;            /* Address of output message data */
  MQCHAR48  StreamName;           /* Name of stream */
  MQCHAR48  QMgrName;             /* Name of local queue manager */
  MQCHAR48  DestinationQName;     /* Name of destination queue */
  MQCHAR48  DestinationQMgrName;  /* Name of destination queue
                                     manager */
 } MQPXP;
Home