Create Data Queue (CRTDTAQ)

The Create Data Queue (CRTDTAQ) command creates a data queue and stores it in a specified library.

Data queues, which are a type of OS/400 system object, are used to communicate and store data used by several programs either within a job or between jobs. Multiple jobs can send or receive data from a single queue.

For more information about data queues on output queues, see the Basic Printing information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

The Create Data Queue (CRTDTAQ) command optionally creates a distributed data management (DDM) data queue when TYPE(*DDM) is specified. The DDM data queue is used as a reference data queue by programs to access data queues located on a remote (target) system in the DDM network. Programs on the local (source) system refer to a remote data queue by the DDM data queue's name, not by the remote data queue's name. The DDM data queue name, however, can be the same as the remote data queue name.

The DDM data queue on the source system contains the name of the remote data queue and the name of the remote (target) system on which the remote data queue is located.

Restrictions: Users of this command must have add (*ADD) authority for the library where the data queue is located.

Parameters

Keyword	Description	Choices	Notes
DTAQ	Data queue	Qualified object name	Required, Positional 1
	Qualifier 1: Data queue	Name
	Qualifier 2: Library	Name, *CURLIB
TYPE	Type	STD, DDM	Optional
MAXLEN	Maximum entry length	1-64512	Optional, Positional 2
FORCE	Force to auxiliary storage	NO, YES	Optional
SEQ	Sequence	FIFO, LIFO, *KEYED	Optional
KEYLEN	Key length	1-256	Optional
SENDERID	Include sender ID	NO, YES	Optional
SIZE	Queue size	Element list	Optional
	Element 1: Maximum number of entries	Integer, MAX16MB, MAX2GB
	Element 2: Initial number of entries	Integer, 16
AUTORCL	Automatic reclaim	NO, YES	Optional
RMTDTAQ	Remote data queue	Qualified object name	Optional
	Qualifier 1: Remote data queue	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
RMTLOCNAME	Remote location	Communications name, *RDB	Optional
RDB	Relational database	Name	Optional
DEV	APPC device description	Name, *LOC	Optional
LCLLOCNAME	Local location	Communications name, LOC, NETATR	Optional
MODE	Mode	Communications name, *NETATR	Optional
RMTNETID	Remote network identifier	Communications name, LOC, NETATR, *NONE	Optional
TEXT	Text 'description'	Character value, *BLANK	Optional
AUT	Authority	Name, LIBCRTAUT, CHANGE, ALL, USE, *EXCLUDE	Optional

Top

Data queue (DTAQ)

Specifies the data queue to be created.

This is a required parameter.

Qualifier 1: Data queue

name: Specify the name of the data queue.

Qualifier 2: Library

*CURLIB: The current library for the job is used to locate the data queue. If no current library entry exists in the library list, QGPL is used.
name: Specify the library where the data queue is located.

Type (TYPE)

Specifies the type of data queue to be created. A standard data queue or a distributed data management (DDM) data queue can be created.

*STD: A standard data queue is created. The MAXLEN parameter is required with the use of this value.
*DDM: A DDM data queue is created. This value requires the name of the remote data queue accessed (RMTDTAQ parameter) and the name of the remote (target) system that the data queue is located on (RMTLOCNAME parameter).

Force to auxiliary storage (FORCE)

Specifies whether the data queue is forced to auxiliary storage when entries are sent or received for this data queue.

Note: This parameter is valid only when TYPE(*STD) is specified.

*NO: Send and receive operations are not immediately forced to auxiliary storage.
*YES: Send and receive operations are immediately forced to auxiliary storage. This ensures that the changes are not lost if a system failure occurs. This requires additional system overhead.

Sequence (SEQ)

Specifies the sequence in which entries are received from the data queue.

Notes:

If the data queue is associated with an output queue, the sequence value should be *FIFO or *LIFO."
This parameter is valid only when TYPE(*STD) is specified.

*FIFO: Data queue entries are received in a first-in first-out sequence.
*LIFO: Data queue entries are received in a last-in first-out sequence.
*KEYED: Data queue entries are received by key. A key is a prefix added to an entry by its sender.

Queue size (SIZE)

Specifies the amount of storage allocated for the data queue. Parameter elements consist of the maximum number of entries and the initial number of entries for the data queue.

Note: This parameter is valid only when TYPE(*STD) is specified.

Element 1: Maximum number of entries

