Queue Object APIs

Queue objects is the native and basic IPC method in IBM i. They are not only used to synchronize and exchange data between MI processes but also used to coordinate the communication between an MI process and the SLIC; for exmaple, the QMIRQ (MI responce queue). While the most used and well-known types of queue object are DTAQ (Data Queue) and USRQ (User Queue). DTAQ and USRQ share the commons features of a queue object. Their MI object-type code is hex 0A; their MI object-subtype code is hex 01 and hex 02 for DTAQ and USRQ respectively. As to difference between them, you can simply regard USRQ as a more lightweight and powerful while less robust DTAQ.

As an MI object, a queue object has the following "methods" (operations):

• ENQ. Enqueue an entry (message) into a queue object.
• DEQ. Dequeue an entry (message) from a queue object.
• MATQAT. Materialize (retrieve) the attributes of a queue object.
• MATQMSG. Materialize the entries on a queue object, optionally with a specific search argument.
• Create or destroy a queue object. These MI instructions haven't been docuemnted by IBM and could be blocked instructions.

Our queue object APIs are to provide support for operations on USRQs and DTAQs corresponding to the MI instructions ENQ, DEQ, MATQAT, and MATQMSG. (Until V7R1, IBM didn't provide corresponding APIs for USRQ objects.) These queue object APIs can be:

• called by host programs written in any HLLs
• called by remote clients via language specific libraries; for example IBM Toolbox for Java for Java clients and as-400 for ActionScript3 clients.

Content

• Usage Notes
• The Enqueue (ENQ) API

Usage Notes

Here lists a few usage notes:

• The queue object APIs discussed here are implemented based on the ENQ, DEQ, MATQAT, and MATQMSG MI instructions. They're applicable to USRQs or DTAQs. Note that, since the queue object management APIs run in user state, they cannot be used to operate on queue objects in system domain at security level 40 or above, for example, a DTAQ or a USRQ created in system domain.
• The queue object APIs are program objects and hence expect parameters passed by reference, in other words, parameters of type space pointer.
• Prototypes of the queue object APIs in ILE RPG are available through q-api.rpgleinc .

The Enqueue (ENQ) API

The Enqueue (ENQ) API enqueues an entry (or referred to as a message) into a queue object. The prototype of the ENQ API in ILE RPG.

     /*************************************************************/
     /* The Enqueue (ENQ) API                                     */
     /* Enquque a entry (message) to a queue object.              */
     /*                                                           */
     /* @example test/t168.rpgle                                  */
     /*************************************************************/
     d enq             pr                  extpgm('I5TOOLKIT/ENQ')
     /* qualified queue name. char(10) q-name + char(10) lib-name */
     d     q_name                    20a
     /* MI object subtype code. hex 01 for DTAQ, hex 02 for USRQ. */
     d     subtype                    1a
     d     key_len                   10i 0
     d     key                        1a   options(*varsize)
     d     msg_len                   10i 0
     d     msg                        1a   options(*varsize)
     /* optional API error code */
     d     ec                              likeds(qusec_t)
     d                                     options(*nopass)

Examples of in ILE RPG and ILE COBOL

Here're exapmles of using the ENQ API to Work with Queue Object in host HLLs, such as ILE RPG and ILE COBOL.

• ILE RPG program t168.rpgle enqueues a keyed USRQ.
• ILE COBOL program cbl018.cblle enqueues a FIFO USRQ.