Library: Database access (OMDB) legacy library Include: omdb.xin

Declaration

  define external  function dbRecordMove
         read-only dbField  record

  or

  define external  function dbRecordMove
         read-only dbField  record
      to value     integer  absolute

  or

  define external  function dbRecordMove
         read-only dbField  record
      by value     integer  relative

Argument definitions

record

is a dbField 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 dbRecordMove to change the position of the data cursor within the specified record set.

Requirements

You must include the following line at the beginning of your OmniMark program:

  include "omdb.xin"

The database connection represented by dbDatabase must be

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

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

The dbField 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 (the cursor moves to the first row of the record set)
  • DB_NEXT (the cursor moves to the next row of the record set)
  • DB_PRIOR (the cursor moves to the previous row of the record set)
  • DB_LAST (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)

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 dbRecordExists 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 OCI8 or OCI8i interface, you can only advance to the next record. Some ODBC drivers allow additional flexibility.

Example

        repeat
           exit unless dbRecordExists my-query

           repeat over my-query
              output dbFieldValue my-query null '-dnf-'
              output '%t' when ! #last
           again
           output '%n'

           dbRecordMove my-query
         again

Other Library Functions    dbClose    dbCommit    dbDatabase    dbExecute    dbField    dbFieldPrepare    dbFieldSink    dbFieldValue    dbIsVersionCompatible    dbLibraryVersion    dbLibraryVersionOCI8    dbLibraryVersionOCI8i    dbLibraryVersionODBC    dbOpenOCI8    dbOpenOCI8i    dbOpenODBC    dbProcedure    dbProcedureClose    dbProcedureExecute    dbProcedureOpen    dbQuery    dbRecordExists    dbRecordMove    dbRecordSetMove    dbRollback    dbSetTransactionType    dbStatement    dbStatementCompile    dbStatementDiscard    dbStatementExecute    dbStatementStreamingExecute    dbTable    dbTableClose    dbTableDelete    dbTableInsert    dbTableOpen    dbTableUpdate

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