Retrieve Data Area (QWCRDTAA) API

The Retrieve Data Area (QWCRDTAA) API allows you to retrieve the contents of a data area. Distributed data management (DDM) data areas are supported by this API. In other words, this API can retrieve a data area value from a data area that exists on a remote AS/400.

Authorities and Locks

Library Authority

*USE

Data Area Authority

*USE

Data Area Lock

*SHRRD

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold. For the format, see Format of Data Returned.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable described in Format of Data Returned. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.

Qualified data area name

INPUT; CHAR(20)

The first 10 characters contain the data area name, and the second 10 characters contain the name of the library where the data area is located.

When one of the special values is specified, the library name must be blank. The special values for the data area are:

*LDA

Local data area

*GDA

Group data area

*PDA

Program initialization parameter data area

The special values supported for the library name are:

*LIBL

The library list.

*CURLIB

The job's current library.

Starting position

INPUT; BINARY(4)

The first byte of the data area to be retrieved. A value of 1 will identify the first character in the data area. The maximum value allowed for the starting position is 2000. A value of -1 will return all the characters in the data area.

Length of data

INPUT; BINARY(4)

The length of the data area substring to be retrieved. The length of data parameter must be greater than 0. If the length of data parameter is greater than the size of the data area, the receiver variable is padded with blanks.

The length of data parameter added to the starting position minus one must be between the substring starting position and the data area end; otherwise, CPF1089 (Substring specified for data area not valid) is issued. If you have a small data area and only want the fixed portion of the data returned, you must code -1 for the starting position.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of Data Returned

The receiver variable holds the information returned for the data area. The following table shows the format of the receiver variable.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Bytes available
4	4	BINARY(4)	Bytes returned
8	8	CHAR(10)	Type of value returned
18	12	CHAR(10)	Library name
28	1C	BINARY(4)	Length of value returned
32	20	BINARY(4)	Number of decimal positions
36	24	CHAR(*)	Value

Field Descriptions

Bytes available. The length of all data available to return. All available data is returned if enough space is provided.

Bytes returned. The length of all data actually returned. If the data is truncated because the receiver variable was not sufficiently large to hold all of the data available, this value will be less than the bytes available.

Length of value returned. The length of the value that was returned.

Library name. The name of the library where the data area was found. This field will be blank if one of the special values was specified for the first ten characters of the qualified data area name.

Number of decimal positions. The number of decimal positions.

Type of value returned. The following values may be returned.

*CHAR

A character data area.

*DEC

A decimal data area. The value returned will be a packed decimal value.

*LGL

A logical data area.

Value. The contents of the data area.

Usage Notes

This API is threadsafe, except in the following situations:

• The retrieval of DDM data areas in a job that allows multiple threads is not threadsafe.

• The retrieval of DDM data areas will not be allowed when more than one thread is active in a job.

Error Messages

CPF101A E

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

CPF1015 E

Data area &1 in &2 not found.

CPF1016 E

No authority to data area &1 in &2.

CPF1021 E

Library &1 not found for data area &2.

CPF1022 E

No authority to library &1 data area &2.

CPF1046 E

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

CPF1063 E

Cannot allocate data area &1 in library &2.

CPF1067 E

Cannot allocate library &1.

CPF1072 E

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

CPF1088 E

Starting position outside of data area.

CPF1089 E

Substring specified for data area not valid.

CPF180B E

Function &1 not allowed.

CPF1863 E

Length of value not valid.

CPF24B4 E

Severe error while addressing parameter list.

CPF3CF1 E

Error code parameter not valid.

CPF3C19 E

Error occurred with receiver variable specified.

CPF3C24 E

Length of the receiver variable is not valid.

CPF3C90 E

Literal value cannot be changed.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.