*---------*---------------*-----------------*----------------*---------------* | CODE | FACTOR 1 | FACTOR 2 | RESULT | INDICATORS | | | | | FIELD | | *---------*---------------*-----------------*----------------*---------------* | CHAIN | Search | File name | Data | NR ER _ | | (N) | argument | | structure | | *---------*---------------*-----------------*----------------*---------------*
The CHAIN operation retrieves a record from a full procedural file (F in position 16 of the file description specifications), sets a record identifying indicator on (if specified on the input specifications), and places the data from the record into the input fields.
Factor 1, the search argument, must contain the key or relative record number used to retrieve the record. If access is by key, factor 1 can be a field name, a named constant, a figurative constant, or a literal. In addition, a KLIST (Define a Composite Key) name can be specified in factor 1 for an externally described file. If access is by relative record number, factor 1 must contain an integer literal or a numeric field with zero decimal positions.
Factor 2 specifies the file or record format name that is to be read. A record format name is valid with an externally described file. If factor 2 is a file name and access is by key, the CHAIN operation retrieves the first record that matches the search argument.
If factor 2 is a record format name and access is by key, the CHAIN operation retrieves the first record of the specified record type whose key matches the search argument. If no record is found of the specified record type that matches the search argument, a no-record-found condition exists.
You can specify a data-structure name in the result field only if the file named in factor 2 is a program described file (identified by an F in position 19 of the file description specification). When you specify a data-structure name in the result field, the CHAIN operation retrieves the first record whose record identifier matches the search argument in factor 1 and places it in the data structure. See File Operations for information on transferring data between the file and the data structure.
For a WORKSTN file, the CHAIN operation retrieves a subfile record.
For a multiple device file, you must specify a record format in factor 2. Data is read from the program device identified by the field specified in the ID entry of the file specifications continuation line. If there is no such entry, data is read from the device for the last successful input operation to the file.
If the file is specified as input, all records are read without locks and position 53 must be blank. If the file is specified as update, all records are locked if position 53 is blank.
If you are reading from an update disk file, you can specify an N in position 53 to indicate that no lock should be placed on the record when it is read. See the RPG/400* User's Guide for more information.
Positions 54 and 55 must contain an indicator that is set on if no record in the file matches the search argument. Positions 56 and 57 can contain an indicator to be set on if the CHAIN operation is not completed successfully. Positions 58 and 59 must be blank.
When the CHAIN operation is successful, the file specified in factor 2 is positioned such that a subsequent read operation retrieves the next sequential record following the retrieved record. When the CHAIN operation is not completed successfully (for example, an error occurs or no record is found), the file specified in factor 2 must be repositioned (for example, by a CHAIN or SETLL operation) before a subsequent read operation can be done on that file.
If an update (on the calculation or output specifications) is done on the file specified in factor 2 immediately after a successful CHAIN operation to that file, the last record retrieved is updated.
Chain Examples illustrates uses of the CHAIN operation.
Figure 15. CHAIN Operation with a File Name in Factor 2
*...1....+....2....+....3....+....4....+....5....+....6....+....7... CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++ C* C* The CHAIN operation retrieves the first record from the file, C* FILEX, that has a key field with the same value as the search C* argument KEY (factor 1). C* C KEY CHAINFILEX 60 INDICATOR 60 C* IF NOT FOUND C* C* If a record with a key value equal to the search argument is not C* found, indicator 60 is set on and the GOTO operation conditioned C* by indicator 60 is processed. If a record is found with a key C* value equal to the search argument, the program continues with C* the calculations after the GOTO operation. C* C 60 GOTO NOTFND
Figure 16. CHAIN Operation with a Record Format Name and with No Lock
*...1....+....2....+....3....+....4....+....5....+....6....+....7... CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++ C* C* The CHAIN operation uses the value contained in the search C* argument KEY to retrieve a record of the record type REC1 from C* an externally described file. If no record is found of the C* specified type that has a key field equal to the search C* argument, indicator 72 is set on. A complex key with a KLIST is C* used to retrieve records from files that have a composite key. C* If a record of the specified type is found that has a key field C* equal to the search argument, the calculations after the GOTO C* operation are processed. C* C KEY CHAINREC1 72 INDICATOR 72 C* IF NOT FOUND C KEY KLIST C KFLD FLD1 C KFLD FLD2 C *IN72 IFEQ *OFF C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++ C* C* The UPDAT operation modifies all the fields in the REC1 record. C* C UPDATREC1 UPDATE C ENDIF C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++ C* C* The following example shows a CHAIN with no lock. C* C MOVE 3 KEY C KEY CHAININPUT N
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.