Data-Area Operations
These operations are available in both the traditional syntax and free-form syntax.
The IN and OUT operations allow you to retrieve and write one or all data areas in a program, depending on the factor 2 entry.
The IN and OUT operations also allow you to control the locking or unlocking of a data area. When a data area is locked, it can be read but not updated by other programs or procedures.
- For an IN operation with *LOCK specified, an exclusive allow read lock state is placed on the data area.
- For an OUT operation with *LOCK the data area remains locked after the write operation
- For an OUT operation with blank the data area is unlocked after it is updated
- UNLOCK is used to unlock data areas and release record locks, the data areas and/or records are not updated.
During the actual transfer of data into or out of a data area, there is a system-internal lock on the data area. If several users are contending for the same data area, a user may get an error message indicating that the data area is not available.
- A data-area operation cannot be done on a data area that is not defined to the operating system.
- Before the IN, OUT, and UNLOCK operations can be done on a data area, you must specify the DTAARA keyword on the definition specification for the data area, or specify the data area in the result field of an *DTAARA DEFINE statement. (For further information on the DEFINE statement, see DEFINE (Field Definition).)
- A locked data area cannot be updated or locked by another RPG program; however, the data area can be retrieved by an IN operation with factor 1 blank.
- A data-area name cannot be the name of a multiple-occurrence data structure, an input record field, an array, an array element, or a table.
- A data area cannot be the subfield of a multiple occurrence data structure, a data-area data structure, a program-status data structure, a file-information data structure (INFDS), or a data structure that appears on an *DTAARA DEFINE statement.
- If the name of the data area is determined at runtime, due to the DTAARA(*VAR) keyword being used, the variable containing the name must be set before an IN operation. If a data area is locked because of a prior *LOCK IN operation, any other operations (IN, OUT, UNLOCK) for the data area will use the previously locked data area, and the variable containing the name will not be consulted.
- If the library name is not specified by the DTAARA keyword, the library list will be used to locate the data area.
A data area data structure is automatically read and locked at program initialization time, and the contents of the data structure are written to the data area when the program ends with LR on. If the data area for a data area data structure is not found, it will be created with an initial value of blanks. If the library list was searched for the data area, the new data area will be created in QTEMP.
In free-form, the DTAARA(*AUTO) keyword specifies that the data structure is a data area data structure. In fixed-form, a data structure defined with a U in position 23 of the definition specifications indicates that the data structure is a data area.
In some cases, you can use the IN, OUT and UNLOCK operation codes to specify further operations for the data area. For a free-form definition, you also specify *USRCTL as a parameter. For a fixed-form definition, you specify the DTAARA keyword.
If the data area for a data area data structure is not found, it will be created with an initial value of blanks. If the library list was searched for the data area, the new data area will be created in QTEMP.
- Specify the DTAARA(*LDA) keyword on the definition specification for the data area.
- Specify UDS on a fixed-form definition specification for the data area and leave the name blank.
- Specify *N as the name on a free-form definition and specify the DTAARA keyword without a name.
- Specify *LDA in factor 2 of a *DTAARA DEFINE statement.
To define the *PDA you may specify the DTAARA(*PDA) keyword on the definition specification for the data area, or specify *PDA in factor 2 of a *DTAARA DEFINE statement.