Create Data Area (CRTDTAARA)

The Create Data Area (CRTDTAARA) command creates a data area and stores it in a specified library. It also specifies the attributes of the data. The data area can also be initialized to a specific value.

Data areas are used to communicate and store data used by several programs either within a job or between jobs. A program can use the value of a data area by using the Retrieve Data Area (RTVDTAARA) command.

If a data area is not used by more than one job at a time, it can be explicitly allocated to the appropriate job. If a data area is used by two or more jobs at the same time, it is protected from simultaneous changes occurring from different jobs. A data area is changed by using the Change Data Area (CHGDTAARA) command. The system does not allow two commands to change the same data area at the same time.

A data area is updated in auxiliary storage any time it is changed. This ensures that the changes are not lost in the event of a program or system failure.

The CRTDTAARA command can optionally create a distributed data management (DDM) data area. This is done by specifying *DDM for the TYPE parameter. The DDM data area is used as a reference data area by programs to access data areas located on a remote (target) system in the DDM network. Programs on the local (source) system reference a remote data area by the DDM data area's name, not by the remote data area's name. The DDM data area name can be the same as the remote data area name).

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

The DDM data area can be used with the RTVDTAARA and CHGDTAARA commands to retrieve and update data areas on remote systems.

Restrictions:

To use this command, the user must have object operational and add authority for the library in which the data area is placed.
This command is conditionally threadsafe. The following restrictions apply:
1. Creating DDM data areas in a job that allows multiple threads is not threadsafe.
2. Creating DDM data areas will fail when more than one thread is active in a job.

Parameters

Keyword	Description	Choices	Notes
DTAARA	Data area	Qualified object name	Required, Positional 1
	Qualifier 1: Data area	Name
	Qualifier 2: Library	Name, *CURLIB
TYPE	Type	DEC, CHAR, LGL, DDM	Required, Positional 2
LEN	Length	Element list	Optional, Positional 3
	Element 1: Length	1-2000
	Element 2: Decimal positions	0-9
VALUE	Initial value	Not restricted	Optional, Positional 4
RMTDTAARA	Remote data area	Qualified object name	Optional
	Qualifier 1: Remote data area	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 area (DTAARA)

Specifies the name and library of the data area being created.

This is a required parameter.

Qualifier 1: Data area

name: Specify the name of the data area being created.

Qualifier 2: Library

*CURLIB: The data area is created in the current library for the thread. If no library is specified as the current library for the thread, the QGPL library is used.
name: Specify the library where the data area is created.

Type (TYPE)

Specifies the type of value contained in the data area being created. The type can contain a character value, a decimal value, or a logical value (1 or 0), or a distributed data management (DDM) data area can be created.

This is a required parameter.

*DEC: This data area contains a decimal value.
*CHAR: This data area contains a character string value.
*LGL: This data area contains a logical value of either one (1) or zero (0) that can be used to represent two opposing conditions such as on/off, true/false, or yes/no.
*DDM: The data area being created is a DDM data area. The data area contains the name of the remote data area accessed and the name of the remote (target) system that the data area is located on.

Length (LEN)

Specifies the length of the data area being created. If it is a decimal data area, the number of decimal digits to the right of the decimal point can be optionally specified. The type of data area determines the maximum length that a value in that area can have and the default length that is assumed when a length is not specified. The maximum lengths and the defaults for each of the three types are as follows:

Decimal
- Maximum -- 24 digits, 9 decimal positions
- Default -- 15 digits, 5 decimal positions
Character
- Maximum -- 2000 characters
- Default -- 32 characters
Logical -- Maximum and default, 1 character

Note: For character types, the default length is the same as the length of the initial value, if one is specified for the Initial value (VALUE) parameter.

Element 1: Length

1-2000: Specify the length that the value in this data area can have. The length of the value in the data area includes the number of decimal positions in the value. The maximum length of the decimal value is 24 digits, of which no more than 9 can be to the right of the decimal point. In order to use the data area in CL programs, the total length must be limited to 15 digits.

Element 2: Decimal positions

0-9: Specify the number of digits to the right of the decimal point for decimal (*DEC) data areas. If this is not specified, a value of 0 is assumed.

Remote data area (RMTDTAARA)

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

Qualifier 1: Remote data area

name: Specify the name of the remote data area.

Qualifier 2: Library

*LIBL: The library list of the called thread on the target system is searched to locate the data area.
*CURLIB: The current library of the called thread on the target system is searched to locate the data area. If the called thread does not have a current library, the QGPL library is used.
name: Specify the library where the remote data area is located.

Remote location (RMTLOCNAME)

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

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

*RDB: The remote location information from the relational database entry specified for the Relational database (RDB) parameter is used to determine the remote system.
communications-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 area is created but must exist when the DDM data area 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 area.

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 area is created but must exist when the DDM data area is opened. 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 area. The device description does not need to exist when the DDM data area 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 acquired. 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 Default local location name (LCLLOCNAME) specified in the system network attributes is used.
communications-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 area 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 Default mode (DFTMODE) specified in the system network attributes is used.
communications-name: Specify the name of the mode that is used. 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 area 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 Local network ID (LCLNETID) specified in the system network attributes is used.
*NONE: A remote network ID is not used.
communications-name: 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 area 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 authority for the object is taken from the value specified for the Create authority (CRTAUT) parameter of the library in which the object is being 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 Data Area with a Value of Zero

CRTDTAARA   DTAARA(TOTSALES)  TYPE(*DEC)  LEN(15 2)
            VALUE(0)  TEXT('Total sales accumulator')

This command creates a data area named TOTSALES and stores it in the current library specified for the thread. TOTSALES has the following data attributes: it is a 15-position numeric data area with two decimal positions and with an initial value of 0.

Example 2: Creating a Data Area Initialized to Blanks

CRTDTAARA   DTAARA(CUSTOMER)  TYPE(*CHAR)  LEN(148)
            TEXT('Customer name area')

This command creates the data area named CUSTOMER. It can contain as many as 148 characters in the character string. Because no initial value is specified, the data area is initialized to blanks.

Example 3: Creating a DDM Data Area to Access a Data Area at Another System

CRTDTAARA   DTAARA(SOURCE/SALES)  TYPE(*DDM)
            RMTDTAARA(REMOTE/SALES)  RMTLOCNAME(NEWYORK)

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

Error messages

*ESCAPE Messages

CPF1008: Data area &2 not created.
CPF1015: Data area &1 in &2 not found.
CPF1021: Library &1 not found for data area &2.
CPF1022: No authority to library &1 data area &2.
CPF1023: Data area &1 exists in &2.
CPF1024: TYPE and VALUE parameters not compatible.
CPF1025: LEN and VALUE parameters not compatible.
CPF1026: VALUE parameter must be '0' or '1'.
CPF1047: Length not valid for data area &1 in &2
CPF1062: Null string not valid as character value.
CPF1092: Cannot create data area &2 in library &1.
CPF180B: Function &1 not allowed.
CPF9802: Not authorized to object &2 in &3.