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.
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 enqueues an entry (or referred to as a message
) into a queue object. The prototype of the ENQ API in ILE RPG.
d enq pr extpgm('I5TOOLKIT/ENQ')
d q_name 20a
d subtype 1a
d key_len 10i 0
d key 1a options(*varsize)
d msg_len 10i 0
d msg 1a options(*varsize)
d ec likeds(qusec_t)
Here're exapmles of using the ENQ API to Work with Queue Object in host HLLs, such as ILE RPG and ILE COBOL.