Functions		Platforms
	omodbc - low-level ODBC support

The OmniMark OMODBC library is a collection of ODBC external functions. The library provides easy, efficient, and portable access to ODBC data sources from within an OmniMark program using your existing ODBC-compliant database software drivers. The functions allow you to access all of the ODBC 3.0 functions used to view and manipulate data within a data source so that you can:

• connect to a data source.
• retrieve driver and data source information.
• manipulate connection attributes.
• prepare and execute SQL statements.
• manipulate data within the data source.
• modify the structure of the data.

The OMODBC external function library consists of the following files:

• omodbc.dll or omodbc.so, a dynamic link library binary file that contains the implementation of the OmniMark ODBC API. The library file is dynamically loaded the first time any ODBC API function is called.
• omodbc.xin, the OmniMark include file that defines the ODBC opaque types, external function declarations and required pre-defined values.

The OMODBC external function library requires OmniMark 4.0 or higher. As well, the following lines must be included at the beginning of the OmniMark program:

  ; ODBC function and constant declarations
  include "omodbc.xin"

Migrating from OMODBC 1.0 to OMODBC 2.0

The OMODBC 2.0 library extends the existing library by adding all the new functionality that was introduced in ODBC 3.0. The next biggest change between the OMODBC versions 1.0 and 2.0 is the introduction of OMX variables into the OmniMark language. The OMODBC 2.0 library defines three OMX components that are used in the ODBC functions. These new OMX components are:

1. SQL_Handle_type,
2. SQL_Array_type, and
3. SQL_Vector_type.

The SQL_Handle_type replaces the counter-type variables used in version 1.0 to represent environment, connection and statement handles. Using the OMX component allows for better type-checking in calls to the OMODBC functions.

The SQL_Array_type and SQL_Vector_type replace the MemoryBlock counters used in version 1.0. These OMX components allow better function type-checking and reduce memory access violations and leaks.

Obsolete Functions

The following functions are no longer available in the OMODBC library. The list of replacement functions is also presented.

  OBSOLETE FUNCTION                ALTERNATE
  ----------------------------     --------------------------
  HSQLAllocMemoryBlock             SQLSetArraySize
                                   SQLSetVectorSize

  HSQLCopyCounterToMemoryBlock     SQLSetArrayAsCounter
                                   SQLSetArrayAsCounterShelf
                                   SQLSetVectorAsCounter

  HSQLCopyMemoryBlockToCounter     SQLGetArrayAsCounter
                                   SQLGetArrayAsCounterShelf
                                   SQLGetVectorAsCounter

  HSQLCopyStreamToMemoryBlock      SQLSetArrayAsStream
                                   SQLSetArrayAsStreamShelf
                                   SQLSetArrayAsString
                                   SQLSetVectorAsStream
                                   SQLSetVectorAsString

  HSQLCopyMemoryBlockToStream      SQLGetArrayAsStream
                                   SQLGetArrayAsStreamShelf
                                   SQLGetArrayAsString
                                   SQLGetVectorAsStream
                                   SQLGetVectorAsString

  HSQLFreeMemoryBlock              none

Modified Functions

Introducing the OMX components into the OmniMark language and OMODBC library has made data type changes necessary in the OMODBC functions. In general, these changes can be summarized in the following table:

  VERSION 1.0 DATA TYPE      VERSION 2.0 OMX COMPONENT
  ---------------------      ---------------------
  counter (henv)             SQL_Handle_type
  counter (hdbc)             SQL_Handle_type
  counter (hstmt)            SQL_Handle_type
  counter (MemoryBlock)      SQL_Array_type or SQL_Vector_type

