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 i5/OS 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 Printing category in the IBM i Information Center at http://www.ibm.com/systems/i/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, *DSP, *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

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, a distributed data management (DDM) data queue, or a display 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).

*DSP

A display data queue is created. The data queue will be used with a display file. An interactive job waiting on this data queue will be eligible for inactive job time-out. The MAXLEN parameter is required with the use of this value.

Maximum entry length (MAXLEN)

Specifies the maximum length of the entry that is sent to the data queue.

Notes:

1. If the data queue is associated with an output queue, the maximum length value should be at least 128.
2. This parameter is valid only when TYPE(*STD) is specified.

1-64512

Specify the maximum entry length. Valid values range from 1 through 64512.

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:

1. If the data queue is associated with an output queue, the sequence value should be *FIFO or *LIFO."
2. 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.

Key length (KEYLEN)

Specifies the number of characters in the key.

Note: This parameter is valid only when SEQ(*KEYED) and TYPE(*STD) are specified.

1-256

Specify the key length. Valid values range from 1 through 256.

Include sender ID (SENDERID)

Specifies a sender ID to be attached to each message sent to the Data Queue. The ID contains the job name and the sender's current user profile.

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

*NO

Messages sent do not include the sender ID.

*YES

Messages sent include the sender ID.

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 systems that are at a release of i5/OS 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.

Text 'description' (TEXT)

Specifies text that briefly describes the data queue.

*BLANK

No text is specified.

'description'

Specify no more than 50 characters, enclosed in apostrophes.

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 system

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 a system 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.

CPF6565

User profile storage limit exceeded.

CPF9517

The SIZE parameter is not valid.

CPF9518

The maximum number of entries is too large.

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.