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.

The data area can be journaled when created. Refer to the Start Journal Library (STRJRNLIB) command for more information.

Restrictions:

  1. To use this command, the user must have object operational and add authority for the library in which the data area is placed.
  2. 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

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:

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.

Initial value (VALUE)

Specifies the initial value that is assigned to the data area when it is created. The value must be of the type specified for the Type (TYPE) parameter of this command. If no value is specified, a character data area is initialized to blanks, a decimal data area is initialized to a value of 0, and a logical data area is initialized to 0.

unrestricted-value
Specify the initial value of the data area.

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.

Text 'description' (TEXT)

Specifies the text that briefly describes the object.

*BLANK
No text is specified.
'description'
Specify no more than 50 characters of text, 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 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.