CRTDTAARA (Create Data Area)

CRTDTAARA Command syntax diagram

 

Purpose

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 optionally be initialized to a specific value.

Data areas (which are a type of operating system object) 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 CHGDTAARA commands to change the same data area at the same time.

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

The Create Data Area (CRTDTAARA) command can optionally create a distributed data management (DDM) data area. This is done by specifying *DDM on 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 refer to a remote data area by the DDM data area's name, not by the remote data area's name. (The DDM data area name, however, 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

  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. Create DDM data areas in a job that allows multiple threads is not threadsafe.

    2. Create DDM data areas will fail when more than one thread is active in a job.

 

Required Parameters

DTAARA
Specifies the qualified name of the data area being created. The name of the data area can be qualified by one of the following library values:

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

library-name: Specify the name of the library where the data area is created.

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

TYPE
Specifies the type of value contained in the data area being created. The data area can contain a character value, a decimal value, a logical one (1) or zero (0), or a Distributed Data Management (DDM) data area can be created.

*DEC: The data area contains a decimal value.

*CHAR: The data area contains a character string value.

*LGL: The 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.

 

Optional Parameters

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 (specified by the TYPE parameter) determines the maximum length that its value can have and the default length that is assumed if LEN is not specified. The maximum lengths and the defaults for each of the three types are described in Table 1, at the end of this description.

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

Element 1: Value Length

length: Specify the maximum length of the value in this data area. Valid values range from 1 through 2000.

Element 2: Number of Decimal Positions

decimal-positions: Specify the number of decimal positions that the value in this data area can have. This option is valid only for decimal data areas. 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. The total length of the data area in CL programs cannot exceed 15 digits. If TYPE(*DEC) is specified and the number of decimal positions is not specified, a value of 0 is assumed. Valid values range from 0 through 9.

VALUE
Specifies the beginning value that is assigned to the data area when it is created. The beginning value must be of the type specified by the TYPE parameter. If no beginning 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'.

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.

The name of the data area can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

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

library-name: Specify the name of the library to be used.

remote-data-area-name: Specify up to 10 characters for a data area name that identifies the remote data area accessed.

  • 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 area.

  • If *CURLIB is specified, the current library in the called job on the target system is searched to locate the data area.

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 iSeries 400 computers that are at a release of OS/400 that supports remote data areas.

remote-location-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.

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.

device-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.

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.

local-location-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.

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.

mode-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.

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 area is accessed.

AUT
Specifies the authority being given to the users who do not have specific authority to the data area, who are not on an authorization list, and whose user group has no specific authority to the object.

*LIBCRTAUT: The public authority for the data area is taken from the value on the CRTAUT parameter of the target library. (The target library is the library that is to contain the data area. The public authority is determined when the data area is created. If the CRTAUT value for the library changes after the data area is created, the new value does 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 authority and object management authority. The user can change the object and perform basic functions on the object. Change authority provides object operational 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 on the object except those limited to the owner or controlled by authorization list management 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 can also change ownership of the data area.

*USE: The user performs basic operations on the data area, such as running a program or displaying the contents of a file. The user cannot change the data area. *USE authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the data area.

authorization-list-name: Specify the name of the authorization list used.

TEXT
Specifies text that briefly describes the data area.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Table 1. Data Area Lengths

Type Maximum Length Default Length
Decimal 24 digits, 9 decimal positions 15 digits, 5 decimal positions
Character 2000 characters 32 characters
Logical 1 character 1 character

Examples for CRTDTAARA

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 job. 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.

The following example describes the creation of a DDM data area.

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

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 an iSeries 400 in New York.

Error messages for CRTDTAARA

*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.