The FETCH statement assigns the values of the current row in a result table (see result table name) to parameters.
<fetch_statement> ::=
FETCH [FIRST | LAST | NEXT | PREV | <position> | SAME]
[<result_table_name>] INTO <parameter_spec>,...
<position> ::= POS
(<unsigned_integer>) | POS (<parameter_spec>)
| ABSOLUTE <integer> | ABSOLUTE <parameter_spec>
| RELATIVE <integer> | RELATIVE <parameter_spec>
result_table_name, parameter_spec, unsigned_integer, integer
If no result table name is specified, the fetch statement refers to the last unnamed result table that was generated (see named/unnamed result table).
Depending on the search method, either all the rows in the result table are searched when the OPEN CURSOR statement, the SELECT statement (select_statement), or the SELECT statement (named_select_statement) is executed and the result table is generated, or each subsequent row in the result table is searched when a FETCH statement is executed, but they are not physically stored. This must be taken into account for the time behavior of FETCH statements. Depending on the isolation level selected, this can also cause locking problems with a FETCH, e.g. return code 500 - LOCK REQUEST TIMEOUT.
Let C be the position in the result table. The return code 100 - ROW NOT FOUND - is output and no values are assigned to the parameters if any of the following conditions is satisfied:
· The result table is empty.
· C is positioned on or after the last result table row, and FETCH or FETCH NEXT is specified.
· C is positioned on or before the first row of the result table and FETCH PREV is specified.
· FETCH is specified with a position which does not lie within the result table.
· FETCH FIRST or FETCH LAST: the result table is not empty. C is positioned in the first or last row of the result table and the values of this row are assigned to the parameters.
· FETCH or FETCH NEXT: C is positioned before a row in the result table. C is positioned in this row and the values of this row are assigned to the parameters.
· FETCH or FETCH NEXT: C is positioned in a row that is not the last row in the result table. C is positioned in the next row and the values in this row are assigned to the parameters.
· FETCH PREV: C is positioned behind a row in the result table. C is positioned in this row and the values of this row are assigned to the parameters.
· FETCH PREV: C is positioned in a row that is not the first row in the result table. C is positioned in the previous row and the values in this row are assigned to the parameters.
Independently of whether an ORDER clause is specified, there is an implicit order of the rows in a result table, to enable internal numbering. This can be displayed by specifying a rowno column as a selected column. The specified position refers to this internal numbering.
If a position is defined with POS, the parameter specification must denote a positive integer.
If a position that is less than or equal to the number of rows in the result table was defined with POS, C is set to the corresponding row and the values of this row are assigned to the parameters. If a position that is greater than the number of rows in the result table was specified, the message 100 – ROW NOT FOUND is output.
Let x be the value of the integer or parameter specification specified with the position. Let abs_x be the absolute value of x.
· FETCH ABSOLUTE and x is : FETCH ABSOLUTE is the same as a FETCH POS.
· FETCH ABSOLUTE and x=0: the return code 100 – row not foundis set.
· FETCH ABSOLUTE and x is negative: C is set after the last row of the result table where FETCH PREV is executed abs_x times. The last row found is the result of the SQL statement. This description refers to the logic and not the flow of the statement. If abs_x is larger than the number of rows in the result table, the message 100 – ROW NOT FOUND is output.
Let x be the value of the integer or parameter specification specified with the position. Let abs_x be the absolute value of x.
· FETCH RELATIVE and x is positive: FETCH NEXT is executed x times from the current position in the result table C.
· FETCH RELATIVE and x=0: corresponds to a FETCH SAME.
· FETCH RELATIVE and x is negative: FETCH PREV is executed abs_x times starting from C. This description refers to the logic and not the flow of the statement. The return code 100 – row not found is output if one of the conditions in the section "row not found" is fulfilled.
The last row found in the result table is output again.
The parameter specification specified in position must denote an integer.
The remaining parameters in the parameter specification are output parameters. The parameter identified by the nth parameter specification corresponds to the nth value in the current result table row. If the number of columns in this row exceeds the number of specified parameters, the column values for which no corresponding parameters exist are ignored. If the number of columns in the row is less than the number of specified parameters, no values are assigned to the remaining parameters. You must specify an indicator name in order to assign NULL values or special NULL values.
Numbers are converted and character strings are truncated or lengthened, if necessary, to suit the corresponding parameters. If an error occurs when assigning a value to a parameter, the value is not assigned and no further values are assigned to the corresponding parameters for this fetch statement. Any values that have already been assigned to parameters remain unchanged.
Let p be a parameter and v the corresponding value in the current row of the result table.
· v is a number: p must be a numeric parameter and v must be within the permissible range of p.
· v is a character string: p must be an alphanumeric parameter.
If no FOR REUSE was specified in the QUERY statement (see SELECT statement), subsequent INSERT, update, or delete statements that refer to the underlying base table and are executed by the current user or by other users can cause several executions of a fetch statement to denote different rows in the result table, even though the same position was specified.
You can prevent other users from
making changes by executing a LOCK statement for
the entire table or by using the isolation
level 2, 3, 15, 20, or 30
with the CONNECT statement
or the LOCK
option of the query
statement.
FOR REUSE must be specified if this is not possible or if the user makes
changes to this table. Changes made in the meantime are not visible in this
case.
If a result table that was physically created contains LONG columns and if the isolation levels 0, 1, and 15 are used, consistency between the content of the LONG columns and that of the other columns is not ensured. If the result table was not physically generated, consistency is not ensured at isolation level 0 only. For this reason, it is advisable to ensure consistency by using a LOCK statement or the isolation levels 2, 3, 20, or 30.