OMDB is the OmniMark database interface library, a set of functions that let you access and manipulate information in both relational and XML databases. This library uses either your existing ODBC-compliant database software drivers or Oracle 8i (or higher) client installation or XML database connection libraries.

OMDB is designed to be as database vendor and database interface independent as possible. In a few places, OMDB's behavior is dependent on the database vendor or interface, and notes have been added to the documentation specifying the differences.

The library consists of the following files:

• "omdb.dll" (Windows) or "omdb.so" (UNIX) -- the dynamic link library file that creates the required opaque data types and contains the functions used to manipulate those components.
• "omdb_odbc.dll" (Windows) or "omdb_odbc.so" (UNIX) - the dynamic link library that enables accessing databases using ODBC.
• "omdb_oci8i.dll" (Windows) or "omdb_oci8i.so" (UNIX) - the dynamic link library that enables accessing databases using OCI8i.
• "omdb_oci9i.dll" (Windows) or "omdb_oci9i.so" (UNIX) - the dynamic link library that enables accessing databases using OCI9i.
• "omdb_oci10g.dll" (Windows) or "omdb_oci10g.so" (UNIX) - the dynamic link library that enables accessing databases using OCI10g.
• "omdb_oci11g.so" (UNIX) - the dynamic link library that enables accessing databases using OCI11g.
• "omdb_sedna.dll" (Windows) or "omdb_sedna.so" (UNIX) - the dynamic link library that enables accessing Sedna databases.
• "omdb.xmd" -- the OmniMark include file that contains the opaque data type definitions, the function declarations, and the required predefined variables.

Using the OMDB library is an introduction to the functions in the library, with sample code illustrating their use.

The OMDB functions and opaque data types

OMDB functions allow you to:

• connect to and disconnect from a database (db.open-odbc, db.open-oci8i, db.open-oci9i, db.open-oci10g, db.open-oci11g, db.open-sedna, db.close)
• modify transactions (db.set-transaction-type, db.commit, db.rollback)
• open and close tables within a database (db.open-table, db.close)
• manipulate data in tables (db.delete, db.insert, db.update)
• access and execute stored procedures (db.open-procedure, db.execute, db.close)
• execute statements against your database (db.execute-in, db.query, db.compile-statement, db.execute, db.streaming-execute, db.prepare, db.writer, db.discard)
• load content into your database (db.document-writer-sedna)
• work with the results of a query (db.record-exists, db.move-record, db.advance-recordset, db.reader)

The functions in this library use the following opaque data types:

• db.database -- used by functions performing actions on the database as a whole.
• db.field -- used to retrieve a data value from a query.
• db.table -- used to modify the contents of a single table in the relational database.
• db.statement -- used to compile an SQL statement.
• db.procedure -- used to access a stored procedure in a database.

All dates, times, and timestamps are retrieved in the Date and Time library format. (This format returns the time with a time zone offset from UTC time.)

Requirements

To use the OMDB functions in your OmniMark program, you have to add the following statement to your program:

      import "omdb.xmd" prefixed by db.

Requirements - ODBC

If you are running OmniMark under UNIX and using ODBC to access databases, you must explicitly specify the location of your ODBC driver before you can use the OMDB library functions. Presuming your ODBC driver is installed in /usr/local/odbc:

• If you use 'sh' as your shell, then issue these commands:
  

    LD_LIBRARY_PATH=/usr/local/odbc/lib:$LD_LIBRARY_PATH
    export LD_LIBRARY_PATH
  

• If you use the C shell, then issue this command line:
  

    setenv LD_LIBRARY_PATH=/usr/local/odbc/lib:$LD_LIBRARY_PATH
  

Requirements - OCI

To make use of the OCI interface for accessing a database, you must have SQL*NET installed on your machine and configured to locate the database server(s) you wish to access. The Oracle 8i, 9i 10g and 11g client installations are supported.

Usage Notes

The functions db.execute-in and db.query accept query/execute strings passed to them in either the named parameter sql or in the named parameter statement. It is an error to use both parameters in the same call. For non-relational databases the named parameter statement must be used. The Sedna XML database was developed by the MODIS group of the Institute for System Programming of the Russian Academy of Sciences (ISPRAS). It is open-source software and is freely available from http://www.modis.ispras.ru/Development/sedna.htm.

