Send Data Queue (QSNDDTAQ) API

The Send Data Queue (QSNDDTAQ) API sends data to the specified data queue. When an entry is sent to a standard data queue, the storage allocated for each entry will be the value specified for the maximum entry length on the Create Data Queue (CRTDTAQ) command.

Distributed data management (DDM) data queues are supported using this API. This means that you can use this API to send data to a data queue that exists on a remote iSeries.

Authorities and Locks

Data Queue Authority

*OBJOPR and *ADD

Data Queue Library Authority

*EXECUTE

When using optional parameter group 3 and the journal entry was deposited for a data queue with the sender ID attribute set to *YES, authority to the current profile in the sender ID of the journal entry

*USE

Data Queue Lock

*EXCLRD

Internally, when a job uses API QSNDDTAQ (Send Data Queue), QRCVDTAQ (Receive Data Queue), QMHQRDQD (Retrieve Data Queue Description), or QMHRDQM (Retrieve Data Queue Message), a cache is created to allow faster access to the data queue. An entry in the cache means a user is authorized to the data queue. An entry is added to the cache when a user calling one of the APIs has the required authority to the data queue. An entry is also added to the cache when QSNDDTAQ is called to handle a journal entry for a data queue created with the sender ID attribute set to *YES, and the user requesting the the send function has the required authority to the current profile name in the sender ID information of the journal entry. The data in the cache is used until the job ends, so if you need to immediately change a user's authority to one of these objects, you may need to end that user's jobs.

Required Parameter Group

Data queue name

INPUT; CHAR(10)

The name of the data queue to send the data to.

Library name

INPUT; CHAR(10)

The name of the library where the data queue resides.

You can use these special values for the library name:

*LIBL	The library list
*CURLIB	The job's current library.

Note: To improve data queue performance, the data queue APIs remember addressing information for the last data queues used. This occurs when a specific (not *LIBL or *CURLIB) value is provided for the library name, and the data queue is located in the system auxiliary storage pool (ASP number 1) or a basic user ASP (ASP numbers 2-32). The addressing information for data queues located in independent ASPs is not saved.

Because the addressing information is saved, users of this API should be aware of the following scenarios.

Scenario 1

If, a job references a library-specific data queue, the data queue is moved using the Move Object (MOVOBJ) command or renamed using the Rename Object (RNMOBJ) command, and a new data queue is created with the same name and library as the data queue that was renamed or moved, then, the job continues to reference the original data queue, not the newly created data queue.

Scenario 2

If, a job references a library-specific distributed data management (DDM) data queue, the DDM data queue is moved using the Move Object (MOVOBJ) command or renamed using the Rename Object (RNMOBJ) command, and a new data queue is created with the same name and library as the DDM data queue that was renamed or moved, then, the job continues to reference the original DDM data queue, not the newly created data queue.

Scenario 3

If, a job references a DDM data queue, which starts a DDM target job (DDM conversation) on a remote system that references a library-specific data queue, the data queue on the remote system is moved using the Move Object (MOVOBJ) command or renamed using the Rename Object (RNMOBJ) command, and on the remote system, a new data queue is created with the same name and library as the data queue that was renamed or moved, then, the DDM target job continues to reference the original data queue on the remote system, not the newly created data queue, only when the same DDM target job is used for the subsequent data queue operation. If a new DDM target job is used for the subsequent data queue operation, then the newly created data queue will be used on the remote system.

Note: For more information on creating DDM data queues and on DDM target jobs, see Distributed Data Management in the iSeries Information Center.

Length of data

INPUT; PACKED(5,0)

The number of characters to be sent to the data queue.

Note: An error occurs if the value specified is greater than the length specified by the maximum lenght (MAXLEN) parameter on the Create Data Queue (CRTDTAQ) command, unless optional parameter group 3 is specified. With optional parameter group 3, the length of the data provided in the journal entry should be specified, and it could be longer than the maximum entry length. This will be handled appropriately by the API.

Data

INPUT; CHAR(*)

The data to be sent to the data queue.

Note: If the length of this field is larger than the length of data parameter, only the number of characters (beginning from the left) as defined by the length of data parameter are sent to the data queue. If the length of this variable is smaller than the length of data parameter, unexpected results can occur.

Optional Parameter Group 1

Length of key data

INPUT; PACKED(3,0)

The number of characters in the key data parameter.

Note: The maximum value is the value that is specified on the KEYLEN parameter on the Create Data Queue (CRTDTAQ) command.

Key data

INPUT; CHAR(*)

The data sent to the data queue. This value must be at least as long as the value specified in the length of key data parameter; otherwise, unexpected results can occur.

Optional Parameter Group 2

Asynchronous request

INPUT; CHAR(10)

Whether the send data queue request to a DDM data queue should be processed asynchronously. This parameter only applies to DDM data queues. Valid values are *YES and *NO. An error will occur if *YES is specified for a non-DDM data queue. If the value *YES is specified for the asynchronous request parameter for a DDM data queue and an error occurs on the operation, the error will not be detected until the next time the data queue is accessed.

Note: If this parameter is specified, the key length and key data parameters must also be specified even if they are not applicable. In that event, the key length should be zero and blanks should be specified for the key data.

Optional Parameter Group 3

Data is from a journal entry

INPUT; CHAR(10)

Indicate whether the data, in parameter four, came from a journal entry. This parameter only applies to a non-DDM data queue. Valid values are *YES and *NO.

When using this paramter the data queue needs to have the same attributes as the journaled data queue. To ensure the attributes of the data queue are the same as the journaled data queue, save the journaled data queue and restore it to the system where this API will be called with optional parameter group 3 specified. Refer to Journal management for information on journaling.

Note: When using this parameter, the length of data in parameter three should be obtained from the journal entry. The length could be longer than the maximum entry length of the data queue and this will be handled appropriately by the API, an error will not be issued.

Note: If this parameter is specified, the key length, key data, and asynchronous request parameters must also be specified even if they are not applicable. In that event, the key length should be zero, key data should be blanks and *NO should be specified for the asynchronous request.

Usage Notes

This API can be used in a multithreaded job to send entries to a non-DDM data queue. It cannot be used in a job that allows multiple threads to send entries to a DDM data queue.

Error Messages