Support This Project Get i5/OS Programmer's Toolkit at SourceForge.net. Fast, secure and Free Open Source software downloads

The DEQUSRQ (Dequeue User Queue) API

Go back to main page of i5/OS Programmer's Toolkit.

The DEQUSRQ (Dequeue User Queue) API dequeues a message from a keyed or FIFO/LIFO user queue. This API frees a HLL programmer from dealing with the DEQ instruction directly when dequeuing a user queue.

Parameters of DEQUSRQ

Num Parameter Name Input/Output Parameter Type and Length Remark
1 Queue Object in char(20) Queue name and queue library, e.g. 'Q_NAME Q_LIB'
2 Time Enqueued out char(26) Timestamp in ISO format
3 Wait Flag in char(1) '0', do NOT wait; '1', wait
4 Timeout Value in bin(4) Timeout value in seconds. A negative timeout value means to wait indefinitely. If wait flag is set to '0', this parameter is ignored.
5 Access-state Flag in char(1) '0', do not modify the PAG access state; '1', modify the PAG access state
6 MPL Option in char(1) '0', leave current MPL; '1', remain in current MPL
7 Key Data in/out char(*) On input, represents the selection key; on output, contains the key data of the dequeued messsage
8 Key Relation in char(2) The relation bwteen the actual key and the selection key. Valid inputs are: 'GT', 'LT', 'NE', 'EQ', 'GE', 'LE'.
9 Key Length in bin(4) Input key length, must be equal to or greater than actural key length of a user queue.
10 Key Length Returned out(4) bin(4) The actural key length of the user queue or 0 if the queue is non-keyed.
11 Message Text out char(*) Message text of the dequeued message.
12 Message Text Length in bin(4) Length of user provied buffer.
13 Message Text Length Available out bin(4) Actual message text length of the dequeued message

Remarks:
If Wait Flag is set to '0' (don't wait), then Timeout Value is ignored.

The Key Data represents the selection key on input and contains the key data of the dequeued messsage on output.

Valid inputs of Key Relation include: 'GT', 'LT', 'NE', 'EQ', 'GE', 'LE'. If an invalid key relation value is specified, DEQUSRQ raises CPF9504.

If an invalid Key Length is specified, DEQUSRQ raises CPF9507 and returns the proper key length in Key Length Returned.

Usage Example

Here is an ILE RPG program that dequeues a user queue by the DEQUSRQ API.
     d q_obj           s             20a   inz('Q61       LSBIN')
     d timeout_val     s             10i 0 inz(604800)                          /* 1 week */
     d keylen_in       s             10i 0 inz(5)                               /* key length = 5 */
     d keylen_out      s             10i 0
     d msglen_in       s             10i 0 inz(16)
     d msglen_out      s             10i 0

     c                   call      'DEQUSRQ'
     c                   parm                    q_obj
     c                   parm                    enq_time         26
     c                   parm      '1'           use_timeout       1            /* wait */
     c                   parm                    timeout_val
     c                   parm      '1'           mod_acc_sts       1
     c                   parm      '0'           mpl_option        1
     c                   parm      'ABCDE'       key               5            /* selection key: 'ABCDE' */
     c                   parm      'GE'          key_relation      2            /* dequeue messages whose key greater than 'ABCDE' */
     c                   parm                    keylen_in
     c                   parm                    keylen_out
     c                   parm                    msg              16
     c                   parm                    msglen_in
     c                   parm                    msglen_out

     c                   seton                                          lr

Support This Project
Generated on Mon Aug 1 22:50:21 2011 for i5/OS Programmer's Toolkit: Queue Tools by  doxygen 1.5.9