ODBC API Reference Guide

RDMe ODBC API Reference GuideRaima Database Manager 11.0 ODBC API Reference Guide 1 RDMe ODBC API Reference Guide Trademarks Raima Database Manager® (RDM®), RDM Embedded® and RDM Server® are trademarks of Raima Inc. and may be registered in the United States of America and/or other countries. All other names may be trademarks of their respective owners. This guide may contain links to third-party Web sites that are not under the control of Raima Inc. and Raima Inc. is not responsible for the content on any linked site. If you access a third-party Web site mentioned in this guide, you do so at your own risk. Inclusion of any links does not imply Raima Inc. endorsement or acceptance of the content of those third-party sites. Contents Introduction Advanced Topics RDM ODBC API Reference Return Codes ODBC ODBC C Data Types Registering RDM ODBC Driver Glossary Index 3 7 23 29 174 175 177 183 194 2 RDMe ODBC API Reference Guide Contents Contents Introduction Comparing the ODBC API with the Native RSQL API Basic ODBC Application Steps Allocating Handles Environment Handle Connection Handle Statement Handle Descriptor Handle Connecting to a Data Source Choosing the Connection Type Setting the Data Source Name Establishing a Connection Executing an SQL Statement Allocating a Statement Handle Preparing an SQL Statement Executing an SQL Statement Committing or Rolling Back Transactions Retrieving the Result Set Binding Columns Fetching Columns Advanced Topics Working with Parameters Fetching Multiple Rows at Once Retrieving Data in Parts RDM ODBC API Reference SQLAllocHandle SQLBindCol Contents 3 7 7 9 12 12 12 12 12 14 15 15 16 18 18 18 18 19 21 21 21 23 23 25 27 29 32 34 3 RDMe ODBC API Reference Guide SQLBindParameter SQLCancel SQLCloseCursor SQLColAttribute SQLColumns SQLConnect SQLCopyDesc SQLDescribeCol SQLDescribeParam SQLDescribeStmt SQLDisconnect SQLDriverConnect SQLEndTran SQLExecDirect SQLExecute SQLExtendedTran SQLFetch SQLFetchScroll SQLForeignKeys SQLFreeHandle SQLFreeStmt SQLGetConnectAttr SQLGetCursorName SQLGetData SQLGetDescField SQLGetDescRec SQLGetDiagField SQLGetDiagRec SQLGetEnvAttr 36 38 40 42 45 47 50 52 54 56 59 61 64 66 68 70 74 76 78 80 82 84 86 88 90 92 94 96 98 Contents 4 . RDMe ODBC API Reference Guide SQLGetFunctions SQLGetInfo SQLGetStmtAttr SQLGetTypeInfo SQLMoreResults SQLNativeSql SQLNumParams SQLNumResultCols SQLParamData SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SQLPutData SQLRowCount SQLSetConnectAttr SQLSetCursorName SQLSetDescField SQLSetDescRec SQLSetEnvAttr SQLSetError SQLSetStmtAttr SQLSpecialColumns SQLStatistics SQLTables SQLTransactStatus Summary Listing of RDM SQL Server API Functions rdmsqlserver_init rdmsqlserver_start 100 102 104 106 108 110 112 114 116 118 120 122 124 126 128 130 137 139 141 143 146 148 155 158 160 162 164 165 168 Contents 5 . RDMe ODBC API Reference Guide rdmsqlserver_stop rdmsqlserver_term Return Codes ODBC ODBC C Data Types Registering RDM ODBC Driver Overview Opening the ODBC Driver Manager Configuring the default DSN entry Working with Default Databases Changing the Advanced Options Adding a new DSN entry Removing an existing DSN entry Using the ODBC Driver Glossary Index 170 172 174 175 177 177 177 178 178 179 180 181 182 183 194 Contents 6 . h for basic and extended ODBC functionality.RDMe ODBC API Reference Guide Introduction RDM provides a separate ODBC API that allows SQL applications to be written using the industry-standard Open Data Base Connectivity C language interface to perform database operations using standard SQL. SQLTables. function calling sequence) that is used in an ODBC application is also needed in a RSQL application. All of the functions are prefixed with "SQL". ODBC to RDM SQL API Function Mapping ODBC API Function SQLAllocHandle SQLBindCol SQLBindParameter SQLCancel SQLCloseCursor SQLColAttribute SQLColumns SQLConnect RSQL Function rsqlAllocConn rsqlAllocStmt n/a rsqlBindParam n/a rsqlCloseStmt rsqlGetColDescr n/a n/a Comments Allocation of connection and statement handles are made through separated functions. extension. Not all ODBC functions have an equivalent RSQL API function... Connections are initiated when rsqlAllocConn is called. (e. Table 2. ODBC API functions that are not listed do not have a RSQL API counterpart. SQLDescribeCol SQLDescribeParam SQLDescribeStmt SQLDisconnect SQLEndTran rsqlTransRollback SQLExecDirect rsqlGetColDescr rsqlGetParamDescr rsqlGetStmtDescr n/a rsqlTransCommit   rsqlExecDirect SQLDescribeStmt is a Raima Inc. However. sqlext. ODBC data types and constant declarations are provided in the standard header files: sql. Databases are opened through calls to rsqlOpenDB or rsqlOpenCat. Comparing the ODBC API with the Native RSQL API The following table provides a mapping of the ODBC API functions with the RSQL API functions. Introduction 7 . etc) are implemented in the RDM ODBC layer as select statements on built-in virtual system catalog tables which are described later in this section. SQLColumns. Even though ODBC was developed by Microsoft for use on the Windows operating system. and RDM-specific functionality.51 of the Microsoft ODBC specification.h for basic ODBC functionality. extended. Applications written using this API can be both directly-linked to the RDM database engine or can run as client programs that access a RDM SQL server program (rdmsqlserver) running on a separate computer.h for basic.g. Also note that those functions that do have a RSQL API equivalent do not have the same function arguments.g. Column result values are not bound but are returned by rsqlFetch or rsqlGetData. the basic operational approach (e. sqlrext. the RDM ODBC implementation is available on every OS platform that RDM supports. There is no environment handle. Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. Call rsqlCloseStmt to cancel statement processing. Connections are closed when rsqlFreeConn is called. Some. The RDM ODBC implementation is based on version 3. Introduction 8 . ODBC is available and can certainly be used if DBMS independence and/or use of a standard SQL API is needed. Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. SQLGetCursorName SQLGetData SQLMoreResults SQLNumParams SQLNumResultCols SQLPrepare SQLPrimaryKeys SQLProcedures SQLPutData SQLRowCount SQLSetConnectAttr SQLSetCursorName SQLSetError SQLSpecialColumns SQLTables SQLTransactStatus rsqlFreeConn rsqlFreeStmt rsqlGetAutoCommit Not all ODBC connection attributes have a RDM equivalent. n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. However. Not rsqlGetDateFormat all RDM connection attributes have an ODBC equivalent. rsqlSetDateSeparator rsqlSetDeferBlobMode rsqlSetReadOnlyTrmode rsqlSetCursorName rsqlSetErrorCallback SQLSetError is a Raima Inc.RDMe ODBC API Reference Guide ODBC API Function SQLExecute SQLExtendedTran RSQL Function rsqlExecute rsqlTransStart rsqlTransSavepoint rsqlTransRelease rsqlTransCommit rsqlTransRollback rsqlFetch n/a Comments We believe that separate calls represent a better API design than a single call with a control variable SQLFetch SQLForeignKeys SQLFreeHandle SQLGetConnectAttr Note that the rsqlFetch returns the column result values-no bound columns. extension. rsqlGetDateSeparator rsqlGetDeferBlobMode rsqlGetReadOnlyTrmode rsqlGetCursorName rsqlGetData rsqlMoreResults rsqlGetNumParams rsqlGetNumResultCols rsqlPrepare n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. Not rsqlSetDateFormat all RDM connection attributes have an ODBC equivalent. rsqlPutData rsqlGetRowCount rsqlSetAutoCommit Not all ODBC connection attributes have a RDM equivalent. n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. rsqlTransStatus The advantage of using the native API instead of ODBC is that it is simpler and more efficient with a smaller footprint.  d. you will need a statement handle for  each statement that will be compiled once but potentially executed multiple times.  Call SQLExecDirect("Open *database name*") in order to open your database. commit the  transaction.  Call SQLExecute to execute the appropriate statements that implement the database access  needs for each particular function.  Call SQLSetEnvAttr(hEnv.  Prepare your application to execute SQL statements as follows.0). You can allocate as many  statement handles as you need in your application. but this time you are allocating your connection handle (hCon in the  example below)  d.  When your application is ready to terminate you need to…  a.  1.  c. This will  set the version of ODBC that you want to use with your database  c.  Call SQLFreeHandle for each allocated connection which automatically closes all open databases. You will need to call SQLFreeStmt on a select for which you do not call SQLFetch  through to the end of the result set.  Call SQLAllocHandle a third time to allocate your statement handle.  Call SQLPrepare to compile each of the statements that will need to be executed by your application.  Set up and initialize your application’s use of the SQL API as follows.  g. SQL_ATTR_ODBC_VERSION. create a savepoint.  Possibly call SQLParamData and SQLPutData to process any needed data-at-exec blob parameters specified in insert and update statements.  b.  a.  At this point your application is execution ready.  Call SQLSet* functions such as SQLSetConnectAttr to set up specific database attributes and  operational parameters. which will be used in allocating your  connection handle.  Call SQLAllocHandle again.  Call transaction statements using SQLExtendedTran in order to start the transaction. terminates the connection and frees the connection handle and all its associated dynamically  Introduction 9 .  Call SQLConnect to connect to the database  e.  4. *ODBC_VERSION. Alternatively.  Call SQLFreeStmt or SQLFreeHandle for each statement handle allocated in step 1e. That means that your application will …  a.  Call SQLFetch to retrieve the result rows from an executed select statement. or rollback a transaction.  Call SQLAllocHandle to allocate your environment handle.  b.  a. if the select is  updateable. Typically.  b.RDMe ODBC API Reference Guide Basic ODBC Application Steps An ODBC SQL C application program consists of a set of calls to the SQL API functions in a particular sequence as outlined below.  f.  Call SQLBindParameter to bind your application’s variables to any parameter markers that were  specified in the SQL statements prepared in the prior step.  3. you would only do this for statements that only need to  be executed once.  b. Alternatively you can call SQLExecDirect to both compile and  execute a statement in a single call. You may also need  to call SQLGetData to retrieve blob data results a block at a time.  2. Usually. you may need to call SQLGetCursorName or SQLSetCursorName associated with  a related positioned update or delete statement to change the current row returned from the call to  SQLFetch.   /* connection handle  */     SQLHSTMT  hStmt. This can be seen with the common Hello World example.  Call SQLFreeHandle for your environment handle. (SQLPOINTER) SQL_OV_ODBC3.      SQLAllocHandle(SQL_HANDLE_DBC. Hello World! If you follow the basic procedure listed above you can easily create a simple database where you insert some data and the retrieve the data to be displayed back out.h" /* The RDM SQL API. read the text field from database and print it out. 0 is success */     SQLCHAR   sz[32]. SQL_EMPSTR. (SQLCHAR *) "open hello_worldODBC". hEnv. /* statement handle   */     SQLHENV   hEnv.  /* Allocates statement handle    */     SQLExecDirect(hStmt. (SQLCHAR *) "INSERT INTO info(myChar) VALUES('Hello  Introduction 10 .h>   #include "sqlrext.  c.  /* environment handle */     SQLLEN    iLen = 0. /* holds return value. SQL_EMPSTR. insert a    record  **    containing a text field. /********************************************************************* **    HELLO WORLD SQL   **    --------------  **    This document describes the process to create a simple database. &hCon).  /* Allocates connection handle  */       /* Connects to server */     SQLConnect(hCon.  SQL_EMPSTR. SQL_NTS.  /* Opens  the database           */     /* Create a Hello World record */     SQLAllocHandle(SQL_HANDLE_STMT. &hStmt). SQL_ATTR_ODBC_VERSION. &hEnv). SQL_NTS). This will be ok because we know what the expected results are. SQL_ NTS).      SQLHDBC   hCon.RDMe ODBC API Reference Guide allocated memory.   /* Allocates env handle */     SQLSetEnvAttr(hEnv. hCon.     const char *const *argv) {         SQLRETURN iRet. 0). hCon. &hStmt). /* allocates the statement handle */     SQLExecDirect(hStmt. SQL_NTS.       SQLAllocHandle(SQL_HANDLE_ENV. In the example below return codes are mostly ignored for simplicity.                  /* connects to database*/     SQLAllocHandle(SQL_HANDLE_STMT. SQL_NULL_HANDLE.   **********************************************************************/   #include <stdio. */     #define SQL_EMPSTR      ((SQLCHAR *) "") /* any string */     int main(       int                argc.     /* Fetch data from database into program variables. (SQLCHAR *) "SELECT myChar FROM info". */     SQLDisconnect(hCon).sizeof(sz). */     (void) SQLFreeHandle(SQL_HANDLE_DBC. transaction is started by the first insert statement. */     SQLExecDirect(hStmt.sz).SQL_NTS).&iLen). hCon). */     (void) SQLFreeHandle(SQL_HANDLE_STMT.     (void) SQLFreeHandle(SQL_HANDLE_ENV.     /* Commit the insert. */     SQLEndTran(SQL_HANDLE_DBC.     /* Bind SQL fields to program variables.sz.RDMe ODBC API Reference Guide World!')".SQL_COMMIT).hStmt).     /* Close the database.         /* Free the SQL statement handle.hCon. /*lint !e534 */     /* Free the database handles. SQL_NTS).     printf("%s\n\n". hEnv).1.     return 0.     /* Query the database for the record created. */     SQLFetch(hStmt) . */     SQLBindCol(hStmt. }    Introduction 11 .SQL_C_CHAR. Statement Handle A statement handle is the handle that manages resources and options specific to a particular SQL statement operation. Descriptor Handle A descriptor handle is the handle that manages the detailed characteristics and information both an application and the ODBC driver use internally. Operations such as positioned update and delete require the use of multiple statement handles on one connection. In a multi-thread environment. An application tells the ODBC driver to allocate a handle by calling SQLAllocHandle. There are two types of descriptors: application descriptors and implementation descriptors. An application can allocate multiple statement handles on one connection handle in order to execute different SQL statements on one data source. ARD An ARD maintains information about a row/column returned to an application when it fetches data from a data source. Introduction 12 . Both application and implementation descriptors have two subcategories: parameter descriptors and row descriptors. there are four types of descriptor handles as below. An application must allocate an environment handle in order to access an RDM data source. Connection Handle A connection handle is the handle that manages resources and options specific to a connection to a data source.RDMe ODBC API Reference Guide Allocating Handles ODBC lets an application manage interactions with data sources through ODBC handles. An application can call SQLAllocHandle using SQL_HANDLE_ENV as the first argument in order to allocate an environment handle. RDM ODBC requires that each thread have its own connection handle. Multiple environment handles can be allocated inside an application. Environment Handle An environment handle is the base handle that manages global resources and options for an application. An application can call SQLAllocHandle using SQL_HANDLE_STMT as the first argument and an existing connection handle as the second in order to allocate a statement handle. Together. An application can allocate multiple connection handles on one environment handle in order to manage multiple connections to the same or different data sources. Application Parameter Descriptor Application Row Descriptor APD An APD maintains information about a dynamic parameter an application uses when executing an SQL statement. An application must allocate a connection handle in order to access an RDM data source. There are four types of ODBC handles. An application descriptor stores information an application maintains for its operations. An implementation descriptor stores information the ODBC driver uses internally. An application must allocate a statement handle in order to execute SQL statements against an RDM data source. An application can call SQLAllocHandle using SQL_HANDLE_DBC as the first argument and an existing environment handle as the second in order to allocate a connection handle.     if (SQL_SUCCEEDED(rc)) {         /* Allocate a connection handle */         rc = SQLAllocHandle(SQL_HANDLE_DBC.         if (SQL_SUCCEEDED(rc)) {             /* Connect to the local data source. Example 1 Allocating handles #include "sqlext. The code for                connectToDataSource is shown in the next                section */             rc = connectToDataSource(hDbc). and tell the ODBC drivers to use them instead of the implicitly-allocated descriptors.     SQLHDBC   hDbc. NULL.         }           (void) SQLFreeHandle(SQL_HANDLE_ENV. An application can explicitly allocate application descriptors (APD and ARD) by calling SQLAllocHandle using SQL_HANDLE_DESC as the first argument and an existing connection handle as the second.       /* Allocate an environment handle */     rc = SQLAllocHandle(SQL_HANDLE_ENV. Descriptors explicitly allocated by an application cannot be used as implementation descriptors (IPD and IRD). Implementation Row Descriptor All the four descriptors are implicitly allocated by the ODBC driver.h"   int main(void)   {       SQLRETURN rc.                   (void) SQLDisconnect(hDbc). &hEnv).             if (SQL_SUCCEEDED(rc)) {                 /* Do some database operations */                 rc = runDbOperations(hDbc).             }               (void) SQLFreeHandle(SQL_HANDLE_DBC.     SQLHENV   hEnv. The following example illustrates how to allocate ODBC handles using SQLAllocHandle. }    Introduction 13 .     }       return 0. IRD An IRD maintains information about a row/column defined on a data source from which an application fetches data.RDMe ODBC API Reference Guide Implementation Parameter Descriptor IPD An IPD maintains information about a dynamic parameter the ODBC driver uses internally when an application executes an SQL statement. hEnv). hEnv. hDbc). &hDbc). which has its own RDM SQL engine that in turn communicates with the target TFServer. database running on a PowerPC device being accessed by a remote Windows desktop).. by calling SQLConnect. Remote Data Source See the rdmsqlserver section for more information. an RDM data source can be a transaction file server (TFServer) or a remote server process (RDMSQLServer) that accesses the TFServer. Figure 2. The SQL processing will be performed within the RDMSQLServer process and the results returned to the application. The application will connect to the default TFS and the SQL processing will be performed within the application process. A connection to a TFServer is called "local" connection. In RDM ODBC.RDMe ODBC API Reference Guide Connecting to a Data Source An application will use the connection handle it allocated in order to connect to an RDM data source. Figure 1. where the RDM ODBC Driver uses the local RDM SQL engine directly linked to it in order to interact with the target TFServer. 2) the TFServer is supporting a database on a hardware architecture that is binary incompatible with the RDM ODBC API application hardware architecture (e.g. This client/server configuration would be used in configurations where: 1) the network speed is too slow for performing SQL engine access to the database. A typical RDM ODBC application is illustrated in Figure 1 below. A connection to an RDMSQLServer is called "remote" connection as the RDM ODBC Driver uses its remote procedure call (RPC) layer to talk to an RDMSQLServer over TCP/IP. or. Local Data Source The same RDM ODBC application can connect to an external RDM SQL engine by providing the remote connection attributes. Introduction 14 . If the connection type is explicitly set to remote (that is. If neither the SQL_ATTR_RDM_REMOTE_NAME nor the SQL_ATTR_RDM_TFS_NAME attribute is set (and the connection type is not explicitly set with the SQL_ATTR_RDM_CONN_TYPE attribute). it can explicitly set the connection type by setting the SQL_ATTR_RDM_CONN_TYPE connection attribute with a call to SQLSetConnectAttr before calling SQLConnect. In that case. If the SQL_ATTR_RDM_REMOTE_NAME attribute is not set. an application can let the RDM ODBC Driver choose the connection type implicitly by specifying the value for the two connection attributes: SQL_ATTR_RDM_REMOTE_NAME and SQL_ATTR_RDM_TFS_ NAME. First. the RDM ODBC Driver will attempt to establish a local connection. the SQL_ATTR_RDM_CONN_TYPE attribute is set to SQL_CT_ UNKNOWN). If the value in the SQL_ATTR_RDM_TFS_NAME attribute is not set. If the value in the SQL_ATTR_RDM_REMOTE_NAME attribute is not set. Setting the Data Source Name In RDM ODBC. and if the SQL_ATTR_RDM_ TFS_NAME attribute is set to a non-null. the RDM ODBC Driver will use a remote connection. If the SQL_ATTR_RDM_REMOTE_NAME attribute is not set or set to an empty string. by setting the SQL_ATTR_RDM_CONN_TYPE connection attribute to SQL_CT_REMOTE). non-empty value. If SQL_CT_REMOTE is specified. the default name ("localhost") will be used. the value stored in the SQL_ATTR_RDM_TFS_NAME connection attribute will be used as the data source name. a data source name is the hostname of the computer where the target TFServer (for a local connection) or the RDMSQLServer (for a remote connection) is running. the RDM ODBC Driver will use a remote connection. the RDM ODBC Driver will rely upon the value specified for the first argument of SQLConnect. Introduction 15 . non-empty string. the value specified for the first argument of SQLConnect will be used as the remote data source name. a local connection will be used. If that value is not set. If the SQL_ATTR_RDM_REMOTE_NAME attribute is set to a non-null.RDMe ODBC API Reference Guide Choosing the Connection Type An application can choose the type of connection it uses in two ways. the value stored in the SQL_ATTR_RDM_REMOTE_NAME attribute will be used as the remote data source name. the default name ("localhost") will be used. If the application specifies SQL_CT_LOCAL. if the value is a non-null. Otherwise. If neither value is set. "localhost" will be used as the local data source name. If the connection type is not explicitly set (that is. the RDM ODBC Driver will use a remote connection. If the connection type is explicitly set to local (that is. The SQL_ATTR_RDM_CONN_TYPE attribute is set to SQL_CT_UNKNOWN by default. The SQL_ATTR_RDM_REMOTE_NAME and SQL_ATTR_TFS_NAME attributes are set to NULL by default. non-empty string. the RDM ODBC Driver will use a local connection. by setting the SQL_ATTR_RDM_CONN_TYPE connection attribute to SQL_CT_LOCAL). the value stored in the SQL_ATTR_ RDM_TFS_NAME attribute will be used as the local data source name. Alternatively. the value stored in the SQL_ATTR_RDM_REMOTE_NAME connection attribute will be used as the data source name.  In this            case. SQL_IS_UINTEGER). NULL. NULL. SQL_ATTR_RDM_CONN_TYPE. the TFServer is running on the computer whose            hostname is "david-lnx" */ Introduction 16 . */         rc = SQLConnect(hDbc.     if (SQL_SUCCEEDED(rc)) {         /* Since SQL_ATTR_RDM_CONN_TYPE is not set. In this            case. SQL_ATTR_RDM_TFS_NAME. or SQL_SUCCESS_WITH_INFO if the operation succeeds but the RDM ODBC Driver returned diagnostic information that may include warnings.       /* Set connection type to remote */     rc = SQLSetConnectAttr(hDbc.RDMe ODBC API Reference Guide Establishing a Connection An application calls SQLConnect to establish a connection to an RDM data source. "david-lnx"            will be used as the local data source name. SQL_NTS). NULL. SQLConnect returns SQL_ERROR when an error occurs. 0. RDMSQLServer is running on the same computer            as the application. The following examples illustrate how an application can establish a connection to a data source. an application can call SQLGetDiagRec to retrieve the details of the diagnostics. }    Example 3 Using SQL_ATTR_RDM_REMOTE_NAME #include "sqlrext.h" /* RDM extension SQL header file */   SQLRETURN connectToDataSource(       SQLHDBC hDbc) {       SQLRETURN rc.             (SQLPOINTER) SQL_CT_REMOTE. Example 2 Setting a remote connection #include "sqlrext.             (SQLPOINTER) "david-lnx". 0).h" /* RDM extension SQL header file */   SQLRETURN connectToDataSource(       SQLHDBC hDbc) {       SQLRETURN rc.     }       return rc. "localhost"            will be used as the remote data source name. If SQLConnect returns a value other than SQL_SUCCESS.     if (SQL_SUCCEEDED(rc)) {         /* Since SQL_ATTR_RDM_REMOTE_NAME is not set.       /* This implicitly sets the connection type as local */     rc = SQLSetConnectAttr(hDbc. 0. SQLConnect returns SQL_SUCCESS to let the application know a connection to the specified data source has been successfully established.  0. 0).          /* Neither SQL_ATTR_RDM_CONN_TYPE.        the driver will use the value specified in the first        argument of SQLConnect to determine the connection type        and data source name.h" /* RDM extension SQL header file */   SQLRETURN connectToDataSource(       SQLHDBC hDbc) {       SQLRETURN rc.             NULL. nor               SQL_ATTR_RDM_REMOTE_NAME nor SQL_ATTR_TFS_NAME is set. 0). SQLDriverConnect accepts a connection string that may have the values for SQL_ATTR_RDM_REMOTE_NAME and SQL_ATTR_RDM_TFS_NAME embedded together. NULL. NULL. (SQLCHAR *) "tom-mac". }    Example 4 Using SQLConnect #include "sqlrext. 0. }    An application can also establish a connection to a data source by using SQLDriverConnect. SQL_NTS.     }       return rc. "tom-mac" will be        used as the remote data source name. Introduction 17 . In this case. NULL. NULL.       return rc. 0. see SQLDriverConnect in the ODBC API Function Reference section. where the        RDMSQLServer is running on the computer whose hostname        is "tom-mac" */     rc = SQLConnect(hDbc. For details.RDMe ODBC API Reference Guide         rc = SQLConnect(hDbc. SQLExecDirect prepares and executes the specified SQL statement at once. such as syntax errors and references to tables/columns that do not exist. An application can prepare a statement by calling SQLPrepare. Allocating a Statement Handle Before executing an SQL statement. Preparing an SQL statement means the RDM ODBC Driver (and its underlying RDM SQL engine) parses the statement and stores the information necessary to execute it later.       /* Allocate a statement handle */ Introduction 18 .     SQLHSTMT  hStmt. This process can also detect any errors that are in the statement. Executing an SQL statement involves the following steps. Preparing an SQL Statement An application can "prepare" an SQL statement before actually executing it. A prepared statement can be executed multiple times without being prepared again. passing SQL_HANDLE_STMT to the first argument and an existing connection handle to the second.RDMe ODBC API Reference Guide Executing an SQL Statement Once a connection to a data source has been established. Executing an SQL Statement Once an SQL statement has been prepared. see the Working with Parameters section. an application can execute SQL statements to interact with the databases managed by the data source. the preparation and execution steps can be combined into a single call to SQLExecDirect. For details about dynamic parameter binding. The following example illustrates how an application can allocate a statement handle and execute a statement that opens the NSFAWARDS database. A connection to a data source must already be established on the connection handle in order to allocate a statement handle on it.h"   SQLRETURN runDbOperations(       SQLHDBC hDbc) {       SQLRETURN rc. an application needs to allocate a statement handle by calling SQLAllocHandle. This is useful when executing a statement with dynamic parameter binding. If an application needs to execute the same SQL statement only once. Example 5 Opening a database #include "sqlrdm. an application can call SQLExecute to perform the actual execution of the statement. RDMe ODBC API Reference Guide     rc = SQLAllocHandle(SQL_HANDLE_STMT. '1'".e. Those statements are called "data manipulation language (DML) statements. hDbc. &hStmt). so an application must manually commit or roll back a transaction by calling SQLEndTran. Example 6 Inserting a new row #include "sqlrdm.                 SQL_NTS). (SQLCHAR *) "OPEN nsfawards".                 (SQLCHAR *) pszStmt. 'M'.     if (SQL_SUCCEEDED(rc)) {         rc = SQLExecDirect(hStmt.     if (SQL_SUCCEEDED(rc)) {         rc = SQLExecDirect(hStmt. RDM ODBC automatically starts a transaction so that the changes can be committed (i. aborted). The following examples illustrate how an INSERT statement can be executed including transaction processing. Introduction 19 . hStmt).           (void) SQLFreeHandle(SQL_HANDLE_STMT. &hStmt). }    Committing or Rolling Back Transactions Statements. (SQLCHAR *) "OPEN nsfawards". UPDATE and DELETE may make changes to the data stored in the data source.e. It attempts to insert a new row into the PERSON table of the NSFAWARDS database. Microsoft ODBC specification says transactions are committed automatically with each DML statement by default (called "autocommit").         if (SQL_SUCCEEDED(rc)) {             /* Execute an INSERT statement */             rc = SQLExecDirect(hStmt. Bill'. saved) or rolled back (i. hDbc.     }       return rc. SQL_NTS).                if (SQL_SUCCEEDED(rc)) {                  /* INSERT successful.                 SQL_NTS). commit the change */                  (void) SQLEndTran(SQL_HANDLE_DBC." When executing a DML statement.     SQLHSTMT    hStmt. hDbc. such as INSERT. The autocommit feature can be turned on by setting the SQL_ATTR_AUTOCOMMIT connection attribute to SQL_AUTOCOMMIT_ON. the "autocommit" feature is turned off by default. For RDM ODBC.       /* Allocate a statement handle */     rc = SQLAllocHandle(SQL_HANDLE_STMT.     const char *pszStmt = "INSERT INTO person VALUES "                           "'Houglum.h"   SQLRETURN runDbOperations(       SQLHDBC hDbc) {       SQLRETURN   rc.              }         }         (void) SQLFreeHandle(SQL_HANDLE_STMT. hStmt). }    Introduction 20 .     }       return rc.                          SQL_ROLLBACK). abort the change */                  (void) SQLEndTran(SQL_HANDLE_DBC. hDbc.              }              else {                  /* INSERT failed.RDMe ODBC API Reference Guide                          SQL_COMMIT). RDMe ODBC API Reference Guide Retrieving the Result Set SQL statements can return data from the data source. cb2. Binding Columns First.     char        szJob[2]. An application can call SQLBindCol on each of the columns for which it needs to access the returned values." An application binds a column by specifying the pointer to a variable for each returned column through a call to SQLBindCol. an application should tell RDM ODBC where it wants the result set to be stored.                 SQL_NTS). This step is called "binding columns.     SQLHSTMT    hStmt. An application typically calls SQLFetch repeatedly until it returns SQL_NO_DATA. an application can call SQLFetch to retrieve the result set." Retrieving the result set involves two steps.h"   SQLRETURN runDbOperations(       SQLHDBC hDbc) {       SQLRETURN   rc. The data an application retrieves from the data source comes in one or more rows that in turn include one or more columns." Queries can be executed in the same manner as the other SQL statements. an application must take additional steps to retrieve the data. Introduction 21 .     char        szName[36].     if (SQL_SUCCEEDED(rc)) {         /* Open the NSFAWARDS database first */         rc = SQLExecDirect(hStmt. Each call to SQLFetch puts the values of the current result row into the variables bound to the columns by SQLBindCol. Example 7 Retrieving rows from PERSON #include "sqlrdm.     char        szGender[2]. SQLFetch retrieves the result set one row at a time by default. This set of data is called "result set. cb. Fetching Columns After binding necessary columns. &hStmt). (SQLCHAR *) "OPEN nsfawards". Those statements that do are called "queries. However.       /* Allocate a statement handle */     rc = SQLAllocHandle(SQL_HANDLE_STMT. hDbc.     const char *pszStmt = "SELECT * FROM person". The following example illustrates how to retrieve all the rows stored in the PERSON table of the NSFAWARDS table.     SQLLEN      cb1. which indicates the end of the result set has been reached.                     }                 } while (SQL_SUCCEEDED(rc)).                         if (cb3 != SQL_NULL_DATA)                              printf("Jobclass = %s\n". sizeof(szName).     }       return rc. SQL_C_CHAR. }    The last argument of SQLBindCol specifies the pointer to a variable where the ODBC drive will store the length of the returned column data. A value of SQL_NULL_DATA indicates that the returned column contains NULL. &cb3).                 (void) SQLBindCol(hStmt 3.                         szGender. SQL_NTS).             }         }         (void) SQLFreeHandle(SQL_HANDLE_STMT. hStmt). sizeof(szJob). &cb1).                   /* This means fetch completed successfully */                 if (rc == SQL_NO_DATA)                     rc = SQL_SUCCESS. szJob).                         if (cb2 != SQL_NULL_DATA)                              printf("Gender = %s\n". szGender).               if (SQL_SUCCEEDED(rc)) {                 /* Bind all the 3 columns */                  (void) SQLBindCol(hStmt 1.                     if (SQL_SUCCEEDED(rc)) {                         if (cb1 != SQL_NULL_DATA)                              printf("Name = %s\n".                         szJob. SQL_C_CHAR. SQL_C_CHAR. sizeof(szGender).                   do {                     /* Fetch as many rows as there are */                     rc = SQLFetch(hStmt). szName). Introduction 22 .                         szName.                 (SQLCHAR *) pszStmt. &cb2).                 (void) SQLBindCol(hStmt 2.RDMe ODBC API Reference Guide         if (SQL_SUCCEEDED(rc)) {             /* Execute a SELECT statement */             rc = SQLExecDirect(hStmt. Example 10 Dynamic parameter binding #include "sqlrdm. as shown below. Freddie'. it saves an application time if the identical portion of the statements can be prepared just once. '1'. RDM ODBC provides that exact feature. '1'. an application inserting multiple rows into a table typically executes an INSERT statement differing only in the actual values to insert.    Calling SQLExecDirect three times will get the job done. 'F'.     char gender[2]. Example 8 Multiple INSERT statements INSERT INTO person VALUES 'Jackson. but it is not the most efficient way of handling the case as SQLExecDirect prepares and executes each statement. ?. Example 9 Statement with parameter markers INSERT INTO person VALUES ?. Michael'. An application can perform parameter binding on each of the parameter markers of a parameterized statement by calling SQLBindParameter. This allows an application to dynamically change the values that go with a statement after the statement has been prepared and before it has been executed. For instance. Statements that include parameter markers are called parameterized statements. Since the syntax of the three statements is identical. ?.h"   typedef struct person {       char name[36].RDMe ODBC API Reference Guide Advanced Topics Working with Parameters Oftentimes an application needs to execute multiple SQL statements that are almost identical. INSERT INTO person VALUES 'Swift. called dynamic parameter binding. SQLBindParameter lets an application specify a variable to store the value that will replace the parameter marker at statement execution time.     char jobclass[2]. An application can prepare an SQL statement replacing the actual values with the symbols called parameter markers ('?').     /* Three rows to insert into the PERSON table */   static const PERSON people[] = {   Advanced Topics 23 . The following example inserts three rows into the PERSON table using dynamic parameter binding. '2'. and the insertion of different values can be executed separately. } PERSON.   INSERT INTO person VALUES 'Mercury. 'F'. 'M'. Taylor'.     const char *pszInsert = "INSERT INTO person VALUES ?.RDMe ODBC API Reference Guide     {"Jackson. 1. For fixed data types. ii < RLEN(people).                 SQL_C_CHAR. &cb1).gender).       /* Assumption: hStmt has already been allocated */          /* Prepare the statement once */     rc = SQLPrepare(hStmt. Michael". SQL_CHAR. people[ii]. szGender.         (void) SQLBindParameter(hStmt. cb3. "2"}. SQL_PARAM_INPUT.     {"Mercury.             strcpy(szGender. 0. 0. szName. 0. SQL_CHAR. 0. 1. &cb2).         }           if (SQL_SUCCEEDED(rc))             SQLEndTran(SQL_HANDLE_DBC. ?. 1. people[ii]. szJob.                 SQL_C_CHAR.     {"Swift. &cb3). "M".     if (SQL_SUCCEEDED(rc)) {         /* Bind parameters for the three parameter markers */         (void) SQLBindParameter(hStmt. (SQLCHAR *) pszInsert.               cb1 = cb2 = cb3 = SQL_NTS.     SQLLEN      cb1.                 SQL_C_CHAR.         (void) SQLBindParameter(hStmt. hDbc. SQL_PARAM_INPUT. SQL_PARAM_INPUT. 1.     SQLRETURN insertMultipleRows(       SQLHDBC  hDbc. Freddie". }                   The last argument of SQLBindParameter can be used to specify the length of the actual data bound to a parameter. 0. "1"} }. For character and binary data types. ?". cb2.           for (ii = 0. ii++) {             /* Copy the values of the ii-th row into bound variables */              strcpy(szName. hDbc. "F".     uint16_t    ii. 1. SQL_COMMIT).name). Taylor". people[ii]. "M". the content of the argument is ignored.     }       return rc.         else             SQLEndTran(SQL_HANDLE_DBC. "1"}.     SQLHSTMT hStmt) {       SQLRETURN   rc. 35. SQL_CHAR.             strcpy(szJobclass. SQL_NTS).               /* Execute the prepared statement using the variables                that are just bound to the parameters */             rc = SQLExecute(hStmt). SQL_ROLLBACK). the Advanced Topics 24 . 0.jobclass).             if (!SQL_SUCCEEDED(rc))                 break. If the value of the attribute is 0 (as is by default). SQLFetch returns SQL_SUCCESS_WITH_INFO. or SQL_NTS if the data is a null-terminated string.     SQLLEN      cb1[ROW_ARRAY_SIZE]. In a situation like that. one of the 10 rows retrieved may have its data truncated. It can be a significant network overhead for an application accessing the data source through a remote server. An application can also tell the ODBC driver to store the statuses of all result rows into an array specified by the application. Finally.     char        szJob[ROW_ARRAY_SIZE][2]. It can be done by setting the SQL_ATTR_ROW_STATUS_PTR statement attribute to the pointer to the array of SQLUSMALLINTs. if 10 rows are to be fetched at a time.h"   #define ROW_ARRAY_SIZE 10 /* Fetch 10 rows at a time */     SQLRETURN runDbOperations(       SQLHDBC hDbc) {       SQLRETURN   rc. An application can call SQLGetDiagRec to retrieve all the errors and warnings contained in the result set. The cardinality of the array should match the number of result rows to retrieve at once. An application can call SQLSetStmtAttr and set the SQL_ATTR_ROW_ARRAY_SIZE statement attribute to the number of rows to retrieve with a single call to SQLFetch.                 cb2[ROW_ARRAY_SIZE]. Example 11 Retrieving multiple rows #include "sqlrdm.     char        szName[ROW_ARRAY_SIZE][36]. SQL_ NULL_DATA should be specified to indicate that NULL will be inserted into the corresponding column. SQLFetch retrieves one row at a time. When one call to SQLFetch returns multiple rows.     SQLHSTMT    hStmt. To reduce network traffic. The following example illustrates how to retrieve 10 rows at a time from the PERSON table. RDM ODBC provides a way to tell its driver to retrieve the specified number of rows at a time.     const char *pszStmt = "SELECT * FROM person". For instance. When an application fetches multiple rows at a time. where some (but not all) returned rows contain errors or warnings.                 cb3[ROW_ARRAY_SIZE]. an application can set the SQL_ATTR_ROWS_FETCHED_PTR statement attribute to the pointer to an SQLULEN variable to have the number of returned rows stored in that variable. the return code of SQLFetch itself cannot represent the potentially different statuses of the retrieved rows.RDMe ODBC API Reference Guide length should be expressed in the number of bytes. the variable bound to an INTEGER column must be declared as "int16_t var[10]". For instance. Advanced Topics 25 . the variable it binds to a column must be an array whose cardinality should match the number of rows to retrieve. as shown in Example 11.     char        szGender[ROW_ARRAY_SIZE][2]. Fetching Multiple Rows at Once SQLFetch retrieves one row of the result set at a time. RDMe ODBC API Reference Guide     SQLULEN     ucbFetchedRows.                                   szJob[ii]). 0).                         szGender.                     (SQLPOINTER) ROW_ARRAY_SIZE. SQL_NTS). &hStmt).                 (void) SQLBindCol(hStmt 2. 5) is the size of one element                    of the bound variable */                  (void) SQLBindCol(hStmt 1. szName[ii]). &cb3).                         szJob.                                  szGender[ii]). note that the length                    argument (arg.               /* Specify the storage for the # of fetched rows */             (void) SQLSetStmtAttr(hStmt. hStmt). SQL_C_CHAR. sizeof(szName[0]). sizeof(szGender[0]).                         }                     }                 }             }         }         (void) SQLFreeHandle(SQL_HANDLE_STMT.                         }                         if (cb3[ii] != SQL_NULL_DATA) {                              printf("Jobclass = %s\n". SQL_C_CHAR.                 (void) SQLBindCol(hStmt 3. hDbc. &cb2).                   while ((rc = SQLFetch(hStmt)) != SQL_NO_DATA) {                     /* ucbFetchedRows = # of rows */                     for (ii = 0.                         if (cb2[ii] != SQL_NULL_DATA) {                              printf("Gender = %s\n".               if (SQL_SUCCEEDED(rc)) {                 /* Bind all the 3 columns. ii++) {                         if (cb1[ii] != SQL_NULL_DATA)                              printf("Name = %s\n". SQL_ATTR_ROW_ARRAY_SIZE. SQL_C_CHAR. cb1).                     SQL_ATTR_ROWS_FETCHED_PTR.                         szName. ii < ucbFetchedRows. sizeof(szJob[0]).               /* Execute a SELECT statement */             rc = SQLExecDirect(hStmt.                     (SQLPOINTER) &ucbFetchedRows.                 (SQLCHAR *) pszStmt. 0). (SQLCHAR *) "OPEN nsfawards".       /* Allocate a statement handle */     rc = SQLAllocHandle(SQL_HANDLE_STMT. Advanced Topics 26 .     if (SQL_SUCCEEDED(rc)) {         /* Open the NSFAWARDS database first */         rc = SQLExecDirect(hStmt.     SQLULEN     ii.         if (SQL_SUCCEEDED(rc)) {             /* Specify to retrieve 10 rows at a time */             (void) SQLSetStmtAttr(hStmt.                 SQL_NTS). it may not always be efficient. When it has retrieved the last chunk of data. This allows an application to call SQLGetData on the same column multiple times in order to retrieve the column data by the size specified with the function. desired or even possible to retrieve the whole content of a column that contains string or binary data. SQLGetData returns SQL_SUCCESS_WITH_INFO (SQLSTATE "01S02" – data truncated) if there is more data to be retrieved on that column. if an application calls SQLGetData with the size of data set to 100 on a column that contains a 800-character string. The RDM ODBC Driver only supports forward-only cursors. SQLGetData returns SQL_NO_DATA. For instance. If called after the last part of the data has been retrieved. }    With an ODBC driver that supports scrollable cursors. an application can call SQLFetchScroll to scroll the result set back and forth. not before. An application can use this mechanism to detect the last read of the data. On the other hand. it will need to call the function 8 times on that column in order to read in the whole data. SQLGetData works similarly to SQLBindCol except that SQLGetData is called after the row is fetched.             SQL_NTS).       /* Assumption. Retrieving Data in Parts Binding columns using SQLBindCol allows an application to retrieve the content of a given column in one shot. an application can retrieve the data in parts by calling SQLGetData. floating-point number and date/time where the size of the data is known before fetching the column. it returns SQL_SUCCESS. hStmt is already allocated */       rc = SQLExecDirect(hStmt.     if (SQL_SUCCEEDED(rc)) {         while ((rc = SQLFetch(hStmt)) != SQL_NO_DATA) {             do { Advanced Topics 27 . While it provides SQLFetchScroll. In that case. such as an integer.     char      szData[100]. the function only accepts SQL_FETCH_NEXT as the fetch type. The following example illustrates how an application can retrieve a character data in parts using SQLGetData. It works well when the column contains fixed-length data.h"   #define MAX_FETCH_SIZE 100     SQLRETURN getCharData(       SQLHSTMT hStmt) {       SQLRETURN rc. #include "sqlrdm.RDMe ODBC API Reference Guide     }       return rc. (SQLCHAR *) "SELECT col1 FROM vartable". It means SQLFetch and SQLFetchScroll currently work the same way in RDM ODBC.         }     }       return rc. 1.             } while (rc == SQL_SUCCESS_WITH_INFO). SQLGetData returns SQL_NO_DATA except for the first call. NULL). If called on a fixed-length column more than once.RDMe ODBC API Reference Guide                 rc = SQLGetData(hStmt. Advanced Topics 28 . }    This mechanism can only be used to retrieve character or binary data in parts.             printf("\n"). szData).                         MAX_FETCH_SIZE. szData.                 if (SQL_SUCCEEDED(rc))                     printf("%s". SQL_C_CHAR. Retrieves the basic result data set for a column Retrieves description of a parameter marker Retrieves the type of the SQL statement executed on the handle. Descriptions include the following:  l  l  l  l  l Purpose Conformance Syntax Arguments Return values All of the following APIs conform to the ODBC 3. The Unicode functions are implemented as functions with a suffix of "W". Establishes connections to RDM databases via RDM ODBC. Closes the connection associated with a specified handle Establishes connections to RDM databases via RDM ODBC.51 specification unless otherwise noted. Closes a cursor that has been opened on a statement and discards pending results. Function Reference Pages This section contains topics for the following functions: Function Name SQLAllocHandle SQLBindCol SQLBindParameter SQLCancel SQLCloseCursor SQLColAttribute Description Allocates an environment.RDMe ODBC API Reference Guide RDM ODBC API Reference The topics in this section describe each ODBC function in alphabetical order. Unicode API Functions The RDM ODBC API supports both ANSI and Unicode versions of all functions that accept pointers to character strings or SQLPOINTER in their arguments. Returns descriptor information for a column in a result set. connection. a 32-bit descriptor-dependent value. The driver returns this information as a result set on the specified StatementHandle. RDM specific extensions to the APIs will be documented in the Diagnostics or Comments sections of the page. Copies descriptor information from one descriptor handle to another. If function does not contain a Diagnostics or Comments section. Binds a buffer to a parameter marker in an SQL statement. Descriptor information is returned as a character string. Cancels the processing on a statement. statement. the MSDN documentation applies to that specific function. or descriptor handle Binds application data buffers to columns in the result set. Accepts more connection options than SQLConnect. or an integer value. Requests a commit or rollback for active transactions SQLColumns SQLConnect SQLCopyDesc SQLDescribeCol SQLDescribeParam SQLDescribeStmt SQLDisconnect SQLDriverConnect SQLEndTran RDM ODBC API Reference 29 . Returns the list of column names in specified tables. such as SQLExecDirectW and SQLGetInfoW. Each function is defined as a C programming language function. Frees resources associated with a specific environment. This function does not support returning primary keys from multiple tables in a single call. SQLParamData is used together with SQLPutData to supply parameter data at statement execution time. Returns the current setting of a statement attribute. closes any open cursors associated with the statement. and with SQLGetData to retrieve streamed output parameter data.RDMe ODBC API Reference Guide Function Name SQLExecDirect SQLExecute SQLExtendedTran SQLFetch SQLFetchScroll SQLForeignKeys Description Prepares and executes an SQL statement Executes a previously prepared SQL statement Performs a transaction operation Fetches data from a bound column to an application variable Fetches the specified rowset of data from the result set and returns data for all bound columns. Returns the current setting or value of a single field of a descriptor record. data type. Returns the column names that make up the primary key for a table. 30 SQLFreeHandle SQLFreeStmt SQLGetConnectAttr SQLGetCursorName SQLGetData SQLGetDescField SQLGetDescRec SQLGetDiagField SQLGetDiagRec SQLGetEnvAttr SQLGetFunctions SQLGetInfo SQLGetStmtAttr SQLGetTypeInfo SQLMoreResults SQLNativeSql SQLNumParams SQLNumResultCols SQLParamData SQLPrepare SQLPrimaryKeys RDM ODBC API Reference . discards pending results. or descriptor handle. Prepares an SQL string for execution. and storage of column or parameter data. The driver returns the information as a result set. Determines whether more results are available on a statement containing SELECT. Retrieves current field value of a status record Retrieves current values of several common fields of a status record Returns the current setting of an environment attribute. Returns general information about the driver and data source associated with a connection. INSERT. Returns the current setting of a connection attribute. Returns the SQL string as modified by the driver. frees all resources associated with the statement handle. statement. or DELETE statements and. Returns information about whether a driver supports a specific ODBC function. Retrieves the cursor name of an SQL statement handle Retrieves data for a single column in the result set. Returns the current settings or values of multiple fields of a descriptor record. Determines the number of parameters in a prepared statement Returns the number of columns in a result set. The fields returned describe the name. or. connection. UPDATE. optionally. Stops processing associated with a specific statement. initializes processing for those results. SQLNativeSql does not execute the SQL statement. if so. It can be called multiple times to retrieve variable-length data in parts. SQLForeignKeys can return a list of foreign keys in the specified table (columns in the specified table that refer to primary keys in other tables) or a list of foreign keys in other tables that refer to the primary key in the specified table. Returns information about data types supported by the data source. The driver returns each list as a result set on the specified statement. SQLProcedures Returns the list of procedure names stored in a specific data source.RDMe ODBC API Reference Guide Function Name Description SQLProcedureColumns Returns the parameter and column information about the specified procedures. parameters of the SQL_LONGVARBINARY or SQL_LONGVARCHAR types). or DELETE SQLSetConnectAttr Sets attributes that govern aspects of connections. SQLTransactStatus Retrieves the type and status of the transaction possibly executed on the handle. SQLSetError Registers user-defined status/error handling functions. SQLRowCount Gets row count in a table following an INSERT. or a named entity that can be invoked using input and output parameters. and table types. This function can be used to send character or binary data values in parts to a column with a character. SQLPutData Allows an application to send data for a parameter or column to the driver at statement execution time. SQLStatistics Retrieves a list of statistics about a single table and the indexes associated with the table. SQLSetCursorName Associates a cursor name with an active statement. or data source–specific data type (for example. SQLSetEnvAttr Sets attributes that govern aspects of environments. stored in a specific data source. SQLSetDescField Sets the value of a single field of a descriptor record. RDM ODBC API Reference 31 . or schema names. Procedure is a generic term used to describe an executable object. SQLTables Returns the list of table. binary. The driver returns the information as a result set. UPDATE. catalog. SQLSetStmtAttr Sets attributes related to a statement SQLSpecialColumns Returns the information about the set of columns that uniquely identifies a row in the table. SQLSetDescRec Sets multiple descriptor fields that affect the data type and buffer bound to a column or parameter data. RDMe ODBC API Reference Guide SQLAllocHandle Allocates an environment, connection, statement, or descriptor handle. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLAllocHandle(         SQLSMALLINT      HandleType,         SQLHANDLE        InputHandle,         SQLHANDLE       *OutputHandle) Arguments HandleType     (input) The type of handle to be allocated by SQLAllocHandle. Must be one of the following values:  l SQL_HANDLE_ENV  l SQL_HANDLE_DBC  l SQL_HANDLE_STMT InputHandle (input)  l SQL_HANDLE_DESC The input handle in whose context the new handle is to be allocated. If HandleType is SQL_HANDLE_ENV, this is SQL_NULL_HANDLE. If HandleType is SQL_HANDLE_DBC, this must be an environment handle, and if it is SQL_HANDLE_STMT or SQL_HANDLE_DESC, it must be a connection handle. Pointer to a buffer in which to return the handle to the newly allocated data structure. OutputHandlePtr (output) Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code RDM ODBC API Reference Description 32 RDMe ODBC API Reference Guide SQL_SUCCESS SQL_SUCCESS_WITH_INFO Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. Function completed successfully, possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Function failed due to an invalid environment, connection, statement, or descriptor handle. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is passed for an argument that requires a connection handle. SQL_ERROR SQL_INVALID_HANDLE Comments This function allocates an environment, connection, or SQL statement handle and its associated resources. RDM does not require you to allocate an environment handle before allocating connection or statement  handles, and doing so currently has no effect. The environment handle type is included only for ODBC  compatibility.  For more information, reference MSDN documentation for SQLAllocHandle. RDM ODBC API Reference 33 RDMe ODBC API Reference Guide SQLBindCol Binds application data buffers to columns in the result set. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLBindCol(         SQLHSTMT         StatementHandle,         SQLUSMALLINT     ColumnNumber,         SQLSMALLINT      TargetType,         SQLPOINTER       TargetValue,         SQLLEN           BufferLength,         SQLLEN          *StrLen_or_Ind) Arguments StatementHandle     (input) ColumnNumber (input) TargetType TargetValue (input) (output) Statement handle. The column's location in the result data set. Columns are numbered sequentially from left to right, starting with 1, as they appear in the result data set. The data type of the value buffer that the column data being retrieved is to be stored in. A pointer to a location in memory where the driver is to store column data when it is retrieved (fetched) from the result data set or where the application is to store column data that is to be written to a data source with a positioned UPDATE or DELETE operation. The size of the buffer. A pointer to a location in memory where this function is to store either the size of the data value associated with the column or a special indicator value associated with the column data. BufferLength StrLen_or_Ind (input) (output) Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 34 The application calls SQLGetDiagField to retrieve additional information from the header record. Function failed due to an invalid environment. connection. reference MSDN documentation for SQLBindCol. No additional information is available from SQLGetDiagRec or SQLGetDiagField. For more information. such as when a statement handle is passed for an argument that requires a connection handle. RDM ODBC API Reference 35 . possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. This indicates a programming error. Function completed successfully. Function failed. statement. or descriptor handle. The contents of any output arguments to the function are undefined. SQL_ERROR SQL_INVALID_HANDLE Comments This function binds application data buffers to columns in the result set.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. This code is returned only when the handle is a null pointer or is the wrong type. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. ordered sequentially in increasing parameter order. ParameterValuePtr (deferred  input) BufferLength (input/output) Length of the ParameterValuePtr buffer in bytes.       SQLSMALLINT     ParameterType. The size of the column or expression of the corresponding parameter marker. The size of the buffer. Parameter number.0 Standards Compliance: ODBC Syntax SQLRETURN SQLBindParameter(       SQLHSTMT        StatementHandle. The C data type of the parameter. The type of the parameter.       SQLULEN         ColumnSize. A pointer to a buffer for the parameter's data.       SQLSMALLINT     InputOutputType. StrLen_or_IndPtr (deferred  A pointer to a buffer for the parameter's length.       SQLUSMALLINT    ParameterNumber.RDMe ODBC API Reference Guide SQLBindParameter Binds a buffer to a parameter marker in an SQL statement. starting at 1.       SQLLEN *        StrLen_or_IndPtr) Arguments StatementHandle     (input) ParameterNumber (input) InputOutputType ValueType ParameterType ColumnSize DecimalDigits (input) (input) (input) (input) (input) Statement handle.       SQLLEN          BufferLength. Conformance Version Introduced: ODBC 2. input) Required Headers #include "sqlext.       SQLSMALLINT     ValueType.       SQLSMALLINT     DecimalDigits. The decimal digits of the column or expression of the corresponding parameter marker.       SQLPOINTER      ParameterValuePtr.h" RDM ODBC API Reference 36 . This indicates a programming error. Function failed. such as when a statement handle is passed for an argument that requires a connection handle. Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLBindParameter. statement. or descriptor handle. possibly with a nonfatal error (warning). connection. This code is returned only when the handle is a null pointer or is the wrong type. Function failed due to an invalid environment. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.RDMe ODBC API Reference Guide Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. No additional information is available from SQLGetDiagRec or SQLGetDiagField. SQL_ERROR SQL_INVALID_HANDLE For more information. RDM ODBC API Reference 37 . Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The contents of any output arguments to the function are undefined. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Conformance Version Introduced: ODBC 1. statement. This indicates a programming error.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLCancel(         SQLHSTMT         StatementHandle) Arguments StatementHandle     (input) Statement handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. This code is returned only when the handle is a null pointer or is the wrong type. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. connection. The contents of any output arguments to the function are undefined. possibly with a nonfatal error (warning). Function completed successfully. Function failed. or descriptor handle. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. such as when a statement handle is 38 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . Function failed due to an invalid environment. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.RDMe ODBC API Reference Guide SQLCancel Cancels the processing on a statement. RDMe ODBC API Reference Guide passed for an argument that requires a connection handle. RDM ODBC API Reference 39 . For more information.  l A function running on the statement on another thread. Comments On RDM. SQLCancel supports the following type of processing. The following types of processing are not supported due to the driver limitations.  l A function on a statement that needs data.  l A function running asynchronously on a statement. reference MSDN documentation for SQLCancel. 0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLCloseCursor(         SQLHSTMT         StatementHandle) Arguments StatementHandle     (input) Statement handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Required Headers #include "sql. possibly with a nonfatal error (warning). This code is returned only when the handle is a null pointer or is the wrong type. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. or descriptor handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Conformance Version Introduced: ODBC 3.RDMe ODBC API Reference Guide SQLCloseCursor Closes a cursor that has been opened on a statement and discards pending results. Function failed due to an invalid environment. The application calls SQLGetDiagField to retrieve additional information from the header record.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Function completed successfully. connection. This indicates a programming error. Function failed. statement. such as when a statement handle is 40 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . No additional information is available from SQLGetDiagRec or SQLGetDiagField. RDM ODBC API Reference 41 . For more information.RDMe ODBC API Reference Guide passed for an argument that requires a connection handle. reference MSDN documentation for SQLCloseCursor.       SQLSMALLINT *   StringLengthPtr. SQL_COLUMN_TABLE_NAME). This handle defines which field in the IRD should be queried (for example. The descriptor handle. or an integer value. If FieldIdentifier is an ODBC-defined field and *CharacterAttributePtr is an integer. the field is unused. The number of the record in the IRD from which the field value is to be retrieved. ordered sequentially in increasing column order. this argument should be the length of *CharacterAttributePtr.       SQLPOINTER      CharacterAttributePtr. BufferLength can have the following values:  l If CharacterAttributePtr is a pointer to a pointer. Conformance Version Introduced: ODBC 3. If the *CharacterAttributePtr is a Unicode string (when calling SQLColAttributeW).0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLColAttribute (       SQLHSTMT        StatementHandle.RDMe ODBC API Reference Guide SQLColAttribute Returns descriptor information for a column in a result set. If CharacterAttributePtr is NULL.       SQLUSMALLINT    FieldIdentifier. a 32-bit descriptor-dependent value. StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by CharacterAttributePtr. If FieldIdentifier is a driver-defined field. Pointer to a buffer in which to return the value in the FieldIdentifier field of the ColumnNumber row of the IRD. FieldIdentifier (input) CharacterAttributePtr (output) BufferLength (input) RDM ODBC API Reference 42 . if the field is a character string. Column 0 can be specified in this argument.       SQLPOINTER      NumericAttributePtr) Arguments StatementHandle     ColumnNumber (input) (input) Statement handle. this field is ignored. This argument corresponds to the column number of result data. Descriptor information is returned as a character string.       SQLUSMALLINT    ColumnNumber. Otherwise. If FieldIdentifier is an ODBC-defined field and CharacterAttributePtr points to a character string or binary buffer. starting at 1. BufferLength should  have the value SQL_IS_POINTER. the application indicates the nature of the field to the Driver Manager by setting the BufferLength argument. Columns can be described in any order.       SQLSMALLINT     BufferLength. the BufferLength argument must be an even number. but all values except SQL_DESC_TYPE and SQL_DESC_OCTET_LENGTH will return undefined values. RDMe ODBC API Reference Guide  l If CharacterAttributePtr is a pointer to a character string, the BufferLength is the length of the buffer.  l If CharacterAttributePtr is a pointer to a binary buffer, the application  places the result of the SQL_LEN_BINARY_ATTR(length) macro in  BufferLength. This places a negative value in BufferLength.  l If CharacterAttributePtr is a pointer to a fixed-length data type, BufferLength must be one of the following: SQL_IS_INTEGER, SQL_IS_ UNINTEGER, SQL_SMALLINT, or SQLUSMALLINT.   Pointer to a buffer in which to return the total number of bytes (excluding the null-termination byte for character data) available to return in *CharacterAttributePtr. For character data, if the number of bytes available to return is greater than or equal to BufferLength, the descriptor information in *CharacterAttributePtr is truncated to BufferLength minus the length of a null-termination character and is null-terminated by the driver. For all other types of data, the value of BufferLength is ignored and the driver assumes the size of *CharacterAttributePtr is 32 bits. Pointer to an integer buffer in which to return the value in the FieldIdentifier field of the ColumnNumber row of the IRD, if the field is a numeric descriptor type, such as SQL_DESC_COLUMN_LENGTH. Otherwise, the field is unused. StringLengthPtr (output) NumericAttributePtr (output) Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. Function completed successfully, possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Function failed due to an invalid environment, connection, statement, or descriptor handle. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is 43 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference RDMe ODBC API Reference Guide passed for an argument that requires a connection handle. For more information, reference MSDN documentation for SQLColAttribute. RDM ODBC API Reference 44 RDMe ODBC API Reference Guide SQLColumns Returns the list of column names in specified tables. The driver returns this information as a result set on the specified StatementHandle. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLColumns(         SQLHSTMT         StatementHandle,         SQLCHAR         *CatalogName,         SQLSMALLINT      NameLength1,         SQLCHAR         *SchemaName,         SQLSMALLINT      NameLength2,         SQLCHAR         *TableName,         SQLSMALLINT      NameLength3,         SQLCHAR         *ColumnName,         SQLSMALLINT      NameLength4) Arguments StatementHandle     (input) CatalogName (input) Statement handle. Catalog name. If a driver supports catalogs for some tables but not for others, such as when the driver retrieves data from different DBMSs, an empty string ("") indicates those tables that do not have catalogs. CatalogName cannot contain a string search pattern. Length in characters of *CatalogName. String search pattern for schema names. If a driver supports schemas for some tables but not for others, such as when the driver retrieves data from different DBMSs, an empty string ("") indicates those tables that do not have schemas. Length in characters of *SchemaName. String search pattern for table names. Length in characters of *TableName. String search pattern for column names. Length in characters of *ColumnName. NameLength1 SchemaName (input) (input) NameLength2 TableName NameLength3 ColumnName NameLength4 (input) (input) (input) (input) (input) Required Headers #include "sql.h" RDM ODBC API Reference 45 For more information. Function completed successfully. No additional information is available from SQLGetDiagRec or SQLGetDiagField. such as when a statement handle is passed for an argument that requires a connection handle. The contents of any output arguments to the function are undefined. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. This indicates a programming error. If no database is open on the data source. reference MSDN documentation for SQLColumns. RDM ODBC API Reference 46 . The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment. statement. or descriptor handle. SQL_ERROR SQL_INVALID_HANDLE Comments SQLColumns returns the information that pertain to the databases that are currently open. possibly with a nonfatal error (warning). The application calls SQLGetDiagField to retrieve additional information from the header record. SQLColumns returns an empty result set. connection. Function failed. This code is returned only when the handle is a null pointer or is the wrong type.RDMe ODBC API Reference Guide Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Length of *UserName in characters.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code RDM ODBC API Reference Description 47 . Conformance Version Introduced: ODBC 1. Length of *ServerName in characters.         const SQLCHAR   *ServerName.         SQLSMALLINT      NameLength2.         SQLSMALLINT      NameLength3) Arguments ConnectionHandle     (input) ServerName (input) NameLength1 (input) UserName NameLength2 Authentication NameLength3 (input) (input) (input) (input) Connection handle. Specify SQL_NTS if Authentication is a null-terminated string. This parameter is not used.         SQLSMALLINT      NameLength1. see the Comments section.         const SQLCHAR   *Authentication. Specify SQL_NTS if ServerName is a nullterminated string.         const SQLCHAR   *UserName. The name of the remote server. This parameter is not used. Specify SQL_NTS if UserName is a null-terminated string. For the details. Required Headers #include "sql.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLConnect(         SQLHDBC          ConnectionHandle. Length of *Authentication in characters.RDMe ODBC API Reference Guide SQLConnect Establishes connections to RDM databases via RDM ODBC. This indicates a programming error. Connection already in use. Function failed. The specified connection handle is already used for an existing connection. set with SQL_ATTR_RDM_CONN_TYPE attribute using SQLSetConnectAttr. Connection Type NULL/empty Not set ServerName Local Remote Actual Connection Local Local Remote Actual Server Names TFS Remote TFS Remote TFS Remote SQL_ATTR_RDM_TFS_NAME N/A SQL_ATTR_RDM_TFS_NAME N/A SQL_ATTR_RDM_TFS_NAME SQL_ATTR_RDM_REMOTE_ NAME 48 RDM ODBC API Reference . such as when a statement handle is passed for an argument that requires a connection handle. Description The RDM ODBC Driver does not support the specified value for the ValuePtr argument in SQLSetConnectAttr. 08001 08002 HY001 HY013 Comments The value for the ServerName parameter specifies the name of the remote server for the data source. It is the TCP/IP host name of the computer where the remote server is running. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Driver memory allocation error The RDM ODBC driver failed to allocate memory required to complete the operation. The behavior of SQLConnect changes depending upon the combination of this value and the connection type. connection. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. as follows. or descriptor handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.RDMe ODBC API Reference Guide SQL_SUCCESS SQL_SUCCESS_WITH_INFO Function completed successfully. possibly with a nonfatal error (warning). Function completed successfully. Unable to connect. Memory management error The function could not complete the operation due to the out-ofmemory condition in the data source. The specified value has been substituted by a similar value. statement. The application calls SQLGetDiagField to retrieve additional information from the header record. This code is returned only when the handle is a null pointer or is the wrong type. The contents of any output arguments to the function are undefined. The function returns SQL_SUCCESS_WITH_INFO. SQL_ERROR SQL_INVALID_HANDLE Diagnostics SQLSTATE 01S02 Error Option value changed. Function failed due to an invalid environment. The RDM ODBC driver was not able to connect to the data source. RDM ODBC API Reference 49 . Authentication. Values specified for those parameters will be ignored.RDMe ODBC API Reference Guide ServerName Set Connection Type Not set Local Remote Actual Connection Remote Local Remote Actual Server Names TFS Remote TFS Remote TFS Remote SQL_ATTR_RDM_TFS_NAME ServerName ServerName N/A SQL_ATTR_RDM_TFS_NAME ServerName The UserName. For more information. NameLength2 and NameLength3 parameters are currently not used in RDM ODBC since RDM does not support user authentication. reference MSDN documentation for SQLConnect. Arguments SourceDescHandle     (input) TargetDescHandle (input) Source descriptor handle. Target descriptor handle.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLCopyDesc(      SQLHDESC     SourceDescHandle. The application calls SQLGetDiagField to retrieve additional information from the header record. Required Headers #include "sql. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Conformance Version Introduced: ODBC 3. TargetDescHandle cannot be set to a handle to an IRD.      SQLHDESC     TargetDescHandle). Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. 50 SQL_ERROR RDM ODBC API Reference . Function completed successfully. The TargetDescHandle argument can be a handle to an application descriptor or an IPD.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. or SQLCopyDesc will return SQLSTATE HY016 (Cannot modify an implementation row descriptor). The contents of any output arguments to the function are undefined.RDMe ODBC API Reference Guide SQLCopyDesc Copies descriptor information from one descriptor handle to another. Function failed. possibly with a nonfatal error (warning). or descriptor handle. statement. For more information. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGetDiagField. such as when a statement handle is passed for an argument that requires a connection handle. reference MSDN documentation for SQLCopyDesc. This code is returned only when the handle is a null pointer or is the wrong type. connection. RDM ODBC API Reference 51 .RDMe ODBC API Reference Guide SQL_INVALID_HANDLE Function failed due to an invalid environment.         SQLSMALLINT      BufferLength. the driver returns 0. If the data type cannot be determined. Pointer to a buffer in which to return the size (in characters) of the column on the data source. ordered sequentially in increasing column order. If ColumnName is NULL. NameLengthPtr will still return the total number of characters (excluding the null-termination character for character data) available to return in the buffer pointed to by ColumnName. Column number of result data. This value is read from the SQL_DESC_NAME field of the IRD.         SQLSMALLINT     *DecimalDigitsPtr.         SQLCHAR         *ColumnName. the driver returns an empty string.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDescribeCol(         SQLHSTMT         StatementHandle. If the column is unnamed or the column name cannot be determined. the driver returns SQL_UNKNOWN_TYPE. Pointer to a buffer in which to return the total number of characters (excluding the null termination) available to return in *ColumnName. or a driver-specific SQL data type. Pointer to a null-terminated buffer in which to return the column name. If the column size cannot be determined.         SQLULEN         *ColumnSizePtr.         SQLUSMALLINT     ColumnNumber.         SQLSMALLINT     *DataTypePtr.RDMe ODBC API Reference Guide SQLDescribeCol Retrieves the basic result data set for a column Conformance Version Introduced: ODBC 1. the column name in *ColumnName is truncated to BufferLength minus the length of a null-termination character. in characters. BufferLength NameLengthPtr (input) (output) DataTypePtr (output) ColumnSizePtr (output) DecimalDigitsPtr (output) RDM ODBC API Reference 52 . starting at 1. Length of the *ColumnName buffer. This will be one of the values in SQL Data Types. This value is read from the SQL_DESC_CONCISE_TYPE field of the IRD. If the number of characters available to return is greater than or equal to BufferLength. Pointer to a buffer in which to return the SQL data type of the column.         SQLSMALLINT     *NameLengthPtr.         SQLSMALLINT     *NullablePtr) Arguments StatementHandle     (input) ColumnNumber (input) ColumnName (output) Statement handle. Pointer to a buffer in which to return the number of decimal digits of the column on the data source. If the number of decimal digits cannot be determined or is not applicable. the driver returns 0. RDM ODBC API Reference 53 .RDMe ODBC API Reference Guide NullablePtr (output) Pointer to a buffer in which to return a value that indicates whether the column allows NULL values. possibly with a nonfatal error (warning).  l SQL_NULLABLE: The column allows NULL values. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. This indicates a programming error. The value is one of the following:  l SQL_NO_NULLS: The column does not allow NULL values.  Required Headers #include "sql. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. This code is returned only when the handle is a null pointer or is the wrong type.  l SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column  allows NULL values. statement. reference MSDN documentation for SQLDescribeCol. Function failed due to an invalid environment. Function completed successfully. Function failed. The contents of any output arguments to the function are undefined. No additional information is available from SQLGetDiagRec or SQLGetDiagField. The application calls SQLGetDiagField to retrieve additional information from the header record.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. SQL_ERROR SQL_INVALID_HANDLE For more information. or descriptor handle. such as when a statement handle is passed for an argument that requires a connection handle. connection. This value is read from the SQL_DESC_NULLABLE field of the IRD. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.         SQLSMALLINT     *NullablePtr) Arguments StatementHandle     (input) ParamNumber (input) Statement handle. in characters. Pointer to a buffer in which to return the size. Returns Return Code RDM ODBC API Reference Description 54 .         SQLULEN         *ParameterSizePtr. starting with 1.         SQLUSMALLINT     ParameterNumber.         SQLSMALLINT     *DecimalDigitsPtr. Pointer to a buffer in which to return the number of decimal digits of the column or expression of the corresponding parameter as defined by the data source.         SQLSMALLINT     *DataTypePtr.RDMe ODBC API Reference Guide SQLDescribeParam Retrieves description of a parameter marker Conformance Version Introduced: ODBC 1. Pointer to a buffer in which to return a value that indicates whether the parameter allows NULL values. as they appear in the SQL statement.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDescribeParam(         SQLHSTMT         StatementHandle. DataTypePtr (output) ParameterSizePtr (output) DecimalDigitsPtr (output) NullablePtr (output) Required Headers #include "sqlext. Parameter numbers are numbered sequentially from left to right. of the column or expression of the corresponding parameter marker as defined by the data source. Pointer to a buffer in which to return the SQL data type of the parameter. Specifies the parameter number in the SQL statement text. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. SQL_ERROR SQL_INVALID_HANDLE For more information. RDM ODBC API Reference 55 . Function failed due to an invalid environment. The contents of any output arguments to the function are undefined. The application calls SQLGetDiagField to retrieve additional information from the header record. connection. This indicates a programming error. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. statement. Function failed.RDMe ODBC API Reference Guide SQL_SUCCESS SQL_SUCCESS_WITH_INFO Function completed successfully. Function completed successfully. reference MSDN documentation for SQLDescribeParam. or descriptor handle. possibly with a nonfatal error (warning). such as when a statement handle is passed for an argument that requires a connection handle. such as when a statement handle is 56 SQL_INVALID_HANDLE RDM ODBC API Reference . Function failed. Returns Return Code SQL_SUCCESS SQL_ERROR Description Function completed successfully.RDMe ODBC API Reference Guide SQLDescribeStmt Retrieves the type of the SQL statement executed on the handle. Required Headers #include "sqlrext. The application calls SQLGetDiagField to retrieve additional information from the header record. Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQL_API SQLDescribeStmt(     SQLHSTMT         StatementHandle. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Possible values returned through this parameter are described in the Comments section below. The contents of any output arguments to the function are undefined. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment. statement.     SQLUSMALLINT    *pStmtType) Arguments StatementHandle      (input) pStmtType (output) Statement handle. connection. The type of the SQL statement executed on the statement handle. or descriptor handle. This code is returned only when the handle is a null pointer or is the wrong type.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. SQL statement executed OPEN [ DATABASE ] <database> OPEN [ DATABASE ] <database-union> CLOSE [ DATABASE ] <database> SELECT INSERT UPDATE DELETE BEGIN [ WORK ] COMMIT [ WORK ] SAVEPOINT <trans-id> RELEASE SAVEPOINT <trans-id> ROLLBACK [ WORK ] CREATE PROCEDURE <procedure> DROP PROCEDURE <procedure> EXECUTE <procedure> SET SET COLUMN STATS LOCK TABLE <table> UNLOCK TABLE <table> INITIALIZE [ DATABASE ] <database> CREATE CATALOG FOR <id> IMPORT EXPORT Dynamic DDL statement[1] Value of pStmtType SQL_RDM_STMT_OPEN SQL_RDM_STMT_DBUNION SQL_RDM_STMT_CLOSE SQL_RDM_STMT_SELECT SQL_RDM_STMT_INSERT SQL_RDM_STMT_UPDATE SQL_RDM_STMT_DELETE SQL_RDM_STMT_START SQL_RDM_STMT_COMMIT SQL_RDM_STMT_SAVEPOINT SQL_RDM_STMT_RELEASE SQL_RDM_STMT_ROLLBACK SQL_RDM_STMT_CRPROC SQL_RDM_STMT_DRPROC SQL_RDM_STMT_EXECUTE SQL_RDM_STMT_SET SQL_RDM_STMT_SETCOLUMN SQL_RDM_STMT_LOCK SQL_RDM_STMT_UNLOCK SQL_RDM_STMT_INITDB SQL_RDM_STMT_CRCAT SQL_RDM_STMT_IMPORT SQL_RDM_STMT_EXPORT SQL_RDM_STMT_DDL RDM ODBC API Reference 57 . This function was called before the statement was prepared. Comments The following table describes the types of SQL statements executed and the corresponding values of the statement type returned to this function through pStmtType.RDMe ODBC API Reference Guide passed for an argument that requires a connection handle. Diagnostics SQLSTATE HY009 HY010 Error Invalid use of null pointer Function sequence error Description A null pointer was specified for the pStmtType argument. RDMe ODBC API Reference Guide [1]Any of the DDL statements supported by RDM. such as CREATE DATABASE and CREATE TABLE. RDM ODBC API Reference 58 . returns SQL_RDM_STMT_DDL. This code is returned only when the handle is a null pointer or is the wrong type. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. or descriptor handle. such as when a statement handle is 59 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference .RDMe ODBC API Reference Guide SQLDisconnect Closes the connection associated with a specified handle Conformance Version Introduced: ODBC 1. This indicates a programming error. The application calls SQLGetDiagField to retrieve additional information from the header record. Function completed successfully.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDisconnect(         SQLHDBC          ConnectionHandle) Arguments ConnectionHandle     (input) Connection handle. Required Headers #include "sql. possibly with a nonfatal error (warning). The contents of any output arguments to the function are undefined. connection. statement. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Function failed due to an invalid environment. Function failed. RDM ODBC API Reference 60 . For more information.RDMe ODBC API Reference Guide passed for an argument that requires a connection handle. reference MSDN documentation for SQLDisconnect. 0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDriverConnect(         SQLHDBC          ConnectionHandle.         const SQLCHAR   *InConnectionString.         SQLCHAR         *OutConnectionString.         SQLSMALLINT     *StringLength2Ptr. or an empty string. If the number of characters available to return is greater than or equal to BufferLength. a partial connection string. Length of the *OutConnectionString buffer. in characters if the string is Unicode. Length of *InConnectionString.024 characters for this buffer. Upon successful connection to the target data source. the completed connection string in *OutConnectionString is truncated to BufferLength minus the length of a null-termination character. Conformance Version Introduced: ODBC 1.         SQLUSMALLINT     DriverCompletion) Arguments ConnectionHandle     (input) WindowHandle (input) InConnectionString (input) StringLength1 (input) Connection handle. Applications should allocate at least 1.         SQLHWND          WindowHandle.RDMe ODBC API Reference Guide SQLDriverConnect Establishes connections to RDM databases via RDM ODBC. Accepts more connection options than SQLConnect. or bytes if string is ANSI or DBCS. Pointer to a buffer in which to return the total number of characters (excluding the null-termination character) available to return in *OutConnectionString. in characters. Flag that indicates whether the Driver Manager or driver must prompt for more connection information OutConnectionString (output) BufferLength StringLength2Ptr (input) (output) DriverCompletion (input) Required Headers #include "sqlext. Window handle. A full connection string (see the syntax in "Comments").         SQLSMALLINT      StringLength1.h" RDM ODBC API Reference 61 .         SQLSMALLINT      BufferLength. this buffer contains the completed connection string. Pointer to a buffer for the completed connection string. If TFS is specified. This indicates a programming error. Function completed successfully. Function failed. This keyword should be specified instead of DSN when an application attempts to specify our driver with the DRIVER keyword through the Microsoft ODBC DM. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The value of this keyword is ignored if the application is linked directly with the RDM ODBC Driver. The application calls SQLGetDiagField to retrieve additional information from the header record. Function failed due to an invalid environment. Name of the TFServer. Keyword DSN Attribute Value Description When the application accesses the RDM ODBC Driver through Microsoft ODBC Driver Manager (DM). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. possibly with a nonfatal error (warning). Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. This code is returned only when the handle is a null pointer or is the wrong type. RDM will use its default remote server name ("localhost"). SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA Comments InConnectionString RDM accepts the following connection string keywords. Name of the remote server. RDM will use the default value (21553). this is the name of an ODBC data source that points to RDM. RDM will use its default TFServer name ("localhost"). or descriptor handle. No additional information is available from SQLGetDiagRec or SQLGetDiagField. 62 PORT TFS[1] REMOST_HOST[1] RDM ODBC API Reference . If REMOTE_HOST is not specified. in which case the DM will remove the DSN keyword from the connection string. such as when a statement handle is passed for an argument that requires a connection handle. connection.RDMe ODBC API Reference Guide Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. TCP/IP port number the TFServer is listening on. statement. No more data was available. If PORT is not specified. RDM ODBC API Reference 63 .RDMe ODBC API Reference Guide Keyword DATABASE Attribute Value Description Name of the database to open upon successful connection to the data source. For more information. reference MSDN documentation for SQLDriverConnect. The handle. possibly with a nonfatal error (warning).h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagField to retrieve additional information from the header record. One of the following two values:  l SQL_COMMIT  l SQL_ROLLBACK     Required Headers #include "sql. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully.      SQLHANDLE     Handle. of the type indicated by HandleType.RDMe ODBC API Reference Guide SQLEndTran Requests a commit or rollback for active transactions Conformance Version Introduced: ODBC 3. 64 RDM ODBC API Reference . The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function completed successfully. indicating the scope of the transaction.      SQLSMALLINT   CompletionType) Arguments HandleType     Handle CompletionType (input) (input) (input) Handle type identifier.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLEndTran(      SQLSMALLINT   HandleType. Contains either SQL_HANDLE_ENV (if Handle is an environment handle) or SQL_HANDLE_DBC (if Handle is a connection handle). This code is returned only when the handle is a null pointer or is the wrong type. connection. reference MSDN documentation for SQLEndTran. Function failed due to an invalid environment. RDM ODBC API Reference 65 . or descriptor handle. statement. This indicates a programming error.RDMe ODBC API Reference Guide SQL_ERROR Function failed. such as when a statement handle is passed for an argument that requires a connection handle. SQL_INVALID_HANDLE For more information. No additional information is available from SQLGetDiagRec or SQLGetDiagField. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Length of *StatementText in characters. Function completed successfully. possibly with a nonfatal error (warning).h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. or 66 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . The application calls SQLGetDiagField to retrieve additional information from the header record. statement. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.         const SQLCHAR   *StatementText.         SQLINTEGER       TextLength) Arguments StatementHandle     (input) StatementText (input) TextLength (input) Statement handle. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully.RDMe ODBC API Reference Guide SQLExecDirect Prepares and executes an SQL statement Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLExecDirect(         SQLHSTMT         StatementHandle. SQL statement to be executed. Function failed. The contents of any output arguments to the function are undefined. Required Headers #include "sql. Function failed due to an invalid environment. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. connection. This code is returned only when the handle is a null pointer or is the wrong type. More data is needed. SQL_NEED_DATA SQL_NO_DATA For more information. This indicates a programming error.RDMe ODBC API Reference Guide descriptor handle. No additional information is available from SQLGetDiagRec or SQLGetDiagField. such as when parameter data is sent at execution time or additional connection information is required. reference MSDN documentation for SQLExecDirect. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. No more data was available. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. RDM ODBC API Reference 67 . such as when a statement handle is passed for an argument that requires a connection handle. if any. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. No additional information is available from SQLGetDiagRec or SQLGetDiagField. The contents of any output arguments to the function are undefined.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLExecute(      SQLHSTMT     StatementHandle). Function completed successfully. or descriptor handle. This indicates a programming error. Function failed due to an invalid environment. such as when a statement handle is 68 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . The application calls SQLGetDiagField to retrieve additional information from the header record. possibly with a nonfatal error (warning).RDMe ODBC API Reference Guide SQLExecute Executes a previously prepared SQL statement Conformance Version Introduced: ODBC 1. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Arguments StatementHandle     (input) Statement handle. This code is returned only when the handle is a null pointer or is the wrong type. Required Headers #include "sql. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. statement. Function failed. connection. reference MSDN documentation for SQLExecute. RDM ODBC API Reference 69 .RDMe ODBC API Reference Guide passed for an argument that requires a connection handle. such as when parameter data is sent at execution time or additional connection information is required. No more data was available. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. More data is needed. SQL_NEED_DATA SQL_NO_DATA For more information. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. if any. this parameter is ignored. The length of TransactionID in characters.  l SQL_FALSE   Transaction is read-write If OperationType is not SQL_START or SQL_COMMIT. of the type indicated by HandleType.     SQLSMALLINT      TransType. TransactionID is required with SQL_SAVEPOINT and SQL_RELEASE. this parameter is ignored. indicating the scope of the transaction.     const SQLCHAR   *TransactionID. an internal system value will be used. The handle.     SQLSMALLINT      StringLengthPtr)  Arguments HandleType Handle OperationType (input) (input) (input) Handle type identifier. as follows:  l SQL_TRUE   Transaction is read-only. TransactionID (input) StringLengthPtr (input) RDM ODBC API Reference 70 . Contains either SQL_HANDLE_ENV (if Handle is an environment handle) or SQL_HANDLE_DBC (if Handle is a connection handle). SQL_NTS can be used to indicate that TransactionID is null-terminated. Character string that indicates the unique ID of the transaction operation. If Operation Code is SQL_COMMIT. If TransactionID is not specified with SQL_START. One of the following operation types:  l SQL_START   -Start a transaction  l SQL_SAVEPOINT -Create a save point in a transaction  l SQL_RELEASE Release a save point in a transaction  l SQL_COMMIT -Commit a transaction ReadOnly (input)  l SQL_ROLLBACK -Rollback a transaction  Read-only mode.RDMe ODBC API Reference Guide SQLExtendedTran Performs a transaction operation Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQL_API SQLExtendedTran(     SQLSMALLINT      HandleType.     SQLSMALLINT      ReadOnly.     SQLHANDLE        Handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment. statement. The application calls SQLGetDiagField to retrieve additional information from the header record. SQL_SAVEPOINT or SQL_RELEASE is specactive ified for OperationType and a read-only transaction is active on the connection associated with Handle. or descriptor handle. Transaction state unknown When HandleType is SQL_HANDLE_ENV and one or more of the connections in Handle failed to complete the transaction. Transaction already active SQL_START is specified for OperationType and a transaction is already active on the connection associated with Handle. Memory allocation error Either the ODBC driver or the SQL engine failed to allocate sufficient memory to complete the required operation. connection. The contents of any output arguments to the function are undefined. possibly with a nonfatal error (warning). The function returns SQL_SUCCESS_WITH_INFO. Read-only transaction already SQL_START. Function failed. Connection not open The RDM ODBC driver is not connected to a data source. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. SQL_ERROR SQL_INVALID_HANDLE Diagnostics SQLSTATE 01000 08003 25000 Error General warning Description General error returned from the RDM ODBC driver. This code is returned only when the handle is a null pointer or is the wrong type. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Function sequence error This function was called after SQLExecute or SQLEx71 25001 25S01 HY001 HY010 RDM ODBC API Reference .RDMe ODBC API Reference Guide Required Headers #include "sqlrext. such as when a statement handle is passed for an argument that requires a connection handle. This indicates a programming error.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Function completed successfully. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. An application can roll back the database changes that are made after the save point by calling SQLExtendedTran with SQL_ROLLBACK and the ID that matches the one associated with the save point. If NULL or an empty string is specified for the TransactionID parameter. and roll back to the last save point. An application must specify a unique ID of the save point using the TransactionID parameter. An application can manually release. An application can optionally specify the unique ID of the transaction by using the TransactionID parameter. The value in OperationType is not one of the following: HY012 Invalid transaction operation code HY013 HY092  l SQL_START  l SQL_SAVEPOINT  l SQL_RELEASE  l SQL_COMMIT  l SQL_ROLLBACK Memory management error The RDM SQL engine failed to allocate sufficient memory to complete the required operation. Invalid attribute/option identifier The value in HandleType is not one of the following values:  l SQL_HANDLE_ENV  l SQL_HANDLE_DBC Comments SQLExtendedTran allows an RDM ODBC application to start a transaction. as well as committing and rolling back a transaction. an internal system ID will be used Creating a save point SQLExtendedTran can be used to create a save point in the current readwrite transaction. A call to SQLEndTran to either commit or abort the current transaction will automatically release all save points. All save points created after the specified save point will be released. An application can roll back a transaction to a particular save point by calling SQLExtendedTran specifying SQL_ROLLBACK for OperationType and the ID associated with the save point. any of the save points it created by calling SQLExtendedTran specifying SQL_RELEASE for OperationType and the ID associated with the save point. Starting a transaction SQLExtendedTran can be called to start a regular ("read-write") transaction or a "read-only" transaction. All save points inside the Releasing a save point Rolling back to a save point Committing a transaction RDM ODBC API Reference 72 . To start a read-only transaction. The value specified for the ReadOnly parameter determines the type of transaction to start. the entire transaction will be aborted. A call to SQLExtendedTran to roll back to a save point will automatically release all the save points created after that save point. An application can commit all changes in a transaction by calling SQLEndTran or SQLExtendedTran specifying SQL_COMMIT. specify SQL_TRUE for the ReadOnly parameter. create a save point inside the current transaction. or discard. If the specified ID is not associated with any existing save point.RDMe ODBC API Reference Guide ecDirect but before all the parameters were bound. Aborting a transaction An application can abort an entire transaction by calling SQLEndTran or SQLExtendedTran specifying SQL_ROLLBACK.RDMe ODBC API Reference Guide transaction will be released. If no transaction is active. If no transaction is active. For SQLExtendedTran. All save points inside the transaction will be released. SQL_ SUCCESS will be returned. RDM ODBC API Reference 73 . specify NULL or the ID of the transaction itself for TransactionID. SQL_SUCCESS will be returned. h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLFetch(      SQLHSTMT     StatementHandle). This indicates a programming error. connection. statement. such as when a statement handle is 74 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . Function completed successfully. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed. Function failed due to an invalid environment. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. Arguments StatementHandle     (input) Statement handle. Required Headers #include "sql. This code is returned only when the handle is a null pointer or is the wrong type. possibly with a nonfatal error (warning).RDMe ODBC API Reference Guide SQLFetch Fetches data from a bound column to an application variable Conformance Version Introduced: ODBC 1. The contents of any output arguments to the function are undefined. or descriptor handle. The application calls SQLGetDiagField to retrieve additional information from the header record. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. No additional information is available from SQLGetDiagRec or SQLGetDiagField. RDMe ODBC API Reference Guide passed for an argument that requires a connection handle. For more information. reference MSDN documentation for SQLFetch. RDM ODBC API Reference 75 . RDMe ODBC API Reference Guide SQLFetchScroll Fetches the specified rowset of data from the result set and returns data for all bound columns. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLFetchScroll(       SQLHSTMT      StatementHandle,       SQLSMALLINT   FetchOrientation,       SQLLEN        FetchOffset); Arguments StatementHandle     (input) FetchOrientation (input) Statement handle. Type of fetch:  l SQL_FETCH_NEXT  l SQL_FETCH_PRIOR  l SQL_FETCH_FIRST  l SQL_FETCH_LAST  l SQL_FETCH_ABSOLUTE  l SQL_FETCH_RELATIVE FetchOffset (input)  l SQL_FETCH_BOOKMARK Number of the row to fetch. The interpretation of this argument depends on the value of the FetchOrientation argument. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code RDM ODBC API Reference Description 76 RDMe ODBC API Reference Guide SQL_SUCCESS SQL_SUCCESS_WITH_INFO Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. Function completed successfully, possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Function failed due to an invalid environment, connection, statement, or descriptor handle. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is passed for an argument that requires a connection handle. No more data was available. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA Comments Cursor Support SQLFetchScroll in RDM ODBC currently only supports the forward-only cursor. Therefore, the only accepted value for the FetchOrientation parameter is SQL_FETCH_NEXT. Specifying any other fetch type for FetchOrientation will result in the "Fetch type out of range" (SQLSTATE HY106) error. The value specified for the FetchOffset parameter is ignored. For more information, reference MSDN documentation for SQLFetchScroll. RDM ODBC API Reference 77 RDMe ODBC API Reference Guide SQLForeignKeys SQLForeignKeys can return:  l A list of foreign keys in the specified table (columns in the specified table that refer to primary keys in other  tables).  l A list of foreign keys in other tables that refer to the primary key in the specified table. The driver returns each list as a result set on the specified statement. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLForeignKeys(      SQLHSTMT       StatementHandle,      SQLCHAR *      PKCatalogName,      SQLSMALLINT    NameLength1,      SQLCHAR *      PKSchemaName,      SQLSMALLINT    NameLength2,      SQLCHAR *      PKTableName,      SQLSMALLINT    NameLength3,      SQLCHAR *      FKCatalogName,      SQLSMALLINT    NameLength4,      SQLCHAR *      FKSchemaName,      SQLSMALLINT    NameLength5,      SQLCHAR *      FKTableName,      SQLSMALLINT    NameLength6); Arguments StatementHandle     (input) PKCatalogName (input) NameLength1 PKSchemaName NameLength2 PKTableName NameLength3 FKCatalogName NameLength4 FKSchemaName NameLength5 FKTableName (input) (input) (input) (input) (input) (input) (input) (input) (input) (input) Statement handle. Primary key table catalog name. PKCatalogName cannot contain a string search pattern. Length of *PKCatalogName, in characters. Primary key table schema name. PKSchemaName cannot contain a string search pattern. Length of *PKSchemaName, in characters. Primary key table name. PKTableName cannot contain a string search pattern. Length of *PKTableName, in characters. Foreign key table catalog name. FKCatalogName cannot contain a string search pattern. Length of *FKCatalogName, in characters. Foreign key table schema name. FKSchemaName cannot contain a string search pattern. Length of *FKSchemaName, in characters. Foreign key table name. FKTableName cannot contain a string search pattern. RDM ODBC API Reference 78 SQLForeignKeys returns an empty result set. statement. possibly with a nonfatal error (warning). such as when a statement handle is passed for an argument that requires a connection handle. This indicates a programming error. reference MSDN documentation for SQLForeignKeys. For more information. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. RDM ODBC API Reference 79 . The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. connection. Required Headers #include "sqlext. Function completed successfully. Function failed due to an invalid environment. SQL_ERROR SQL_INVALID_HANDLE Comments SQLForeignKeys returns the information that pertains to the databases that are currently open. This code is returned only when the handle is a null pointer or is the wrong type. The application calls SQLGetDiagField to retrieve additional information from the header record. or descriptor handle. No additional information is available from SQLGetDiagRec or SQLGetDiagField.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. If no database is open on the data source. The contents of any output arguments to the function are undefined. Function failed. in characters. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.RDMe ODBC API Reference Guide NameLength6 (input) Length of *FKTableName. or descriptor handle. statement. Returns Return Code SQL_SUCCESS SQL_ERROR RDM ODBC API Reference Description Function completed successfully.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The handle to be freed. Function failed. Handle (input) Required Headers #include "sql.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLFreeHandle(      SQLSMALLINT   HandleType. connection. Arguments HandleType     (input) The type of handle to be freed by SQLFreeHandle. The application calls SQLGetDiagRec or SQLGet80 . SQLFreeHandle returns SQL_ INVALID_HANDLE. Conformance Version Introduced: ODBC 3. Must be one of the following values:  l SQL_HANDLE_DBC  l SQL_HANDLE_DESC  l SQL_HANDLE_ENV  l SQL_HANDLE_STMT If HandleType is not one of these values.RDMe ODBC API Reference Guide SQLFreeHandle Frees resources associated with a specific environment. The application calls SQLGetDiagField to retrieve additional information from the header record.      SQLHANDLE     Handle). This code is returned only when the handle is a null pointer or is the wrong type. The contents of any output arguments to the function are undefined. or descriptor handle. statement. RDM ODBC API Reference 81 . connection. such as when a statement handle is passed for an argument that requires a connection handle. reference MSDN documentation for SQLFreeHandle.RDMe ODBC API Reference Guide DiagField to retrieve additional information. No additional information is available from SQLGetDiagRec or SQLGetDiagField. SQL_INVALID_HANDLE For more information. Function failed due to an invalid environment. This indicates a programming error. RDMe ODBC API Reference Guide SQLFreeStmt Stops processing associated with a specific statement. or. If this operation is performed on an explicitly allocated descriptor that is shared by more than one statement. discards pending results. SQLCloseCursor can also be called to close a cursor.      SQLUSMALLINT   Option). this option has no effect for the application. the operation will affect the bindings of all statements that share the descriptor. optionally. this operation will affect the bindings of all the statements that share the descriptor.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLFreeStmt(      SQLHSTMT       StatementHandle. see Closing the Cursor. Arguments StatementHandle     (input) Option (input) Statement handle. closes any open cursors associated with the statement. One of the following options: SQL_ CLOSE: Closes the cursor associated with StatementHandle (if one was defined) and discards all pending results. RDM ODBC API Reference 82 . If no cursor is open. The application can reopen this cursor later by executing a SELECT statement again with the same or different parameter values. A call to SQLFreeStmt with an Option of SQL_DROP is mapped in the Driver Manager to SQLFreeHandle. For more information. to do that. SQL_RESET_PARAMS: Sets the SQL_DESC_COUNT field of the APD to 0. SQL_DROP: This option is deprecated. SQL_UNBIND: Sets the SQL_DESC_COUNT field of the ARD to 0. the SQL_DESC_DATA_PTR field of the ARD for the bookmark column is set to NULL. Notice that if this operation is performed on an explicitly allocated descriptor that is shared by more than one statement. Conformance Version Introduced: ODBC 1. frees all resources associated with the statement handle. This does not unbind the bookmark column. releasing all parameter buffers set by SQLBindParameter for the given StatementHandle. releasing all column buffers bound by SQLBindCol for the given StatementHandle. or descriptor handle. possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. This indicates a programming error. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. RDM ODBC API Reference 83 . Function failed due to an invalid environment. The contents of any output arguments to the function are undefined. statement.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagField to retrieve additional information from the header record. connection. Function completed successfully. such as when a statement handle is passed for an argument that requires a connection handle. Function failed. SQL_ERROR SQL_INVALID_HANDLE For more information.RDMe ODBC API Reference Guide Required Headers #include "sql. This code is returned only when the handle is a null pointer or is the wrong type. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. reference MSDN documentation for SQLFreeStmt. No additional information is available from SQLGetDiagRec or SQLGetDiagField. A pointer to a buffer in which to return the total number of bytes (excluding the nulltermination character) available to return in *ValuePtr.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetConnectAttr(      SQLHDBC        ConnectionHandle.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.      SQLINTEGER     Attribute. A pointer to memory in which to return the current value of the attribute specified by Attribute. this argument should be the length of *ValuePtr. the data in *ValuePtr is truncated to BufferLength minus the length of the null-termination character and is null-terminated by the driver. Conformance Version Introduced: ODBC 3. If *ValuePtr is a null pointer.RDMe ODBC API Reference Guide SQLGetConnectAttr Returns the current setting of a connection attribute.      SQLPOINTER     ValuePtr. no length is returned. StringLengthPtr (output) Required Headers #include "sql. Arguments ConnectionHandle     (input) Attribute (input) ValuePtr (output) BufferLength (input) Connection handle. If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer.      SQLINTEGER *   StringLengthPtr). If Attribute is an ODBC-defined attribute and *ValuePtr is an integer. If the attribute value is a character string and the number of bytes available to return is greater than BufferLength minus the length of the null-termination character. Attribute to retrieve. RDM ODBC API Reference 84 .      SQLINTEGER     BufferLength. BufferLength is ignored. Function failed. such as when a statement handle is passed for an argument that requires a connection handle. connection. SQL_ERROR SQL_INVALID_HANDLE Comments The attributes accepted by SQLGetConnectAttr are listed under SQLSetConnectAttr. This indicates a programming error. Function failed due to an invalid environment. The application calls SQLGetDiagField to retrieve additional information from the header record. The contents of any output arguments to the function are undefined. No additional information is available from SQLGetDiagRec or SQLGetDiagField. reference MSDN documentation for SQLGetConnectAttr. RDM ODBC API Reference 85 . statement. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. This code is returned only when the handle is a null pointer or is the wrong type. For more information. possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function completed successfully. or descriptor handle.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. Pointer to a buffer in which to return the cursor name.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetCursorName(      SQLHSTMT        StatementHandle.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagRec or SQLGet- SQL_ERROR RDM ODBC API Reference 86 . Function completed successfully.      SQLCHAR *       CursorName. Pointer to memory in which to return the total number of characters (excluding the null-termination character) available to return in *CursorName. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Required Headers #include "sql. Length of *CursorName. Arguments StatementHandle     CursorName BufferLenght NameLengthPrt (input) (output) (input) (output) Statement handle. possibly with a nonfatal error (warning). Function failed. in characters.RDMe ODBC API Reference Guide SQLGetCursorName Retrieves the cursor name of an SQL statement handle Conformance Version Introduced: ODBC 1.      SQLSMALLINT     BufferLength.      SQLSMALLINT *   NameLengthPtr). reference MSDN documentation for SQLGetCursorName. connection. SQL_INVALID_HANDLE For more information. RDM ODBC API Reference 87 . such as when a statement handle is passed for an argument that requires a connection handle. The contents of any output arguments to the function are undefined. or descriptor handle. This code is returned only when the handle is a null pointer or is the wrong type. statement. This indicates a programming error. Function failed due to an invalid environment.RDMe ODBC API Reference Guide DiagField to retrieve additional information. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Pointer to the buffer in which to return the length or indicator value. For a list of valid C data types and type identifiers Pointer to the buffer in which to return the data. which starts at 1. This returns an error when the data being fetched is NULL. The bookmark column is column number 0. Arguments StatementHandle     (input) Col_or_Param_Num (input) Statement handle. It can be called multiple times to retrieve variable-length data in parts. For retrieving column data. The type identifier of the C data type of the *TargetValuePtr buffer.       SQLLEN *       StrLen_or_IndPtr).       SQLPOINTER     TargetValuePtr.       SQLSMALLINT    TargetType. no length or indicator value is returned.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. it is the number of the column for which to return data. RDM ODBC API Reference 88 . If this is a null pointer. Length of the *TargetValuePtr buffer in bytes. Conformance Version Introduced: ODBC 1. this can be specified only if bookmarks are enabled.       SQLLEN         BufferLength. For retrieving parameter data.       SQLUSMALLINT   Col_or_Param_Num. it is the ordinal of the parameter.RDMe ODBC API Reference Guide SQLGetData Retrieves data for a single column in the result set. Result set columns are numbered in increasing column order starting at 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetData(       SQLHSTMT       StatementHandle. TargetType (input) TargetValuePrt (output) BufferLength (input) StrLen_or_IndPtr (output) Required Headers #include "sql. This code is returned only when the handle is a null pointer or is the wrong type. Function completed successfully. or descriptor handle. such as when a statement handle is passed for an argument that requires a connection handle. The application calls SQLGetDiagField to retrieve additional information from the header record. No additional information is available from SQLGetDiagRec or SQLGetDiagField. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. RDM ODBC API Reference 89 . possibly with a nonfatal error (warning). Function failed due to an invalid environment. reference MSDN documentation for SQLGetData. connection. This indicates a programming error.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. SQL_ERROR SQL_INVALID_HANDLE For more information. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. statement. The contents of any output arguments to the function are undefined. Function failed. 0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDescField(      SQLHDESC        DescriptorHandle.      SQLSMALLINT     RecNumber.      SQLINTEGER *    StringLengthPtr). FieldIdentifier ValuePtr (input) (output) BufferLength (input) StringLengthPtr (output) Required Headers #include "sql.h" RDM ODBC API Reference 90 . If ValuePtr is NULL. Conformance Version Introduced: ODBC 3. RecNumber is ignored. Indicates the descriptor record from which the application seeks information. If FieldIdentifier is an ODBC-defined field and *ValuePtr is an integer. this argument should be the length of *ValuePtr. Pointer to a buffer in which to return the descriptor information. If FieldIdentifier is an ODBC-defined field and ValuePtr points to a character string or a binary buffer.      SQLINTEGER      BufferLength. If the FieldIdentifier argument indicates a header field.      SQLSMALLINT     FieldIdentifier. StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by ValuePtr. If RecNumber is less than or equal to SQL_DESC_COUNT but the row does not contain data for a column or parameter. BufferLength is ignored. Arguments DescriptorHandle     (input) RecNumber (input) Descriptor handle.RDMe ODBC API Reference Guide SQLGetDescField Returns the current setting or value of a single field of a descriptor record. The data type depends on the value of FieldIdentifier.      SQLPOINTER      ValuePtr. Descriptor records are numbered from 0. with record number 0 being the bookmark record. Indicates the field of the descriptor whose value is to be returned. a call to SQLGetDescField will return the default values of the fields. Pointer to the buffer in which to return the total number of bytes (excluding the number of bytes required for the null-termination character) available to return in *ValuePtr. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. or descriptor handle. reference MSDN documentation for SQLGetDescField. Function completed successfully. This indicates a programming error. SQL_ERROR SQL_INVALID_HANDLE For more information. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. This code is returned only when the handle is a null pointer or is the wrong type. possibly with a nonfatal error (warning). connection. No additional information is available from SQLGetDiagRec or SQLGetDiagField. such as when a statement handle is passed for an argument that requires a connection handle. The contents of any output arguments to the function are undefined. Function failed due to an invalid environment. statement. Function failed. RDM ODBC API Reference 91 . The application calls SQLGetDiagField to retrieve additional information from the header record.RDMe ODBC API Reference Guide Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. If the number of characters was greater than or equal to BufferLength. Length of the *Name buffer.       SQLSMALLINT *   StringLengthPtr. A pointer to a buffer in which to return the value of the SQL_DESC_TYPE field for the descriptor record. The RecNumber argument must be less than or equal to the value of SQL_ DESC_COUNT. If RecNumber is less than or equal to SQL_DESC_COUNT but the row does not contain data for a column or parameter. StringLengthPtr will still return the total number of characters (excluding the null-termination character for character data) available to return in the buffer pointed to by Name. and storage of column or parameter data. excluding the null-termination character. a call to SQLGetDescRec will return the default values of the fields.       SQLSMALLINT *   TypePtr. and is null-terminated by the driver.       SQLSMALLINT *   SubTypePtr.       SQLSMALLINT     RecNumber. Descriptor records are numbered from 1. For records whose type is SQL_DATETIME or SQL_INTERVAL. Indicates the descriptor record from which the application seeks information.       SQLSMALLINT *   PrecisionPtr.RDMe ODBC API Reference Guide SQLGetDescRec Returns the current settings or values of multiple fields of a descriptor record.       SQLLEN *        LengthPtr. A pointer to a buffer in which to return the SQL_DESC_NAME field for the descriptor record. If Name is NULL.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDescRec(       SQLHDESC        DescriptorHandle. data type.       SQLSMALLINT     BufferLength. with record number 0 being the bookmark record.       SQLCHAR *       Name. Arguments DescriptorHandle     (input) RecNumber (input) Descriptor handle. the data in *Name is truncated to BufferLength minus the length of a null-termination character. The fields returned describe the name. A pointer to a buffer in which to return the number of characters of data available to return in the *Name buffer. Conformance Version Introduced: ODBC 3. this is a pointer to a buffer in which to return the value of the SQL_DESC_DATETIME_INTERVAL_ Name (output) BufferLength StringLengthPtr (input) (output) TypePtr SubTypePtr (output) (output) RDM ODBC API Reference 92 .       SQLSMALLINT *   NullablePtr).       SQLSMALLINT *   ScalePtr. in characters. Function failed due to an invalid environment.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Function failed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Function completed successfully. RDM ODBC API Reference 93 . connection. such as when a statement handle is passed for an argument that requires a connection handle. A pointer to a buffer in which to return the value of the SQL_DESC_PRECISION field for the descriptor record. SQL_NO_DATA is returned if DescriptorHandle is an IRD handle and the statement is in the prepared or executed state but there was no open cursor associated with it. No more data was available. A pointer to a buffer in which to return the value of the SQL_DESC_NULLABLE field for the descriptor record. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type. LengthPtr PrecisionPtr ScalePtr NullablePtr (output) (output) (output) (output) Required Headers #include "sql. For more information. The application calls SQLGetDiagField to retrieve additional information from the header record. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLGetDescRec. This indicates a programming error. or descriptor handle. A pointer to a buffer in which to return the value of the SQL_DESC_OCTET_ LENGTH field for the descriptor record. possibly with a nonfatal error (warning). SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA SQL_NO_DATA is returned if RecNumber is greater than the current number of descriptor records. statement. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.RDMe ODBC API Reference Guide CODE field. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. A pointer to a buffer in which to return the value of the SQL_DESC_SCALE field for the descriptor record.      SQLSMALLINT *   StringLengthPtr) Arguments HandleType     (input) A handle type identifier that describes the type of handle for which diagnostics are required. it should be more than 0. If DiagIdentifier is an ODBC-defined diagnostic and DiagInfoPtr points to a character string or a binary buffer. BufferLength is ignored. If the number of bytes available to return is greater than or equal to BufferLength. If not. this argument should be the length of *DiagInfoPtr. Indicates the status record from which the application seeks information. StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by DiagInfoPtr. The data type depends on the value of DiagIdentifier. DiagIdentifier DiagInfoPtr (input) (output) BufferLength (input) StringLengthPtr (output) RDM ODBC API Reference 94 . of the type indicated by HandleType. Must be one of the following:  l SQL_HANDLE_ENV  l SQL_HANDLE_DBC  l SQL_HANDLE_STMT Handle RecNumber (input) (input)  l SQL_HANDLE_DESC     A handle for the diagnostic data structure. If the DiagIdentifier argument indicates any field of the diagnostics header. If DiagIdentifier is an ODBC-defined field and *DiagInfoPtr is an integer. Pointer to a buffer in which to return the total number of bytes (excluding the number of bytes required for the null-termination character) available to return in *DiagInfoPtr.      SQLHANDLE       Handle. If DiagInfoPtr is NULL. the text in *DiagInfoPtr is truncated to BufferLength minus the length of a null-termination character. for character data.RDMe ODBC API Reference Guide SQLGetDiagField Retrieves current field value of a status record Conformance Version Introduced: ODBC 3.      SQLSMALLINT     BufferLength. RecNumber is ignored.      SQLSMALLINT     RecNumber. Status records are numbered from 1. Indicates the field of the diagnostic whose value is to be returned. Pointer to a buffer in which to return the diagnostic information.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDiagField(      SQLSMALLINT     HandleType.      SQLPOINTER      DiagInfoPtr.      SQLSMALLINT     DiagIdentifier. No additional information is available from SQLGetDiagRec or SQLGetDiagField.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. SQL_ERROR SQL_INVALID_HANDLE For more information. This code is returned only when the handle is a null pointer or is the wrong type. RDM ODBC API Reference 95 . The contents of any output arguments to the function are undefined. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. possibly with a nonfatal error (warning). Function completed successfully. connection. The application calls SQLGetDiagField to retrieve additional information from the header record. This indicates a programming error. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. Function failed due to an invalid environment. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. such as when a statement handle is passed for an argument that requires a connection handle.RDMe ODBC API Reference Guide Required Headers #include "sql. reference MSDN documentation for SQLGetDiagField. Function failed. or descriptor handle. statement. This information is contained in the SQL_DIAG_MESSAGE_TEXT diagnostic field. This information is contained in the SQL_DIAG_SQLSTATE diagnostic field.      SQLHANDLE       Handle. Pointer to a buffer in which to return the diagnostic message text string.      SQLINTEGER *    NativeErrorPtr. Pointer to a buffer in which to return the total number of characters (excluding the number of characters required for the null-termination character) available to return in *MessageText. Must be one of the following:  l SQL_HANDLE_ENV  l SQL_HANDLE_DBC  l SQL_HANDLE_STMT Handle RecNumber SQLState (input) (input) (output)  l SQL_HANDLE_DESC     A handle for the diagnostic data structure.      SQLSMALLINT     BufferLength.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDiagRec(      SQLSMALLINT     HandleType.      SQLSMALLINT *   TextLengthPtr) Arguments HandleType     (input) A handle type identifier that describes the type of handle for which diagnostics are required.      SQLSMALLINT     RecNumber. the next three indicate the subclass. Length of the *MessageText buffer in characters. Pointer to a buffer in which to return a five-character SQLSTATE code (and terminating NULL) for the diagnostic record RecNumber. This information is contained in the SQL_DIAG_NATIVE diagnostic field. Indicates the status record from which the application seeks information. NativeErrorPtr MessageText BufferLength TextLengthPtr (output) (output) (input) (output) RDM ODBC API Reference 96 .RDMe ODBC API Reference Guide SQLGetDiagRec Retrieves current values of several common fields of a status record Conformance Version Introduced: ODBC 3.      SQLCHAR *       MessageText. Status records are numbered from 1. The first two characters indicate the class. If the number of characters available to return is greater than BufferLength. of the type indicated by HandleType. Pointer to a buffer in which to return the native error code. the diagnostic message text in *MessageText is truncated to BufferLength minus the length of a null-termination character. specific to the data source.      SQLCHAR *       SQLState. There is no maximum length of the diagnostic message text. This code is returned only when the handle is a null pointer or is the wrong type. statement. such as when a statement handle is passed for an argument that requires a connection handle. This indicates a programming error. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. No additional information is available from SQLGetDiagRec or SQLGetDiagField. possibly with a nonfatal error (warning).h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Function failed due to an invalid environment. The contents of any output arguments to the function are undefined. SQL_ERROR SQL_INVALID_HANDLE For more information. The application calls SQLGetDiagField to retrieve additional information from the header record. connection. or descriptor handle.RDMe ODBC API Reference Guide Required Headers #include "sql. Function failed. reference MSDN documentation for SQLGetDiagRec. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function completed successfully. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. RDM ODBC API Reference 97 . A pointer to a buffer in which to return the total number of bytes (excluding the nulltermination character) available to return in *ValuePtr. Pointer to a buffer in which to return the current value of the attribute specified by Attribute. BufferLength is unused. StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by ValuePtr. If ValuePtr is a null pointer.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.      SQLINTEGER *   StringLengthPtr) Arguments EnvironmentHandle   (input)   Attribute (input) ValuePtr (output) Environment handle. this argument should be the length of *ValuePtr. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetEnvAttr(      SQLHENV        EnvironmentHandle. the data in *ValuePtr is truncated to BufferLength minus the length of a null-termination character and is null-terminated by the driver. If *ValuePtr is an integer. If ValuePtr points to a character string. BufferLength (input) StringLengthPtr (output) Required Headers #include "sql.      SQLINTEGER     BufferLength. RDM ODBC API Reference 98 . no length is returned.      SQLPOINTER     ValuePtr. BufferLength is ignored.RDMe ODBC API Reference Guide SQLGetEnvAttr Returns the current setting of an environment attribute. Attribute to retrieve.      SQLINTEGER     Attribute. If the attribute value is a character string and the number of bytes available to return is greater than or equal to BufferLength. If ValuePtr is NULL. If the attribute value is not a character string. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type. SQL_ERROR SQL_INVALID_HANDLE Comments The attributes accepted by SQLGetEnvAttr are listed under SQLSetEnvAttr. This indicates a programming error. Function completed successfully. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLGetEnvAttr. statement. such as when a statement handle is passed for an argument that requires a connection handle. connection. Function failed. For more information. The contents of any output arguments to the function are undefined. The application calls SQLGetDiagField to retrieve additional information from the header record. RDM ODBC API Reference 99 . possibly with a nonfatal error (warning). or descriptor handle. Function failed. possibly with a nonfatal error (warning). Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. Conformance Version Introduced: ODBC 1. SQL_API_ODBC3_ ALL_FUNCTIONS or SQL_API_ALL_FUNCTIONS. If FunctionId identifies a single ODBC function. and SQL_FALSE if it is not supported. Function completed successfully.RDMe ODBC API Reference Guide SQLGetFunctions Returns information about whether a driver supports a specific ODBC function. The application calls SQLGetDiagField to retrieve additional information from the header record. Required Headers #include "sql. The application calls SQLGetDiagRec or SQLGet- SQL_ERROR RDM ODBC API Reference 100 .0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetFunctions(      SQLHDBC           ConnectionHandle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.      SQLUSMALLINT *    SupportedPtr) Arguments ConnectionHandle     (input) FunctionId (input) SupportedPtr (output) Connection handle. SupportedPtr points to a single SQLUSMALLINT value that is SQL_TRUE if the specified function is supported by the driver.      SQLUSMALLINT      FunctionId. A #define value that identifies the ODBC function of interest. such as when a statement handle is passed for an argument that requires a connection handle. The contents of any output arguments to the function are undefined. RDM ODBC API Reference 101 .RDMe ODBC API Reference Guide DiagField to retrieve additional information. statement. or descriptor handle. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type. Function failed due to an invalid environment. SQL_INVALID_HANDLE For more information. This indicates a programming error. connection. reference MSDN documentation for SQLGetFunctions.      SQLSMALLINT *   StringLengthPtr) Arguments ConnectionHandle     (input) InfoType (input) InfoValuePtr (output) Connection handle. BufferLength (input) StringLengthPtr (output) RDM ODBC API Reference 102 . the information returned will be one of the following: a null-terminated character string.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetInfo(      SQLHDBC         ConnectionHandle. If the value in *InfoValuePtr is not a character string or if InfoValuePtr is a null pointer. If the InfoType argument is SQL_DRIVER_HDESC or SQL_DRIVER_HSTMT. or a SQLUINTEGER binary value. For all other types of data. an SQLUINTEGER bitmask. depending on the InfoType. based on the InfoType. an SQLUINTEGER flag.      SQLUSMALLINT    InfoType. Type of information. an SQLUSMALLINT value. the InfoValuePtr argument is both input and output. For character data. Conformance Version Introduced: ODBC 1.the BufferLength argument is ignored. if the number of bytes available to return is greater than or equal to BufferLength. Pointer to a buffer in which to return the information.      SQLSMALLINT     BufferLength. Depending on the InfoType requested.      SQLPOINTER      InfoValuePtr. Length of the *InfoValuePtr buffer.) If InfoValuePtr is NULL. the information in *InfoValuePtr is truncated to BufferLength bytes minus the length of a null-termination character and is null-terminated by the driver.RDMe ODBC API Reference Guide SQLGetInfo Returns general information about the driver and data source associated with a connection. the value of BufferLength is ignored and the driver assumes the size of *InfoValuePtr is SQLUSMALLINT or SQLUINTEGER. Pointer to a buffer in which to return the total number of bytes (excluding the null-termination character for character data) available to return in *InfoValuePtr. The driver assumes that the size of *InfoValuePtr is SQLUSMALLINT or SQLUINTEGER. (See the SQL_DRIVER_ HDESC or SQL_DRIVER_HSTMT descriptors later in this function description for more information. StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by InfoValuePtr. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. statement. possibly with a nonfatal error (warning). Function failed. This code is returned only when the handle is a null pointer or is the wrong type. Function completed successfully. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully.RDMe ODBC API Reference Guide Required Headers #include "sql. No additional information is available from SQLGetDiagRec or SQLGetDiagField. or descriptor handle. RDM ODBC API Reference 103 . Function failed due to an invalid environment. The application calls SQLGetDiagField to retrieve additional information from the header record. connection. reference MSDN documentation for SQLGetInfo. SQL_ERROR SQL_INVALID_HANDLE For more information. The contents of any output arguments to the function are undefined. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. such as when a statement handle is passed for an argument that requires a connection handle. This indicates a programming error. 0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetStmtAttr(      SQLHSTMT        StatementHandle.      SQLPOINTER      ValuePtr. no length is returned. If Attribute is an ODBC-defined attribute and *ValuePtr is an integer. If ValuePtr is NULL.RDMe ODBC API Reference Guide SQLGetStmtAttr Returns the current setting of a statement attribute. this argument should be the length of *ValuePtr. the data in *ValuePtr is truncated to BufferLength minus the length of a null-termination character and is null-terminated by the driver. Conformance Version Introduced: ODBC 3. If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. BufferLength (input) StringLengthPtr (output) Required Headers #include "sql. Pointer to a buffer in which to return the value of the attribute specified in Attribute.      SQLINTEGER *    StringLengthPtr) Arguments StatementHandle     (input) Attribute (input) ValuePtr (output) Statement handle. If ValuePtr is a null pointer. BufferLength is ignored A pointer to a buffer in which to return the total number of bytes (excluding the nulltermination character) available to return in *ValuePtr.      SQLINTEGER      Attribute. and the number of bytes available to return is greater than or equal to BufferLength. If the attribute value is a character string. Attribute to retrieve. RDM ODBC API Reference 104 .      SQLINTEGER      BufferLength. StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by ValuePtr. This code is returned only when the handle is a null pointer or is the wrong type. or descriptor handle. SQL_ERROR SQL_INVALID_HANDLE Comments The attributes accepted by SQLGetStmtAttr are listed under SQLSetStmtAttr.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. Function completed successfully. connection. RDM ODBC API Reference 105 . The contents of any output arguments to the function are undefined. Function failed. This indicates a programming error. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. statement. The application calls SQLGetDiagField to retrieve additional information from the header record. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Function failed due to an invalid environment. possibly with a nonfatal error (warning). such as when a statement handle is passed for an argument that requires a connection handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLGetStmtAttr. For more information. or descriptor handle. Conformance Version Introduced: ODBC 1. This indicates a programming error. connection. The application calls SQLGetDiagField to retrieve additional information from the header record.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Function failed. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. Required Headers #include "sql. The SQL data type. possibly with a nonfatal error (warning). statement.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetTypeInfo(      SQLHSTMT      StatementHandle. No additional information is available from SQLGetDiagRec or SQLGet106 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.      SQLSMALLINT   DataType) Arguments StatementHandle     (input) DataType (input) Statement handle.RDMe ODBC API Reference Guide SQLGetTypeInfo Returns information about data types supported by the data source. Function failed due to an invalid environment. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function completed successfully. The contents of any output arguments to the function are undefined. This code is returned only when the handle is a null pointer or is the wrong type. such as when a statement handle is passed for an argument that requires a connection handle.RDMe ODBC API Reference Guide DiagField. reference MSDN documentation for SQLGetTypeInfo. RDM ODBC API Reference 107 . For more information. RDMe ODBC API Reference Guide SQLMoreResults Determines whether more results are available on a statement containing SELECT. The contents of any output arguments to the function are undefined. INSERT. connection. or descriptor handle. or DELETE statements and. Function completed successfully. Function failed. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. UPDATE. initializes processing for those results. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. if so.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLMoreResults(      SQLHSTMT     StatementHandle) Arguments StatementHandle     (input) Statement handle. Conformance Version Introduced: ODBC 1. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. This indicates a programming error. Function failed due to an invalid environment. Required Headers #include "sqlext. statement. possibly with a nonfatal error (warning). This code is returned only when the handle is a null 108 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . No additional information is available from SQLGetDiagRec or SQLGetDiagField.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDMe ODBC API Reference Guide pointer or is the wrong type. RDM ODBC API Reference 109 . such as when a statement handle is passed for an argument that requires a connection handle. No more data was available. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLMoreResults. SQL_NO_DATA For more information. SQL text string to be translated. SQLNativeSql does not execute the SQL statement. If the number of characters available to return is greater than or equal to BufferLength. If OutStatementText is NULL.      SQLCHAR       *  OutStatementText.      const SQLCHAR *  InStatementText.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLNativeSql(      SQLHDBC          ConnectionHandle.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.      SQLINTEGER       TextLength1. Number of characters in the *OutStatementText buffer. Conformance Version Introduced: ODBC 1. TextLength2Ptr will still return the total number of characters (excluding the null-termination character for character data) available to return in the buffer pointed to by OutStatementText. the translated SQL string in *OutStatementText is truncated to BufferLength minus the length of a null-termination character. Pointer to a buffer in which to return the translated SQL string.RDMe ODBC API Reference Guide SQLNativeSql Returns the SQL string as modified by the driver. BufferLength TextLength2 (input) (output) Required Headers #include "sqlext. Length in characters of *InStatementText text string.      SQLINTEGER       BufferLength.      SQLINTEGER    *  TextLength2Ptr) Arguments ConnectionHandle     (input) InStatementText (input) TextLength1 (input) OutStatementText (output) Connection handle. RDM ODBC API Reference 110 . Pointer to a buffer in which to return the total number of characters (excluding null-termination) available to return in *OutStatementText. or descriptor handle. SQL_ERROR SQL_INVALID_HANDLE For more information. statement. This code is returned only when the handle is a null pointer or is the wrong type. The contents of any output arguments to the function are undefined. possibly with a nonfatal error (warning). No additional information is available from SQLGetDiagRec or SQLGetDiagField. reference MSDN documentation for SQLNativeSql. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. connection. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment. such as when a statement handle is passed for an argument that requires a connection handle.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. This indicates a programming error. The application calls SQLGetDiagField to retrieve additional information from the header record. Function failed. RDM ODBC API Reference 111 . Function completed successfully. No additional information is available from SQLGetDiagRec or SQLGet112 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. This indicates a programming error. statement. Function failed due to an invalid environment. The contents of any output arguments to the function are undefined. or descriptor handle. Required Headers #include "sqlext. Function failed.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. possibly with a nonfatal error (warning). The application calls SQLGetDiagField to retrieve additional information from the header record. Function completed successfully. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. connection.RDMe ODBC API Reference Guide SQLNumParams Determines the number of parameters in a prepared statement Conformance Version Introduced: ODBC 1. Pointer to a buffer in which to return the number of parameters in the statement.      SQLSMALLINT *   ParameterCountPtr) Arguments StatementHandle     (input) ParameterCountPtr (output) Statement handle.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLNumParams(      SQLHSTMT        StatementHandle. such as when a statement handle is passed for an argument that requires a connection handle. This code is returned only when the handle is a null pointer or is the wrong type.RDMe ODBC API Reference Guide DiagField. reference MSDN documentation for SQLNumParams. For more information. RDM ODBC API Reference 113 . possibly with a nonfatal error (warning). Conformance Version Introduced: ODBC 1. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLNumResultCols(      SQLHSTMT        StatementHandle. or descriptor handle. connection.      SQLSMALLINT *   ColumnCountPtr) Arguments StatementHandle     (input) ColumnCountPtr (output) Statement handle. Function failed due to an invalid environment. No additional information is available from SQLGetDiagRec or SQLGet114 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . Pointer to a buffer in which to return the number of columns in the result set. This indicates a programming error. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagField to retrieve additional information from the header record. Function completed successfully. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. statement. The contents of any output arguments to the function are undefined. Function failed.RDMe ODBC API Reference Guide SQLNumResultCols Returns the number of columns in a result set. Required Headers #include "sql. This code is returned only when the handle is a null pointer or is the wrong type. RDM ODBC API Reference 115 . For more information. such as when a statement handle is passed for an argument that requires a connection handle. reference MSDN documentation for SQLNumResultsCol.RDMe ODBC API Reference Guide DiagField. Function failed. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLParamData(      SQLHSTMT       StatementHandle.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Required Headers #include "sql. The application calls SQLGetDiagField to retrieve additional information from the header record. Conformance Version Introduced: ODBC 1. Pointer to a buffer in which to return the address of the ParameterValuePtr buffer specified in SQLBindParameter (for parameter data) or the address of the TargetValuePtr buffer specified in SQLBindCol (for column data). and with SQLGetData to retrieve streamed output parameter data. The contents of any out116 SQL_ERROR RDM ODBC API Reference .RDMe ODBC API Reference Guide SQLParamData SQLParamData is used together with SQLPutData to supply parameter data at statement execution time. possibly with a nonfatal error (warning). Function completed successfully.      SQLPOINTER *   ValuePtrPtr) Arguments StatementHandle     (input) ValuePtrPtr (output) Statement handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. as contained in the SQL_DESC_DATA_PTR descriptor record field. This code is returned only when the handle is a null pointer or is the wrong type. RDM ODBC API Reference 117 . such as when a statement handle is passed for an argument that requires a connection handle. statement.RDMe ODBC API Reference Guide put arguments to the function are undefined. Function failed due to an invalid environment. reference MSDN documentation for SQLParamData. This indicates a programming error. or descriptor handle. No additional information is available from SQLGetDiagRec or SQLGetDiagField. connection. SQL_INVALID_HANDLE For more information. Length of *StatementText in characters. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.RDMe ODBC API Reference Guide SQLPrepare Prepares an SQL string for execution. Required Headers #include "sql. Function failed. or 118 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference .0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLPrepare(      SQLHSTMT      StatementHandle. connection. Function failed due to an invalid environment. Arguments StatementHandle     (input) StatementText (input) TextLength (input) Statement handle. The contents of any output arguments to the function are undefined. Conformance Version Introduced: ODBC 1. Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record.      SQLCHAR *     StatementText.      SQLINTEGER    TextLength).h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. possibly with a nonfatal error (warning). SQL text string. statement. RDMe ODBC API Reference Guide descriptor handle. For more information. RDM ODBC API Reference 119 . No additional information is available from SQLGetDiagRec or SQLGetDiagField. reference MSDN documentation for SQLPrepare. such as when a statement handle is passed for an argument that requires a connection handle. This code is returned only when the handle is a null pointer or is the wrong type. This indicates a programming error.      SQLCHAR *      SchemaName. Length in characters of *CatalogName.      SQLCHAR *      TableName.      SQLSMALLINT    NameLength3). Length in characters of *SchemaName. Returns Return Code RDM ODBC API Reference Description 120 . Arguments StatementHandle     CatalogName NameLength1 SchemaName NameLength2 TableName NameLength3 (input) (input) (input) (input) (input) (input) (input) Statement handle.      SQLCHAR *      CatalogName. This function does not support returning primary keys from multiple tables in a single call.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Required Headers #include "sqlext.RDMe ODBC API Reference Guide SQLPrimaryKeys Returns the column names that make up the primary key for a table. The driver returns the information as a result set. SchemaName cannot contain a string search pattern. Catalog name. Schema name. Length in characters of *TableName. Table name. TableName cannot contain a string search pattern.      SQLSMALLINT    NameLength2.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLPrimaryKeys(      SQLHSTMT       StatementHandle.      SQLSMALLINT    NameLength1. This argument cannot be a null pointer. Conformance Version Introduced: ODBC 1. CatalogName cannot contain a string search pattern. SQL_ERROR SQL_INVALID_HANDLE Comments SQLPrimaryKeys returns the information that pertains to the databases that are currently open.RDMe ODBC API Reference Guide SQL_SUCCESS SQL_SUCCESS_WITH_INFO Function completed successfully. RDM ODBC API Reference 121 . connection. If no database is open on the data source. This indicates a programming error. statement. Function failed. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type. such as when a statement handle is passed for an argument that requires a connection handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLPrimaryKeys. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment. The contents of any output arguments to the function are undefined. For more information. Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. possibly with a nonfatal error (warning). or descriptor handle. SQLPrimaryKeys returns an empty result set.      SQLSMALLINT   NameLength2. String search pattern for procedure names. String search pattern for procedure schema names.      SQLSMALLINT   NameLength3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLProcedureColumns(      SQLHSTMT      StatementHandle. Length in characters of *ProcName.RDMe ODBC API Reference Guide SQLProcedureColumns Returns the parameter and column information about the specified procedures. CatalogName cannot contain a string search pattern. Arguments StatementHandle     CatalogName NameLength1 SchemaName NameLength2 ProcName NameLength3 ColumnName NameLength4 (input) (input) (input) (input) (input) (input) (input) (input) (input) Statement handle.      SQLCHAR *     SchemaName.      SQLSMALLINT   NameLength4). Required Headers #include "sqlext. RDM ODBC API Reference 122 . Conformance Version Introduced: ODBC 1. Length in characters of *SchemaName.      SQLCHAR *     CatalogName.      SQLSMALLINT   NameLength1.      SQLCHAR *     ColumnName. Procedure catalog name. String search pattern for column names.      SQLCHAR *     ProcName. Length in characters of *CatalogName. Length in characters of *ColumnName.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. SQL_ERROR SQL_INVALID_HANDLE Comments SQLProcedureColumns returns the information that pertains to the databases that are currently open. such as when a statement handle is passed for an argument that requires a connection handle. For more information. The contents of any output arguments to the function are undefined. This code is returned only when the handle is a null pointer or is the wrong type. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function completed successfully. connection. Function failed. statement. Function failed due to an invalid environment. If no database is open on the data source. RDM ODBC API Reference 123 . The application calls SQLGetDiagField to retrieve additional information from the header record. This indicates a programming error. reference MSDN documentation for SQLProcedureColumns. SQLProcedureColumns returns an empty result set. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. No additional information is available from SQLGetDiagRec or SQLGetDiagField. possibly with a nonfatal error (warning). or descriptor handle.      SQLCHAR *      ProcName. Procedure is a generic term used to describe an executable object. Required Headers #include "sqlext.      SQLCHAR *      SchemaName.      SQLCHAR *      CatalogName. Procedure catalog.RDMe ODBC API Reference Guide SQLProcedures Returns the list of procedure names stored in a specific data source. Length in characters of *CatalogName.      SQLSMALLINT    NameLength2. String search pattern for procedure names.      SQLSMALLINT    NameLength1. Conformance Version Introduced: ODBC 1. String search pattern for procedure schema names.      SQLSMALLINT    NameLength3).h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS RDM ODBC API Reference Description Function completed successfully. or a named entity that can be invoked using input and output parameters. Length in characters of *ProcName.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLProcedures(      SQLHSTMT       StatementHandle. Length in characters of *SchemaName. Arguments StatementHandle     CatalogName NameLength1 SchemaName NameLength2 ProcName NameLength3 (input) (input) (input) (input) (input) (input) (input) Statement handle. The application calls SQLGet124 . Function failed. RDM ODBC API Reference 125 . The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. connection. No additional information is available from SQLGetDiagRec or SQLGetDiagField. or descriptor handle. If no database is open on the data source. Function failed due to an invalid environment. For more information. such as when a statement handle is passed for an argument that requires a connection handle. SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Comments SQLProcedures returns the information that pertains to the databases that are currently open. reference MSDN documentation for SQLProcedures. SQLProcedures returns an empty result set. possibly with a nonfatal error (warning). This code is returned only when the handle is a null pointer or is the wrong type. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. statement.RDMe ODBC API Reference Guide DiagField to retrieve additional information from the header record. Function completed successfully. This indicates a programming error. Specifies the amount of data sent in a call to SQLPutData. Pointer to a buffer containing the actual data for the parameter or column. parameters of the SQL_LONGVARBINARY or SQL_LONGVARCHAR types). Returns Return Code SQL_SUCCESS Description Function completed successfully.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLPutData(       SQLHSTMT     StatementHandle. Length of *DataPtr.       SQLLEN       StrLen_or_Ind). or data source–specific data type (for example. The application calls SQLGetDiagField to retrieve additional information from the header record.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.RDMe ODBC API Reference Guide SQLPutData Allows an application to send data for a parameter or column to the driver at statement execution time. StrLen_or_Ind (input) Required Headers #include "sql. The data must be in the C data type specified in the ValueType argument of SQLBindParameter (for parameter data) or the TargetType argument of SQLBindCol (for column data).       SQLPOINTER   DataPtr. This function can be used to send character or binary data values in parts to a column with a character. Arguments StatementHandle     (input) DataPtr (input) Statement handle. binary. Conformance Version Introduced: ODBC 1. The amount of data can vary with each call for a given parameter or column. RDM ODBC API Reference 126 . The contents of any output arguments to the function are undefined. or descriptor handle.. Function failed due to an invalid environment. Function failed. SQL_ LONGWVARCHAR and SQL_LONGVARBINARY. SQL_ERROR SQL_INVALID_HANDLE Comments SQLPutData can only be called to insert or update column values. This code is returned only when the handle is a null pointer or is the wrong type. SQLPutData can only be used with columns of the following data types: SQL_LONGVARCHAR. No additional information is available from SQLGetDiagRec or SQLGetDiagField. statement. Calling SQLPutData on a column of any other data type returns a "data-at-exec params only allowed for blob (long var. For more information. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLPutData. such as when a statement handle is passed for an argument that requires a connection handle.. connection. Calling SQLPutData on any other type of SQL statement returns a "data-at-exec params only allowed with INSERT VALUES/UPDATE" error (SQLSTATE "RX021").) columns" error ("SQLSTATE RX022"). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. RDM ODBC API Reference 127 .RDMe ODBC API Reference Guide SQL_SUCCESS_WITH_INFO Function completed successfully. This indicates a programming error. possibly with a nonfatal error (warning). Also. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. UPDATE. Required Headers #include "sql. or DELETE Conformance Version Introduced: ODBC 1. Function failed.RDMe ODBC API Reference Guide SQLRowCount Gets row count in a table following an INSERT. or descriptor handle.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLRowCount (     SQLHSTMT StatementHandle. Points to a buffer in which to return a row count.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The contents of any output arguments to the function are undefined. This indicates a programming error. possibly with a nonfatal error (warning). Function completed successfully. Function failed due to an invalid environment. The application calls SQLGetDiagField to retrieve additional information from the header record. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. statement.      SQLINTEGER *RowCount)  Arguments StatementHandle     (input) RowCount (output) Statement handle. connection. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. No additional information is available from SQLGetDiagRec or SQLGet128 SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference . For more information. Comments If the last SQL statement executed was not an INSERT. SQLRowCount will return -1 to *RowCount. such as when a statement handle is passed for an argument that requires a connection handle.RDMe ODBC API Reference Guide DiagField. reference MSDN documentation for SQLRowCount. DELETE. This code is returned only when the handle is a null pointer or is the wrong type. UPDATE. IMPORT or EXPORT. RDM ODBC API Reference 129 . The application calls SQLGet130 . this argument should be the length of *ValuePtr.RDMe ODBC API Reference Guide SQLSetConnectAttr Sets attributes that govern aspects of connections. Arguments ConnectionHandle     (input) Attribute (input) ValuePtr (input) Connection handle. StringLength is ignored. this argument should contain the number of bytes in the string.      SQLPOINTER    ValuePtr. ValuePtr will be a 32-bit unsigned integer value or will point to a nullterminated character string. Attribute to set.      SQLINTEGER    StringLength). If Attribute is an ODBC-defined attribute and ValuePtr is an integer. StringLength (input) Required Headers #include "sql. If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer. Note that if the Attribute argument is a driver-specific value. Returns Return Code SQL_SUCCESS RDM ODBC API Reference Description Function completed successfully. Conformance Version Introduced: ODBC 3. the value in ValuePtr may be a signed integer.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetConnectAttr(      SQLHDBC       ConnectionHandle.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies." Pointer to the value to be associated with Attribute.      SQLINTEGER    Attribute. Depending on the value of Attribute. listed in "Comments. For character string data. RDMe ODBC API Reference Guide DiagField to retrieve additional information from the header record. Function completed successfully, possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Function failed due to an invalid environment, connection, statement, or descriptor handle. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is passed for an argument that requires a connection handle. No more data was available. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA Comments Attribute SQL_ATTR_ACCESS_MODE[1][5] ODBC ValuePtr Contents 1.0 An SQLUINTEGER value that specifies the access mode of the database. RDM accepts the following values: SQL_MODE_READ_ONLY = the database will be opened with the read-only mode. It is equivalent of specifying "r" as the core-level open mode. SQL_MODE_READ_WRITE = the database will be opened for read/write access. It is equivalent of specifying "s" as the core-level open mode. This is the default. SQL_MODE_EXCLUSIVE = the database will be opened with the exclusive-access mode. Only one user can access the database. An SQLUINTEGER value that enables the connectionlevel asynchronous execution support. RDM supports the following values: SQL_ASYNC_ENABLE_OFF = Connection-level asynchronous execution is not supported. A read-only SQLUINTEGER value that specifies whether or not the automatic population of the implementation parameter descriptor (IPD) is supported. RDM supports the following values: SQL_TRUE = Automatic population of the IPD is sup- SQL_ATTR_ASYNC_ENABLE 3.0 SQL_ATTR_AUTO_IPD 3.0 RDM ODBC API Reference 131 RDMe ODBC API Reference Guide Attribute ODBC ValuePtr Contents ported. An application can set the SQL_ATTR_ENABLE_AUTO_IPD statement attribute to enable the automatic population of the IPD. This is a read-only attribute and cannot be set by SQLSetConnectAttr. An SQLUINTEGER value that specifies whether transactions are committed automatically or manually. RDM supports the following values: SQL_AUTOCOMMIT_ON = Transactions are committed automatically. This is the default value when RDM is accessed through Microsoft ODBC Driver Manager. SQL_AUTOCOMMIT_OFF = Transactions need to be manually committed by calling SQLEndTran. This is the default when RDM is accessed directly from an ODBC application. A read-only SQLUINTEGER value that indicates whether or not the connection to the data source is active. RDM supports the following values: SQL_CD_TRUE = The connection to the RDM runtime engine has been established. SQL_CD_FALSE = The connection to the RDM runtime engine has been terminated. Note that the returned value of this attribute may not accurately indicate a "lost" connection. This is a read-only attribute and cannot be set by SQLSetConnectAttr. An SQLUINTEGER value that specifies the number of seconds a request made by the driver waits until it returns to the application. RDM supports the following values: 0 = there is no timeout. A character string that specifies the name(s) of the databases to open at the time of connection. RDM supports multiple databases to be open simultaneously. The database names are to be delimited by semicolons. An SQLUINTEGER value that specifies the number of seconds the driver waits for the login request until returning to the application. RDM supports the following values: 132 SQL_ATTR_AUTOCOMMIT[2] 1.0 SQL_ATTR_CONNECTION_DEAD 3.5 SQL_ATTR_CONNECTION_TIMEOUT 1.0 SQL_ATTR_CURRENT_CATALOG[1] 2.0 SQL_ATTR_LOGIN_TIMEOUT 1.0 RDM ODBC API Reference RDMe ODBC API Reference Guide Attribute ODBC ValuePtr Contents 0 = there is no timeout. An SQLUINTEGER value that specifies how the string arguments of catalog functions are to be treated. RDM supports the following values: SQL_FALSE = the string arguments are not treated as identifiers. Case is significant. They can contain search patterns. An SQLULEN value that tells the Driver Manager whether to use the ODBC cursor library. RDM supports the following values: SQL_CUR_USE_DRIVER = use the RDM ODBC driver's cursor. An SQLUINTEGER value that indicates the transaction isolation level of the current connection. RDM supports the following values: SQL_ATTR_METADATA_ID 3.0 SQL_ATTR_ODBC_CURSORS 2.0 SQL_ATTR_TXN_ISOLATION 1.0 SQL_ATTR_RDM_DBCAT[1] SQL_TXN_SERIALIZABLE = transactions are serializable. Dirty reads, non-repeatable reads and phantoms are not allowed. RDM A SQLPOINTER value that specifies the pointer to the RDM database catalog buffer. More than catalog buffers can be specified. Calling SQLSetConnectAttr with this attribute multiple times will append the specified value to the existing catalog buffer list. SQLGetConnectAttr with this attribute will return the catalog buffer list. The number of pointers in the list can be retrieved by using the SQL_ATTR_RDM_DBCAT_ COUNT attribute. RDM A read-only SQLUINTEGR value that indicates the number of catalog buffer pointers stored in the catalog buffer list. This is a read-only attribute and cannot be set by SQLSetConnectAttr. RDM An SQLUINTEGER value that indicates whether the reading of BLOB data is deferred. The following values are supported. SQL_FALSE = the reading of BLOB data is not deferred. It means the entire BLOB value is retrieved when a BLOB column is fetched whether or not the col- SQL_ATTR_RDM_DBCAT_COUNT SQL_ATTR_RDM_DEFER_BLOB RDM ODBC API Reference 133 SQL_ATTR_RDM_REMOTE_NAME[1] RDM SQL_ATTR_RDM_RESERVE_BYTES[1] RDM SQL_ATTR_RDM_TFS_PORT[1] RDM SQL_ATTR_RDM_TFSINIT_DISKLESS[4] RDM SQL_ATTR_RDM_TFSINIT_DOCROOT[4] RDM SQL_ATTR_RDM_TFSINIT_LOGFILE[4] If the value of this attribute is not set and the RDM_ DOCROOT environment variable is set. If SQL_TRUE. A call to SQLGetData will retrieve the actual column value." An SQLUINTEGER value that indicates the number of bytes RDM SQL will reserve at connection time. the value in RDM_DOCROOT will be used. It means the value of a BLOB column is not retrieved when the column is fetched but not bound. The name of the remote server can be specified with the SQL_ATTR_RDM_REMOTE_NAME attribute A character string that indicates the name of the remote RDM host that the driver will connect to for database access. the application's working directory will be used. The default value is 0. SQL_ATTR_RDM_REMOTE_CONN[1][3] SQL_TRUE = the reading of BLOB data is deferred. The default is 21553. SQL_CT_LOCAL = the RDM ODBC Driver will use the embedded core engine. If neither is set. This is the default. RDM A character string that contains the name of the log file RDM ODBC API Reference 134 . A 32-bit integer that indicates whether the embedded TFServer uses the "diskless" mode. SQL_CT_UNKNOWN = Whether RDM ODBC uses the embedded core engine or a remote server is unknown. the driver uses the "diskless" mode. A call to SQLGetData will simply copy the already-retrieved data into the application buffer. A character string that contains the documentation root (docroot) of the embedded TFServer. The default is "localhost.RDMe ODBC API Reference Guide Attribute ODBC ValuePtr Contents umn is bound. The following values are supported. RDM An SQLUINTEGER value that indicates the type of connection an application makes with the RDM core engine. The default is SQL_FALSE. An SQLUSMALLINT value that indicates the port number the target TFS is listening on. This is the default. SQL_CT_REMOTE = the RDM ODBC Driver will use the RPC mechanism to connect to the specified remote server that accesses the core engine through TCP/IP. This is the default. If SQL_FALSE. the driver does not use the "diskless" mode. However. A 32-bit integer that contains the port number of the embedded TFServer. both read and write operations will be allowed. the values set after a con- nection has been established will not take effect until the existing connection has been closed and a new one has been established. RDM ODBC API Reference 135 . If SQL_TRUE. in which case the console output will be directed to stdout. more detailed message will be printed out to the TFSever console (or a file if the application uses the SQL_ATTR_RDM_TFS_ STDOUT attribute). This is identical to SQL_TFSTYPE_TFS unless the RDM source code is modified and recompiled. If SQL_TRUE. such detailed messages will not be displayed. If SQL_FALSE. The default is NULL. SQL_TFSTYPE_DEFAULT = The default TFServer will be used. the embedded TFServer will only allow read operations on its databases. RDM supports the following values: SQL_TFSTYPE_TFS = An embedded TFServer (TFST) will be used. A charater string that contains the name of the file the stdout of the embedded TFServer will be redirected to. RDM A 32-bit integer that indicates whether the verbose mode is enabled. The default is SQL_FALSE. SQL_TFSTYPE_RPC = A remote TFServer (TFSR) will be used. SQL_ATTR_RDM_TFSINIT_PORT[4] SQL_ATTR_RDM_TFS_READONLY[4] RDM RDM SQL_ATTR_RDM_TFSINIT_STDOUT[4] RDM SQL_ATTR_RDM_TFSINIT_TYPE RDM SQL_ATTR_RDM_TFSINIT_VERBOSE[4] [1]Those attributes can be set before or after connecting to RDM SQL. The default value is SQL_TFSTYPE_DEFAULT. A 32-bit integer that indicates the type of the TFServer used with an application. If SQL_FALSE. A 32-bit integer that indicates whether the embedded TFServer is in read-only mode.RDMe ODBC API Reference Guide Attribute ODBC ValuePtr Contents where the activities of the embedded TFServer will be logged. This option requires that an application have access to a running TFServer process. The default is SQL_ FALSE. The default is NULL. in which case activities will not be logged. The default value is port 21553. SQL_TFSTYPE_STANDALONE = A standalone TFServer (TFSS) will be used. the values set or retrieved before a connection has been established may not reflect the value stored in the RDM SQL SQL engine. SQL_ATTR_RDM_TFS_NAME.RDMe ODBC API Reference Guide [2]Those attributes can be set before and after connecting to RDM SQL. For more information. RDM ODBC API Reference 136 . the value of first argument. the processing of a SQL statement that is not read-only on a read-connection gives a STATE 42000 error at the statement preparation time. The application should always set/get those attribute values while the connection to the data source is on. For details. [5] In RDM ODBC. [3] If the SQL_ATTR_RDM_CONN_TYPE attribute is set to SQL_CT_UNKNOWN at the time of connection. reference MSDN documentation for SQLSetConnectAttr. Once the connection type has been determined. that type will be stored in the SQL_ATTR_RDM_CONN_ TYPE attribute. SQLConnect or SQLDriverConnect will determine the connection type by checking the values of SQL_ATTR_ RDM_REMOTE_NAME. see SQLConnect and SQLDriverConnect. However. and in the case of SQLConnect. [4] Values set with those attributes will have no effect if the application does not use an embedded TFServer ("tfss" or "tfst"). NameLength (input) Required Headers #include "sql. Cursor name. Function completed successfully. Length in characters of *CursorName. Conformance Version Introduced: ODBC 1.      SQLSMALLINT  BufferLength)  Arguments StatementHandle     (input) CursorName (input) Statement handle. The application calls SQLGetDiagField to retrieve additional information from the header record. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetCursorName (     SQLHSTMT     StatementHandle. possibly with a nonfatal error (warning). For efficient processing.      SQLCHAR     *CursorName. The application calls SQLGetDiagRec or SQLGet- SQL_ERROR RDM ODBC API Reference 137 . the delimiter should be positioned as the first character in the cursor name. and if the cursor name includes a delimited identifier. the cursor name should not include any leading or trailing spaces in the cursor name.RDMe ODBC API Reference Guide SQLSetCursorName Associates a cursor name with an active statement.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. Function failed. reference MSDN documentation for SQLCursorName. Function failed due to an invalid environment. This indicates a programming error. statement. This code is returned only when the handle is a null pointer or is the wrong type. or descriptor handle. The contents of any output arguments to the function are undefined. connection.RDMe ODBC API Reference Guide DiagField to retrieve additional information. such as when a statement handle is passed for an argument that requires a connection handle. No additional information is available from SQLGetDiagRec or SQLGetDiagField. SQL_INVALID_HANDLE For more information. RDM ODBC API Reference 138 . The RecNumber argument is ignored for header fields. Conformance Version Introduced: ODBC 3. For character string data.      SQLSMALLINT   FieldIdentifier. either all four of the bytes are used or just two of the four are used. The data type depends on the value of FieldIdentifier.      SQLPOINTER    ValuePtr.      SQLSMALLINT   RecNumber.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetDescField(      SQLHDESC      DescriptorHandle.      SQLINTEGER    BufferLength). Arguments DescriptorHandle     (input) RecNumber (input) Descriptor handle. Descriptor records are numbered from 0. this argument should contain the number of bytes in the string. this argument should be the length of *ValuePtr. FieldIdentifier ValuePtr (input) (input) BufferLength (input) Required Headers #include "sql. with record number 0 being the bookmark record. Indicates the descriptor record containing the field that the application seeks to set. RDM ODBC API Reference 139 . or a 4-byte value. If ValuePtr is a 4-byte value.RDMe ODBC API Reference Guide SQLSetDescField Sets the value of a single field of a descriptor record. depending on the value of the FieldIdentifier argument. Pointer to a buffer containing the descriptor information.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. If FieldIdentifier is an ODBC-defined field and ValuePtr points to a character string or a binary buffer. Indicates the field of the descriptor whose value is to be set. No additional information is available from SQLGetDiagRec or SQLGetDiagField. or descriptor handle. SQL_ERROR SQL_INVALID_HANDLE For more information. such as when a statement handle is passed for an argument that requires a connection handle. statement. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. reference MSDN documentation for SQLSetDescField. The application calls SQLGetDiagField to retrieve additional information from the header record. This indicates a programming error. Function failed. RDM ODBC API Reference 140 . Function failed due to an invalid environment. This code is returned only when the handle is a null pointer or is the wrong type. connection. The contents of any output arguments to the function are undefined. Function completed successfully.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Arguments DescriptorHandle     (input) RecNumber (input) Descriptor handle.RDMe ODBC API Reference Guide SQLSetDescRec Sets multiple descriptor fields that affect the data type and buffer bound to a column or parameter data.       SQLLEN *      StringLengthPtr.       SQLLEN *      IndicatorPtr). (input/output) The value to which to set the SQL_DESC_INDICATOR_PTR field for the descriptor record.       SQLLEN        Length. (input) The value to which to set the SQL_DESC_PRECISION field for the descriptor record.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetDescRec(       SQLHDESC      DescriptorHandle.       SQLPOINTER    DataPtr. This argument must be equal to or greater than 0. (input/output) The value to which to set the SQL_DESC_OCTET_LENGTH_PTR field for the descriptor record.       SQLSMALLINT   Type. this is the value to which to set the SQL_DESC_DATETIME_INTERVAL_CODE field. Indicates the descriptor record that contains the fields to be set. Conformance Version Introduced: ODBC 3. If RecNumber is greater than the value of SQL_DESC_COUNT.       SQLSMALLINT   RecNumber. with record number 0 being the bookmark record. SQL_DESC_COUNTis changed to the value of RecNumber.       SQLSMALLINT   Scale. (input) The value to which to set the SQL_DESC_TYPE field for the descriptor record. StringLengthPtr can be set to a null pointer to set the SQL_DESC_OCTET_LENGTH_PTR field to a null pointer. (input) For records whose type is SQL_DATETIME or SQL_INTERVAL.       SQLSMALLINT   SubType. This must not be an IRD handle. Type SubType Length Precision Scale DataPtr IndicatorPtr RDM ODBC API Reference 141 .       SQLSMALLINT   Precision. (input) The value to which to set the SQL_DESC_OCTET_LENGTH field for the descriptor record. Descriptor records are numbered from 0. IndicatorPtr can be set to a null pointer to set the SQL_DESC_INDICATOR_PTR field to a null pointer. (input) The value to which to set the SQL_DESC_SCALE field for the descriptor record. This indicates a programming error. connection. such as when a statement handle is passed for an argument that requires a connection handle.RDMe ODBC API Reference Guide Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagField to retrieve additional information from the header record. reference MSDN documentation for SQLSetDescRec. or descriptor handle. Function failed due to an invalid environment. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Function failed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. SQL_ERROR SQL_INVALID_HANDLE For more information. RDM ODBC API Reference 142 . statement. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function completed successfully. possibly with a nonfatal error (warning). Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The contents of any output arguments to the function are undefined. This code is returned only when the handle is a null pointer or is the wrong type. 0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetEnvAttr(      SQLHENV      EnvironmentHandle.      SQLINTEGER   StringLength). Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO RDM ODBC API Reference Description Function completed successfully.RDMe ODBC API Reference Guide SQLSetEnvAttr Sets attributes that govern aspects of environments." Pointer to the value to be associated with Attribute. this argument should contain the number of bytes in the string. listed in "Comments.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Attribute to set. possibly with a nonfatal error (warn143 .      SQLINTEGER   Attribute. StringLength is ignored. For character string data. The application calls SQLGetDiagField to retrieve additional information from the header record. If ValuePtr is an integer.      SQLPOINTER   ValuePtr. StringLength (input) Required Headers #include "sql. Depending on the value of Attribute. Function completed successfully. ValuePtr will be a 32-bit integer value or point to a null-terminated character string. this argument should be the length of *ValuePtr. Conformance Version Introduced: ODBC 3. If ValuePtr points to a character string or a binary buffer. Arguments EnvironmentHandle   (input)   Attribute (input) ValuPtr (input) Environment handle. x behavior. RDM accepts the following values: SQL_CP_OFF = Connection pooling is turned off. or descriptor handle. The contents of any output arguments to the function are undefined. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment. A 32-bit integer that determines how the driver returns 144 SQL_ATTR_CP_MATCH 3. time.0 SQL_ATTR_ODBC_VERSION 3. This indicates a programming error.0 SQL_ATTR_OUTPUT_NTS RDM ODBC API Reference 3. Function failed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. SQL_OV_ODBC3 = The driver exhibits the following ODBC 3. RDM does not support setting this value since it does not support connection pooling.x behavior:  l The driver returns and expects ODBC 3. such as when a statement handle is passed for an argument that requires a connection handle. This code is returned only when the handle is a null pointer or is the wrong type. No additional information is available from SQLGetDiagRec or SQLGetDiagField.x SQLSTATE codes  when SQLGetDiagField. statement.0 . or SQLGetDiagRec is called  l The CatalogName argument in a call to SQLTables accepts a search pattern.0 A 32-bit SQLUINTEGER value that enables or disables connection pooling at the environment level.x codes  for date.  l The driver does not support C data type extensibility. connection.RDMe ODBC API Reference Guide ing). RDM accepts the following values. Attribute SQL_ATTR_CONNECTION_POOLING ODBC ValuePtr contents 3. A 32-bit SQLUINTEGER value that determines how a connection is chosen from a connection pool. RDM does not require that this attribute be explicitly set before an application calls other functions that have an SQLHENV argument. SQL_ERROR SQL_INVALID_HANDLE Comments Attribute and ValuePtr RDM accepts the following attribute values. and timestamp  l The driver returns ODBC 3. A 32-bit integer that determines whether certain functionality exhibits ODBC 2.x behavior or ODBC 3. For more information. reference MSDN documentation for SQLSetEnvAttr.RDMe ODBC API Reference Guide Attribute ODBC ValuePtr contents string data. RDM ODBC API Reference 145 . If SQL_TRUE. If SQL_FALSE. the driver does not return string data null-terminated. the driver returns string data null-terminated. Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQLSetError(     SQLSMALLINT     HandleType.     SQLRETURN       ErrorCode. indicating the scope of the transaction. The following values are accepted. (See Error Handler Prototype below).     SQLHANDLE       Handle.     ECALLBACK       ErrorHandler).h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Required Headers #include "sqlrext. The ODBC error code for which to register the error handler. The application can specify NULL in order to unregister the error handler.RDMe ODBC API Reference Guide SQLSetError Registers user-defined status/error handling functions. of the type indicated by HandleType. RDM ODBC API Reference 146 . A pointer to the error handler function.  l SQL_HANDLE_DBC  l SQL_HANDLE_DESC Handle ErrorCode ErrorHandler (input) (input) (input)  l SQL_HANDLE_STMT The handle.  Arguments HandleType (input) Handle type identifier. statement. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.     SQLRETURN  error_code). This function was called after SQLExecute or SQLExecDirect but before all the parameters were bound.     SQLHANDLE  Handle. Function failed due to an invalid environment.  Return Codes Return Code SQL_SUCCESS SQL_ERROR Description Function completed successfully. such as when a statement handle is passed for an argument that requires a connection handle. Function failed. The contents of any output arguments to the function are undefined. connection.RDMe ODBC API Reference Guide Error Handler Prototype int32_t SQL_API errHandler(     int16_t   HandleType. The application calls SQLGetDiagField to retrieve additional information from the header record. SQL_INVALID_HANDLE Diagnostics SQLSTATE HY001 HY010 Error Memory allocation error Function sequence error Description Either the ODBC driver or the SQL engine failed to allocate sufficient memory to complete the required operation. or descriptor handle. RDM ODBC API Reference 147 . This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type. h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. this argument should be the length of *ValuePtr.     SQLINTEGER StringLength) Arguments StatementHandle     (input) Attribute (input) ValuePtr (input) Statement handle. Pointer to the value to be associated with Attribute. Returns Return Code SQL_SUCCESS Description Function completed successfully.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetStmtAttr(     SQLHSTMT StatementHandle.     SQLINTEGER Attribute. ValuePtr will be a 32-bit unsigned integer value. If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer. The application calls SQLGetDiagField to retrieve additional information from the header record. StringLength is ignored. or will point to a null-terminated character string.RDMe ODBC API Reference Guide SQLSetStmtAttr Sets attributes related to a statement Conformance Version Introduced: ODBC 3.     SQLPOINTER ValuePtr. StringLength (input) Required Headers #include "sql. If Attribute is an ODBC-defined attribute and ValuePtr is an integer. 148 RDM ODBC API Reference . Specifies the statement option type. Possible values are described in "Comments" below. Depending on the value of Attribute. the ARD will revert to the implicitly allocated internal handle. SQL_NULL_ DESC can be specified to dissociate the current handle from the APD. SQL_ NULL_DESC can be specified to dissociate the current handle from the APD. This code is returned only when the handle is a null pointer or is the wrong type.0 The handle to the APD. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. in that case. or descriptor handle. The possible values are: SQL_ASYNC_ENABLE_OFF = Disable statement-level asynchronous execution support (default). This indicates a programming error. The handle will replace the handle currently associated with the APD. in that case. Function failed. This attribute cannot be set to an implicitly allocated handle except for the handle that was originally implicitly allocated for this ARD. The handle will replace the handle currently associated with the APD.0 RDM ODBC API Reference 149 . statement.RDMe ODBC API Reference Guide SQL_SUCCESS_WITH_INFO Function completed successfully. The handle to the ARD.0 SQL_ATTR_ASYNC_ENABLE 3. The contents of any output arguments to the function are undefined. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed due to an invalid environment. An SQLULEN value that specifies whether functions on this statement handle are executed asynchronously. This attribute cannot be set to an implicitly allocated handle except for the handle that was originally implicitly allocated for this APD. the APD will revert to the implicitly allocated internal handle. The following values are not supported: SQL_ASYNC_ENABLE_ON SQL_ATTR_APP_ROW_DESC 3. such as when a statement handle is passed for an argument that requires a connection handle. connection. possibly with a nonfatal error (warning). Attribute SQL_ATTR_APP_PARAM_DESC ODBC ValuePtr contents 3. No additional information is available from SQLGetDiagRec or SQLGetDiagField. SQL_ERROR SQL_INVALID_HANDLE Comments Attributes and ValuePtr RDM accepts the following attribute values. The following values are not supported: SQL_CURSOR_STATIC SQL_CURSOR_KEYSET_DRIVEN SQL_CURSOR_DYNAMIC SQL_ATTR_CURSOR_SCROLLABLE 3. The following values are not supported: SQL_INSENSITIVE SQL_SENSITIVE An SQLULEN value that specifies the cursor type. An SQLULEN value that specifies whether the cursor is scrollable. The following values are not supported: SQL_ATTR_CURSOR_SENSITIVITY SQL_SCROLLABLE An SQLULEN value that specifies whether the cursors on the statement handle makes visible the changes made to a result set by another cursor. The following values are not supported: SQL_CONCUR_ROWVER SQL_CONCUR_VALUES If an unsupported value is specified. The possible values are: SQL_UNSPECIFIED = Whether the cursors on the statement handle makes visible the changes made to a result set by another cursor is unspecified (default). SQL_CONCUR_LOCK = Cursor uses the lowest-level locking necessary to perform updates. The possible values are: SQL_CURSOR_FORWARD_ONLY = The cursor scrolls forward-only (default). SQLSetStmtAttr substitutes SQL_CONCUR_LOCK for it and returns 01S02 ("option value changed") at execution time.0 SQL_ATTR_CURSOR_TYPE 2. The possible values are: SQL_NONSCROLLABLE = The cursor is not scrollable (default).0 RDM ODBC API Reference 150 .0 A SQLULEN value that specifies the cursor concurrency.RDMe ODBC API Reference Guide Attribute SQL_ATTR_CONCURRENCY ODBC ValuePtr contents 2. The possible values are: SQL_CONCUR_READ_ONLY = Cursor is read-only. Only SQL_FETCH_NEXT is supported for SQLFetchScroll. updates are not allowed (default). The application can call SQLGetStmtAttr to retrieve the value of the attribute. SQL_FALSE = The IPD is not automatically populated after SQLPrepare(). This is a read-only attribute.RDM does not support this attribute. An SQLULEN value that specifies whether the IPD is populated automatically. RDM ODBC Driver attempts to return all available data. The following values are not supported: RDM ODBC API Reference 151 SQL_ATTR_FETCH_BOOKMARK_PTR SQL_ATTR_IMP_PARAM_DESC 3. Not supported.0 ValuePtr contents RDM ODBC only supports forward-only cursors.0 SQL_ATTR_METADATA_ID 3. The handle to the IPD. The default value is 0. The handle to the IRD. An SQLULEN value that specifies the number of rows in the keyset for a keyset-driven cursor. In that case. An SQLULEN value that specifies the maximum amount of data the RDM ODBC driver returns from a binary or character column. An SQLULEN value that specifies how the string arguments of catalog functions are treated. If the specified length is less than the length of the available data.RDMe ODBC API Reference Guide Attribute SQL_ATTR_ENABLE_AUTO_IPD ODBC 3.0 SQL_ATTR_MAX_ROWS 1. In that case. The possible values are: SQL_TRUE = The IPD is automatically populated after SQLPrepare. The possible values are: SQL_FALSE = the string arguments of catalog functions are not treated as identifiers. If set to non-zero.0 SQL_ATTR_IMP_ROW_DESC 3. Arguments are case-sensitive and may contain a string search pattern (default). The application should call SQLDescribeParam to obtain the IPD information (default). Setting this attribute has no effect. this value sets the maximum value for the cursor row count.0 3.0 SQL_ATTR_KEYSET_SIZE 2. Setting this attribute has no effect.0 . The default value is 0. The application can call SQLGetStmtAttr to retrieve the value of the attribute. An SQLULEN value that specifies the maximum number of rows returned by a select statement.0 SQL_ATTR_MAX_LENGTH 1. the data is truncated and SQL_SUCCESS is returned. RDM ODBC Driver attempts to return all rows. This is a read-only attribute. or no timeout) specified by ODBC. Not supported. If non-null. SQL_NOSCAN_ON = SQL strings are not scanned for escape sequences.0 SQL_ATTR_RETRIEVE_DATA 2.0 1. the value is effective on the connection level in RDM ODBC. The default value for this attribute is 10 (seconds). The affected fields are: SQL_DESC_DATA_PTR SQL_DESC_INDICATOR_PTR SQL_DESC_OCTET_LENGTH_PTR The default value is NULL. Not supported. Setting this attribute has no effect. SQL_ATTR_PARAM_OPERATION_PTR SQL_ATTR_PARAM_STATUS_PTR SQL_ATTR_PARAMS_PROCESSED_PTR SQL_ATTR_PARMSET_SIZE SQL_ATTR_QUERY_TIMEOUT1 3. Not supported. Changing the value of this attribute on one statement handle will affect all the other statement handles allocated from the same connection handle. Setting this attribute has no effect. They are passed directly to the data source. Not supported.0 3. the pointer will be dereferenced.0 1Although SQL_ATTR_QUERY_TIMEOUT is a statement attribute. The possible values are: SQL_NOSCAN_OFF = SQL strings are scanned for escape sequences (default).0 Row-wise binding is not supported. Setting this attribute has no effect. and the value contained will be added to each of the dereferenced fields in the APD.0 SQL_ATTR_PARAM_BIND_TYPE 3. Setting this attribute has no effect. If locking is not granted within the specified timeout period.RDMe ODBC API Reference Guide Attribute SQL_ATTR_NOSCAN ODBC 1. The possible values are: SQL_PARAM_BIND_BY_COLUMN = Perform columnwise binding (default).0 3. An SQLULEN value that specifies the number of seconds RDM SQL uses in requesting locks on databases for statement execution. the statement execution returns with a "timeout expired " error (SQLSTATE "HYT00"). An SQULEN value that specifies whether SQLFetch SQL_ATTR_PARAM_BIND_OFFSET_PTR 3. It is different from the default value (0. An SQLULEN value that specifies the binding orientation to be used for dynamic parameters. RDM ODBC API Reference 152 . An SQLULEN pointer that points to an offset value added to pointers to change dynamic parameter binding.0 ValuePtr contents SQL_TRUE An SQLULEN value that indicates whether the RDM ODBC Driver should scan SQL strings for escape sequences.0 3. The default value of this attribute is NULL.0 SQL_ATTR_ROW_OPERATION_PTR SQL_ATTR_ROW_STATUS_PTR 3. Not supported. An SQLULEN pointer that points to an offset value added to pointers to change column binding. An SQLULEN value that indicates the number of the current row in the entire result set.0 RDM ODBC API Reference 153 . An SQLUSMALLINT pointer that points to an array of SQLUSMALLINT values that will contain the row status values after SQLFetch or SQLFetchScroll was called.0 SQL_ATTR_ROWS_FETCHED_PTR 3.RDMe ODBC API Reference Guide Attribute ODBC ValuePtr contents and SQLFetchScroll retrieve data after it positions the cursor. The possible values are: SQL_RD_ON = Data are retrieved (default). If the value cannot be determined or there is no current row.0 SQL_RD_OFF An SQLULEN value that specifies the number of rows returned by each call to SQLFetch or SQLFetchScroll. and the value contained will be added to each of the dereferenced fields in the ARD. This is a read-only attribute. If nonnull. 0 will be returned. The following values are not supported: SQL_ATTR_ROW_ARRAY_SIZE 3. SQL_ATTR_ROW_BIND_OFFSET_PTR 3. SQL_ATTR_ROW_NUMBER 2. An SQLULEN value that specifies the binding orientation to be used for column binding The possible values are: SQL_BIND_BY_COLUMN = Perform column-wise binding (default). In that case.0 3. The array has the same number of elements as the number of rows in the rowset. The affected fields are: SQL_DESC_DATA_PTR SQL_DESC_INDICATOR_PTR SQL_DESC_OCTET_LENGTH_PTR The default value is NULL. Setting this attribute has no effect. The application can call SQLGetStmtAttr to retrieve the value of the attribute. row status values will not be returned to the application.0 SQL_ATTR_ROW_BIND_TYPE 1.0 Row-wise binding is not supported. the pointer will be dereferenced. The default value is 1. An SQLULEN pointer that points to a buffer in which the number of rows fetched by SQLFetch or SQLFetchScroll is stored. In that case. SQL_ATTR_SIMULATE_CURSOR 2.RDMe ODBC API Reference Guide Attribute ODBC ValuePtr contents The default value of this attribute is NULL.0 RDM ODBC API Reference 154 . reference MSDN documentation for SQLSetStmtAttr. The following values are not supported: SQL_UB_ON For more information.0 SQL_ATTR_USE_BOOKMARKS 2. SQL_SC_UNIQUE = The driver guarantees that simulated positioned update and delete statements affect only one row (default). An SQLULEN value that specifies whether RDM ODBC Driver guarantees positioned update and delete statements affect only one row. SQL_SC_TRY_UNIQUE = The driver tries to guarantee that simulated positioned update and delete statements affect only one row. SQL_SC_UNIQUE is the default value for RDM ODBC since RDM provides the native SQL support that guarantees that simulated positioned update and delete statements affect only one row. An SQLULEN value that specifies whether bookmarks are used with a cursor. the number of result rows will not be returned to the application. The possible values are: SQL_SC_NON_UNIQUE = The driver does not guarantee that simulated positioned update and delete statements affect only one row. Specifying SQL_SC_ TRY_UNIQUE or SQL_SC_NON_UNIQUE will return SQL_SUCCESS_WITH_INFO ("01S02"). The possible values are: SQL_UB_OFF = Off (default). Conformance Version Introduced: ODBC 1. such as when the driver retrieves data from different DBMSs.      SQLSMALLINT   NameLength3. Length in characters of *CatalogName. Arguments StatementHandle     (input) IdentifierType (input) Statement handle for retrieved results. Must be one of the following values: SQL_BEST_ROWID: Returns the optimal column or set of columns that. TableName cannot contain a string search pattern.      SQLSMALLINT   Nullable). CatalogName cannot contain a string search pattern. Type of column to return. SchemaName cannot contain a string search pattern. allows any row in the specified table to be uniquely identified.      SQLSMALLINT   NameLength1. SQL_ROWVER: Returns the column or columns in the specified table.      SQLCHAR *     TableName.      SQLCHAR *     SchemaName.      SQLSMALLINT   NameLength2.      SQLSMALLINT   Scope.RDMe ODBC API Reference Guide SQLSpecialColumns Returns the information about the set of columns that uniquely identifies a row in the table. CatalogName (input) NameLength1 SchemaName (input) (input) NameLength2 TableName (input) (input) RDM ODBC API Reference 155 . Table name. If a driver supports schemas for some tables but not for others.0 Standards Compliance: Open Group Syntax SQLRETURN SQLSpecialColumns(      SQLHSTMT      StatementHandle.      SQLCHAR *     CatalogName. an empty string ("") denotes those tables that do not have catalogs. by retrieving values from the column or columns. Catalog name for the table. This argument cannot be a null pointer. Length in characters of *SchemaName. if any. Schema name for the table. an empty string ("") denotes those tables that do not have schemas.      SQLSMALLINT   IdentifierType. A column can be either a pseudo-column specifically designed for this purpose (as in Oracle ROWID or Ingres TID) or the column or columns of any unique index for the table. that are automatically updated by the data source when any value in the row is updated by any transaction (as in SQLBase ROWID or Sybase TIMESTAMP). If a driver supports catalogs for some tables but not for others. such as when the driver retrieves data from different DBMSs. or descriptor handle. Function completed successfully. Determines whether to return special columns that can have a NULL value. A later reselect using rowid may not return a row if the row was updated or deleted by another transaction. Nullable (input) Required Headers #include "sql. This indicates a programming error. SQL_SCOPE_TRANSACTION: The rowid is guaranteed to be valid for the duration of the current transaction. Must be one of the following: SQL_SCOPE_CURROW: The rowid is guaranteed to be valid only while positioned on that row. possibly with a nonfatal error (warning). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Some drivers cannot support SQL_NO_NULLS. SQL_SCOPE_SESSION: The rowid is guaranteed to be valid for the duration of the session (across transaction boundaries).RDMe ODBC API Reference Guide NameLenght3 Scope (input) (input) Length in characters of *TableName. and these drivers will return an empty result set if SQL_NO_NULLS was specified. The application calls SQLGetDiagField to retrieve additional information from the header record. Minimum required scope of the rowid. The contents of any output arguments to the function are undefined. Must be one of the following: SQL_NO_NULLS: Exclude special columns that can have NULL values. The returned rowid may be of greater scope. SQL_NULLABLE: Return special columns even if they can have NULL values. No additional SQL_ERROR SQL_INVALID_HANDLE RDM ODBC API Reference 156 . Function failed. Function failed due to an invalid environment.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. statement. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. Applications should be prepared for this case and request SQL_NO_NULLS only if it is absolutely required. connection. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. SQLSpecialColumns returns an empty result set. For more information. This code is returned only when the handle is a null pointer or is the wrong type. reference MSDN documentation for SQLSpecialColumns. such as when a statement handle is passed for an argument that requires a connection handle. If no database is open on the data source. Comments SQLSpecialColumns returns the information that pertains to the databases that are currently open.RDMe ODBC API Reference Guide information is available from SQLGetDiagRec or SQLGetDiagField. RDM ODBC API Reference 157 . an empty string ("") indicates those tables that do not have schemas.      SQLSMALLINT     NameLength3.      SQLSMALLINT     NameLength2. If a driver supports schemas for some tables but not for others.h" Libraries Library Name rdmrdbc11 RDM ODBC API Reference Description RDM ODBC API Library 158 . Type of index: SQL_INDEX_UNIQUE or SQL_INDEX_ALL.      SQLUSMALLINT    Reserved).      SQLSMALLINT     NameLength1. SchemaName cannot contain a string search pattern. This argument cannot be a null pointer. Conformance Version Introduced: ODBC 1.      SQLCHAR *       SchemaName. SchemaName cannot contain a string search pattern. Arguments StatementHandle     CatalogName NameLength1 SchemaName (input) (input) (input) (input) Statement handle for retrieved results. Length in characters of *SchemaName. such as when the driver retrieves data from different DBMSs. Schema name. Catalog name.      SQLUSMALLINT    Unique. Length in characters of *CatalogName. Table name. The driver returns the information as a result set. Length in characters of *TableName.      SQLCHAR *       CatalogName. NameLength2 TableName NameLenght3 Unique Reserved (input) (input) (input) (input) (input) Required Headers #include "sql.RDMe ODBC API Reference Guide SQLStatistics Retrieves a list of statistics about a single table and the indexes associated with the table.      SQLCHAR *       TableName.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLStatistics(      SQLHSTMT        StatementHandle. statement. For more information. The application calls SQLGetDiagField to retrieve additional information from the header record. or descriptor handle. The contents of any output arguments to the function are undefined. No additional information is available from SQLGetDiagRec or SQLGetDiagField. SQLStatistics returns an empty result set. such as when a statement handle is passed for an argument that requires a connection handle. This indicates a programming error. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function completed successfully. This code is returned only when the handle is a null pointer or is the wrong type. If no database is open on the data source.RDMe ODBC API Reference Guide See Library Naming Conventions section for full library name and a list of library dependencies. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. connection. Function failed. SQL_ERROR SQL_INVALID_HANDLE Comments SQLStatistics returns the information that pertains to the databases that are currently open. reference MSDN documentation for SQLStatistics. Function failed due to an invalid environment. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. RDM ODBC API Reference 159 . possibly with a nonfatal error (warning).      SQLSMALLINT    NameLength2.      SQLCHAR *      CatalogName. String Search pattern for table names. Length in characters of *CatalogName. catalog. String search pattern for schema names.      SQLCHAR *      SchemaName. or schema names. RDM ODBC API Reference 160 . and table types. Length in characters of *TableName. Conformance Version Introduced: ODBC 1. Arguments StatementHandle     CatalogName NameLength1 SchemaName NameLength2 TableName NameLenght3 TableType NameLength4 (input) (input) (input) (input) (input) (input) (input) (input) (input) Statement handle for retrieved results.RDMe ODBC API Reference Guide SQLTables Returns the list of table. List of table types to match.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies.      SQLCHAR *      TableName. Length in characters of *SchemaName.      SQLSMALLINT    NameLength1.      SQLSMALLINT    NameLength3. Length in characters of *TableType Required Headers #include "sql.      SQLCHAR *      TableType. Catalog name.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLTables(      SQLHSTMT       StatementHandle.      SQLSMALLINT    NameLength4). stored in a specific data source. connection. SQLTables returns an empty result set. such as when a statement handle is passed for an argument that requires a connection handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed.RDMe ODBC API Reference Guide Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The application calls SQLGetDiagField to retrieve additional information from the header record. For more information. This indicates a programming error. possibly with a nonfatal error (warning). or descriptor handle. reference MSDN documentation for SQLTables. RDM ODBC API Reference 161 . Function failed due to an invalid environment. If no database is open on the data source. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. SQL_ERROR SQL_INVALID_HANDLE Comments SQLTables returns the information that pertains to the databases that are currently open. No additional information is available from SQLGetDiagRec or SQLGetDiagField. This code is returned only when the handle is a null pointer or is the wrong type. Function completed successfully. statement. Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQL_API SQLTransactStatus(     SQLSMALLINT      HandleType. RDM ODBC API Reference 162 . Function completed successfully. Contains either SQL_ HANDLE_ENV (if Handle is an environment handle) or SQL_HANDLE_DBC (if Handle is a connection handle). The application calls SQLGetDiagField to retrieve additional information from the header record. see the table in the Comments section below. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. indicating the scope of the transaction. possibly with a nonfatal error (warning). of the type indicated by HandleType. The handle.RDMe ODBC API Reference Guide SQLTransactStatus Retrieves the type and status of the transaction possibly executed on the handle. The status of the transaction on the handle. For the possible return values for pActive.     SQLHANDLE        Handle. Handle pActive (input) (output) Required Headers #include "sqlrext.     SQLSMALLINT     *pActive) Arguments HandleType (input) Handle type identifier.h" Libraries Library Name rdmrdbc11 Description RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. The following values are accepted. and one or more of the connection handles associated with it failed to retrieve the status of its transaction. or descriptor handle. This code is returned only when the handle is a null pointer or is the wrong type. connection. This indicates a programming error. SQL_INVALID_HANDLE Diagnostics SQLSTATE 08003 25S01 Error Connection not open Transaction state unknown Description The Handle argument specifies a connection handle and is not connected to the data source. The contents of any output arguments to the function are undefined. RDM ODBC API Reference 163 . statement. such as when a statement handle is passed for an argument that requires a connection handle.e. A regular (i.e. No additional information is available from SQLGetDiagRec or SQLGetDiagField. Function failed due to an invalid environment. The Handle argument specifies an environment handle. Value of pActive SQL_TXN_INACTIVE SQL_TXN_REGULAR SQL_TXN_READONLY Description No transaction is active on the specified handle. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. updatable) transaction is active on the specified handle. HY009 Invalid use of null pointer Comments The following table describes the possible return values of the status of the transaction through the pActive argument. A null pointer was specified for the pActive argument. snapshot) is active on the specified handle.RDMe ODBC API Reference Guide SQL_ERROR Function failed. A read-only transaction (i. RDMe ODBC API Reference Guide Summary Listing of RDM SQL Server API Functions The following table lists alphabetically the functions used to initialize the RDM SQL Server in various configurations. Function rdmsqlserver_init rdmsqlserver_start rdmsqlserver_stop rdmsqlserver_term Description Provide RDM SQL with parameters to start up as a server Begin running connections from rdbc Stop running connections from rdbc Terminate the use of the RDM SQL Server. releasing resources RDM ODBC API Reference 164 .      const char *stdout_file.      TFS_TYPE    tfs_type. defaults are used. If NULL.         RDMSQL_CTX      **sql_ctx)  Parameters params sql_ctx (input) (output) Parameters required for server operation. This function will also initialize the TFS unless one has already been started.RDMe ODBC API Reference Guide rdmsqlserver_init Start up a RDM SQL Server Prototype int32_t rdmsqlserver_init(         const SQL_PARAMS *params. TRUE or FALSE. stopping or terminating this server.  SQL_PARAMS structure definition Element port rd_only no_disk verbose tfs_type no_tfsrun logfile stdout_file Declaration uint16_t uint32_t uint32_t uint16_t TFS_TYPE uint16_t const char * const char * Description TFS anchor port. Description Call rdmsqlserver_init to set up the RDM SQL server.   } SQL_PARAMS. If the value is NULL or "stdout" the messages will be sent to RDM ODBC API Reference 165 . SQL_PARAMS prototypes   typedef struct {      uint16_t    port.      uint16_t    verbose.      const char *docroot. Verbose. true or false. The type of Transactional File Server to use Whether the tfserver should be started or not (listen) File name to open for logging. Any successful call to rdmsqlserver_init requires a corresponding call to rdmsqlserver_term before termination of the application. Handle used for running. TRUE or FALSE.      uint32_t    no_disk. Read-only device. The name of a file to write informational messages instead of displaying them to stdout. Can be NULL.      uint32_t    rd_only. Diskless mode.      uint16_t    no_tfsrun. This function must be called prior to any rdbc API function calls unless you relay on an external RDM SQL server. Should match TFS -p port number (use 21553 if default).      SQL_PARAMS sparams. d_tfsinitEx d_tfsrun Example static RDMSQL_CTX *sql_ctx = NULL.        static uint16_t sql_finished = 0. Required Headers #include "rdmsqlserver.no_disk= get_tfsNoDisk ().      sparams.port= get_tfsPort (). Return Codes Value 0 -225 -227 -904 Name S_OKAY S_TX_DOCROOT_USED S_TX_INVTFSTYPE S_NOMEMORY Description normal return.rd_only= get_tfsReadOnly ().RDMe ODBC API Reference Guide Element Declaration Description stdout. okay The docroot is already in use Invalid TFS type out of memory See Also rdmsqlserver_start rdmsqlserver_stop rdmsqlserver_term SQLConnect d_tfsinit.      sparams. If the value is an empty string ("") no messages will be displayed.h" Libraries Library Name rdmsqlserver11 Description RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies.         sparams. RDM ODBC API Reference 166 . stdout_file= NULL.verbose= FALSE.      if (sStatus == S_OKAY) {          sStatus = rdmsqlserver_run(sql_ctx. TRUE.docroot= get_tfsDocroot ().      sparams. &sql_ctx).      sparams.          if (sStatus == S_OKAY) {                 /* The main part of your application */                 (void) rdmsqlserver_term(sql_ctx).no_tfsrun= TRUE.      sparams.      sparams.      }  RDM ODBC API Reference 167 .          }          (void) rdmsqlserver_term(sql_ctx).RDMe ODBC API Reference Guide      sparams.         sStatus = rdmsqlserver_init(&sparams.tfs_type= tfsType (). &sql_finished). h" Libraries Library Name rdmsqlserver11 Description RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies. this function will return immediately. must have been obtained through a rdmsqlserver_initcall. This parameter may be NULL if it won't be used. the rdmsqlserver_stopfunction must be used. Description This function begins the execution of the RDM SQL server listening and connection threads. To terminate the server cleanly at a later time. sql_ctx. This allows an application to know when the TFS listening threads have terminated. start a new thread for processing utility functionality. This function will also start the TFS listening threads unless rdmsqlserver_init what started with the SQL_PARAMS struct member no_tfsrun set to TRUE. Required Headers #include "rdmsqlserver. The sql_done parameter is set to 0 by rdmsqlserver_start. and will be set to 1 if the rdmsqlserver utility with -stop option has signaled the server to shut down. This allows the calling program to proceed with other calls to the SQL functions. RDM ODBC API Reference 168 . When threaded is FALSE. The handle. If threaded is TRUE.RDMe ODBC API Reference Guide rdmsqlserver_start Begin execution of RDM SQL server listening and connection threads Prototype int32_t rdmsqlserver_start(         RDMSQL_CTX *sql_ctx. Set to TRUE when server thread has terminated and cleaned up. enabling the connection of other SQL clients in this process. this function will not return unless there is an error or the RDM SQL server has been externally signaled for termination. Parameters sql_ctx threaded rep_done (input) (input) (input) Handle returned from a successful rdmsqlserver_init If TRUE.         DB_BOOLEAN  threaded         uint16_t    rep_done). no_tfsrun= TRUE.      sparams.verbose= FALSE.docroot= get_tfsDocroot ().         sparams.      }  RDM ODBC API Reference 169 .tfs_type= tfsType ().          if (sStatus == S_OKAY) {                 /* The main part of your application */                 (void) rdmsqlserver_term(sql_ctx).      if (sStatus == S_OKAY) {          sStatus = rdmsqlserver_run(sql_ctx.      sparams.      SQL_PARAMS sparams.rd_only= get_tfsReadOnly (). okay Invalid replication handle provided generic tx_ error TCP/IP listen failure in TFS out of memory invalid NULL parameter See Also rdmsqlserver_init rdmsqlserver_stop rdmsqlserver_term SQLConnect d_tfsrun Example static RDMSQL_CTX *sql_ctx = NULL.      sparams. &sql_finished).      sparams.        static uint16_t sql_finished = 0.      sparams.         sStatus = rdmsqlserver_init(&sparams.      sparams.RDMe ODBC API Reference Guide Return Codes Value 0 -43 -200 -216 -904 -924 Name S_OKAY S_INVREPHANDLE S_TX_ERROR S_TX_LISTEN S_NOMEMORY S_INVNULL Description normal return. TRUE.      sparams. &sql_ctx).port= get_tfsPort ().stdout_file= NULL.          }          (void) rdmsqlserver_term(sql_ctx).no_disk= get_tfsNoDisk (). RDMe ODBC API Reference Guide rdmsqlserver_stop Terminate RDM SQL Server listening and connection threads Prototype int32_t rdmsqlserver_stop(         RDMSQL_CTX *sql_ctx) Parameters sql_ctx (input) Handle returned from a successful rdmsqlserver_init Description This function stops the execution of the RDM SQL server listening and connection threads. Calling rdmsqlserver_start. This function will also stop the TFS listening and connection threads unless rdmsqlserver_init what started with the SQL_PARAMS struct member no_tfsrun set to TRUE. if successful.h" Libraries Library Name rdmsqlserver11 Description RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies. Required Headers #include "rdmsqlserver. requires a call to rdmsqlserver_stop. unless they have already been terminated. On successful termination all threads initiated by rdmsqlserver_start have been terminated. Return Codes Value 0 Name S_OKAY Description normal return. okay See Also rdmsqlserver_start rdmsqlserver_term d_tfsstop RDM ODBC API Reference 170 . verbose= FALSE.no_tfsrun= TRUE.      sparams.docroot= get_tfsDocroot (). TRUE.          }          (void) rdmsqlserver_term(sql_ctx).stdout_file= NULL.          if (sStatus == S_OKAY) {                 /* The main part of your application */                 (void) rdmsqlserver_term(sql_ctx).      sparams.      sparams.      sparams.      }  RDM ODBC API Reference 171 .      sparams.      SQL_PARAMS sparams. &sql_ctx).      if (sStatus == S_OKAY) {          sStatus = rdmsqlserver_run(sql_ctx. &sql_finished).      sparams.tfs_type= tfsType ().      sparams.no_disk= get_tfsNoDisk ().        static uint16_t sql_finished = 0.RDMe ODBC API Reference Guide Example static RDMSQL_CTX *sql_ctx = NULL.         sStatus = rdmsqlserver_init(&sparams.rd_only= get_tfsReadOnly ().port= get_tfsPort ().         sparams. This function will also terminate the TFS unless one was already started before the rdmsqlserver_init was called and that instance have not been signaled for termination.h" Libraries Library Name rdmsqlserver11 Description RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies.RDMe ODBC API Reference Guide rdmsqlserver_term Terminate a RDM SQL Server Prototype int32_t rdmsqlserver_term(         RDMSQL_CTX *sql_ctx) Parameters sql_ctx (input) Handle returned from a successful rdmsqlserver_init Description Call rdmsqlserver_term to terminate a RDM SQL server that was previously started with rdmsqlserver_initThis function must be called prior to termination but after any rdbc API function calls if rdmsqlserver_init was called. Required Headers #include "rdmsqlserver. okay See Also rdmsqlserver_init rdmsqlserver_stop d_tfsterm RDM ODBC API Reference 172 . Return Codes Value 0 Name S_OKAY Description normal return.      sparams.      if (sStatus == S_OKAY) {          sStatus = rdmsqlserver_run(sql_ctx.verbose= FALSE. &sql_ctx).      sparams.rd_only= get_tfsReadOnly ().stdout_file= NULL.      sparams.      sparams.      sparams.docroot= get_tfsDocroot ().port= get_tfsPort ().      sparams.          }          (void) rdmsqlserver_term(sql_ctx).      sparams.no_disk= get_tfsNoDisk ().RDMe ODBC API Reference Guide Example static RDMSQL_CTX *sql_ctx = NULL.        static uint16_t sql_finished = 0.      }  RDM ODBC API Reference 173 .         sparams.tfs_type= tfsType ().          if (sStatus == S_OKAY) {                 /* The main part of your application */                 (void) rdmsqlserver_term(sql_ctx). TRUE.         sStatus = rdmsqlserver_init(&sparams. &sql_finished).no_tfsrun= TRUE.      SQL_PARAMS sparams. statement. Function failed due to an invalid environment. It checks the return code of the function to determine if the end of the result set was reached (SQL_NO_DATA). the following code calls SQLFetch to retrieve the rows in a result set. connection. No more data was available.    } else if (rc == SQL_ERROR) {       // Call function to display error information. if any. This code is returned only when the handle is a null pointer or is the wrong type. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. such as when parameter data is sent at execution time or additional connection information is required. or descriptor handle. SQLHSTMT    hstmt. All other return codes provide run-time information. or if an error occurred (SQL_ERROR). This indicates a programming error.RDMe ODBC API Reference Guide Return Codes ODBC Each function in ODBC returns a code.     while ((rc=SQLFetch(hstmt)) != SQL_NO_DATA) {      if (rc == SQL_SUCCESS_WITH_INFO) {       // Call function to display warning information. Function failed. if any warning information was returned (SQL_SUCCESS_WITH_INFO). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. }   The return code SQL_INVALID_HANDLE always indicates a programming error and should never be encountered at run time. 174 SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA SQL_NEED_DATA Return Codes ODBC . known as its return code. possibly with a nonfatal error (warning). which indicates the overall success or failure of the function.       break. No additional information is available from SQLGetDiagRec or SQLGetDiagField. such as when a statement handle is passed for an argument that requires a connection handle. although SQL_ERROR may indicate a programming error. The following table defines the return codes. SQLRETURN   rc. The application calls SQLGetDiagField to retrieve additional information from the header record. For example. More data is needed. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. The contents of any output arguments to the function are undefined. Function completed successfully.    }    // Process row. Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO Description Function completed successfully. RDMe ODBC API Reference Guide ODBC C Data Types The C data type is specified in the SQLBindCol and SQLGetData functions with the TargetType argument and in the SQLBindParameter function with the ValueType argument. } TIME_STRUCT. The table also lists the ODBC C data type that corresponds to each identifier and the definition of this data type. The following table lists valid type identifiers for the C data types. } DATE_STRUCT.     SQLUSMALLINT day.[a] struct tagTIME_STRUCT  {     SQLUSMALLINT  hour. It can also be specified by calling SQLSetDescField to set the SQL_DESC_CONCISE_TYPE field of an ARD or APD. or by calling SQLSetDescRec with the Type argument (and the SubType argument if needed) and the DescriptorHandle argument set to the handle of an ARD or APD. C type identifier SQL_C_CHAR SQL_C_WCHAR SQL_C_SSHORT SQL_C_USHORT SQL_C_SLONG SQL_C_ULONG SQL_C_FLOAT SQL_C_DOUBLE SQL_C_BIT SQL_C_STINYINT SQL_C_UTINYINT SQL_C_SBIGINT SQL_C_UBIGINT SQL_C_BINARY SQL_C_TYPE_DATE ODBC C typedef SQLCHAR * SQLWCHAR * SQLSMALLINT SQLUSMALLINT SQLINTEGER SQLUINTEGER SQLREAL SQLDOUBLE.     SQLUSMALLINT second.[a] struct tagTIMESTAMP_ STRUCT {     SQLSMALLINT year. SQL_C_TYPE_TIME SQL_TIME_STRUCT SQL_C_TYPE_TIMESTAMP SQL_TIMESTAMP_STRUCT ODBC C Data Types 175 .     SQLUSMALLINT  month.     SQLUSMALLINT day.     SQLUSMALLINT minute.     SQLUSMALLINT  month. SQLFLOAT SQLCHAR SQLSCHAR SQLCHAR SQLBIGINT SQLUBIGINT SQLCHAR * SQL_DATE_STRUCT C type unsigned char * wchar_t * int16_t uint16_t int32_t uint32_t float double unsigned char int8_t uint8_t int64_t uint64_t unsigned char * struct tagDATE_STRUCT  {     SQLSMALLINT year. RDMe ODBC API Reference Guide C type identifier ODBC C typedef C type     SQLUSMALLINT  hour.     SQLUSMALLINT second. (See Constraints of the Gregorian Calendar later in this appendix.999 (1 less than 1 billion). and second fields in the datetime C data types must conform to the constraints of the Gregorian calendar. ODBC C Data Types 176 .000. for a millionth of a second (one microsecond) is 1. and for a billionth of a second (one nanosecond) is 1. For example.000. [a] [a] The values of the year.000. minute. the value of the fraction field for a half-second is 500.     SQLUINTEGER fraction. day.000. for a thousandth of a second (one millisecond) is 1.999.     SQLUSMALLINT minute. hour.000.) [b] The value of the fraction field is the number of billionths of a second and ranges from 0 through 999. month.[b] } TIMESTAMP_STRUCT. RDMe ODBC API Reference Guide Registering RDM ODBC Driver Overview On Microsoft Windows. The user will be able to configure the default DSN entry or create one or more new DSN entries as necessary.   6. Windows 7 is used for this purpose." Click "Administrative Tools." A dialog box that looks like this should be displayed (Figure 1)." Make sure your "View By" selection shows "Category.   5. the RDM ODBC Driver will be registered with Microsoft ODBC Driver Manager (ODBC DM). Click "Control Panel.   3. The registration will be performed automatically as part of the product installation.   4. take the following steps." Double-click "Data Sources (ODBC). This allows any application built with the Microsoft ODBC libraries to access RDM databases through ODBC DM.   2.  1. The registration will create one default Data Source Name (DSN) entry for the RDM ODBC Driver. Figure 1: ODBC Data Source Administrator Registering RDM ODBC Driver 177 ." Click "System and Security.  Click the Start Button on the Windows task bar. Opening the ODBC Driver Manager To access the registered ODBC driver entries. Options Working with Default Databases Figure 3: Database Configuration Registering RDM ODBC Driver 178 ." Description is a text description of the DSN entry." Each tab its own default entry for RDM. such as the driver connection type. click "Databases.RDMe ODBC API Reference Guide Configuring the default DSN entry To configure the default DSN entry for RDM ODBC." "System DSN" or "File DSN") and click "Configure. Changes made with the entry in one tab will not affect those in other tabs. The "ODBC Raima Database Manager Setup" dialog box will be displayed (Figure 2). To change the value. type in the desired text in the edit box and click "OK. Figure 2: ODBC RDM Setup Data Source Name Description Databases Data Source Name is a unique identifier of the DSN entry. RDM ODBC will open the specified databases once it successfully connects to the RDM server. To add.” The RDM ODBC Driver requires that one or more default databases be specified with ODBC DM. highlight the entry named “RDM” on one of the DSN tabs ("User DSN. To change the value." The "Database Configuration" dialog will be displayed (Figure 3). The default value is "RDM". type in the desired text in the edit box and click “OK. The "ODBC RDM Setup" dialog will expand as shown in Figure 5. modify or remove default databases. Click the "Options" button to configure the advanced options. When you click "Add" to add a new default database. When finished. highlight it and click "Remove." To remove an existing database. TFServer the database is stored on. Modify the Server and Port Number values if necessary. the value specified here will be used as the default server name. modify the Name. The dialog box will expand as follows." To modify an existing default database.RDMe ODBC API Reference Guide Default Server Default Server is the default alias of the RDM TFServer the database is stored on. Registering RDM ODBC Driver 179 ." Clicking "Add" or "Modify" will display the "New/Modify Database" dialog box. type the desired name in the Name edit box. the value specified here will be used as the default TCP/IP port number. click "OK. Default Port Number To add a new database. Server and Port Number entries as necessary. click "OK. Default Port Number is the default TCP/IP port number the RDM TFServer is listening on. The "New Database" dialog box will be displayed (Figure 4). Figure 4: New Database To add a new default database. highlight the database to modify and click "Modify. When you click "Add" to add a new default database. click "Add. When finished." Changing the Advanced Options Click the "Options" button on the "ODBC Raima Database Manager Setup" dialog box (shown in Figure 2) in order to access the advanced configuration options." To modify an existing database. Some third-party ODBC tools may require this option to be set one way or the other in order to access RDM databases." "System DSN" or "File DSN") and click "Add." This option enables/disables the schema name support in the RDM ODBC Driver. This value is ignored when the connection type is "Local. Specify the name of the host where the remote server is running here when selecting the "Remote" connection type." Change this option to "Remote" in order to connect to a remote server.RDMe ODBC API Reference Guide Figure 5: ODBC RDM Setup with Advanced Options Connection Type The RDM ODBC Driver allows the application to access RDM databases locally through TFServer or remotely through our remote server (called rdmsqlserver)." The "Create New Data Source" dialog box will be displayed (Figure 6). highlight the entry named "RDM" on one of the DSN tabs ("User DSN. Registering RDM ODBC Driver 180 . We recommend that this option not be changed unless your ODBC tool does not correctly work with RDM ODBC with the default value." The default value is "localhost. The support is disabled by default. Remote Server Use Database Name As Adding a new DSN entry To add a new DSN entry for RDM ODBC. The default connection type is "Local. Figure 7: Confirmation Dialog Click "Yes" to remove the selected DSN entry. See the Configuring the default DSN Entry” section for details on the options." "System DSN" or "File DSN") and click "Remove. highlight the entry you wish to remove on one of the DSN tabs ("User DSN.RDMe ODBC API Reference Guide Figure 6: Create New Data Source Highlight "RDM" and click "Finish. Registering RDM ODBC Driver 181 ." The confirmation dialog will be displayed (Figure 7)." The "ODBC RDM Setup" dialog box (Figure 2) will be displayed. Removing an existing DSN entry To remove an existing DSN entry for RDM ODBC. you must first start an instance of rdmsqlserver in the location of the document root.exe -d c:\database\  Registering RDM ODBC Driver 182 . or by passing in the location with -d. rdmsqlserver will start it's own TFS internally.  cd database\ > >start rdmsqlserver.exe   or >start rdmsqlserver.RDMe ODBC API Reference Guide Using the ODBC Driver In order to use the RDM ODBC Driver. Note that by default. All RDM Embedded database input and output is performed using a cache. compound key A key field composed of any combination of fields (not necessarily contiguous) from a record. Two important properties of a B-tree are that all nodes are at least half-full and that the tree is always balanced (that is. a B-tree is a fast data-indexing method that organizes the index into a multi-level set of nodes. connect The process of inserting a member record occurrence into a set occurrence. C cache A set of buffers used to optimize database input and output operations. combine The concatenation of the members of two or more set types into one set type.RDMe ODBC API Reference Guide Glossary B B-tree Also called a multiway tree. in which database operations are performed. Each node contains a sorted array of key values (the indexed data). A well-organized B-tree will have only three or four levels. commit The point at which database changes made during a single transaction are actually written to the database files. current owner table. The currency tables consist of the current member table. Glossary 183 . currency tables A table of database addresses maintained by the RDM Embedded runtime system for controlling record access and set navigation. Each field of a compound key may be stored in ascending or descending order. an identical number of nodes must be read in order to locate all keys at any given level in the tree). and the current record. buffer An in-memory store of data read from a disk file. Other terms used for field include: attribute. A field has associated with it attributes such as name. type (for example. data file An RDM Embedded file defined in a DDL specification that contains occurrences of one or more record types. d_findnm. or d_findpm). the database address of a record occurrence that is a valid member of that set. the current member of a set is the last record accessed using a set navigation function (d_findfm. D data field A field represents the basic unit of information storage in a database and is always defined to be an element of a record. frequently referred to as a DB_ADDR. RDM Embedded's Database Definition Language has been designed to be used with the C programming language. char or int). current record Contains the database address of the most recently accessed record instance. Glossary 184 . for each set. current owner Contains for each set. Composed of two numbers: the file index and the slot within the file. and length. the current owner of a set is established using the set navigation function d_findco or by using a currency manipulation function. or column. database An organized collection of related files. Usually. the database address of a record occurrence that is a valid owner of that set. The current database is changed by the database number function argument or by function d_setdb. Usually. database definition language A programming-like language used to define the structure and content of a database. d_findlm. current member Contains.RDMe ODBC API Reference Guide current database The database that is currently accessible by the RDM Embedded runtime functions when multiple databases have been opened. entity. database address The location in the database of a record occurrence. Either 4 or 8 bytes long. 1). dictionary A repository containing a definition of the content and structure of a database. In RDM Embedded. Glossary 185 .0. dbrep. a server (tfserver.RDMe ODBC API Reference Guide DDL A programming-like language used to define the structure and content of a database.0. RDM Embedded's Database Definition Language has been designed to be used with the C programming language. or dbrepsql) may be located through the domain name of the computer it is running on. "localhost" always refers to the same computer as the application is running on (IP address is always 127. no files outside of this path may be accessed. A special domain name. dbmirror. The "ping" utility must be able to locate the IP address associated with this name. domain name The "name" of a computer which has visibility to another computer. document root The path to the directory under which all files will be stored. disconnect The process of removing a member record from a set occurrence. This may be a published name available on DNS servers and across the Internet. together with the port on which it is listening. It is used by the RDM Embedded runtime library functions for accessing and manipulating information from that database. Sometimes called deadly embrace. destimation database The db_REVISE-created database that stores the specified revisions. deadlock A situation in which multiple processes accessing the same database each hold locks needed by the other processes in such a way that none of the processes can proceed. derived revision A revision that can be derived from a comparison of the source and destination database dictionary files. delete chain A linked list containing deleted records or nodes to be reused when a new record or node is created. or an internal network name visible only within a workgroup. Within the domain of one TFS. K key A field through which rapid and/or sorted access to a record is desired. files are used to store records and keys. entity. F field A field represents the basic unit of information storage in a database and is always defined to be an element of a record. Other terms used for field include: attribute. Glossary 186 . A field has associated with it attributes such as name. I index A set of key values through which rapid retrieval of a record is provided. H hierarchical database model A data representation in which the relationships between record types are formed from parent-child structures. In RDM Embedded. type (for example. The term is often used synonymously with key file. similar to the index of a book.RDMe ODBC API Reference Guide E environment variable A programmer-specified operating system parameter that is used to identify configuration information to the runtime system. char or int). and length. such that a record type may have many child relationships but only one parent relationship. J join The creation of one record type from a hierarchy of record types. or column. file The primary physical storage unit into which a database is organized. It is the default domain name used by RDM Embedded utilities and runtime library. there are many related occurrences of type A. lock A multi-user database synchronization mechanism. A and B. many-to-many relationships can be implemented using two one-to-many sets through a third. Locks can be applied to the entire database or to files. One occurrence of the owner record type is related to many occurrences of a member record type. It may. there are many related occurrences of type B and. such that for each occurrence of type A. in fact. for each occurrence of type B.RDMe ODBC API Reference Guide key file A file that only contains keys. Logging is used to support the ability to perform a recovery in the event a failure occurs during a commit. intersection record type. contain more than one index because multiple key types can be contained in a single RDM Embedded key file. previous member in the set. Glossary 187 . L localhost A special Domain Name that always refers to the computer on which the application software is running. member of set Specifies a one-to-many relationship between record types. M many-to-many relationship A relationship between two record types. member pointer Stores set membership linkage information. logging The process of making a copy of the database changes made during a transaction prior to a commit. Each one contains the database addresses of the owner record. key scan The process of performing an ordered traversal through all (or a subset of all) occurrences of a given key field. Also called a set type. In RDM Embedded. and next member in the set. used to prevent simultaneous updates to shared data. There is one member pointer stored with a record per set for which the record is a member. Multiple set membership distinguishes the Network database model from the Hierarchical database model. node A component of a B-tree. owner of set Specifies a one-to-many relationship between record types. consisting of a page of sorted keys stored in a key file. where the current occurrence of a record type is used to bookmark the position on a record type scan. P page Files are blocked into contiguous fixed-length segments called pages. although the current record will also be set by the scanning functions. A page is the unit of database I/O performed in RDM Embedded. d_recprev. Also called a set type. key scanning. Record occurrences are ordered by their physical appearance in a data file.RDMe ODBC API Reference Guide N navigation The process of retrieving records from a database by moving through various navigational methods. path name The sequence of directories in a hierarchical file system that must be traversed to locate a particular file. Glossary 188 . where any given record type may be the owner of multiple types of sets and the member of multiple types of sets. normalize The elimination of redundant record instances that own a new set. d_recnext. O occurrence One record instance within a record type. One occurrence of the owner record type is related to many occurrences of a member record type. d_reclast). resulting in a one-tomany relationship. specifically associated with record type scanning (d_recfrst. network database model A data representation in which the relationships are explicitly defined and maintained through sets of owner/members. and record-type scanning. Methods include set navigation. The current occurrence is not the same as the current record. In a C program. Q queue A first-in-first-out waiting list.168. each server (tfserver. port Together with an IP address. Jim. An employee record occurrence could be "name: Jones. recovery The process of completing the transaction of a process that failed during a commit.com is a domain name. An individual execution of an RDM Embedded application program. When the locked resource becomes available. record occurence One individual instance in a database of a record of a particular type. employee_id. A database consists of many occurrences of many different record types. dbmirror.140. dbrep or dbrepsql) identifies the port number that should be used to locate it. and pay. and its IP address is 198. a pointer is data stored in a record occurrence that provides the necessary information for locating related record occurrences. R record Used synonymously with record type or record occurrence depending on the context in which the term is used.RDMe ODBC API Reference Guide pointer In a database. an employee record type may consist of the fields name. process An independently executing task or program. The IP address is normally obtained through a domain name lookup (e. tfs.200). Lock requests for a locked resource will be placed at the end of a queue. a port number uniquely identifies an endpoint by which a TCP/IP connection can be made to another program. the first lock request on the queue will be granted. a pointer is a variable that contains a memory address. pay: 3400".g. job_title. For example. In RDM Embedded. Glossary 189 . employee_id: c87101. projection The placement of fields from one record type into one or more new record types. job_title: engr.raima. Glossary 190 . respectively. with results (return code. Tables and columns are analogous to RDM Embedded records and fields. RPC A programming mechanism that makes a library call appear to operate in the program space of an application. return parameter values) transferred back to the caller. A client application places a function identifier and parameter contents into a packet that is first transferred to the server. Revision Definition Language The RDL supplies information to db_REVISE that cannot be derived from a comparison of the source and destination dictionary files. return parameter values) transferred back to the caller. runtime system The RDM Embedded C language library functions that perform all of the database access required by an application program while it is executing.RDMe ODBC API Reference Guide redundant data Identical data that is stored in multiple locations in a database. A client application places a function identifier and parameter contents into a packet that is first transferred to the server. each composed of one or more columns. even though the actual function exists in the program space of another program (called a "server"). remote procedure call A programming mechanism that makes a library call appear to operate in the program space of an application. root node The top or start node of a B-tree. Inter-table relationships are defined through use of common column names and data. with results (return code. S schema A conceptual model of the structure of a database that defines the data contents and relationships. relational database model A data representation in which a database is viewed as consisting of two-dimensional tables. Typically used to form relationships between tables in a relational database management system. even though the actual function exists in the program space of another program (called a "server"). A database definition language specification is an implementation of a particular schema. slot A position in a data or key file for storage of a single record or key occurrence. static revision A revision that can be performed without changing the existing database content or structure. source database The database containing the data that is to be revised. specified revision A revision requiring specification by an RDL statement. the database address of the first member record occurrence. system record A special record type used to define the "top" record in a network database. set scan The process of performing an ordered traversal through all (or a subset of all) member record occurrences of a given set occurrence. split The separation of a multiple-member set type into two or more set types. set occurence An individual instance of a set in which one owner record occurrence has one or more member record occurrences connected to it. the system Glossary 191 . There is one set pointer stored with a record per set for which the record is an owner. updates to shared data are performed serially. There is only one occurrence of the system record in a database. in a multi-user database environment. one user at a time. Also called a set type. and the database address of the last member record occurrence in the set. This database is used in a read-only manner. synchronization The process of ensuring that. One occurrence of the owner record type is related to many occurrences of a member record type. It is defined by naming "system" as a set owner in one or more set definitions in the DDL.RDMe ODBC API Reference Guide set Specifies a one-to-many relationship between record types. set pointer Stores set ownership linkage information. Each one contains a count of the number of members in the set. When a database is opened. with all locks and database updates associated with the transaction. A task represents one user in a multi-user environment. T task In an RDM Embedded Application. Differentiated from a Process in that a process may contain one or more threads. transaction A group of related database changes that are written to the database as a single unit during a commit. The TFS may also be linked directly into an application in order to avoid the RPC overhead of calling a separate server. The tfserver utility links to the TFS to allow it to run as a separate utility. is set as the current owner of all sets for which it is named as owner. The logical consistency of a database is maintained by placing all related updates within transactions. It is used to avoid deadlock. The TFS may also be linked directly into an application in order to avoid the RPC overhead of calling a separate server. and is treated as a separate user in a multi-user environment. Threads within the same process share common (or global) data but have their own stacks. It must be allocated through the d_opentask function and closed through the d_closetask function. if it exists. transactional file server A software component within the RDM Embedded system that maintains safe multi-user transactional updates to a set of files. which keeps track of the thread's context. timeout An event that occurs when a lock request has waited on a queue longer than a pre-determined amount of time. TFS A software component within the RDM Embedded system that maintains safe multi-user transactional updates to a set of files. A task can also represent one database transaction. In RDM Embedded Applications. and responds to page requests. Glossary 192 . each thread must be associated with its own task variable. and responds to page requests. a task is a block of allocated memory that stores the complete database context for a thread of execution. It may not be a set member.RDMe ODBC API Reference Guide record. thread An independent flow of control within a computer operating system. The tfserver utility links to the TFS to allow it to run as a separate utility. RDMe ODBC API Reference Guide W working database A temporary database created by db_REVISE for use only during the database revision process. Glossary 193 . db_REVISE removes the working database when the revision process is complete. RDMe ODBC API Reference Guide Index R rdmsqlserver_init 165 rdmsqlserver_start 168 rdmsqlserver_stop 170 rdmsqlserver_term 172 S SQLAllocHandle 32 SQLBindCol 34 SQLBindParameter 36 SQLCancel 38 SQLCloseCursor 40 SQLColAttribute 42 SQLColAttributeW 42 SQLColumns 45 SQLColumnsW 45 SQLConnect 47 SQLConnectW 47 SQLCopyDesc 50 SQLDescribeCol 52 SQLDescribeColW 52 SQLDescribeParam 54 SQLDescribeStmt 56 SQLDisconnect 59 SQLDriverConnect 61 SQLDriverConnectW 61 SQLEndTran 64 SQLExecDirect 66 Index 194 . RDMe ODBC API Reference Guide SQLExecDirectW 66 SQLExecute 68 SQLExtendedTran 70 SQLFetch 74 SQLFetchScroll 76 SQLForeignKeys 78 SQLForeignKeysW 78 SQLFreeHandle 80 SQLFreeStmt 82 SQLGetConnectAttr 84 SQLGetConnectAttrW 84 SQLGetCursorName 86 SQLGetCursorNameW 86 SQLGetData 88 SQLGetDescField 90 SQLGetDescRec 92 SQLGetDiagField 94 SQLGetDiagFieldW 94 SQLGetDiagRec 96 SQLGetDiagRecW 96 SQLGetEnvAttr 98 SQLGetFunctions 100 SQLGetInfo 102 SQLGetStmtAttr 104 SQLGetTypeInfo 106 SQLMoreResults 108 SQLNativeSql 110 SQLNumParams 112 SQLNumResultCols 114 Index 195 . RDMe ODBC API Reference Guide SQLParamData 116 SQLPrepare 118 SQLPrepareW 118 SQLPrimaryKeys 120 SQLPrimaryKeysW 120 SQLProcedureColumns 122 SQLProcedureColumnsW 122 SQLProcedures 124 SQLProceduresW 124 SQLPutData 126 SQLRowCount 128 SQLSetConnectAttr 130 SQLSetConnectAttrW 130 SQLSetCursorName 137 SQLSetCursorNameW 137 SQLSetDescField 139 SQLSetDescFieldW 139 SQLSetDescRec 141 SQLSetDescRecW 141 SQLSetEnvAttr 143 SQLSetError 146 SQLSetStmtAttr 148 SQLSpecialColumns 155 SQLSpecialColumnsW 155 SQLStatistics 158 SQLStatisticsW 158 SQLTables 160 SQLTablesW 160 SQLTransactStatus 162 Index 196 .