| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Qualified data area name | Input | Char(20) |
| 4 | Starting position | Input | Binary(4) |
| 5 | Length of data | Input | Binary(4) |
| 6 | Error code | I/O | Char(*) |
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 IBM® i.
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.
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.
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. |
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.
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.
The structure in which to return error information. For the format of the structure, see Error code parameter.
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 |
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.
This API is threadsafe, except in the following situations:
| Message ID | Error Message Text |
|---|---|
| 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. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| 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. |