RTVDTAARA (Retrieve Data Area)

RTVDTAARA Command syntax diagram

 

Purpose

The Retrieve Data Area (RTVDTAARA) command is used in a CL program or REXX procedure to retrieve all or part of a specified data area and to copy it into a CL variable. RTVDTAARA does not retrieve any other attributes of the data area. Existence of the data area is not required at the time the CL program is compiled.

If the job is a group job, the data area specified may be the group data area (*GDA). This data area is automatically associated with the group, and it is inaccessible 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 Link to PDF book.

A local data area (*LDA) is a character data area that is 1024 bytes in length, and it is automatically associated with the job. Another job cannot access the local data area.

If the job is a prestart job, the data area specified may be the data area that contains program initialization parameter data (*PDA). This data area is automatically associated with the prestart job and is inaccessible from other jobs. The length of this character data area is 2000 bytes. More information about prestart jobs is in the Work Management book.

When a local data area or group data area must be retrieved during the processing of the RTVDTAARA command, the data area is locked during the retrieval operation so that commands in other jobs cannot change or destroy it until the operation is complete. If the data area is shared with other jobs and is updated in steps involving more than one command in a job, the data area should be explicitly allocated to that job until all the steps have been performed. A data area other than a local data area, group data area, or program initialization parameter data area can be explicitly allocated with the Allocate Object (ALCOBJ) command. No allocation is necessary for a local data area, group data area, or program initialization parameter data area.

 

Restrictions

  1. To use this command, the user must have *USE authority for the data area and *EXECUTE authority for the library where the data area is located. No specific authority is required to retrieve the value of a local data area or group data area.

  2. This command is conditionally threadsafe. The following restrictions apply:

    1. Retrieving DDM data areas in a job that allows multiple threads is not threadsafe.

    2. Retrieving 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 whose value is retrieved.

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.

Element 1: Data Area Name

data-area-name: Specify the name of the data area whose value is being retrieved.

Element 2: Data Area Options

*GDA: The value of the group data area is being retrieved. This value is valid only if this is a group job.

*LDA: The value of the local data area is being retrieved.

*PDA: The value of the program initialization parameter data area is being retrieved. This value is valid only if this is a prestart job.

The substring retrieval option, which is valid for character data areas only, specifies the starting position and the length of the portion of the data area that is being retrieved into the CL character variable.

Element 3: Starting Position of the Data Area

*ALL: The entire data area is retrieved.

substring-starting-position: Specify the starting position of the data area being retrieved.

Element 4: Length of the Data Area

substring-length: Specify the length of the data area substring being retrieved.

It is not possible to retrieve data outside the data area. The combination of starting position and length must always specify positions within the data area.

RTNVAR
Specifies the name of the CL program variable that receives the contents of the data area being returned.

No type conversion is performed by the RTVDTAARA command:

  • If RTNVAR is declared as TYPE(*DEC), the data area retrieved must be TYPE(*DEC).

  • If RTNVAR is declared as TYPE(*CHAR), the data area retrieved must be either TYPE(*CHAR) or TYPE(*LGL).

  • If RTNVAR is declared as TYPE(*LGL), the data area retrieved must be either TYPE(*LGL) or TYPE(*CHAR) with a value of either '0' or '1'.

If a retrieved character string is shorter than the length of the variable specified by the RTNVAR parameter, the value is padded on the right with blanks. The retrieved string length must be less than or equal to the CL variable length.

When decimal data areas are retrieved, the decimals are aligned. The value of the integer portion of the data area must fit into the integer portions of the CL variable. Fractional data is truncated if the fraction contains more digits than the CL variable.

Examples for RTVDTAARA

Assume data area DA1 has been created by the following command: 

CRTDTAARA   DTAARA(DA1)  TYPE(*CHAR)  LEN(3)  VALUE(ABC)

and variable &CLVAR1 has been declared as: 

DCL   VAR(&CLVAR1)  TYPE(*CHAR) LEN(5)  VALUE(VWXYZ)

Example 1: Running This Command 

RTVDTAARA   DTAARA(DA1)  RTNVAR(&CLVAR1)

sults in:


   
&CLVAR1 = 'ABC  '





Example 2: Running This Command


   
RTVDTAARA   DTAARA(DA1 (2 1))  RTNVAR(&CLVAR1)




   
sults in:


   
&CLVAR1 = 'B    '





Example 3: Decimal Data Area Example



Assume data area DA2 has been created with the following attributes:


   
CRTDTAARA   DTAARA(DA2)  TYPE(*DEC)  LEN(5 2)  VALUE(12.39)





and variable &CLVAR2 has been declared as:


   
DCL   VAR(&CLVAR2)  TYPE(*DEC)  LEN(5 1)  VALUE(4567.8)





Example 4: Running This Command


   
RTVDTAARA   DTAARA(MYLIB/&DTAARA)  RTNVAR(&CLVAR2)




   
sults in:


   
CLVAR2 = 0012.3





Note that fractional digits are truncated instead of rounded.



Error messages for RTVDTAARA



*ESCAPE Messages




CPF0811



RTNVAR parameter has incorrect length for data area.



CPF0812



RTNVAR parameter type not valid for data area &1.



CPF0813



Value in data area &1 not logical value.



CPF101A



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



CPF1015



Data area &1 in &2 not found.



CPF1016



No authority to data area &1 in &2.



CPF1021



Library &1 not found for data area &2.



CPF1022



No authority to library &1 data area &2.



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.



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.



CPF180B



Function &1 not allowed.



CPF9899



Error occurred during processing of command.End of change