get relative

The EGL get relative statement reads a numerically specified row in a relational-database result set. The row is identified in relation to the cursor position in the result set.

You can use this statement only if you specified the scroll option in the related open statement.

Syntax diagram for the get relative statement

position

An integer item or literal.

If the value of position is positive, the position is an increment to the current numeric position in the result set. Specifying get relative 2 when the cursor is on the first row, for example, retrieves the third row; and specifying get relative 1 is equivalent to specifying get next.

If the value of position is negative, the position is a decrement to the current numeric position in the result set. Specifying get relative -2 when the cursor is on the third row, for example, retrieves the first row; and specifying get relative -1 is equivalent to specifying get previous.

A value of zero for position retrieves the row at the cursor position already in effect and is equivalent to specifying get current.

record name

Name of an SQL record.

from resultSetID

An ID that ties the get relative 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 (:).

If you issue a get relative statement to retrieve a row that was selected by an open statement that 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 relative 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 relative statement that attempts to access a row that is not in the result set, 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
resultSetID
SQL support

Related tasks
Syntax diagram