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

Declaration

define external  function db.move-dynamic-record
       read-only db.field  record

or

define external  function db.move-dynamic-record
       read-only db.field  record
    to value     integer  absolute

or

define external  function db.move-dynamic-record
       read-only db.field  record
    by value     integer  relative

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.

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

Requirements

The database connection represented by db.database must be

• open (else external exception OMDB209).
• in scope (else external exception OMDB103).

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:

• not be supplied if the relative parameter is used (else external exeption OMDB208)
• be one of the following:
  • db.first-record (the cursor moves to the first row of the record set)
  • db.next-record (the cursor moves to the next row of the record set)
  • db.previous-record (the cursor moves to the previous row of the record set)
  • db.last-record (the cursor moves to the last row of the record set)
  • a positive integer "n" (the cursor moves to the "n"th row of the record set)
  • zero (the cursor remains where it is)
  • a negative integer "n" (the cursor moves to the nth row from the end of the record set, where the last row is "-1" etc)

The relative parameter must:

• not be supplied if the absolute parameter is used (else external exeption OMDB208)
• be one of the following:
  • a positive integer "n" (the cursor moves "n" rows ahead in the record set)
  • a negative integer (the cursor moves "n" rows back in the record set)
  • zero (the cursor moves to the first row in the record set)

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. If using the OCI8i interface, you can only advance to the next record. 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' when ! #last
           again
           output '%n'
  
           db.move-dynamic-record my-query by 2
         again

Related Syntax    db.query    db.move-record    db.record-exists    db.reader    db.field

Other Library Functions    db.advance-recordset    db.close    db.commit    db.compile-statement    db.database    db.delete    db.discard    db.document-writer-sedna    db.execute    db.execute-in    db.field    db.insert    db.is-null    db.move-dynamic-record    db.move-record    db.omdb-version    db.omdb-version-oci10g    db.omdb-version-oci11g    db.omdb-version-oci8i    db.omdb-version-oci9i    db.omdb-version-odbc    db.omdb-version-sedna    db.open-oci10g    db.open-oci11g    db.open-oci8i    db.open-oci9i    db.open-odbc    db.open-procedure    db.open-sedna    db.open-table    db.prepare    db.procedure    db.query    db.reader    db.record-exists    db.rollback    db.set-transaction-type    db.statement    db.streaming-execute    db.table    db.update    db.writer

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]