OMDB Generated Exceptions

This is a complete list of the OMDB library external exceptions that may be thrown back to the calling OmniMark program. These are all catchable using the #external-exception label.

  OMDB001  Failed to allocate memory
  OMDB002 The database does not support the requested operation
  OMDB101  db.database is not currently open for statement execution
  OMDB103  The source db.database has left the current scope and is no longer available
  OMDB104  The source db.database has changed internal state
  OMDB105  The specified SQL statement has a zero length
  OMDB106  The specified transaction mode value is invalid
  OMDB107  The database does not support streaming LOB parameters.
  OMDB202  SQL query must return at least one column
  OMDB204  This database driver may only retrieve BLOB columns after all other columns.
           Reorder the columns in your query.
  OMDB205  The record set is not positioned on a valid row
  OMDB206  The database does not support the requested cursor movement
  OMDB207  The attempted field retrieval order requires an implicit refresh of the
           record set that is not supported by this database
  OMDB208  Absolute and relative cursor positions cannot both be specified
  OMDB209  The database has been closed since the query was executed
  OMDB210  An invalid value was specified for the cursor type
  OMDB302  db.field is not currently associated with a query
  OMDB303  The SQL operation associated with the db.field returns a single record
           that does not support cursor movement
  OMDB304  The db.field argument shelf contains no columns
  OMDB305  The db.field is not a streaming execution handle
  OMDB306  The db.field is a streaming execution handle
  OMDB307  An external output has already been created for the current parameter
  OMDB402  The requested stored procedure could not be found
  OMDB403  Unable to determine the parameter type in the procedure
  OMDB404  The number of parameters in the procedure exceeds OMDB's internal limit
  OMDB405  The db.procedure item is not currently open for processing requests
  OMDB406  The input value exceeds the maximum length allowed by the procedure parameter
  OMDB407  The procedure has more input parameters than items on the input shelf
  OMDB408  The specified procedure name has a zero length
  OMDB409  All of the procedure parameter description arguments must be supplied
  OMDB410  All of the procedure parameter description shelves must contain
           the same number of items
  OMDB411  The item keys of the procedure parameter description shelves are
           inconsistent with each other
  OMDB412  The procedure parameter data size must not be less than zero
  OMDB413  The procedure has been re-executed, so previous data is no longer available
  OMDB501  A database error occurred
  OMDB601  db.table is not currently open for processing
  OMDB603  The stream item key has no matching table column name
  OMDB604  The date/time stream shelf item must be in OmniMark date format
  OMDB605  The specified table name has a zero length
  OMDB606  The specified table record contains zero items
  OMDB607  The table record item has no key value
  OMDB701  db.statement is not currently open for processing
  OMDB702  The compiled statement requires input values
  OMDB703  The shelf of input parameter values for the compiled statement has too few items
  OMDB704  The compiled statement is a query and requires a db.field shelf
           argument to receive the results
  OMDB705  The input stream length exceeds the maximum size allowed by the parameter
  OMDB706  The ODBC driver is unable to determine the data types of the parameters
           in the SQL statement. The shelf of parameter data types is required by
           db.compile-statement using this ODBC driver.
  OMDB707  The shelf of input parameter data types values for the compiled
           statement has too few items
  OMDB708  An invalid value was specified for a parameter data type
  OMDB709  The number of parameters exceeds the database's limit
  OMDB710  A streaming execute operation is currently active on this statement
  OMDB711  This statement does not have an active streaming execute operation
  OMDB712  The data for this parameter has already been received
  OMDB801  Sedna server error occurred
  OMDB802  XML document is not specified
  OMDB803  Document in database is not specified
  OMDB804  The cursor is not positioned on a valid item
  OMDB999  An internal error was detected. Contact Stilo.

Platform support

The following Oracle clients can be used on the specified platforms:

• Windows - 8i, 9i, 10g, 11g
• Linux - 8i, 11g
• Linux RedHat Enterprise 5 - 11g
• AIX 4.3.3 - 8i, 9i
• AIX 5.3 - 10g
• HP/UX PA-RISC - 8i, 9i
• HP/UX Itanium -9i, 10g
• Solaris 2.6 - 8i
• Solaris 8 - 8i, 9i
• Solaris 10 - 11g

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 ]