db.move-dynamic-record

function

Library: Database access (OMDB)
Import : omdb.xmd

Declaration
export external function 
   move-dynamic-record    read-only field   record
                       by value     integer relative optional
                       to value     integer absolute optional

      

Argument definitions

record
is a db.field shelf bound to a record set created by an SQL query
absolute
is the absolute position to which to move the cursor. A positive number indicates the number of records from the beginning, with +1 being the first record. A negative number indicates the position from the end, with -1 being the last record.
relative
is the number of rows to move the cursor. This value can be either positive or negative, with negative values indicating reverse movement within the record set.


Purpose

Use db.move-dynamic-record to change the position of the data cursor within the specified record set.

Requirements

The database connection used to obtain record must be

The db.field shelf must be associated with a query (else external exception OMDB302).

The db.field shelf record must exist.

The absolute parameter must:

The relative parameter must:

Usage Notes

The data cursor points to the currently active row of the record set. By default (neither the absolute nor the relative parameter is supplied), the cursor advances to the next row of the record set.

You can move the data cursor beyond the record set boundaries. However, if you attempt to retrieve a field value in this situation, external exception OMDB205 will be thrown. Hint: Before attempting to retrieve field values, you should use the db.record-exists function to verify that the data cursor is within the record set boundaries.

What sort of cursor movement is possible depends on the database and database interface being used. Some ODBC drivers, as well as the OCI9 and OCI10g interfaces, allow additional flexibility. You must specify the optional cursor parameter as being db.dynamic-cursor when creating the result set. However, it is recommended to use a static cursor and db.move-record unless the functionality of db.move-dynamic-record is required, as dynamic cursors are more expensive than static cursors.

Example


  db.query my-db sql my-sql into my-query cursor db.dynamic-cursor
  
  repeat
     exit 
        unless db.record-exists my-query
  
     repeat over my-query
        output db.reader of my-query null '-DNF-'
        output '%t' 
           unless #last
     again
     output '%n'
  
     db.move-dynamic-record my-query by 2
  again