9.220 SND_TO_DATA_QUEUE
Þ Note: Built-In Function Rules.
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.
For use with
|
Arguments
|
Return Values
No Return Values.
Technical Notes - General
- 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.
Technical Notes - IBM i Operating System
- 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.
Technical Notes - Windows Operating Systems
- 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).
Examples
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)