One of the following is used to specify the maximum number of entries that can be added to a data queue.

*MAX16MB: The system will calculate the maximum number of entries that can be added to the queue and will be allowed to grow to a maximum size of approximately 16 megabytes(MB). One megabyte equals 1,048,576 bytes. This value with an initial number of entries of 16 provides compatibility with releases of the operating system earlier than Version 4 Release 5 Modification 0 (V4R5M0).
*MAX2GB: The system will calculate the maximum number of entries that can be added to the data queue. The data queue will be allowed to grow to a maximum size of approximately 2 gigabytes (GB). One gigabyte equals 1,073,741,824 bytes.
number-of-entries: The data queue will be allowed to hold at least this number of entries. Based on the extend size used by the machine, the maximum number of data queue entries may be slightly higher than the specified value. The value specified must be greater than 0.

Element 2: Initial number of entries

Specifies the amount of storage that will initially be allocated to the data queue. The queue will be created to hold the initial number of entries of the maximum entry length.

16: Initially, storage is allocated to hold 16 entries of the maximum entry length.
initial-number-of-entries: Specify the value for the initial number of entries that the data queue can hold. The value must be greater than 0.

Automatic reclaim (AUTORCL)

Specifies whether the storage allocated for the data queue is automatically reclaimed (released) when the data queue is empty.

Note: This parameter is valid only when TYPE(*STD) is specified.

*NO: The storage allocated for the data queue is not released when the data queue is empty.
*YES: The storage allocated for the data queue is released when the data queue is empty. Storage for the Initial Number of Entries value will remain allocated.

Remote data queue (RMTDTAQ)

Specifies the remote data queue on the target system. The data queue does not need to exist when the DDM data queue is created.

Qualifier 1: Remote data queue

name: Specify the name of the data queue that identifies the remote data queue accessed. The name cannot exceed 10 characters.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.

name: Specify the name of the library to be searched.

If *LIBL (the default library qualifier) is specified or assumed, the library list in the called job on the target system is searched to locate the data queue.
If *CURLIB is specified, the current library in the called job on the target system is searched to locate the data queue.

Remote location (RMTLOCNAME)

Specifies the name of the remote location that is used with this object.

Note: Multiple DDM data queues can use the same remote location for the target system. The remote locations used must point to iSeries systems that are at a release of OS/400 that supports remote data queues.

*RDB: The remote location information from the relational database entry specified for the Relational database (RDB) parameter is used to determine the remote system.
name: Specify the name of the remote location that is associated with the target system. The remote location, which is used in accessing the target system, does not need to exist when the DDM data queue is created but must exist when the DDM data queue is accessed.
More information on remote locations is in the APPC Programming book, SC41-5443.

Relational database (RDB)

Specifies the relational database entry that is used to determine the remote location information for the DDM data queue.

communications-name: Specify the name of the relational database entry that identifies the target system or target ASP group. The relational database name can refer to a remote system or an ASP group that is configured and available on a remote system. The relational database entry does not need to exist when the DDM data queue is created but must exist when the DDM data queue is used. This parameter is required when *RDB is specified for the Remote location (RMTLOCNAME) parameter.

APPC device description (DEV)

Specifies the name of the APPC device description on the source system that is used with this DDM data queue. The device description does not need to exist when the DDM data queue is created.

*LOC: The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used.
name: Specify the name of a communications device associated with the remote location. If the device name is not valid for the remote location, a message is sent when the program device entry is required. More information on device names is in the APPC Programming book, SC41-5443.

Local location (LCLLOCNAME)

Specifies the local location name.

*LOC: The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used.
*NETATR: The LCLLOCNAME value specified in the system network attributes is used.
name: Specify the name of the local location that is associated with the remote location. The local location name is specified only if the user indicates a specific local location for the remote location. If the local location name is not valid for the remote location, an escape message is sent when the DDM data queue is accessed.
More information on local location names is in the APPC Programming book, SC41-5443.

Mode (MODE)

Specifies the mode name that is used with the remote location name to communicate with the target system.

*NETATR: The mode name specified in the network attributes is used.
name: Specify the name of the mode that is used to communicate with the remote system. If the mode name is not valid for any combination of remote location and local location, an escape message is sent when the DDM data queue is accessed.
More information on mode names is in the APPC Programming book, SC41-5443.

Remote network identifier (RMTNETID)

Specifies the remote network identifier (ID) in which the remote location resides that is used to communicate with the target system.

