get previous

The EGL get previous statement either reads the previous row from a relational-database result set or reads the previous record in the file that is associated with a specified EGL indexed record.

You can use this statement for a relational-database result set only if you specified the scroll option in the related open statement.

Syntax diagram for the get previous statement

record name: Name of the I/O object: an indexed or SQL record.
from resultSetID: For SQL processing only, an ID that ties the get previous statement to an open statement run earlier in the same program. For details, see resultSetID.
into: Begins an EGL into clause, which lists the items that receive values from a relational-database table.
item: An item that receives the value of a particular column. Do not precede the item name with a colon (:).

An example for an indexed record is as follows:

  record1.hexKey = "FF";
  set record1 position;

  try
    get previous record1;
  onException
    myErrorHandler(8);
    return;
  end
  
  while (record1 not endOfFile)
    processRecord(record1); // handle the data

    try
      get previous record1;
    onException
      myErrorHandler(8);
      return;
    end
  end

Details on the get previous statement depend on whether you are using an indexed record or are concerned with SQL processing.

Indexed record

When a get previous statement operates on an indexed record, the effect is based on the current file position, which is set by either of these operations:

A successful input or output (I/O) operation such as a get statement or another get previous statement; or
A set statement of the form set record position.

Rules for an indexed record are as follows:

When the file is not open, the get previous statement reads a record with the highest key value in the file.
Each subsequent get previous reads a record that has the next lowest key value in relation to the current file position. An exception for duplicate keys is described later.
After a get previous statement reads the record with the lowest key value in the file, the next get previous statement results in the EGL error value endOfFile.
The current file position is affected by any of these operations:
- An EGL set statement of the form set record position establishes a file position based on the set value, which is the key value in the indexed record that is referenced by the set statement. The subsequent get previous statement against the same indexed record reads the file record that has a key value equal to or less than the set value. If no such record exists, the result of the get previous statement is endOfFile.
  If the set value is filled with hexadecimal FF, the result of a set statement of the form set record position is as follows:
  - The set statement establishes a file position after the last record in the file
  - If a get previous statement is the next I/O operation, the generated code retrieves the last record in the file
- A successful I/O statement other than a get previous statement establishes a new file position, and the subsequent get previous statement against the same EGL record reads the previous file record. After a get next statement reads a file record, for example, the get previous statement either reads the file record with the next-lowest key or returns endOfFile.
- If a get next statement returns endOfFile, the subsequent get previous statement retrieves the last record in the file.
- After an unsuccessful get, get next, or get previous statement, the file position is undefined and must be re-established by a set statement of the form set record position or by an I/O operation other than a get next or get previous statement.
When you are using an alternate index and duplicate keys are in the file, the following rules apply:
- Retrieval of a record with a lower-valued key occurs only after get previous statements have read all the records that have the same key as the most recently retrieved record. The order in which duplicate-keyed records are retrieved is the order in which VSAM returns the records.
- If a get previous statement follows a successful I/O operation other than a get previous, the get previous statement skips over any duplicate-keyed records and retrieves the record with the next lower key.
- The EGL error value duplicate is not set when your program retrieves the last record in a group of records containing the same key.

Consider a file in which the keys in an alternate index are as follows:

  1, 2, 2, 2, 3, 4

Each of the following tables illustrates the effect of running a sequence of EGL statements on the same indexed record.

EGL statement (in order)	Key in the indexed record	Key in the file record retrieved by the statement	EGL error value for COBOL
set (of the form set record position)	1	--	--
get previous	any	1	--

EGL statement (in order)	Key in the indexed record	Key in the file record retrieved by the statement	EGL error value
get	3	3	—
get previous	any	2 (the first of three)	duplicate
get previous	any	2 (the second)	duplicate
get previous	any	2 (the third)	—
get previous	any	1	—

EGL statement (in order)	Key in the indexed record	Key in the file record retrieved by the statement	EGL error value
set (of the form set record position)	2	—	duplicate
get next	any	2 (the first)	—
get next	any	2 (the second)	duplicate
get previous	any	1	—
get previous	any	--	endOfFile

EGL statement (in order)	Key in the indexed record	Key in the file record retrieved by the statement	EGL error value
set (of the form set record position)	1	--	--
get previous	any	1	--

SQL processing

When a get previous statement operates on an SQL record, your code reads the previous row from those selected by an open statement, but only if you have specified the scroll option. If you issue a get previous statement to retrieve a row that was selected by an open statement that also has the forUpdate option, you can do any of these:

Change the row with an EGL replace statement
Remove the row with an EGL delete statement
Change or remove the row with an EGL execute statement

An SQL FETCH statement represents the EGL get previous statement in the generated code. The format of the generated SQL statement cannot be changed, except to set the INTO clause.

If you issue a get previous statement that attempts to access a row that is previous to the first selected row, the EGL run time acts as follows:

Does not copy data from the result set
Leaves the cursor open, with the cursor position unchanged
Sets the SQL record (if any) to noRecordFound

In general, if an error occurs and processing continues, the cursor remains open, with the cursor position unchanged.

Finally, when you specify SQL COMMIT or sysLib.commit, your code retains position in the cursor that was declared in the open statement, but only if you use the hold option in the open statement.

Related concepts
Record types and properties

Related tasks
Syntax diagram