DTAQ_RECEIVE

LANSA Composer

DTAQ_RECEIVE

This activity receives data from a named data queue.

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.

When 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 ends normally but the output parameters are not filled.  The value of the RCVCOUNT output parameter may be used to determine whether an entry was received.

Refer also to the companion DTAQ_CLEAR, DTAQ_SEND and WATCH_DTAQ 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.

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_SEND and WATCH_DTAQ 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 for data to arrive on the data queue if no data is immediately available when the activity is processed.

The default value is 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.

You may also specify the special value *MAX which means that the activity waits indefinitely for data to arrive.  You should understand that this value may cause the activity and hence the processing sequence in which it is contained to stall indefinitely if no data is sent to the data queue.  Other than by the arrival of data, such a processing sequence run may only be terminated by terminating the job, the subsystem in which the job is running or the system.  If you wish a process to wait indefinitely for data to arrive on a data queue, the WATCH_DTAQ activity may provide a more suitable solution.

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.

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.  If data is received successfully, the value will be one (1).  Otherwise the value will be zero (0).  The activity ends normally when no message is available to receive after waiting for the interval specified by the DTAWAIT parameter.

RCVDATALEN:

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
:

If data is received, this parameter 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
:

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.