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 i5/OS.

Authorities and Locks

Library Authority

*EXECUTE

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.

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.

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