[UNIX, Linux, Windows, IBM i]

Writing API exits

You can write exits for every API call using the C programming language.

Available exits

Exits are available for every API call, as follows:
  • MQCB, to reregister a callback for the specified object handle and control activation and changes to the callback
  • MQCTL, to perform controlling actions on the object handles opened for a connection
  • MQCONN/MQCONNX, to provide a queue manager connection handle for use on subsequent API calls
  • MQDISC, to disconnect from a queue manager
  • MQBEGIN, to begin a global unit of work (UOW)
  • MQBACK, to back out a UOW
  • MQCMIT, to commit a UOW
  • MQOPEN, to open an IBM® MQ resource for subsequent access
  • MQCLOSE, to close an IBM MQ resource that had previously been opened for access
  • MQGET, to retrieve a message from a queue that has previously been opened for access
  • MQPUT1, to place a message on to a queue
  • MQPUT, to place a message on to a queue that has previously been opened for access
  • MQINQ, to inquire on the attributes of an IBM MQ resource that has previously been opened for access
  • MQSET, to set the attributes of a queue that has previously been opened for access
  • MQSTAT, to retrieve status information
  • MQSUB, to register the applications subscription to a particular topic
  • MQSUBRQ, to make a request for a subscription

MQ_CALLBACK_EXIT provides an exit function to perform before and after callback processing. For more information, see Callback - MQ_CALLBACK_EXIT.

Writing API exits

Within API exits, the calls take the general form: 

MQ_call_EXIT (parameters, context, ApiCallParameters)
where call is the MQI call name without the MQ prefix; for example, PUT, GET. The parameters control the function of the exit, primarily providing communication between the exit and the external control blocks MQAXP (the API exit parameter structure) and MQAXC (the API exit context structure). context describes the context in which the API exit was called, and ApiCallParameters represent the parameters to the MQI call.

To help you write your API exit, a sample exit, amqsaxe0.c, is provided; this exit generates trace entries to a file that you specify. You can use this sample as your starting point when writing exits. For more information about using the sample exit, see The API exit sample program.

For more information about the API exit calls, external control blocks, and associated topics, see API exit reference.

For general information on how to write, compile and configure an exit, see Writing exits and installable services on AIX, Linux, and Windows.

Using message handles in API exits

You can control which message properties an API exit has access to. Properties are associated with an ExitMsgHandle. Properties set in a put exit are set on the message being put, but properties retrieved in a get exit are not returned to the application.

When you register an MQ_INIT_EXIT exit function using the MQXEP MQI call with Function set to MQXF_INIT and ExitReason set to MQXR_CONNECTION, you pass in an MQXEPO structure as the ExitOpts parameter. The MQXEPO structure contains the ExitProperties field, which specifies the set of properties to be made available to the exit. It is specified as a character string representing the prefix of the properties, which corresponds to an MQRFH2 folder name.

Each API exit receives an MQAXP structure, containing an ExitMsgHandle field. This field is set to a value generated by IBM MQ and is specific to a connection. The handle is therefore unchanged between API exits of the same or different types on the same connection.

In an MQ_PUT_EXIT or MQ_PUT1_EXIT with an ExitReason of MQXR_BEFORE, that is, an API exit performed before putting a message, any properties (other than message descriptor properties) associated with the ExitMsgHandle when the exit completes are set on the message being put. To prevent this happening, set ExitMsgHandle to MQHM_NONE. You can also supply a different message handle.

In an MQ_GET_EXIT and MQ_CALLBACK_EXIT, the ExitMsgHandle is cleared of properties and populated with the properties specified in the ExitProperties field when the MQ_INIT_EXIT was registered, other than message descriptor properties. These properties are not made available to the getting application. If the getting application specified a message handle in the MQGMO (Get message options) field, then any properties associated with that handle, including message descriptor properties, are available to the API exit. To prevent the ExitMsgHandle being populated with properties, set it to MQHM_NONE.
Note: For exit message properties to be processed in:
  • An after MQ_GET_EXIT function, you must define a before MQ_GET_EXIT function for the exit.
  • A before MQ_CALLBACK_EXIT function, you must define a before MQ_CB_EXIT function for the exit.

[MQ 9.3.2 Feb 2023]From IBM MQ 9.3.2, the previous statements concerning MQ-GET-EXIT and MQ_CALLBACK_EXIT no longer apply.

A sample program, amqsaem0.c, is provided to illustrate the use of message handles in API exits.