MQListener in Db2 for z/OS

Db2 for z/OS® provides an asynchronous listener, MQListener. MQListener is a framework for tasks that read from IBM® MQ queues and call Db2 stored procedures with messages as those messages arrive.

MQListener combines messaging with database operations. You can configure the MQListener daemon to listen to the IBM MQ message queues that you specify in a configuration database. MQListener reads the messages that arrive from the queue and calls Db2 stored procedures using the messages as input parameters. If the message requires a reply, MQListener creates a reply from the output that is generated by the stored procedure. The message retrieval order is fixed at the highest priority first, and then within each priority the first message received is the first message served.

MQListener runs as a single multi-threaded process on z/OS UNIX System Services. Each thread or task establishes a connection to its configured message queue for input. Each task also connects to a Db2 database on which to run the stored procedure. The information about the queue and the stored procedure is stored in a table in the configuration database. The combination of the queue and the stored procedure is a task.

MQListener tasks are grouped together into named configurations. By default, the configuration name is empty. If you do not specify the name of a configuration for a task, MQListener uses the configuration with an empty name.

Transaction support in MQListener

There is support for both one-phase and two-phase commit environments. A one-phase commit environment is where DB interactions and MQ interactions are independent. A two-phase commit environment is where DB interactions and MQ interactions are combined in a single unit of work.

'db2mqln1' is the name of the executable for one phase and 'db2mqln2' is the name of the executable for two phase.

Logical ordering of messages in MQListener

The two-phase commit version of the MQListener stored procedure processes messages that are in a group in logical order. The single-phase commit version of the MQListener stored procedure processes messages that are in a group in physical order.

MQListener stored procedure interfaces

The MQListener interface supports two stored procedure formats: with either two or three parameters.

Start of changeThe data type and length of the stored procedure parameters are determined when the MQListener is started. If you change the data type or length of the parameters, the change takes effect when you restart the MQListener. You can use the following commands to restart the MQListener:End of change

mqlistener-command mqlistener-command admin 
    -adminQueue adminqueue-name
    -adminQMgr adminqueuemanager-name
    -adminCommand restart
Start of change

MQListener stored procedure interface with two parameters

This stored procedure interface for MQListener takes the incoming message as input and returns the reply, which might be NULL, as output. For example:

CREATE schema.proc(
 IN INMSG inMsgType, 
 OUT OUTMSG outMsgType)...

The data type for INMSG and the data type for OUTMSG can be VARCHAR, VARBINARY, CLOB, or BLOB, of any length, and are determined at startup. The input data type and output data type can be different data types. Start of changeIf an incoming message is a request or a datagram and has a specified reply-to queue, the message in OUTMSG is sent to the specified queue.End of change The incoming message can be one of the following message types:

  • Datagram
  • Datagram with report requested
  • Request message with reply
  • Request message with reply and report requested
End of change
Start of change

MQListener stored procedure interface with three parameters

This stored procedure interface for MQListener has parameters with the following information:

  • An incoming message as input
  • A reply, which might be NULL, as output
  • A message header, which can be input or output

For example:

CREATE schema.proc(
 IN INMSG inMsgType, 
 OUT OUTMSG outMsgType, 
 INOUT MSGHEADER msgHeaderType)...

The data type for INMSG and the data type for OUTMSG can be VARCHAR, VARBINARY, CLOB, or BLOB, of any length, and are determined at startup. The input data type and output data type can be different data types. Start of changeIf an incoming message is a request or a datagram and has a specified reply-to queue, the message in OUTMSG is sent to the specified queue.End of change The incoming message can be one of the following message types:

  • Datagram
  • Datagram with report requested
  • Request message with reply
  • Request message with reply and report requested

Start of changeThe data type for MSGHEADER can be VARBINARY or BLOB. The minimum length of MSGHEADER is 324, which is the size of the message queuing message descriptor (MQMD) structure for IBM MQ messages. End of change

Start of changeMQListener passes the message header to the stored procedure in the MSGHEADER parameter. The stored procedure can get the message descriptor properties from the MSGHEADER parameter. If the message is a request message, the stored procedure can specify the properties for the reply queue and reply queue manager in the MSGHEADER parameter. The output message in OUTMSG is sent to that specified queue.End of change

End of change