| Note: Built-In Function Rules Usage Options |
Places one or more entries from a working list onto an IBM i or Windows emulated data queue. Refer to IBM supplied manuals for more details of data queues.
| 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. |
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 argument 3. | 1 | 5 | 0 | 0 |
3 | L | Req | The name of the working list whose entries are to be sent to the specified data queue. | 1 | 10 |
No Return Values.
When the working list contains multiple entries, all entries are sent to the data queue in one operation. For example, if a working list had an entry length of 20 bytes, and it contained 7 entries, then the actual length of the data record sent to the data queue would be 20 * 7 = 140 bytes. This processing must be considered when specifying the MAXLEN parameter of the IBM supplied CRTDTAQ (create data queue) command under IBM i.
If a list is passed to the Built-In Function that contains zero (0) entries no error occurs and no data is written to the data queue.
For maximum speed, no significant checking is performed by this Built-In Function. Errors with lengths or data types may cause failures that require detailed analysis of error information.
The backup, recovery and maintenance of any data queues accessed via this Built-In Function is entirely the responsibility of the user.
Data queues are persistent objects but their data content can be lost or corrupted during a system failure.
Data queues are limited in how much information they can store. Typically no more than 16Mb of data should be queued at any point in time.
The data queue specified must be created by using the IBM supplied CRTDTAQ (create data queue) command.
Data queues may be cleared by using the IBM supplied API QCLRDTAQ.
Data queues may be deleted by using the IBM supplied DLTDTAQ (Delete Data Queue) command.
The data queue must be able to be located in the job's current library list. Support for fully qualified library/queue names is not provided in the interests of good design practice.
Data queues are automatically created when they are referenced.
Data queues may be cleared by deleting the file used to store the data queue data. They will be automatically (re)created the next time they are referenced.
Data queues may be deleted by deleting the file used to store the data queue data and the file used to control data queue locking.
Data queues are stored in a normal Windows file.
The data queue storage file name is an 8 character conversion of the data queue name. The conversion process uses the same algorithm as is used to convert 10 character LANSA process names to an 8.3 formatted DLL name.
The data queue storage files are suffixed by .EDQ (for Emulated Data Queue) and .LDQ (for Lock Data Queue). The .LDQ file will only exist if a function has at some time attempted a receive operation from the queue.
The .EDQ file stores the actual queue data. Space in this file is reused as queue entries are removed, thus the size of this file represents a high water mark.
The .LDQ file is used to logically lock a data queue during receive operations. This file can be deleted at any time as it is automatically (re)created on demand.
By default data queue storage files are created in the <sysdir>\x_ppp directory (where ppp is the partition) of the current LANSA environment.
The location of the data queue storage files can be controlled by using the DPTH= parameter of the X_RUN command. For example, DPTH=c:\temp would cause all data queues to be created and accessed in the c:\temp directory.
The DPTH= parameter value can be dynamically altered in an application by using the SET_SESSION_VALUE Built-In Function.
You should not use the DPTH= parameter for any purpose other than the simple one time redirection of all data queue accesses to an alternative directory. Complicated designs that use many instances a single data queue name in many different directories should be avoided (for the same reason that support for IBM i fully qualified library/queue names is not provided).
Receive a customer number and a part number from a screen panel and then place them onto a data queue called PICKLIST:
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)
REQUEST FIELDS(#CUSTNO #PARTNO)
INZ_LIST NAMED(#PICK) NUM_ENTRYS(1)
USE BUILTIN(SND_TO_DATA_QUEUE) WITH_ARGS('PICKLIST' 9 #PICK)
Receive 5 customer numbers and part numbers from a screen panel and then place them onto a data queue called PICKLIST as 5 separate data queue entries:
DEF_LIST NAME(#PICK) FIELDS(#CUSTNO #PARTNO) TYPE(*WORKING) ENTRYS(1)
BEGIN_LOOP FROM(1) TO(5)
REQUEST FIELDS(#CUSTNO #PARTNO)
INZ_LIST NAMED(#PICK) NUM_ENTRYS(1)
USE BUILTIN(SND_TO_DATA_QUEUE) WITH_ARGS ('PICKLIST' 9 #PICK)
END_LOOP
Receive 5 customer numbers and part numbers from a screen panel and then place them onto a data queue called PICKLIST as a single data queue entry:
DEF_LIST NAME(#PICK) FIELDS(#CUSTNO #PARTNO) TYPE(*WORKING) ENTRYS(5)
CLR_LIST NAMED(#PICK)
BEGIN_LOOP FROM(1) TO(5)
REQUEST FIELDS(#CUSTNO #PARTNO)
ADD_ENTRY TO_LIST(#PICK)
END_LOOP
USE BUILTIN(SND_TO_DATA_QUEUE) WITH_ARGS('PICKLIST' 9 #PICK)