CHGDTAARA (Change Data Area)

CHGDTAARA Command syntax diagram

 

Purpose

The Change Data Area (CHGDTAARA) command changes the value of the local data area, the group data area, the program initialization parameter data area, or the specified data area stored in a library. This command does not change the data attributes or any of the object attributes of the data area. The new value must have the same type and a length less than or equal to the data area length or the specified substring length.

In group jobs, the data area specified may be the group data area (*GDA). This data area is automatically associated with the group and cannot be accessed from jobs outside the group. The length of this character data area is 512 bytes. More information about group jobs is in the Work Management book.

The local data area (*LDA) is a character data area 1024 bytes in length. It is automatically associated with your job and jobs outside the group cannot get access to it.

In prestart jobs, the data area specified may be the data area that contains program initialization parameter data (*PDA). This data area is automatically associated with your prestart job and other jobs cannot get access to it. The length of this character data area is 2000 bytes. More information about prestart jobs is in the Work Management book.

For character data areas, a substring of the data area may be changed without affecting the rest of the data area. This substring is defined by specifying the starting position and the length of the substring. In this case, the new value must have a length less than or equal to the substring length.

When the CHGDTAARA command is run to change a data area other than the local data area, group data area, or program initialization parameter data area, that data area is locked to the program during the change operation so that commands in other jobs cannot change or destroy it until the operation is completed. If the data area is shared with other jobs, and it is updated in steps involving more than one command in a job, the data area must be explicitly allocated to that job until all the steps have been performed. Data areas, other than the group data area, local data area, or program initialization parameter data area, can be explicitly allocated with the Allocate Object (ALCOBJ) command. No allocation is necessary when the CHGDTAARA command is run specifying *GDA, *LDA, or *PDA in the DTAARA parameter.

 

Restrictions

1. To use this command, the user must have update authority for the data area being changed and read authority for the library in which it is stored. No specific authority is required for the local data area or the group data area.
   
2. This command is conditionally threadsafe. The following restrictions apply:

   1. Changing DDM data areas in a job that allows multiple threads is not threadsafe.
      
   2. Changing DDM data areas will fail when more than one thread is active in a job.
      
   3. Changing the special data areas (*LDA, *GDA and *PDA) is allowed from the initial thread only and will fail if attempted from a secondary thread.

 

Required Parameters

DTAARA

Specifies the qualified name of the data area whose value is being changed. It optionally specifies, for character data areas only, the starting position and length of the character string that is changed in the data area.

Element 1: Data Area Name

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

*GDA: The group data area associated with a group job is changed.

*LDA: The local data area associated with a job is changed.

*PDA: The program initialization parameter data area associated with a prestart job is changed.

data-area-name: Specify the name of the data area within which a character string is being changed.

Element 2: Starting Position of the Data Area

*ALL: The entire data area is changed.

substring-starting-position: Specify the starting position of the data area that is changed.

Element 3: Length of the Data Area

substring-length: Specify the length of the data area that is changed.

VALUE

Specifies the new value stored in the data area. Specify a value that is valid for the data attributes specified in the data area's description. If TYPE(*CHAR) or TYPE(*LGL) is specified when the data area was created and the value specified here is numeric, the value must be enclosed in apostrophes. If TYPE(*DEC) was specified, the value must not be enclosed in apostrophes.

Examples for CHGDTAARA

Example 1: Changing the Data Area Value

CHGDTAARA   DTAARA(MYLIB/MYDATA)  VALUE(GOODNIGHT)

This command changes the value of the data area named MYDATA in library MYLIB to GOODNIGHT. The data area must be for character data and must be 9 or more characters in length.

Example 2: Changing the Logical Value of the Data Area

CHGDTAARA   PAYROLLSW  '0'

This command changes the logical value of the data area named PAYROLLSW to zero (0). The library search list is used to locate the data area.

Example 3: Changing Specific Characters of the Local Data Area

CHGDTAARA   DTAARA(*LDA  (5 4))  VALUE('TWO')

This command changes characters 5 through 8 of the user's local data area. Because the new value is shorter than the substring, it is padded with a blank.

Error messages for CHGDTAARA

*ESCAPE Messages

CPF101A

Operation on DDM data area &1 in &2 failed.

CPF1015

Data area &1 in &2 not found.

CPF1018

No authority to change data area.

CPF1019

VALUE parameter not correct.

CPF1020

VALUE parameter too long.

CPF1021

Library &1 not found for data area &2.

CPF1022

No authority to library &1 data area &2.

CPF1026

VALUE parameter must be '0' or '1'.

CPF1043

Boundary alignment for data area not valid.

CPF1044

AREA parameter not valid for data area.

CPF1045

CPYPTR parameter not valid for data area.

CPF1046

DTAARA(*GDA) not valid because job not group job.

CPF1062

Null string not valid as character value.

CPF1063

Cannot allocate data area &1 in library &2.

CPF1067

Cannot allocate library &1.

CPF1072

DTAARA(*PDA) not valid because job not prestart job.

CPF1087

Substring not allowed for decimal or logical data area.

CPF1088

Starting position outside of data area.

CPF1089

Substring specified for data area not valid.

CPF1138

VALUE parameter not valid type for data area &1.

CPF1155

VALUE parameter too long for data area &1.

CPF1162

Boundary alignment for data area &1 not valid.

CPF1163

AREA parameter not valid for data area &1.

CPF1168

CPYPTR parameter not valid for data area &1.

CPF1170

Starting position outside of data area &1.

CPF1192

Substring specified for data area &1 not valid.

CPF180B

Function &1 not allowed.

CPF180C

Function &1 not allowed.

CPF18BE

Data area &1 not changed because entry not journaled.

CPF9899

Error occurred during processing of command.>