The following table presents the list of all the OMODBC 1.0 functions and all affected arguments.

  FUNCTION             VER 1.0 TYPE   VER 1.0 ARG VER 2.0 OMX COMPONENT
  --------             ------------   ----------- ------------

  SQLAllocConnect      counter        henv        SQL_Handle_type
                       counter        hdbc        SQL_Handle_type

  SQLAllocEnv          counter        henv        SQL_Handle_type

  SQLAllocStmt         counter        hdbc        SQL_Handle_type
                       counter        hstmt       SQL_Handle_type

  SQLBindCol           counter        hstmt       SQL_Handle_type
                       counter        rgbValue    SQL_Array_type
                       counter        pcbValue    SQL_Array_type

  SQLBindParameter     counter        hstmt       SQL_Handle_type
                       counter        rgbValue    SQL_Array_type
                       counter        pcbValue    SQL_Array_type

  SQLBrowseConnect     counter        hdbc        SQL_Handle_type

  SQLCancel            counter        hstmt       SQL_Handle_type

  SQLColAttributes     counter        hstmt       SQL_Handle_type

  SQLColumnPrivileges  counter        hstmt       SQL_Handle_type

  SQLColumns           counter        hstmt       SQL_Handle_type

  SQLConnect           counter        hdbc        SQL_Handle_type

  SQLDataSources       counter        henv        SQL_Handle_type

  SQLDescribeCol       counter        hstmt       SQL_Handle_type

  SQLDescribeParam     counter        hstmt       SQL_Handle_type

  SQLDisconnect        counter        hdbc        SQL_Handle_type

  SQLDriverConnect     counter        hdbc        SQL_Handle_type
                       counter        hwnd        SQL_Handle_type

  SQLDrivers           counter        henv        SQL_Handle_type

  SQLError             counter        henv        SQL_Handle_type
                       counter        hdbc        SQL_Handle_type
                       counter        hstmt       SQL_Handle_type

  SQLExecDirect        counter        hstmt       SQL_Handle_type

  SQLExecute           counter        hstmt       SQL_Handle_type

  SQLExtendedFetch     counter        hstmt       SQL_Handle_type
                       counter        rgfRowStatus SQL_Array_type

  SQLFetch             counter        hstmt       SQL_Handle_type

  SQLForeignKeys       counter        hstmt       SQL_Handle_type

  SQLFreeConnect       counter        hdbc        SQL_Handle_type

  SQLFreeEnv           counter        henv        SQL_Handle_type

  SQLFreeStmt          counter        hstmt       SQL_Handle_type

  SQLGetConnectOption  counter        hdbc        SQL_Handle_type
                       counter        pvParam     SQL_Vector_type

  SQLGetCursorName     counter        hstmt       SQL_Handle_type

  SQLGetData           counter        hstmt       SQL_Handle_type

  SQLGetFunctions      counter        hdbc        SQL_Handle_type
                       counter        fExists     SQL_Array_type

  SQLGetInfo           counter        hdbc        SQL_Handle_type
                       counter        rgbInfoValue SQL_Vector_type

  SQLGetStmtOption     counter        hstmt       SQL_Handle_type
                       counter        pvParam     SQL_Vector_type

  SQLGetTypeInfo       counter        hstmt       SQL_Handle_type

  SQLMoreResults       counter        hstmt       SQL_Handle_type

  SQLNativeSql         counter        hdbc        SQL_Handle_type

  SQLNumParams         counter        hstmt       SQL_Handle_type

  SQLNumResultCols     counter        hstmt       SQL_Handle_type

  SQLParamOptions      counter        hstmt       SQL_Handle_type

  SQLPrepare           counter        hstmt       SQL_Handle_type

  SQLPrimaryKeys       counter        hstmt       SQL_Handle_type

  SQLProcedureColumns  counter        hstmt       SQL_Handle_type

  SQLProcedures        counter        hstmt       SQL_Handle_type

  SQLPutData           counter        hstmt       SQL_Handle_type

  SQLRowCount          counter        hstmt       SQL_Handle_type

  SQLSetConnectOption  counter        hdbc        SQL_Handle_type
                       counter        vParam      SQL_Vector_type

  SQLSetCursorName     counter        hstmt       SQL_Handle_type

  SQLSetPos            counter        hstmt       SQL_Handle_type

  SQLSetScrollOptions  counter        hstmt       SQL_Handle_type

  SQLSetStmtOption     counter        hstmt       SQL_Handle_type
                       counter        vParam      SQL_Vector_type

  SQLSpecialColumns    counter        hstmt       SQL_Handle_type

  SQLStatistics        counter        hstmt       SQL_Handle_type

  SQLTablePrivileges   counter        hstmt       SQL_Handle_type

  SQLTables            counter        hstmt       SQL_Handle_type

  SQLTransact          counter        henv        SQL_Handle_type
  	             counter        hdbc        SQL_Handle_type

