DTAQ_SEND

LANSA Composer

previous page next page

DTAQ_SEND

This activity sends data to a named data queue.

This activity treats data sent to 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.

Refer also to the companion DTAQ_RECEIVE, DTAQ_CLEAR and WATCH_DTAQ activities that allows you to receive data 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 are only available on IBM i servers.

(The implementation of this activity on an IBM i server uses the QSNDDTAQ system API.)

Data queues referenced by this activity must already exist on the IBM i server.  You can create a data queue on the IBM i server using the CRTDTAQ command.  For example, the following command creates a data queue named MYDATAQ in library QGPL that can receive data entries of up to 256 characters:

CRTDTAQ DTAQ(QGPL/MYDATAQ) MAXLEN(512)

 

Use of keyed data queues with this activity is not presently supported.

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 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 SND_TO_DATA_QUEUE built-in function.)

The following notes and restrictions apply to using this activity on a Windows server:

  • The TODTAQLIB parameter is not used and its value will be ignored.  (You may use the TODTAQPATH parameter to specify a location for the data queue, if required.)
  • Data queues are automatically created when they are first referenced.
  • The first reference not only creates the data queue, but also permanently sets the entry size for the data queue according to the value of the DTALEN parameter.
  • 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 TODTAQPATH parameter.  Refer to that parameter description for further information.
  • If you have the Visual LANSA documentation available to you, you can find further information pertinent to the Windows implementation of this and related activities in the description of the SND_TO_DATA_QUEUE built-in function, in the LANSA Technical Reference Guide.

 

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:

TODTAQ : Required

This parameter must specify the name of the data queue to which the data is sent.

TODTAQLIB: 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 TODTAQPATH parameter to specify a location for the data queue, if required.

TODTAQPATH: 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 to be 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 TODTAQLIB parameter to specify a location for the data queue, if required.

DTALEN: Required

This parameter must specify the number of characters of data to be sent to the data queue.  The activity supports data lengths between 1 and 1024 inclusive.

On an IBM i server, this value must be consistent with the length specified when the data queue was created using the CRTDTAQ command.

On a Windows server, the first 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.)

SNDDATASNDDATA02
SNDDATA03
SNDDATA04: Optional

These parameters specify the data to be sent to the data queue.  Each parameter specifies up to 256 bytes of data.  The first parameter, SNDDATA is required.  The remaining parameters are optional and only need be specified if you are using data queue entries of length greater than 256, 512 and 768 respectively.

OUTPUT Parameters:

There are no output parameters

previous page start next page