Retrieve Data Area (QWCRDTAA) API
Required Parameter Group:
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(*) |
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes
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 QSYS2.DATA_AREA_INFO view and QSYS2.DATA_AREA_INFO table function can be used as alternatives to this API. See DATA_AREA_INFO view and DATA_AREA_INFO table function for more information.
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.
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
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. |
API introduced: V2R3