ADDRESS PPQ Commands › PPQ Operations Commands › READ Command

READ Command

The READ command reads one or more items from a specified queue.

This command has the following format:

ADDRESS PPQ 'READ QUEUE(qname) [COUNT(numitems)]
                               [CMDRESP(destination)]
                               [ITEMNUM(FIRST|LAST|itemnum)]
                               [PREFIX(newvarname)]                              
                               [REMOVE(YES|NO)]
                               [WAIT(NO|YES|waittime)]'

QUEUE

Specifies the 1- to 16-character name of the queue (qname). The queue name can contain alphanumeric characters and any of these special characters: ! @ # $ _

The queue name cannot contain blanks.

CMDRESP

(Optional) Directs return information, if any, to a specific destination. For a list of valid destination values, see the section Change the Default Return Destination with CMDRESP.

Default: REXX

COUNT

(Optional) Specifies the number of items (numitems) to read from the queue.

Default: 1

ITEMNUM

(Optional) Specifies the starting item to read from the queue. The starting item that you specify must exist; the READ command cannot wait for an item that does not yet exist. Valid ITEMNUM values are:

FIRST

Starts the read operation from the first item in the queue.

LAST

Starts the read operation from the last item in the queue.

itemnum

Starts the read operation from an item number that you specify. (A value of 1 is the same as a value of FIRST.)

Default: FIRST

PREFIX

(Optional) Directs return information to a stem variable name (newvarname) other than the default. For more information, see ADDRESS PPQ Return Information.

Note: The PREFIX operand is only valid if REXX is the destination of the return information.

Default: PPQ.READ

REMOVE

(Optional) Specifies whether the read operation is destructive or nondestructive (that is, whether the READ command removes an item from the queue after it has read the item). Valid values are:

YES

Removes the item from the queue after reading it.

NO

Does not remove the item from the queue after reading it.

Default: YES

WAIT

(Optional) Specifies what the command does if it cannot execute immediately. For example, the queue may be in use or locked by another REXX program. Valid WAIT values are:

NO

Returns a nonzero return code (RC) value immediately. For information about what happens when a command does not execute successfully, see the chapter on using program-to-program queues in the Administrator Guide.

YES

Waits indefinitely while blocking the current REXX program until the queue becomes available and is not empty.

waittime

Specifies the number of seconds to wait (up to 100000) for the queue to become available while blocking the current REXX program. Fractional values (such as 1.5) are valid.

Default: NO

Usage Notes:

• The ITEMNUM operand and the WAIT operand are mutually exclusive.
• When reading from a remote queue, especially using the TCP/IP transport, it is possible to receive return code 4520 (queue not found) indicating errors when the queue exists on the remote machine. These errors can occur if remote host network response times are slow or inconsistent. To alleviate this condition, use the following sample to code a function around the read request to detect the problem and recover from it:

  READRMTPPQ:
  /*
  ********************************************************************
  *     THIS FUNCTION WILL READ A PPQ REMOTE QUEUE WITH TIMEOUT.     *
  ********************************************************************
  * EXAMPLE CALL: RC = READPPQ('RMTQ', 4*60, 'REMOVE(NO) COUNT(2)')  *
  * RETURNS: RC FROM PPQREAD                                         *
  * NOTES: FOR LOCAL QUEUE, USE PPQREAD WAIT() PARAMETER IN PLACE OF *
  *        THIS ROUTINE.                                             *
  ********************************************************************
  **
  */
  QUEUE      = ARG(1)  /* QUEUE NAME          */
  TIMEOUT    = ARG(2)  /* TIME OUT IN SECONDS */
  READ_PARMS = ARG(3)  /* OTHER PPQREAD PARMS */
  
  /* DEFAULT 3 MINUTE TIME OUT */
  IF TIMEOUT = '' THEN TIMEOUT = 3*60
  
  /* ENSURE WAIT PARM */
  IF POS('WAIT(',READ_PARMS) = 0
     THEN READ_PARMS = 'WAIT(1)' READ_PARMS
  
  /* START TIMER */
  X = TIME('R')
  
  /* LOOP UNTIL QUEUE FOUND, TIME OUT, OR ERROR */
  DO UNTIL TIME('E') > TIMEOUT
     ADDRESS 'PPQ' 'READ QUEUE('QUEUE')' READ_PARMS
     IF RC <> 4520 THEN LEAVE
  END
  RETURN RC