WATCH_DTAQ
This is an iterator activity. It will repeatedly attempt to receive data from a named data queue and on each iteration output the data received, if any.
The processing logic nested beneath the WATCH_DTAQ activity is repeated each time that data is received or each time the specified wait time (DTAWAIT parameter) is exceeded (if no data is available to receive).
This activity treats data received from a data queue as character data. Using this activity to interact with applications that send or receive binary data to or from the data queue is not supported.
Upon each iteration in which the activity receives an entry from the named data queue, the data content (and possibly sender information) is available through the output parameters of the activity.
When no data is available to be received (after waiting for the interval specified by the DTAWAIT parameter, if used), the activity iterates normally but the output data parameters are not filled. The value of the RCVCOUNT output parameter may be used to determine whether an entry was received. This behavior allows your solution to perform processing periodically whether data is received or not. For example, your processing sequence might check the value of the *SHUTDOWN built-in variable in order to permit the long running process to be ended in a controlled fashion.
Refer also to the companion DTAQ_CLEAR, DTAQ_RECEIVE and DTAQ_SEND activities that allows you to send and receive data to and from and to perform other operations on a named data queue.
Note: Data queues are persistent objects but their data content can be lost or corrupted during a system failure. Backup, recovery and maintenance of data queues used in your LANSA Composer solution is your responsibility – you should make provision for this in your implementation plans.
Note: Unlike many other iterator activities, this activity will iterate indefinitely unless you take specific action in the iterator block to exit the iteration. It is designed to be used in a potentially long running processing sequence that perpetually waits on a message arriving at the specified message queue and then processes the message or initiates another processing sequence to process the message. For more information refer to Considerations for Extended Duration Processing Sequences .
IBM i Platform Notes
Data queues are a native operating system feature on the IBM i server. The full range of capabilities of this activity is only available on IBM i servers.
(The implementation of this activity on an IBM i server uses the QRCVDTAQ system API.)
Use of keyed data queues with this activity is not presently supported.
Refer to the description of the DTAQ_SEND activity for more complete IBM i Server Platform Notes relating to the suite of DTAQ activities. Refer to IBM i documentation concerning data queues for further information about the operating system features upon which this activity depends.
Windows Server Platform Notes
Although data queues are a native feature of the IBM i server, this activity and the companion DTAQ_CLEAR, DTAQ_RECEIVE and DTAQ_SEND activities are available on Windows servers too, but with a reduced feature set and with other restrictions and caveats.
(The implementation of this activity on a Windows server uses the emulated data queue support in the LANSA run-time, using the RCV_FROM_DATA_QUEUE built-in function.)
The following notes and restrictions apply to using this activity on a Windows server:
- The DTAQLIB parameter is not used and its value will be ignored. (You may use the DTAQPATH parameter to specify a location for the data queue, if required.)
- Data queues are stored in pairs of files in the Windows server file system with .EDQ and .LDQ file extensions. The .EDQ file contains the data queue definition and entries. The .LDQ files are used to logically lock the data queue during receive operations. The file names are determined by the LANSA run-time support used by this activity. The files can be manually cleared or deleted by deleting the associated files. Alternatively the DTAQ_CLEAR activity may be used for this purpose.
- The location of the .EDQ and .LDQ data queue storage files is determined by the value of the DTAQPATH parameter. Refer to that parameter description for further information.
- Refer to the description of the DTAQ_SEND activity for more complete Windows Server Platform Notes relating to the suite of DTAQ activities.
NOTE: On Windows servers, the specific implementation used means that the activity is unable to handle certain types of exceptions that may be considered unexceptional in other circumstances. In such cases the processing sequence containing the activity may simply end abnormally without logging diagnostic information in the Processing Sequence log. This behavior differs from most other LANSA Composer activities and from the IBM i implementation of this activity.
You should be aware of this possibility and be prepared to diagnose such issues in other ways. For example, the x_err.log generated by the LANSA run-time may assist with diagnosing such conditions.
INPUT Parameters:
DTAQ: Required
This parameter must specify the name of the data queue from which the data is to be received.
DTAQLIB: Optional
When running on IBM i servers, this parameter may specify the name of the library containing the data queue. If not specified, a default of *LIBL is used which means the library list is used to locate the named data queue.
When running on a Windows server, this parameter is not used and its value is ignored. You may use the DTAQPATH parameter to specify the location for the data queue, if required.
DTAQPATH: Optional
When running on Windows servers, this parameter may specify the path to the directory in which the data queue .EDQ and .LDQ files are stored. If not specified, the default location is determined by the LANSA run-time according to the effective value of the DPTH= X_RUN parameter.
When running on an IBM i server, this parameter is not used and its value is ignored. You may use the DTAQLIB parameter to specify the location for the data queue, if required.
DTAWAIT: Optional
Specifies the length of time (in seconds) that the activity will wait, on each iteration, for data to arrive on the data queue.
The default value is 20 (twenty) seconds. This default value has been chosen to be less than the default controlled end delay times used on IBM i system commands such as ENDJOB (End Job). You should consider also the corresponding delay times used with IBM i system commands such as ENDSBS (End Subsystem) or PWRDWNSYS (Power Down System). This enables your processing sequence to have the opportunity to check the value of the *SHUTDOWN built-in variable and end in a controlled fashion if one of those commands is issued.
You may specify the special value of 0 (zero) which means that the activity does not wait for the arrival of an entry if one is not immediately available when the activity is processed. Instead the next iteration is performed immediately. Use of this value is not generally recommended with the WATCH_DTAQ activity as it may result in your long-running processing sequence being heavily CPU intensive, instead of simply entering an idle/wait state when it has no work to perform.
You may also specify the special value *MAX which means that the activity waits indefinitely for data to arrive. Use of this value is not generally recommended with the WATCH_DTAQ activity as it will prevent any possibility of effecting controlled end of the processing sequence.
DTARMV: Optional
Specifies whether the data received by the activity is removed from the data queue. The default is *YES, which means the data is removed. You may specify *NO to cause the data not to be removed from the data queue. If you do so, the data can be received again by this activity in the same or another Processing Sequence. You should take care using *NO with the WATCH_DTAQ activity – unless you design your solution to prevent it, your processing sequence will loop, repeatedly processing the same data queue entry.
DTAQELEN: Optional
On an IBM i server, this parameter is not required and its value will be ignored.
On a Windows server, this parameter is required and it must specify the length of the data queue entries. The activity supports data lengths between 1 and 1024 inclusive.
On a Windows server, the first send (DTAQ_SEND) operation for a data queue will automatically create the data queue and will set its entry length. The length specified for subsequent operations to the same data queue must match the length specified on the initial operation that created the data queue. (On Windows servers, LANSA Composer will actually use the next greatest multiple of 256 – for example, if you specify 700 for this parameter, LANSA Composer will actually use the value 768.)
OUTPUT Parameters:
RCVCOUNT:
The received entry count. Upon each iteration, if data is received successfully, the value will be one (1). Otherwise the value will be zero (0).
RCVDATALEN:
Upon each iteration, if data is received, this parameter contains the length of the data received.
(On a Windows server, the activity cannot determine the actual data length received, and the value returned in this parameter is the same as the value provided in the DATAQELEN input parameter.)
RCVDATARCVDATA02
RCVDATA03
RCVDATA04:
Upon each iteration, if data is received, these parameters contains the data. Each parameter receives up to 256 bytes of data. The first parameter, RCVDATA, contains the first up to 256 bytes of data. The remaining parameters are filled only if you are using data queue entries of length greater than 256, 512 and 768 respectively.
SENDJOB
SENDUSER
SENDJOBNBR:
Upon each iteration, if data is received, these output parameters may contain the job name, user name and the job number of the job that sent the data to the data queue.
On an IBM i server, these values will be available only if SENDERID(*YES) was specified when the data queue was created using the CRTDTAQ (Create Data Queue) command.
On a Windows server, the sending job information is not available and these parameters will not be filled.