As well, a few functions have an added parameter to help identify the type of data contained in the SQL_Vector_type argument. This is needed because of the ODBC function requirement that the data in the SQL_Vector_type argument may be passed by value or by reference. All of the underlying ODBC API functions have been deprecated and we recommend using the replacement functions. The affected functions are listed in the following table along with their replacements:

  FUNCTION                ADDED ARG      REPLACEMENT FUNCTION
  --------                ---------      --------------------

  SQLGetStmtOption        ValueType      SQLGetStmtAttr

  SQLSetConnectOption     ValueType      SQLSetConnectAttr

  SQLSetStmtOption        ValueType      SQLSetStmtAttr

Functions    SQL_FUNC_EXISTS    SQL_IsVersionCompatible    SQL_LibraryVersion    SQLAllocConnect    SQLAllocEnv    SQLAllocHandle    SQLAllocStmt    SQLBindCol    SQLBindParameter    SQLBrowseConnect    SQLBulkOperations    SQLCancel    SQLCloseCursor    SQLColAttribute    SQLColAttributes    SQLColumnPrivileges    SQLColumns    SQLConnect    SQLCopyDesc    SQLDataSources    SQLDescribeCol    SQLDescribeParam    SQLDisconnect    SQLDriverConnect    SQLDrivers    SQLEndTran    SQLError    SQLExecDirect    SQLExecute    SQLExtendedFetch    SQLFetch    SQLFetchScroll    SQLForeignKeys    SQLFreeConnect    SQLFreeEnv    SQLFreeHandle    SQLFreeStmt    SQLGetArrayAsCounter    SQLGetArrayAsCounterShelf    SQLGetArrayAsStream    SQLGetArrayAsStreamShelf    SQLGetArrayAsString    SQLGetArrayElementCount    SQLGetArrayElementLen    SQLGetConnectAttr    SQLGetConnectOption    SQLGetCursorName    SQLGetData    SQLGetDescField    SQLGetDescRec    SQLGetDiagField    SQLGetDiagRec    SQLGetEnvAttr    SQLGetFunctions    SQLGetInfo    SQLGetStmtAttr    SQLGetStmtOption    SQLGetTypeInfo    SQLGetVectorAsCounter    SQLGetVectorAsStream    SQLGetVectorAsString    SQLGetVectorSize    SQLMoreResults    SQLNativeSQL    SQLNumParams    SQLNumResultCols    SQLParamData    SQLParamOptions    SQLPrepare    SQLPrimaryKeys    SQLProcedureColumns    SQLProcedures    SQLPutData    SQLRowCount    SQLSetArrayAsCounter    SQLSetArrayAsCounterShelf    SQLSetArrayAsStream    SQLSetArrayAsStreamShelf    SQLSetArrayAsString    SQLSetArraySize    SQLSetConnectAttr    SQLSetConnectOption    SQLSetCursorName    SQLSetDescField    SQLSetDescRec    SQLSetEnvAttr    SQLSetPos    SQLSetScrollOptions    SQLSetStmtAttr    SQLSetStmtOption    SQLSetVectorAsCounter    SQLSetVectorAsStream    SQLSetVectorAsString    SQLSetVectorSize    SQLSpecialColumns    SQLStatistics    SQLTablePrivileges    SQLTables    SQLTransact

Platforms    HP/UX    MS Windows 95/98    MS Windows NT    Sun Solaris

----

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

Copyright © OmniMark Technologies Corporation, 1988-2000.