9.177 RCV_FROM_DATA_QUEUE

Note: Built-In Function Rules     Usage Options

Receives one or more working list's entries from an IBM i or Windows emulated data queue. For more information about data queues refer to the appropriate IBM manuals.

Note: Only use this Built-In Function in applications that are to fully execute under the control of the IBM i or a Windows operating system.

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req A literal or variable that specifies or contains the name of the data queue. This name must conform to IBM i object naming conventions.  This is not checked by the Built-In Function. 1 10     2 N Req A literal or variable that specifies or contains the byte length of one complete entry of the working list specified in return value 1. 1 5 0 0 3 N Req A literal or variable that specifies or contains the length of time (in seconds) that the Built-In Function should wait for data to arrive on the data queue. - A negative value indicates an unlimited wait. - A zero value indicates no wait is required. - A Positive value is the number of seconds. Refer to the appropriate IBM supplied manual for more details of this argument. Refer to IBM supplied program QRCVDTAQ which is what is actually used by this Built-In Function.   1 5 0 0

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 L Req The name of the working list whose entries are to be received from the specified data queue. 1 10

Technical Notes

• This Built-In Function may be used with IBM i or with a Windows operating system. Please refer to the Technical notes associated with the SND_TO_DATA_QUEUE Built-In Function for more information about using data queues under different operating systems.

Examples

Receive a customer number and a part number from a data queue called PICKLIST and then print their details. Assume that the entry is already known to be on the data queue:

DEF_LIST  NAME(#PICK) FIELDS(#CUSTNO #PARTNO) TYPE(*WORKING) ENTRYS(1)

          (where #CUSTNO is defined in the dictionary as a signed 5,0 number and #PARTNO is defined in the dictionary as a packed 7,0 number)

USE       BUILTIN(RCV_FROM_DATA_QUEUE) WITH_ARGS('PICKLIST' 9 0) TO_GET(#PICK)

GET_ENTRY NUMBER(1) FROM_LIST(#PICK)

EXECUTE   SUBROUTINE(PRINT_PICK)

Sit in a permanent loop receiving customer and part number details (one by one) as they arrive. As each arrives its details should be printed:

DEF_LIST  NAME(#PICK) FIELDS(#CUSTNO #PARTNO) TYPE(*WORKING) ENTRYS(1)

BEGIN_LOOP

USE       BUILTIN(RCV_FROM_DATA_QUEUE) WITH_ARGS('PICKLIST'9 -1) TO_GET(#PICK)

GET_ENTRY NUMBER(1) FROM_LIST(#PICK)

EXECUTE   SUBROUTINE(PRINT_PICK)

END_LOOP

Sit in a permanent loop receiving customer and part number details (in blocks of up to 5) as they arrive. As each block arrives it should be printed:

DEF_LIST   NAME(#PICK) FIELDS(#CUSTNO #PARTNO) TYPE(*WORKING) ENTRYS(5) COUNTER(#LISTCOUNT)

BEGIN_LOOP

  USE        BUILTIN(RCV_FROM_DATA_QUEUE) WITH_ARGS('PICKLIST'9 -1) TO_GET(#PICK)

  BEGIN_LOOP USING(#I) FROM(1) TO(#LISTCOUNT)

    GET_ENTRY  NUMBER(#I) FROM_LIST(#PICK)

    EXECUTE    SUBROUTINE(PRINT_PICK)

  END_LOOP

END_LOOP

Note: Routines placing customer/part number pairs onto this data queue can actually place 1,2,3,4 or 5 entries and this function will work successfully. However if a function attempted to place more than 5 entries onto one data queue entry, then this application would fail because working list #PICK can contain at most 5 entries.