9.197 SND_TO_DATA_QUEUE

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.

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 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

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)