*LOC: The remote network ID associated with the remote location is used. If several remote network IDs are associated with the remote location, the system determines which remote network ID is used.
*NETATR: The RMTNETID value specified in the system network attributes is used.
*NONE: No remote network ID is used.
remote-network-ID: Specify the remote network ID that is associated with the remote location. The remote network ID is specified only if the user indicates a specific remote network ID for the remote location. If the remote network ID is not valid for the remote location, an escape message is sent when the DDM data queue is accessed.
More information on remote network IDs is in the APPC Programming book, SC41-5443.

Authority (AUT)

Specifies the authority you are giving to users who do not have specific authority for the object, who are not on an authorization list, and whose group profile or supplemental group profiles do not have specific authority for the object.

*LIBCRTAUT: The system determines the authority for the object by using the value specified for the Create authority (CRTAUT) parameter on the Create Library command (CRTLIB) for the library containing the object to be created. If the value specified for the CRTAUT parameter is changed, the new value will not affect any existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management (*AUTLMGT) authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the object.

*USE: The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.

*EXCLUDE: The user cannot access the object.

name: Specify the name of an authorization list to be used for authority to the object. Users included in the authorization list are granted authority to the object as specified in the list. The authorization list must exist when the object is created.

Examples

Example 1: Creating a Standard Data Queue

CRTDTAQ   DTAQ(DEPTADTA)  MAXLEN(100)  AUT(*EXCLUDE)
          TEXT('Special data + files for DEPTA')

This command creates a data queue named DEPTADTA and puts it in the current library; the maximum length entry is 100. Because AUT(*EXCLUDE) is specified, the data queue can be used and controlled only by the user who created the queue and by users who have been given specific authority. Users in Department A can be given authority to use this data queue by using the Grant Object Authority (GTROBJAUT) command.

Example 2: Creating a DDM Data Queue to Access a Data Queue at Another iSeries 400

CRTDTAQ   DTAQ(SOURCE/SALES)  TYPE(*DDM)
          RMTDTAQ(REMOTE/SALES)  RMTLOCNAME(NEWYORK)

This command creates a DDM data queue named SALES and stores it in the SOURCE library on the source system. This DDM data queue uses the remote location named NEWYORK to access a remote data queue named SALES stored in the REMOTE library on an iSeries 400 in New York.

Example 3: Creating a Data Queue Specifying Size Attributes and Automatic Reclaim

CRTDTAQ   DTAQ(MYLIB/MYDTAQ) MAXLEN(80)
          SIZE(*MAX2GB 100)  AUTORCL(*YES)

This command creates a data queue named MYDTAQ and stores it in the MYLIB library. The maximum entry length is 80 bytes and the queue entries are received in a first-in-first-out (FIFO) sequence. The data queue will initially have storage allocated to hold 100 entries. The data queue can grow to a maximum size of approximately 2 gigabytes. If all queue entries are received, storage for the data queue will be automatically reclaimed.

Error messages

*ESCAPE Messages

CPF2105: Object &1 in &2 type *&3 not found.
CPF2108: Object &1 type *&3 not added to library &2.
CPF2109: NEWOBJ must be *SAME when OBJ parameter is *ALL or generic name.
CPF2110: Library &1 not found.
CPF2113: Cannot allocate library &1.
CPF2116: DATA(*YES) specified and *ALL or *FILE not in OBJTYPE list.
CPF2122: Storage limit exceeded for user profile &1.
CPF2123: No objects of specified name or type exist in library &2.
CPF2130: &1 objects duplicated. &2 objects not duplicated.
CPF2151: Operation failed for &2 in &1 type *&3.
CPF2152: Objects of type *&1 cannot be created into QTEMP.
CPF2162: Duplication of all objects in library &1 not allowed.
CPF2176: Library &1 damaged.
CPF2182: Not authorized to library &1.
CPF2185: TOLIB, TOASPDEV, or NEWOBJ parameter not correct.
CPF2186: Object &1 cannot be created into library &2.
CPF2283: Authorization list &1 does not exist.
CPF327E: Alternative name for file &1 not allowed.
CPF6565: User profile storage limit exceeded.
CPF9810: Library &1 not found.
CPF9820: Not authorized to use library &1.
CPF9827: Object &1 cannot be created or moved into &2.
CPF9830: Cannot assign library &1.
CPF9870: Object &2 type *&5 already exists in library &3.