Function
The RETURN statement obtains individual records in sorted order from the sort-file.
Format
RETURN sort-file-name RECORD [INTO identifier]
AT END imperative-statement-1
[NOT AT END imperative-statement-2]
[END-RETURN]
Syntax rules
sort-file-name must be defined in a sort-file description entry.
The storage area associated with identifier and the record area associated with sort-file-name must not be the same storage area.
General rules
Execution of a RETURN statement has the effect that the next record is made available according to the order specified by the keys of the SORT/MERGE statement. Then it can be processed in the record areas of the sort-file.
If more than one record description is supplied for the logical record of a file, these records will automatically share the same storage area; this corresponds to an implicit redefinition of the area. The contents of any data item which may be outside the area of the current record will be undefined after a RETURN statement is executed.
The INTO phrase may be specified in two cases:
if only one record description is subordinate to the sort-merge file description entry,
if all record names associated with file-name and the data item referenced by identifier describe a group item of an elementary alphanumeric item.
The INTO phrase, when specified, makes the RETURN statement equivalent to a RETURN statement followed by a MOVE statement.
When this phrase is written, records are returned from the sort-file and then moved to the area specified by identifier; identifier must not refer to a data item within the record of that sort-file. The move is made according to the rules specified for a MOVE statement without CORRESPONDING phrase. The size of the current record is determined by rules specified for the RECORD clause (see section "RECORD clause").
If the sort file description entry contains a RECORD IS VARYING clause, the implied move is a group move.The MOVE statement is not carried out if an at end condition occurs.
Any subscripting or indexing of identifier is evaluated after the record has been obtained and immediately before it is moved into the data area.
If the INTO phrase was used, the data will be available both in the record area and in the data item specified by identifier.
The execution of the RETURN statement causes the next existing record in the file referenced by file-name-1, as determined by the keys listed in the SORT or MERGE statement, to be made available in the record area associated with file-name-1.If no next logical record exists in the file referenced by file-name-1, the at end condition exists. Execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred according to the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the RETURN statement and the NOT AT END phrase is ignored, if specified. When the at end condition occurs, execution of the RETURN statement is unsuccessful and the contents of the record area associated with file-name-1 are undefined. After the execution of imperative-statement-1 in the AT END phrase, no RETURN statement may be executed as part of the current output procedure.
If an at end condition does not occur during the execution of a RETURN statement, then after the record is made available and after executing any implicit move resulting from the presence of an INTO phrase, control is transferred to imperative-statement-2, if NOT AT END was specified; otherwise, control is transferred to the end of the RETURN statement.
A RETURN statement may be used only within the range of the output procedure associated with a SORT/MERGE statement for sort-file-name.