Raima Database Manager 11.0

Transcription

1 Raima Database Manager 11.0 ODBC API Reference Guide 1

2 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 3 Introduction 7 Advanced Topics 23 RDM ODBC API Reference 29 Return Codes ODBC 174 ODBC C Data Types 175 Registering RDM ODBC Driver 177 Glossary 183 Index 194 2

3 Contents Contents 3 Introduction 7 Comparing the ODBC API with the Native RSQL API 7 Basic ODBC Application Steps 9 Allocating Handles 12 Environment Handle 12 Connection Handle 12 Statement Handle 12 Descriptor Handle 12 Connecting to a Data Source 14 Choosing the Connection Type 15 Setting the Data Source Name 15 Establishing a Connection 16 Executing an SQL Statement 18 Allocating a Statement Handle 18 Preparing an SQL Statement 18 Executing an SQL Statement 18 Committing or Rolling Back Transactions 19 Retrieving the Result Set 21 Binding Columns 21 Fetching Columns 21 Advanced Topics 23 Working with Parameters 23 Fetching Multiple Rows at Once 25 Retrieving Data in Parts 27 RDM ODBC API Reference 29 SQLAllocHandle 32 SQLBindCol 34 Contents 3

4 SQLBindParameter 36 SQLCancel 38 SQLCloseCursor 40 SQLColAttribute 42 SQLColumns 45 SQLConnect 47 SQLCopyDesc 50 SQLDescribeCol 52 SQLDescribeParam 54 SQLDescribeStmt 56 SQLDisconnect 59 SQLDriverConnect 61 SQLEndTran 64 SQLExecDirect 66 SQLExecute 68 SQLExtendedTran 70 SQLFetch 74 SQLFetchScroll 76 SQLForeignKeys 78 SQLFreeHandle 80 SQLFreeStmt 82 SQLGetConnectAttr 84 SQLGetCursorName 86 SQLGetData 88 SQLGetDescField 90 SQLGetDescRec 92 SQLGetDiagField 94 SQLGetDiagRec 96 SQLGetEnvAttr 98 Contents 4

5 SQLGetFunctions 100 SQLGetInfo 102 SQLGetStmtAttr 104 SQLGetTypeInfo 106 SQLMoreResults 108 SQLNativeSql 110 SQLNumParams 112 SQLNumResultCols 114 SQLParamData 116 SQLPrepare 118 SQLPrimaryKeys 120 SQLProcedureColumns 122 SQLProcedures 124 SQLPutData 126 SQLRowCount 128 SQLSetConnectAttr 130 SQLSetCursorName 137 SQLSetDescField 139 SQLSetDescRec 141 SQLSetEnvAttr 143 SQLSetError 146 SQLSetStmtAttr 148 SQLSpecialColumns 155 SQLStatistics 158 SQLTables 160 SQLTransactStatus 162 Summary Listing of RDM SQL Server API Functions 164 rdmsqlserver_init 165 rdmsqlserver_start 168 Contents 5

6 rdmsqlserver_stop 170 rdmsqlserver_term 172 Return Codes ODBC 174 ODBC C Data Types 175 Registering RDM ODBC Driver 177 Overview 177 Opening the ODBC Driver Manager 177 Configuring the default DSN entry 178 Working with Default Databases 178 Changing the Advanced Options 179 Adding a new DSN entry 180 Removing an existing DSN entry 181 Using the ODBC Driver 182 Glossary 183 Index 194 Contents 6

7 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. 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. Even though ODBC was developed by Microsoft for use on the Windows operating system, the RDM ODBC implementation is available on every OS platform that RDM supports. All of the functions are prefixed with "SQL". ODBC data types and constant declarations are provided in the standard header files: sql.h for basic ODBC functionality; sqlext.h for basic and extended ODBC functionality, sqlrext.h for basic, extended, and RDM-specific functionality. The RDM ODBC implementation is based on version 3.51 of the Microsoft ODBC specification. 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. Not all ODBC functions have an equivalent RSQL API function. Some, (e.g., SQLTables, SQLColumns, 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. Also note that those functions that do have a RSQL API equivalent do not have the same function arguments. However, the basic operational approach (e.g., function calling sequence) that is used in an ODBC application is also needed in a RSQL application. ODBC API functions that are not listed do not have a RSQL API counterpart. Table 2. ODBC to RDM SQL API Function Mapping ODBC API Function RSQL Function Comments SQLAllocHandle rsqlallocconn rsqlallocstmt Allocation of connection and statement handles are made through separated functions. There is no environment handle. SQLBindCol n/a Column result values are not bound but are returned by rsqlfetch or rsqlgetdata. SQLBindParameter rsqlbindparam SQLCancel n/a Call rsqlclosestmt to cancel statement processing. SQLCloseCursor rsqlclosestmt SQLColAttribute rsqlgetcoldescr SQLColumns n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. SQLConnect n/a Connections are initiated when rsqlallocconn is called. Databases are opened through calls to rsqlopendb or rsqlopencat. SQLDescribeCol rsqlgetcoldescr SQLDescribeParam rsqlgetparamdescr SQLDescribeStmt rsqlgetstmtdescr SQLDescribeStmt is a Raima Inc. extension. SQLDisconnect n/a Connections are closed when rsqlfreeconn is called. SQLEndTran rsqltranscommit rsqltransrollback SQLExecDirect rsqlexecdirect Introduction 7

8 ODBC API Function RSQL Function Comments SQLExecute rsqlexecute SQLExtendedTran rsqltransstart rsqltranssavepoint rsqltransrelease rsqltranscommit rsqltransrollback We believe that separate calls represent a better API design than a single call with a control variable SQLFetch rsqlfetch Note that the rsqlfetch returns the column result values-no bound columns. SQLForeignKeys n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. SQLFreeHandle rsqlfreeconn rsqlfreestmt SQLGetConnectAttr rsqlgetautocommit rsqlgetdateformat Not all ODBC connection attributes have a RDM equivalent. Not all RDM connection attributes have an ODBC equivalent. rsqlgetdateseparator rsqlgetdeferblobmode rsqlgetreadonlytrmode SQLGetCursorName rsqlgetcursorname SQLGetData rsqlgetdata SQLMoreResults rsqlmoreresults SQLNumParams rsqlgetnumparams SQLNumResultCols rsqlgetnumresultcols SQLPrepare rsqlprepare SQLPrimaryKeys n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. SQLProcedures n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. SQLPutData rsqlputdata SQLRowCount rsqlgetrowcount SQLSetConnectAttr rsqlsetautocommit rsqlsetdateformat Not all ODBC connection attributes have a RDM equivalent. Not all RDM connection attributes have an ODBC equivalent. rsqlsetdateseparator rsqlsetdeferblobmode rsqlsetreadonlytrmode SQLSetCursorName rsqlsetcursorname SQLSetError rsqlseterrorcallback SQLSetError is a Raima Inc. extension. SQLSpecialColumns n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. SQLTables n/a Database meta-data information is available by executing select statements on the appropriate syscat virtual tables. SQLTransactStatus rsqltransstatus The advantage of using the native API instead of ODBC is that it is simpler and more efficient with a smaller footprint. However, ODBC is available and can certainly be used if DBMS independence and/or use of a standard SQL API is needed. Introduction 8

9 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. 1. Set up and initialize your application s use of the SQL API as follows. a. Call SQLAllocHandle to allocate your environment handle, which will be used in allocating your connection handle. b. Call SQLSetEnvAttr(hEnv, SQL_ATTR_ODBC_VERSION, *ODBC_VERSION,0). This will set the version of ODBC that you want to use with your database c. Call SQLAllocHandle again, but this time you are allocating your connection handle (hcon in the example below) d. Call SQLConnect to connect to the database e. Call SQLAllocHandle a third time to allocate your statement handle. You can allocate as many statement handles as you need in your application. Typically, you will need a statement handle for each statement that will be compiled once but potentially executed multiple times. f. Call SQLExecDirect("Open *database name*") in order to open your database. g. Call SQLSet* functions such as SQLSetConnectAttr to set up specific database attributes and operational parameters. 2. Prepare your application to execute SQL statements as follows. a. Call SQLPrepare to compile each of the statements that will need to be executed by your application. b. 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. At this point your application is execution ready. That means that your application will a. Call SQLExecute to execute the appropriate statements that implement the database access needs for each particular function. Alternatively you can call SQLExecDirect to both compile and execute a statement in a single call. Usually, you would only do this for statements that only need to be executed once. b. Possibly call SQLParamData and SQLPutData to process any needed data-at-exec blob parameters specified in insert and update statements. c. Call transaction statements using SQLExtendedTran in order to start the transaction, commit the transaction, create a savepoint, or rollback a transaction. d. Call SQLFetch to retrieve the result rows from an executed select statement. You may also need to call SQLGetData to retrieve blob data results a block at a time. Alternatively, if the select is updateable, 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. You will need to call SQLFreeStmt on a select for which you do not call SQLFetch through to the end of the result set. 4. When your application is ready to terminate you need to a. Call SQLFreeStmt or SQLFreeHandle for each statement handle allocated in step 1e. b. Call SQLFreeHandle for each allocated connection which automatically closes all open databases, terminates the connection and frees the connection handle and all its associated dynamically Introduction 9

10 allocated memory. c. Call SQLFreeHandle for your environment handle. 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. This can be seen with the common Hello World example. In the example below return codes are mostly ignored for simplicity. This will be ok because we know what the expected results are. /********************************************************************* ** HELLO WORLD SQL ** ** This document describes the process to create a simple database, insert a record ** containing a text field, read the text field from database and print it out. **********************************************************************/ #include <stdio.h> #include "sqlrext.h" /* The RDM SQL API. */ #define SQL_EMPSTR ((SQLCHAR *) "") /* any string */ int main( int argc, const char *const *argv) { SQLRETURN iret; /* holds return value, 0 is success */ SQLCHAR sz[32]; SQLHDBC hcon; /* connection handle */ SQLHSTMT hstmt; /* statement handle */ SQLHENV henv; /* environment handle */ SQLLEN ilen = 0; SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv); /* Allocates env handle */ SQLSetEnvAttr(hEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, 0); SQLAllocHandle(SQL_HANDLE_DBC, henv, &hcon); /* Allocates connection handle */ /* Connects to server */ SQLConnect(hCon, SQL_EMPSTR, SQL_NTS, SQL_EMPSTR, SQL_NTS, SQL_EMPSTR, SQL_ NTS); /* connects to database*/ SQLAllocHandle(SQL_HANDLE_STMT, hcon, &hstmt); /* Allocates statement handle */ SQLExecDirect(hStmt, (SQLCHAR *) "open hello_worldodbc", SQL_NTS); /* Opens the database */ /* Create a Hello World record */ SQLAllocHandle(SQL_HANDLE_STMT, hcon, &hstmt); /* allocates the statement handle */ SQLExecDirect(hStmt, (SQLCHAR *) "INSERT INTO info(mychar) VALUES('Hello Introduction 10

11 World!')", SQL_NTS); /* Commit the insert, transaction is started by the first insert statement. */ SQLEndTran(SQL_HANDLE_DBC,hCon,SQL_COMMIT); /* Query the database for the record created. */ SQLExecDirect(hStmt, (SQLCHAR *) "SELECT mychar FROM info",sql_nts); /* Bind SQL fields to program variables. */ SQLBindCol(hStmt,1,SQL_C_CHAR,sz,sizeof(sz),&iLen); /* Fetch data from database into program variables. */ SQLFetch(hStmt) ; printf("%s\n\n",sz); /* Free the SQL statement handle. */ (void) SQLFreeHandle(SQL_HANDLE_STMT,hStmt); /* Close the database. */ SQLDisconnect(hCon); /*lint!e534 */ /* Free the database handles. */ (void) SQLFreeHandle(SQL_HANDLE_DBC, hcon); (void) SQLFreeHandle(SQL_HANDLE_ENV, henv); return 0; } Introduction 11

12 Allocating Handles ODBC lets an application manage interactions with data sources through ODBC handles. An application tells the ODBC driver to allocate a handle by calling SQLAllocHandle. There are four types of ODBC handles. 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_ENV as the first argument in order to allocate an environment handle. An application must allocate an environment handle in order to access an RDM data source. Multiple environment handles can be allocated inside an application. Connection Handle A connection handle is the handle that manages resources and options specific to a connection to a 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. An application must allocate a connection handle in order to access an RDM data source. An application can allocate multiple connection handles on one environment handle in order to manage multiple connections to the same or different data sources. In a multi-thread environment, RDM ODBC requires that each thread have its own connection handle. Statement Handle A statement handle is the handle that manages resources and options specific to a particular SQL statement operation. 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. An application must allocate a statement handle in order to execute SQL statements against an RDM data source. An application can allocate multiple statement handles on one connection handle in order to execute different SQL statements on one data source. Operations such as positioned update and delete require the use of multiple statement handles on one connection. Descriptor Handle A descriptor handle is the handle that manages the detailed characteristics and information both an application and the ODBC driver use internally. There are two types of descriptors: application descriptors and implementation descriptors. An application descriptor stores information an application maintains for its operations. An implementation descriptor stores information the ODBC driver uses internally. Both application and implementation descriptors have two subcategories: parameter descriptors and row descriptors. Together, there are four types of descriptor handles as below. Application Parameter Descriptor APD An APD maintains information about a dynamic parameter an application uses when executing an SQL statement. Application Row Descriptor ARD An ARD maintains information about a row/column returned to an application when it fetches data from a data source. Introduction 12

13 Implementation Parameter Descriptor IPD An IPD maintains information about a dynamic parameter the ODBC driver uses internally when an application executes an SQL statement. Implementation Row Descriptor IRD An IRD maintains information about a row/column defined on a data source from which an application fetches data. All the four descriptors are implicitly allocated by the ODBC driver. 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, and tell the ODBC drivers to use them instead of the implicitly-allocated descriptors. Descriptors explicitly allocated by an application cannot be used as implementation descriptors (IPD and IRD). The following example illustrates how to allocate ODBC handles using SQLAllocHandle. Example 1 Allocating handles #include "sqlext.h" int main(void) { SQLRETURN rc; SQLHENV henv; SQLHDBC hdbc; /* Allocate an environment handle */ rc = SQLAllocHandle(SQL_HANDLE_ENV, NULL, &henv); if (SQL_SUCCEEDED(rc)) { /* Allocate a connection handle */ rc = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc); if (SQL_SUCCEEDED(rc)) { /* Connect to the local data source. The code for connecttodatasource is shown in the next section */ rc = connecttodatasource(hdbc); if (SQL_SUCCEEDED(rc)) { /* Do some database operations */ rc = rundboperations(hdbc); } (void) SQLDisconnect(hDbc); } (void) SQLFreeHandle(SQL_HANDLE_DBC, hdbc); } (void) SQLFreeHandle(SQL_HANDLE_ENV, henv); } return 0; Introduction 13

14 Connecting to a Data Source An application will use the connection handle it allocated in order to connect to an RDM data source, by calling SQLConnect. In RDM ODBC, an RDM data source can be a transaction file server (TFServer) or a remote server process (RDMSQLServer) that accesses the TFServer. A connection to a TFServer is called "local" connection, where the RDM ODBC Driver uses the local RDM SQL engine directly linked to it in order to interact with the target TFServer. 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, which has its own RDM SQL engine that in turn communicates with the target TFServer. A typical RDM ODBC application is illustrated in Figure 1 below. The application will connect to the default TFS and the SQL processing will be performed within the application process. Figure 1. Local Data Source The same RDM ODBC application can connect to an external RDM SQL engine by providing the remote connection attributes. The SQL processing will be performed within the RDMSQLServer process and the results returned to the application. 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; or, 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., database running on a PowerPC device being accessed by a remote Windows desktop). See the rdmsqlserver section for more information. Figure 2. Remote Data Source Introduction 14

15 Choosing the Connection Type An application can choose the type of connection it uses in two ways. First, 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. If the application specifies SQL_CT_LOCAL, the RDM ODBC Driver will attempt to establish a local connection. If SQL_CT_REMOTE is specified, the RDM ODBC Driver will use a remote connection. Alternatively, 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. If the SQL_ATTR_RDM_REMOTE_NAME attribute is set to a non-null, non-empty value, 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, and if the SQL_ATTR_RDM_ TFS_NAME attribute is set to a non-null, non-empty string, the RDM ODBC Driver will use a local connection. 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), the RDM ODBC Driver will rely upon the value specified for the first argument of SQLConnect. In that case, if the value is a non-null, non-empty string, the RDM ODBC Driver will use a remote connection. Otherwise, a local connection will be used. The SQL_ATTR_RDM_REMOTE_NAME and SQL_ATTR_TFS_NAME attributes are set to NULL by default. The SQL_ATTR_RDM_CONN_TYPE attribute is set to SQL_CT_UNKNOWN by default. Setting the Data Source Name In RDM ODBC, 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. If the connection type is explicitly set to remote (that is, by setting the SQL_ATTR_RDM_CONN_TYPE connection attribute to SQL_CT_REMOTE), the value stored in the SQL_ATTR_RDM_REMOTE_NAME connection attribute will be used as the data source name. If the value in the SQL_ATTR_RDM_REMOTE_NAME attribute is not set, the default name ("localhost") will be used. If the connection type is explicitly set to local (that is, by setting the SQL_ATTR_RDM_CONN_TYPE connection attribute to SQL_CT_LOCAL), the value stored in the SQL_ATTR_RDM_TFS_NAME connection attribute will be used as the data source name. If the value in the SQL_ATTR_RDM_TFS_NAME attribute is not set, the default name ("localhost") will be used. If the connection type is not explicitly set (that is, the SQL_ATTR_RDM_CONN_TYPE attribute is set to SQL_CT_ UNKNOWN), the value stored in the SQL_ATTR_RDM_REMOTE_NAME attribute will be used as the remote data source name. If the SQL_ATTR_RDM_REMOTE_NAME attribute is not set, the value stored in the SQL_ATTR_ RDM_TFS_NAME attribute will be used as the local data source name. If neither value is set, the value specified for the first argument of SQLConnect will be used as the remote data source name. If that value is not set, "localhost" will be used as the local data source name. Introduction 15

16 Establishing a Connection An application calls SQLConnect to establish a connection to an RDM data source. SQLConnect returns SQL_SUCCESS to let the application know a connection to the specified data source has been successfully established. SQLConnect returns SQL_ERROR when an error occurs, or SQL_SUCCESS_WITH_INFO if the operation succeeds but the RDM ODBC Driver returned diagnostic information that may include warnings. If SQLConnect returns a value other than SQL_SUCCESS, an application can call SQLGetDiagRec to retrieve the details of the diagnostics. The following examples illustrate how an application can establish a connection to a data source. Example 2 Setting a remote connection #include "sqlrext.h" /* RDM extension SQL header file */ SQLRETURN connecttodatasource( SQLHDBC hdbc) { SQLRETURN rc; /* Set connection type to remote */ rc = SQLSetConnectAttr(hDbc, SQL_ATTR_RDM_CONN_TYPE, (SQLPOINTER) SQL_CT_REMOTE, SQL_IS_UINTEGER); if (SQL_SUCCEEDED(rc)) { /* Since SQL_ATTR_RDM_REMOTE_NAME is not set, "localhost" will be used as the remote data source name. In this case, RDMSQLServer is running on the same computer as the application. */ rc = SQLConnect(hDbc, NULL, 0, NULL, 0, NULL, 0); } } return rc; Example 3 Using SQL_ATTR_RDM_REMOTE_NAME #include "sqlrext.h" /* RDM extension SQL header file */ SQLRETURN connecttodatasource( SQLHDBC hdbc) { SQLRETURN rc; /* This implicitly sets the connection type as local */ rc = SQLSetConnectAttr(hDbc, SQL_ATTR_RDM_TFS_NAME, (SQLPOINTER) "david-lnx", SQL_NTS); if (SQL_SUCCEEDED(rc)) { /* Since SQL_ATTR_RDM_CONN_TYPE is not set, "david-lnx" will be used as the local data source name. In this case, the TFServer is running on the computer whose hostname is "david-lnx" */ Introduction 16

17 } rc = SQLConnect(hDbc, NULL, 0, NULL, 0, NULL, 0); } return rc; Example 4 Using SQLConnect #include "sqlrext.h" /* RDM extension SQL header file */ SQLRETURN connecttodatasource( SQLHDBC hdbc) { SQLRETURN rc; /* Neither SQL_ATTR_RDM_CONN_TYPE, nor SQL_ATTR_RDM_REMOTE_NAME nor SQL_ATTR_TFS_NAME is set, the driver will use the value specified in the first argument of SQLConnect to determine the connection type and data source name. In this case, "tom-mac" will be used as the remote data source name, where the RDMSQLServer is running on the computer whose hostname is "tom-mac" */ rc = SQLConnect(hDbc, (SQLCHAR *) "tom-mac", SQL_NTS, NULL, 0, NULL, 0); } return rc; An application can also establish a connection to a data source by using SQLDriverConnect. SQLDriverConnect accepts a connection string that may have the values for SQL_ATTR_RDM_REMOTE_NAME and SQL_ATTR_RDM_TFS_NAME embedded together. For details, see SQLDriverConnect in the ODBC API Function Reference section. Introduction 17

18 Executing an SQL Statement Once a connection to a data source has been established, an application can execute SQL statements to interact with the databases managed by the data source. Executing an SQL statement involves the following steps. Allocating a Statement Handle Before executing an SQL statement, an application needs to allocate a statement handle by calling SQLAllocHandle, passing SQL_HANDLE_STMT to the first argument and an existing connection handle to the second. A connection to a data source must already be established on the connection handle in order to allocate a statement handle on it. Preparing an SQL Statement An application can "prepare" an SQL statement before actually executing it. 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. This process can also detect any errors that are in the statement, such as syntax errors and references to tables/columns that do not exist. An application can prepare a statement by calling SQLPrepare. Executing an SQL Statement Once an SQL statement has been prepared, an application can call SQLExecute to perform the actual execution of the statement. A prepared statement can be executed multiple times without being prepared again. This is useful when executing a statement with dynamic parameter binding. For details about dynamic parameter binding, see the Working with Parameters section. If an application needs to execute the same SQL statement only once, the preparation and execution steps can be combined into a single call to SQLExecDirect. SQLExecDirect prepares and executes the specified SQL statement at once. The following example illustrates how an application can allocate a statement handle and execute a statement that opens the NSFAWARDS database. Example 5 Opening a database #include "sqlrdm.h" SQLRETURN rundboperations( SQLHDBC hdbc) { SQLRETURN rc; SQLHSTMT hstmt; /* Allocate a statement handle */ Introduction 18

19 rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); if (SQL_SUCCEEDED(rc)) { rc = SQLExecDirect(hStmt, (SQLCHAR *) "OPEN nsfawards", SQL_NTS); } (void) SQLFreeHandle(SQL_HANDLE_STMT, hstmt); } return rc; Committing or Rolling Back Transactions Statements, such as INSERT, UPDATE and DELETE may make changes to the data stored in the data source. Those statements are called "data manipulation language (DML) statements." When executing a DML statement, RDM ODBC automatically starts a transaction so that the changes can be committed (i.e. saved) or rolled back (i.e. aborted). Microsoft ODBC specification says transactions are committed automatically with each DML statement by default (called "autocommit"). For RDM ODBC, the "autocommit" feature is turned off by default, so an application must manually commit or roll back a transaction by calling SQLEndTran. The autocommit feature can be turned on by setting the SQL_ATTR_AUTOCOMMIT connection attribute to SQL_AUTOCOMMIT_ON. The following examples illustrate how an INSERT statement can be executed including transaction processing. It attempts to insert a new row into the PERSON table of the NSFAWARDS database. Example 6 Inserting a new row #include "sqlrdm.h" SQLRETURN rundboperations( SQLHDBC hdbc) { SQLRETURN rc; SQLHSTMT hstmt; const char *pszstmt = "INSERT INTO person VALUES " "'Houglum, Bill', 'M', '1'"; /* Allocate a statement handle */ rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); if (SQL_SUCCEEDED(rc)) { rc = SQLExecDirect(hStmt, (SQLCHAR *) "OPEN nsfawards", SQL_NTS); if (SQL_SUCCEEDED(rc)) { /* Execute an INSERT statement */ rc = SQLExecDirect(hStmt, (SQLCHAR *) pszstmt, SQL_NTS); if (SQL_SUCCEEDED(rc)) { /* INSERT successful; commit the change */ (void) SQLEndTran(SQL_HANDLE_DBC, hdbc, Introduction 19

20 } SQL_COMMIT); } else { /* INSERT failed; abort the change */ (void) SQLEndTran(SQL_HANDLE_DBC, hdbc, SQL_ROLLBACK); } } (void) SQLFreeHandle(SQL_HANDLE_STMT, hstmt); } return rc; Introduction 20

21 Retrieving the Result Set SQL statements can return data from the data source. Those statements that do are called "queries." Queries can be executed in the same manner as the other SQL statements. However, an application must take additional steps to retrieve the data. The data an application retrieves from the data source comes in one or more rows that in turn include one or more columns. This set of data is called "result set." Retrieving the result set involves two steps. Binding Columns First, an application should tell RDM ODBC where it wants the result set to be stored. This step is called "binding columns." An application binds a column by specifying the pointer to a variable for each returned column through a call to SQLBindCol. An application can call SQLBindCol on each of the columns for which it needs to access the returned values. Fetching Columns After binding necessary columns, an application can call SQLFetch to retrieve the result set. SQLFetch retrieves the result set one row at a time by default. An application typically calls SQLFetch repeatedly until it returns SQL_NO_DATA, which indicates the end of the result set has been reached. Each call to SQLFetch puts the values of the current result row into the variables bound to the columns by SQLBindCol. The following example illustrates how to retrieve all the rows stored in the PERSON table of the NSFAWARDS table. Example 7 Retrieving rows from PERSON #include "sqlrdm.h" SQLRETURN rundboperations( SQLHDBC hdbc) { SQLRETURN rc; SQLHSTMT hstmt; const char *pszstmt = "SELECT * FROM person"; char szname[36]; char szgender[2]; char szjob[2]; SQLLEN cb1, cb2, cb; /* Allocate a statement handle */ rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); if (SQL_SUCCEEDED(rc)) { /* Open the NSFAWARDS database first */ rc = SQLExecDirect(hStmt, (SQLCHAR *) "OPEN nsfawards", SQL_NTS); Introduction 21

22 if (SQL_SUCCEEDED(rc)) { /* Execute a SELECT statement */ rc = SQLExecDirect(hStmt, (SQLCHAR *) pszstmt, SQL_NTS); if (SQL_SUCCEEDED(rc)) { /* Bind all the 3 columns */ (void) SQLBindCol(hStmt 1, SQL_C_CHAR, szname, sizeof(szname), &cb1); (void) SQLBindCol(hStmt 2, SQL_C_CHAR, szgender, sizeof(szgender), &cb2); (void) SQLBindCol(hStmt 3, SQL_C_CHAR, szjob, sizeof(szjob), &cb3); do { /* Fetch as many rows as there are */ rc = SQLFetch(hStmt); if (SQL_SUCCEEDED(rc)) { if (cb1!= SQL_NULL_DATA) printf("name = %s\n", szname); if (cb2!= SQL_NULL_DATA) printf("gender = %s\n", szgender); if (cb3!= SQL_NULL_DATA) printf("jobclass = %s\n", szjob); } } while (SQL_SUCCEEDED(rc)); } /* This means fetch completed successfully */ if (rc == SQL_NO_DATA) rc = SQL_SUCCESS; } } (void) SQLFreeHandle(SQL_HANDLE_STMT, hstmt); } return rc; 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. Introduction 22

23 Advanced Topics Working with Parameters Oftentimes an application needs to execute multiple SQL statements that are almost identical. For instance, an application inserting multiple rows into a table typically executes an INSERT statement differing only in the actual values to insert, as shown below. Example 8 Multiple INSERT statements INSERT INTO person VALUES 'Jackson, Michael', 'M', '1'; INSERT INTO person VALUES 'Swift, Taylor', 'F', '2'; INSERT INTO person VALUES 'Mercury, Freddie', 'F', '1'; Calling SQLExecDirect three times will get the job done, but it is not the most efficient way of handling the case as SQLExecDirect prepares and executes each statement. Since the syntax of the three statements is identical, it saves an application time if the identical portion of the statements can be prepared just once, and the insertion of different values can be executed separately. RDM ODBC provides that exact feature, called dynamic parameter binding. An application can prepare an SQL statement replacing the actual values with the symbols called parameter markers ('?'). Statements that include parameter markers are called parameterized statements. Example 9 Statement with parameter markers INSERT INTO person VALUES?,?,?; An application can perform parameter binding on each of the parameter markers of a parameterized statement by calling SQLBindParameter. SQLBindParameter lets an application specify a variable to store the value that will replace the parameter marker at statement execution time. 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. The following example inserts three rows into the PERSON table using dynamic parameter binding. Example 10 Dynamic parameter binding #include "sqlrdm.h" typedef struct person { char name[36]; char gender[2]; char jobclass[2]; } PERSON; /* Three rows to insert into the PERSON table */ static const PERSON people[] = { Advanced Topics 23

24 }; {"Jackson, Michael", "M", "1"}, {"Swift, Taylor", "F", "2"}, {"Mercury, Freddie", "M", "1"} SQLRETURN insertmultiplerows( SQLHDBC hdbc, SQLHSTMT hstmt) { SQLRETURN rc; const char *pszinsert = "INSERT INTO person VALUES?,?,?"; SQLLEN cb1, cb2, cb3; uint16_t ii; /* Assumption: hstmt has already been allocated */ /* Prepare the statement once */ rc = SQLPrepare(hStmt, (SQLCHAR *) pszinsert, SQL_NTS); if (SQL_SUCCEEDED(rc)) { /* Bind parameters for the three parameter markers */ (void) SQLBindParameter(hStmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 35, 0, szname, 0, &cb1); (void) SQLBindParameter(hStmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 1, 0, szgender, 0, &cb2); (void) SQLBindParameter(hStmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 1, 0, szjob, 0, &cb3); for (ii = 0; ii < RLEN(people); ii++) { /* Copy the values of the ii-th row into bound variables */ strcpy(szname, people[ii].name); strcpy(szgender, people[ii].gender); strcpy(szjobclass, people[ii].jobclass); cb1 = cb2 = cb3 = SQL_NTS; } /* Execute the prepared statement using the variables that are just bound to the parameters */ rc = SQLExecute(hStmt); if (!SQL_SUCCEEDED(rc)) break; } if (SQL_SUCCEEDED(rc)) SQLEndTran(SQL_HANDLE_DBC, hdbc, SQL_COMMIT); else SQLEndTran(SQL_HANDLE_DBC, hdbc, SQL_ROLLBACK); } return rc; The last argument of SQLBindParameter can be used to specify the length of the actual data bound to a parameter. For fixed data types, the content of the argument is ignored. For character and binary data types, the Advanced Topics 24

25 length should be expressed in the number of bytes, or SQL_NTS if the data is a null-terminated string. SQL_ NULL_DATA should be specified to indicate that NULL will be inserted into the corresponding column. Fetching Multiple Rows at Once SQLFetch retrieves one row of the result set at a time. It can be a significant network overhead for an application accessing the data source through a remote server. To reduce network traffic, RDM ODBC provides a way to tell its driver to retrieve the specified number of rows at a time. 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, as shown in Example 11. If the value of the attribute is 0 (as is by default), SQLFetch retrieves one row at a time. When an application fetches multiple rows at a time, the variable it binds to a column must be an array whose cardinality should match the number of rows to retrieve. For instance, if 10 rows are to be fetched at a time, the variable bound to an INTEGER column must be declared as "int16_t var[10]". When one call to SQLFetch returns multiple rows, the return code of SQLFetch itself cannot represent the potentially different statuses of the retrieved rows. For instance, one of the 10 rows retrieved may have its data truncated. In a situation like that, where some (but not all) returned rows contain errors or warnings, SQLFetch returns SQL_SUCCESS_WITH_INFO. An application can call SQLGetDiagRec to retrieve all the errors and warnings contained in the result set. An application can also tell the ODBC driver to store the statuses of all result rows into an array specified by the application. It can be done by setting the SQL_ATTR_ROW_STATUS_PTR statement attribute to the pointer to the array of SQLUSMALLINTs. The cardinality of the array should match the number of result rows to retrieve at once. Finally, 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 following example illustrates how to retrieve 10 rows at a time from the PERSON table. Example 11 Retrieving multiple rows #include "sqlrdm.h" #define ROW_ARRAY_SIZE 10 /* Fetch 10 rows at a time */ SQLRETURN rundboperations( SQLHDBC hdbc) { SQLRETURN rc; SQLHSTMT hstmt; const char *pszstmt = "SELECT * FROM person"; char szname[row_array_size][36]; char szgender[row_array_size][2]; char SQLLEN szjob[row_array_size][2]; cb1[row_array_size], cb2[row_array_size], cb3[row_array_size]; Advanced Topics 25

26 SQLULEN SQLULEN ucbfetchedrows; ii; /* Allocate a statement handle */ rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); if (SQL_SUCCEEDED(rc)) { /* Open the NSFAWARDS database first */ rc = SQLExecDirect(hStmt, (SQLCHAR *) "OPEN nsfawards", SQL_NTS); if (SQL_SUCCEEDED(rc)) { /* Specify to retrieve 10 rows at a time */ (void) SQLSetStmtAttr(hStmt, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER) ROW_ARRAY_SIZE, 0); /* Specify the storage for the # of fetched rows */ (void) SQLSetStmtAttr(hStmt, SQL_ATTR_ROWS_FETCHED_PTR, (SQLPOINTER) &ucbfetchedrows, 0); /* Execute a SELECT statement */ rc = SQLExecDirect(hStmt, (SQLCHAR *) pszstmt, SQL_NTS); if (SQL_SUCCEEDED(rc)) { /* Bind all the 3 columns; note that the length argument (arg. 5) is the size of one element of the bound variable */ (void) SQLBindCol(hStmt 1, SQL_C_CHAR, szname, sizeof(szname[0]), cb1); (void) SQLBindCol(hStmt 2, SQL_C_CHAR, szgender, sizeof(szgender[0]), &cb2); (void) SQLBindCol(hStmt 3, SQL_C_CHAR, szjob, sizeof(szjob[0]), &cb3); while ((rc = SQLFetch(hStmt))!= SQL_NO_DATA) { /* ucbfetchedrows = # of rows */ for (ii = 0; ii < ucbfetchedrows; ii++) { if (cb1[ii]!= SQL_NULL_DATA) printf("name = %s\n", szname[ii]); if (cb2[ii]!= SQL_NULL_DATA) { printf("gender = %s\n", szgender[ii]); } if (cb3[ii]!= SQL_NULL_DATA) { printf("jobclass = %s\n", szjob[ii]); } } } } } (void) SQLFreeHandle(SQL_HANDLE_STMT, hstmt); Advanced Topics 26

27 } } return rc; With an ODBC driver that supports scrollable cursors, an application can call SQLFetchScroll to scroll the result set back and forth. The RDM ODBC Driver only supports forward-only cursors. While it provides SQLFetchScroll, the function only accepts SQL_FETCH_NEXT as the fetch type. It means SQLFetch and SQLFetchScroll currently work the same way in RDM ODBC. Retrieving Data in Parts Binding columns using SQLBindCol allows an application to retrieve the content of a given column in one shot. It works well when the column contains fixed-length data, such as an integer, floating-point number and date/time where the size of the data is known before fetching the column. On the other hand, it may not always be efficient, desired or even possible to retrieve the whole content of a column that contains string or binary data. In that case, an application can retrieve the data in parts by calling SQLGetData. SQLGetData works similarly to SQLBindCol except that SQLGetData is called after the row is fetched, not before. 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. For instance, if an application calls SQLGet- Data with the size of data set to 100 on a column that contains a 800-character string, it will need to call the function 8 times on that column in order to read in the whole data. SQLGetData returns SQL_SUCCESS_WITH_INFO (SQLSTATE "01S02" data truncated) if there is more data to be retrieved on that column. When it has retrieved the last chunk of data, it returns SQL_SUCCESS. An application can use this mechanism to detect the last read of the data. If called after the last part of the data has been retrieved, SQLGetData returns SQL_NO_DATA. The following example illustrates how an application can retrieve a character data in parts using SQLGetData. #include "sqlrdm.h" #define MAX_FETCH_SIZE 100 SQLRETURN getchardata( SQLHSTMT hstmt) { SQLRETURN rc; char szdata[100]; /* Assumption; hstmt is already allocated */ rc = SQLExecDirect(hStmt, (SQLCHAR *) "SELECT col1 FROM vartable", SQL_NTS); if (SQL_SUCCEEDED(rc)) { while ((rc = SQLFetch(hStmt))!= SQL_NO_DATA) { do { Advanced Topics 27

28 } } rc = SQLGetData(hStmt, 1, SQL_C_CHAR, szdata, MAX_FETCH_SIZE, NULL); if (SQL_SUCCEEDED(rc)) printf("%s", szdata); } while (rc == SQL_SUCCESS_WITH_INFO); printf("\n"); } return rc; This mechanism can only be used to retrieve character or binary data in parts. If called on a fixed-length column more than once, SQLGetData returns SQL_NO_DATA except for the first call. Advanced Topics 28

29 RDM ODBC API Reference The topics in this section describe each ODBC function in alphabetical order. Each function is defined as a C programming language function. s include the following: Purpose Conformance Syntax Arguments Return values All of the following APIs conform to the ODBC 3.51 specification unless otherwise noted. RDM specific extensions to the APIs will be documented in the Diagnostics or Comments sections of the page. If function does not contain a Diagnostics or Comments section, the MSDN documentation applies to that specific function. 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. The Unicode functions are implemented as functions with a suffix of "W", such as SQLExecDirectW and SQLGetInfoW. Function Reference Pages This section contains topics for the following functions: Function Name SQLAllocHandle SQLBindCol SQLBindParameter SQLCancel SQLCloseCursor SQLColAttribute SQLColumns SQLConnect SQLCopyDesc SQLDescribeCol SQLDescribeParam SQLDescribeStmt SQLDisconnect SQLDriverConnect SQLEndTran Allocates an environment, connection, statement, or descriptor handle Binds application data buffers to columns in the result set. Binds a buffer to a parameter marker in an SQL statement. Cancels the processing on a statement. Closes a cursor that has been opened on a statement and discards pending results. Returns descriptor information for a column in a result set. Descriptor information is returned as a character string, a 32-bit descriptor-dependent value, or an integer value. Returns the list of column names in specified tables. The driver returns this information as a result set on the specified StatementHandle. Establishes connections to RDM databases via RDM ODBC. Copies descriptor information from one descriptor handle to another. 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. Closes the connection associated with a specified handle Establishes connections to RDM databases via RDM ODBC. Accepts more connection options than SQLConnect. Requests a commit or rollback for active transactions RDM ODBC API Reference 29

30 Function Name SQLExecDirect SQLExecute SQLExtendedTran SQLFetch SQLFetchScroll SQLForeignKeys SQLFreeHandle SQLFreeStmt SQLGetConnectAttr SQLGetCursorName SQLGetData SQLGetDescField SQLGetDescRec SQLGetDiagField SQLGetDiagRec SQLGetEnvAttr SQLGetFunctions SQLGetInfo SQLGetStmtAttr SQLGetTypeInfo SQLMoreResults SQLNativeSql SQLNumParams SQLNumResultCols SQLParamData SQLPrepare SQLPrimaryKeys 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. 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. The driver returns each list as a result set on the specified statement. Frees resources associated with a specific environment, connection, statement, or descriptor handle. Stops processing associated with a specific statement, closes any open cursors associated with the statement, discards pending results, or, optionally, frees all resources associated with the statement handle. Returns the current setting of a connection attribute. Retrieves the cursor name of an SQL statement handle Retrieves data for a single column in the result set. It can be called multiple times to retrieve variable-length data in parts. Returns the current setting or value of a single field of a descriptor record. Returns the current settings or values of multiple fields of a descriptor record. The fields returned describe the name, data type, and storage of column or parameter data. 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 information about whether a driver supports a specific ODBC function. Returns general information about the driver and data source associated with a connection. Returns the current setting of a statement attribute. Returns information about data types supported by the data source. Determines whether more results are available on a statement containing SELECT, UPDATE, INSERT, or DELETE statements and, if so, initializes processing for those results. Returns the SQL string as modified by the driver. SQLNativeSql does not execute the SQL statement. Determines the number of parameters in a prepared statement Returns the number of columns in a result set. SQLParamData is used together with SQLPutData to supply parameter data at statement execution time, and with SQLGetData to retrieve streamed output parameter data. Prepares an SQL string for execution. Returns the column names that make up the primary key for a table. The driver returns the information as a result set. This function does not support returning primary keys from multiple tables in a single call. RDM ODBC API Reference 30

31 Function Name SQLProcedureColumns Returns the parameter and column information about the specified procedures. SQLProcedures Returns the list of procedure names stored in a specific data source. Procedure is a generic term used to describe an executable object, or a named entity that can be invoked using input and output parameters. SQLPutData Allows an application to send data for a parameter or column to the driver at statement execution time. This function can be used to send character or binary data values in parts to a column with a character, binary, or data source specific data type (for example, parameters of the SQL_LONGVARBINARY or SQL_LONG- VARCHAR types). SQLRowCount Gets row count in a table following an INSERT, UPDATE, or DELETE SQLSetConnectAttr Sets attributes that govern aspects of connections. SQLSetCursorName Associates a cursor name with an active statement. SQLSetDescField Sets the value of a single field of a descriptor record. SQLSetDescRec Sets multiple descriptor fields that affect the data type and buffer bound to a column or parameter data. SQLSetEnvAttr Sets attributes that govern aspects of environments. SQLSetError Registers user-defined status/error handling functions. SQLSetStmtAttr Sets attributes related to a statement SQLSpecialColumns Returns the information about the set of columns that uniquely identifies a row in the table. SQLStatistics Retrieves a list of statistics about a single table and the indexes associated with the table. The driver returns the information as a result set. SQLTables Returns the list of table, catalog, or schema names, and table types, stored in a specific data source. SQLTransactStatus Retrieves the type and status of the transaction possibly executed on the handle. RDM ODBC API Reference 31

32 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: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC InputHandle (input) 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_HAN- DLE_STMT or SQL_HANDLE_DESC, it must be a connection handle. OutputHandlePtr (output) Pointer to a buffer in which to return the handle to the newly allocated data structure. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 32

33 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. 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

34 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) Statement handle. ColumnNumber (input) 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. TargetType (input) The data type of the value buffer that the column data being retrieved is to be stored in. TargetValue (output) 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. BufferLength (input) The size of the buffer. StrLen_or_Ind (output) 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. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 34

35 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments This function binds application data buffers to columns in the result set. For more information, reference MSDN documentation for SQLBindCol. RDM ODBC API Reference 35

36 SQLBindParameter Binds a buffer to a parameter marker in an SQL statement. Conformance Version Introduced: ODBC 2.0 Standards Compliance: ODBC Syntax SQLRETURN SQLBindParameter( SQLHSTMT StatementHandle, SQLUSMALLINT ParameterNumber, SQLSMALLINT InputOutputType, SQLSMALLINT ValueType, SQLSMALLINT ParameterType, SQLULEN ColumnSize, SQLSMALLINT DecimalDigits, SQLPOINTER ParameterValuePtr, SQLLEN BufferLength, SQLLEN * StrLen_or_IndPtr) Arguments StatementHandle (input) Statement handle. ParameterNumber (input) Parameter number, ordered sequentially in increasing parameter order, starting at 1. InputOutputType (input) The type of the parameter. ValueType (input) The C data type of the parameter. ParameterType (input) The size of the buffer. ColumnSize (input) The size of the column or expression of the corresponding parameter marker. DecimalDigits (input) The decimal digits of the column or expression of the corresponding parameter marker. ParameterValuePtr (deferred A pointer to a buffer for the parameter's data. input) BufferLength (input/output) Length of the ParameterValuePtr buffer in bytes. StrLen_or_IndPtr (deferred input) A pointer to a buffer for the parameter's length. Required Headers #include "sqlext.h" RDM ODBC API Reference 36

37 Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLBindParameter. RDM ODBC API Reference 37

38 SQLCancel Cancels the processing on a statement. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLCancel( SQLHSTMT StatementHandle) Arguments StatementHandle (input) Statement handle. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is RDM ODBC API Reference 38

39 passed for an argument that requires a connection handle. Comments On RDM, SQLCancel supports the following type of processing. A function on a statement that needs data. The following types of processing are not supported due to the driver limitations. A function running asynchronously on a statement. A function running on the statement on another thread. For more information, reference MSDN documentation for SQLCancel. RDM ODBC API Reference 39

40 SQLCloseCursor Closes a cursor that has been opened on a statement and discards pending results. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLCloseCursor( SQLHSTMT StatementHandle) Arguments StatementHandle (input) Statement handle. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is RDM ODBC API Reference 40

41 passed for an argument that requires a connection handle. For more information, reference MSDN documentation for SQLCloseCursor. RDM ODBC API Reference 41

42 SQLColAttribute Returns descriptor information for a column in a result set. Descriptor information is returned as a character string, a 32-bit descriptor-dependent value, or an integer value. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLColAttribute ( SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLUSMALLINT FieldIdentifier, SQLPOINTER CharacterAttributePtr, SQLSMALLINT BufferLength, SQLSMALLINT * StringLengthPtr, SQLPOINTER NumericAttributePtr) Arguments StatementHandle (input) Statement handle. ColumnNumber (input) The number of the record in the IRD from which the field value is to be retrieved. This argument corresponds to the column number of result data, ordered sequentially in increasing column order, starting at 1. Columns can be described in any order. Column 0 can be specified in this argument, but all values except SQL_DESC_TYPE and SQL_DESC_OCTET_LENGTH will return undefined values. FieldIdentifier (input) The descriptor handle. This handle defines which field in the IRD should be queried (for example, SQL_COLUMN_TABLE_NAME). CharacterAttributePtr (output) Pointer to a buffer in which to return the value in the FieldIdentifier field of the ColumnNumber row of the IRD, if the field is a character string. Otherwise, the field is unused. If CharacterAttributePtr is NULL, 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. BufferLength (input) If FieldIdentifier is an ODBC-defined field and CharacterAttributePtr points to a character string or binary buffer, this argument should be the length of *CharacterAttributePtr. If FieldIdentifier is an ODBC-defined field and *CharacterAttributePtr is an integer, this field is ignored. If the *CharacterAttributePtr is a Unicode string (when calling SQLColAttributeW), the BufferLength argument must be an even number. If FieldIdentifier is a driver-defined field, the application indicates the nature of the field to the Driver Manager by setting the BufferLength argument. BufferLength can have the following values: If CharacterAttributePtr is a pointer to a pointer, BufferLength should have the value SQL_IS_POINTER. RDM ODBC API Reference 42

43 If CharacterAttributePtr is a pointer to a character string, the BufferLength is the length of the buffer. 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. 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. StringLengthPtr (output) 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. NumericAttributePtr (output) 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. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is RDM ODBC API Reference 43

44 passed for an argument that requires a connection handle. For more information, reference MSDN documentation for SQLColAttribute. RDM ODBC API Reference 44

45 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) Statement handle. CatalogName (input) 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. NameLength1 (input) Length in characters of *CatalogName. SchemaName (input) 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. NameLength2 (input) Length in characters of *SchemaName. TableName (input) String search pattern for table names. NameLength3 (input) Length in characters of *TableName. ColumnName (input) String search pattern for column names. NameLength4 (input) Length in characters of *ColumnName. Required Headers #include "sql.h" RDM ODBC API Reference 45

46 Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLColumns returns the information that pertain to the databases that are currently open. If no database is open on the data source, SQLColumns returns an empty result set. For more information, reference MSDN documentation for SQLColumns. RDM ODBC API Reference 46

47 SQLConnect Establishes connections to RDM databases via RDM ODBC. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLConnect( SQLHDBC ConnectionHandle, const SQLCHAR *ServerName, SQLSMALLINT NameLength1, const SQLCHAR *UserName, SQLSMALLINT NameLength2, const SQLCHAR *Authentication, SQLSMALLINT NameLength3) Arguments ConnectionHandle (input) Connection handle. ServerName (input) The name of the remote server. For the details, see the Comments section. NameLength1 (input) Length of *ServerName in characters. Specify SQL_NTS if ServerName is a nullterminated string. UserName (input) This parameter is not used. NameLength2 (input) Length of *UserName in characters. Specify SQL_NTS if UserName is a null-terminated string. Authentication (input) This parameter is not used. NameLength3 (input) Length of *Authentication in characters. Specify SQL_NTS if Authentication is a null-terminated string. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 47

48 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Diagnostics SQLSTATE Error 01S02 Option value changed. The RDM ODBC Driver does not support the specified value for the ValuePtr argument in SQLSetConnectAttr. The specified value has been substituted by a similar value. The function returns SQL_SUCCESS_WITH_INFO Unable to connect. The RDM ODBC driver was not able to connect to the data source Connection already in use. The specified connection handle is already used for an existing connection. HY001 Driver memory allocation error The RDM ODBC driver failed to allocate memory required to complete the operation. HY013 Memory management error The function could not complete the operation due to the out-ofmemory condition in the data source. 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. The behavior of SQLConnect changes depending upon the combination of this value and the connection type, set with SQL_ATTR_RDM_CONN_TYPE attribute using SQLSetConnectAttr, as follows. ServerName Connection Actual Connection Names Actual Server Type NULL/empty Not set Local TFS SQL_ATTR_RDM_TFS_NAME Remote N/A Local Local TFS SQL_ATTR_RDM_TFS_NAME Remote N/A Remote Remote TFS SQL_ATTR_RDM_TFS_NAME Remote SQL_ATTR_RDM_REMOTE_ NAME RDM ODBC API Reference 48

49 ServerName Connection Actual Connection Names Actual Server Type Set Not set Remote TFS SQL_ATTR_RDM_TFS_NAME Remote ServerName Local Local TFS ServerName Remote N/A Remote Remote TFS SQL_ATTR_RDM_TFS_NAME Remote ServerName The UserName, Authentication, NameLength2 and NameLength3 parameters are currently not used in RDM ODBC since RDM does not support user authentication. Values specified for those parameters will be ignored. For more information, reference MSDN documentation for SQLConnect. RDM ODBC API Reference 49

50 SQLCopyDesc Copies descriptor information from one descriptor handle to another. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLCopyDesc( SQLHDESC SourceDescHandle, SQLHDESC TargetDescHandle); Arguments SourceDescHandle (input) Source descriptor handle. TargetDescHandle (input) Target descriptor handle. The TargetDescHandle argument can be a handle to an application descriptor or an IPD. TargetDescHandle cannot be set to a handle to an IRD, or SQLCopyDesc will return SQLSTATE HY016 (Cannot modify an implementation row descriptor). Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField to retrieve additional information. The contents of any output arguments to the function are undefined. RDM ODBC API Reference 50

51 SQL_INVALID_HANDLE 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLCopyDesc. RDM ODBC API Reference 51

52 SQLDescribeCol Retrieves the basic result data set for a column Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDescribeCol( SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLCHAR *ColumnName, SQLSMALLINT BufferLength, SQLSMALLINT *NameLengthPtr, SQLSMALLINT *DataTypePtr, SQLULEN *ColumnSizePtr, SQLSMALLINT *DecimalDigitsPtr, SQLSMALLINT *NullablePtr) Arguments StatementHandle (input) Statement handle. ColumnNumber (input) Column number of result data, ordered sequentially in increasing column order, starting at 1. ColumnName (output) Pointer to a null-terminated buffer in which to return the column name. This value is read from the SQL_DESC_NAME field of the IRD. If the column is unnamed or the column name cannot be determined, the driver returns an empty string. 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. BufferLength (input) Length of the *ColumnName buffer, in characters. NameLengthPtr (output) Pointer to a buffer in which to return the total number of characters (excluding the null termination) available to return in *ColumnName. If the number of characters available to return is greater than or equal to BufferLength, the column name in *ColumnName is truncated to BufferLength minus the length of a null-termination character. DataTypePtr (output) Pointer to a buffer in which to return the SQL data type of the column. This value is read from the SQL_DESC_CONCISE_TYPE field of the IRD. This will be one of the values in SQL Data Types, or a driver-specific SQL data type. If the data type cannot be determined, the driver returns SQL_UNKNOWN_TYPE. ColumnSizePtr (output) Pointer to a buffer in which to return the size (in characters) of the column on the data source. If the column size cannot be determined, the driver returns 0. DecimalDigitsPtr (output) 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 52

53 NullablePtr (output) Pointer to a buffer in which to return a value that indicates whether the column allows NULL values. This value is read from the SQL_DESC_NULLABLE field of the IRD. The value is one of the following: SQL_NO_NULLS: The column does not allow NULL values. SQL_NULLABLE: The column allows NULL values. SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column allows NULL values. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLDescribeCol. RDM ODBC API Reference 53

54 SQLDescribeParam Retrieves description of a parameter marker Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDescribeParam( SQLHSTMT StatementHandle, SQLUSMALLINT ParameterNumber, SQLSMALLINT *DataTypePtr, SQLULEN *ParameterSizePtr, SQLSMALLINT *DecimalDigitsPtr, SQLSMALLINT *NullablePtr) Arguments StatementHandle (input) Statement handle. ParamNumber (input) Specifies the parameter number in the SQL statement text. Parameter numbers are numbered sequentially from left to right, starting with 1, as they appear in the SQL statement. DataTypePtr (output) Pointer to a buffer in which to return the SQL data type of the parameter. ParameterSizePtr (output) Pointer to a buffer in which to return the size, in characters, of the column or expression of the corresponding parameter marker as defined by the data source. DecimalDigitsPtr (output) 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. NullablePtr (output) Pointer to a buffer in which to return a value that indicates whether the parameter allows NULL values. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 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 54

55 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLDescribeParam. RDM ODBC API Reference 55

56 SQLDescribeStmt Retrieves the type of the SQL statement executed on the handle. Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQL_API SQLDescribeStmt( SQLHSTMT StatementHandle, SQLUSMALLINT *pstmttype) Arguments StatementHandle (input) Statement handle. pstmttype (output) The type of the SQL statement executed on the statement handle. Possible values returned through this parameter are described in the Comments section below. Required Headers #include "sqlrext.h" Libraries Library Name rdmrdbc11 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_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- DiagField to retrieve additional information from the header record. Function failed. The application calls SQLGetDiagRec or SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is RDM ODBC API Reference 56

57 passed for an argument that requires a connection handle. Diagnostics SQLSTATE Error HY009 Invalid use of null pointer A null pointer was specified for the pstmttype argument. HY010 Function sequence error 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. 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

58 [1] Any of the DDL statements supported by RDM, such as CREATE DATABASE and CREATE TABLE, returns SQL_RDM_STMT_DDL. RDM ODBC API Reference 58

59 SQLDisconnect Closes the connection associated with a specified handle Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDisconnect( SQLHDBC ConnectionHandle) Arguments ConnectionHandle (input) Connection handle. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is RDM ODBC API Reference 59

60 passed for an argument that requires a connection handle. For more information, reference MSDN documentation for SQLDisconnect. RDM ODBC API Reference 60

61 SQLDriverConnect Establishes connections to RDM databases via RDM ODBC. Accepts more connection options than SQLConnect. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLDriverConnect( SQLHDBC ConnectionHandle, SQLHWND WindowHandle, const SQLCHAR *InConnectionString, SQLSMALLINT StringLength1, SQLCHAR *OutConnectionString, SQLSMALLINT BufferLength, SQLSMALLINT *StringLength2Ptr, SQLUSMALLINT DriverCompletion) Arguments ConnectionHandle (input) Connection handle. WindowHandle (input) Window handle. InConnectionString (input) A full connection string (see the syntax in "Comments"), a partial connection string, or an empty string. StringLength1 (input) Length of *InConnectionString, in characters if the string is Unicode, or bytes if string is ANSI or DBCS. OutConnectionString (output) Pointer to a buffer for the completed connection string. Upon successful connection to the target data source, this buffer contains the completed connection string. Applications should allocate at least 1,024 characters for this buffer. BufferLength (input) Length of the *OutConnectionString buffer, in characters. StringLength2Ptr (output) Pointer to a buffer in which to return the total number of characters (excluding the null-termination character) available to return in *OutConnectionString. If the number of characters available to return is greater than or equal to BufferLength, the completed connection string in *OutConnectionString is truncated to BufferLength minus the length of a null-termination character. DriverCompletion (input) Flag that indicates whether the Driver Manager or driver must prompt for more connection information Required Headers #include "sqlext.h" RDM ODBC API Reference 61

62 Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments InConnectionString RDM accepts the following connection string keywords. Keyword DSN PORT TFS [1] REMOST_HOST [1] Attribute Value When the application accesses the RDM ODBC Driver through Microsoft ODBC Driver Manager (DM), this is the name of an ODBC data source that points to RDM. The value of this keyword is ignored if the application is linked directly with the RDM ODBC Driver. TCP/IP port number the TFServer is listening on. If PORT is not specified, RDM will use the default value (21553). Name of the TFServer. 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, in which case the DM will remove the DSN keyword from the connection string. If TFS is specified, RDM will use its default TFServer name ("localhost"). Name of the remote server. If REMOTE_HOST is not specified, RDM will use its default remote server name ("localhost"). RDM ODBC API Reference 62

63 Keyword DATABASE Attribute Value Name of the database to open upon successful connection to the data source. For more information, reference MSDN documentation for SQLDriverConnect. RDM ODBC API Reference 63

64 SQLEndTran Requests a commit or rollback for active transactions Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLEndTran( SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT CompletionType) Arguments HandleType (input) Handle type identifier. Contains either SQL_HANDLE_ENV (if Handle is an environment handle) or SQL_HANDLE_DBC (if Handle is a connection handle). Handle (input) The handle, of the type indicated by HandleType, indicating the scope of the transaction. CompletionType (input) One of the following two values: SQL_COMMIT SQL_ROLLBACK Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 Function completed successfully. The application calls SQLGet- 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. RDM ODBC API Reference 64

65 SQL_ERROR SQL_INVALID_HANDLE Function failed. The application calls SQLGetDiagRec or SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLEndTran. RDM ODBC API Reference 65

66 SQLExecDirect Prepares and executes an SQL statement Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQL_API SQLExecDirect( SQLHSTMT StatementHandle, const SQLCHAR *StatementText, SQLINTEGER TextLength) Arguments StatementHandle (input) Statement handle. StatementText (input) SQL statement to be executed. TextLength (input) Length of *StatementText in characters. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 RDM ODBC API Reference 66

67 SQL_NEED_DATA SQL_NO_DATA descriptor handle. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGet- DiagField. 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. More data is needed, such as when parameter data is sent at execution time or additional connection information is required. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information, if any. No more data was available. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. For more information, reference MSDN documentation for SQLExecDirect. RDM ODBC API Reference 67

68 SQLExecute Executes a previously prepared SQL statement Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLExecute( SQLHSTMT StatementHandle); Arguments StatementHandle (input) Statement handle. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is RDM ODBC API Reference 68

69 SQL_NEED_DATA SQL_NO_DATA passed for an argument that requires a connection handle. More data is needed, such as when parameter data is sent at execution time or additional connection information is required. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information, if any. No more data was available. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. For more information, reference MSDN documentation for SQLExecute. RDM ODBC API Reference 69

70 SQLExtendedTran Performs a transaction operation Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQL_API SQLExtendedTran( SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT TransType, SQLSMALLINT ReadOnly, const SQLCHAR *TransactionID, SQLSMALLINT StringLengthPtr) Arguments HandleType (input) Handle type identifier. Contains either SQL_HANDLE_ENV (if Handle is an environment handle) or SQL_HANDLE_DBC (if Handle is a connection handle). Handle (input) The handle, of the type indicated by HandleType, indicating the scope of the transaction. OperationType (input) One of the following operation types: SQL_START -Start a transaction SQL_SAVEPOINT -Create a save point in a transaction SQL_RELEASE Release a save point in a transaction SQL_COMMIT -Commit a transaction SQL_ROLLBACK -Rollback a transaction ReadOnly (input) Read-only mode, as follows: SQL_TRUE Transaction is read-only. SQL_FALSE Transaction is read-write If OperationType is not SQL_START or SQL_COMMIT, this parameter is ignored. TransactionID (input) Character string that indicates the unique ID of the transaction operation. If Operation Code is SQL_COMMIT, this parameter is ignored. If TransactionID is not specified with SQL_START, an internal system value will be used. TransactionID is required with SQL_SAVEPOINT and SQL_RELEASE. StringLengthPtr (input) The length of TransactionID in characters. SQL_NTS can be used to indicate that TransactionID is null-terminated. RDM ODBC API Reference 70

71 Required Headers #include "sqlrext.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Diagnostics SQLSTATE Error General warning General error returned from the RDM ODBC driver. The function returns SQL_SUCCESS_WITH_INFO Connection not open The RDM ODBC driver is not connected to a data source Transaction already active SQL_START is specified for OperationType and a transaction is already active on the connection associated with Handle Read-only transaction already active SQL_START, SQL_SAVEPOINT or SQL_RELEASE is specified for OperationType and a read-only transaction is active on the connection associated with Handle. 25S01 Transaction state unknown When HandleType is SQL_HANDLE_ENV and one or more of the connections in Handle failed to complete the transaction. HY001 Memory allocation error Either the ODBC driver or the SQL engine failed to allocate sufficient memory to complete the required operation. HY010 Function sequence error This function was called after SQLExecute or SQLEx- RDM ODBC API Reference 71

72 HY012 Invalid transaction operation code ecdirect but before all the parameters were bound. The value in OperationType is not one of the following: SQL_START SQL_SAVEPOINT SQL_RELEASE SQL_COMMIT SQL_ROLLBACK HY013 Memory management error The RDM SQL engine failed to allocate sufficient memory to complete the required operation. HY092 Invalid attribute/option identifier The value in HandleType is not one of the following values: SQL_HANDLE_ENV SQL_HANDLE_DBC Comments SQLExtendedTran allows an RDM ODBC application to start a transaction, create a save point inside the current transaction, and roll back to the last save point, as well as committing and rolling back a transaction. Starting a transaction Creating a save point Releasing a save point Rolling back to a save point Committing a transaction SQLExtendedTran can be called to start a regular ("read-write") transaction or a "read-only" transaction. The value specified for the ReadOnly parameter determines the type of transaction to start. To start a read-only transaction, specify SQL_TRUE for the ReadOnly parameter. An application can optionally specify the unique ID of the transaction by using the TransactionID parameter. If NULL or an empty string is specified for the TransactionID parameter, an internal system ID will be used SQLExtendedTran can be used to create a save point in the current readwrite transaction. An application must specify a unique ID of the save point using the TransactionID parameter. 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. An application can manually release, or discard, any of the save points it created by calling SQLExtendedTran specifying SQL_RELEASE for OperationType and the ID associated with the save point. A call to SQLEndTran to either commit or abort the current transaction will automatically release all save points. 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 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. All save points created after the specified save point will be released. If the specified ID is not associated with any existing save point, the entire transaction will be aborted. An application can commit all changes in a transaction by calling SQLEndTran or SQLExtendedTran specifying SQL_COMMIT. All save points inside the RDM ODBC API Reference 72

73 Aborting a transaction transaction will be released. If no transaction is active, SQL_SUCCESS will be returned. An application can abort an entire transaction by calling SQLEndTran or SQLExtendedTran specifying SQL_ROLLBACK. For SQLExtendedTran, specify NULL or the ID of the transaction itself for TransactionID. All save points inside the transaction will be released. If no transaction is active, SQL_ SUCCESS will be returned. RDM ODBC API Reference 73

74 SQLFetch Fetches data from a bound column to an application variable Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLFetch( SQLHSTMT StatementHandle); Arguments StatementHandle (input) Statement handle. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null pointer or is the wrong type, such as when a statement handle is RDM ODBC API Reference 74

75 passed for an argument that requires a connection handle. For more information, reference MSDN documentation for SQLFetch. RDM ODBC API Reference 75

76 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) Statement handle. FetchOrientation (input) Type of fetch: SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_ABSOLUTE SQL_FETCH_RELATIVE SQL_FETCH_BOOKMARK FetchOffset (input) 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 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 76

77 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. 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

78 SQLForeignKeys 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). 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) Statement handle. PKCatalogName (input) Primary key table catalog name. PKCatalogName cannot contain a string search pattern. NameLength1 (input) Length of *PKCatalogName, in characters. PKSchemaName (input) Primary key table schema name. PKSchemaName cannot contain a string search pattern. NameLength2 (input) Length of *PKSchemaName, in characters. PKTableName (input) Primary key table name. PKTableName cannot contain a string search pattern. NameLength3 (input) Length of *PKTableName, in characters. FKCatalogName (input) Foreign key table catalog name. FKCatalogName cannot contain a string search pattern. NameLength4 (input) Length of *FKCatalogName, in characters. FKSchemaName (input) Foreign key table schema name. FKSchemaName cannot contain a string search pattern. NameLength5 (input) Length of *FKSchemaName, in characters. FKTableName (input) Foreign key table name. FKTableName cannot contain a string search pattern. RDM ODBC API Reference 78

79 NameLength6 (input) Length of *FKTableName, in characters. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLForeignKeys returns the information that pertains to the databases that are currently open. If no database is open on the data source, SQLForeignKeys returns an empty result set. For more information, reference MSDN documentation for SQLForeignKeys. RDM ODBC API Reference 79

80 SQLFreeHandle Frees resources associated with a specific environment, connection, statement, or descriptor handle. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLFreeHandle( SQLSMALLINT HandleType, SQLHANDLE Handle); Arguments HandleType (input) The type of handle to be freed by SQLFreeHandle. Must be one of the following values: SQL_HANDLE_DBC SQL_HANDLE_DESC SQL_HANDLE_ENV SQL_HANDLE_STMT If HandleType is not one of these values, SQLFreeHandle returns SQL_ INVALID_HANDLE. Handle (input) The handle to be freed. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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_ERROR Function completed successfully. The application calls SQLGet- DiagField to retrieve additional information from the header record. Function failed. The application calls SQLGetDiagRec or SQLGet- RDM ODBC API Reference 80

81 SQL_INVALID_HANDLE DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLFreeHandle. RDM ODBC API Reference 81

82 SQLFreeStmt Stops processing associated with a specific statement, closes any open cursors associated with the statement, discards pending results, or, optionally, frees all resources associated with the statement handle. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLFreeStmt( SQLHSTMT StatementHandle, SQLUSMALLINT Option); Arguments StatementHandle (input) Statement handle. Option (input) One of the following options: SQL_ CLOSE: Closes the cursor associated with StatementHandle (if one was defined) and discards all pending results. The application can reopen this cursor later by executing a SELECT statement again with the same or different parameter values. If no cursor is open, this option has no effect for the application. SQLClose- Cursor can also be called to close a cursor. For more information, see Closing the Cursor. SQL_DROP: This option is deprecated. A call to SQLFreeStmt with an Option of SQL_DROP is mapped in the Driver Manager to SQLFreeHandle. SQL_UNBIND: Sets the SQL_DESC_COUNT field of the ARD to 0, releasing all column buffers bound by SQLBindCol for the given StatementHandle. This does not unbind the bookmark column; to do that, 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, the operation will affect the bindings of all statements that share the descriptor. SQL_RESET_PARAMS: Sets the SQL_DESC_COUNT field of the APD to 0, releasing all parameter buffers set by SQLBindParameter for the given StatementHandle. If this operation is performed on an explicitly allocated descriptor that is shared by more than one statement, this operation will affect the bindings of all the statements that share the descriptor. RDM ODBC API Reference 82

83 Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLFreeStmt. RDM ODBC API Reference 83

84 SQLGetConnectAttr Returns the current setting of a connection attribute. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetConnectAttr( SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER * StringLengthPtr); Arguments ConnectionHandle (input) Connection handle. Attribute (input) Attribute to retrieve. ValuePtr (output) A pointer to memory in which to return the current value of the attribute specified by Attribute. BufferLength (input) If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. If Attribute is an ODBC-defined attribute and *ValuePtr is an integer, BufferLength is ignored. StringLengthPtr (output) A pointer to a buffer in which to return the total number of bytes (excluding the nulltermination character) available to return in *ValuePtr. If *ValuePtr is a null pointer, no length is returned. 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, the data in *ValuePtr is truncated to BufferLength minus the length of the null-termination character and is null-terminated by the driver. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 84

85 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments The attributes accepted by SQLGetConnectAttr are listed under SQLSetConnectAttr. For more information, reference MSDN documentation for SQLGetConnectAttr. RDM ODBC API Reference 85

86 SQLGetCursorName Retrieves the cursor name of an SQL statement handle Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetCursorName( SQLHSTMT StatementHandle, SQLCHAR * CursorName, SQLSMALLINT BufferLength, SQLSMALLINT * NameLengthPtr); Arguments StatementHandle (input) Statement handle. CursorName (output) Pointer to a buffer in which to return the cursor name. BufferLenght (input) Length of *CursorName, in characters. NameLengthPrt (output) Pointer to memory in which to return the total number of characters (excluding the null-termination character) available to return in *CursorName. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR Function completed successfully. The application calls SQLGet- 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 SQLGet- RDM ODBC API Reference 86

87 SQL_INVALID_HANDLE DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLGetCursorName. RDM ODBC API Reference 87

88 SQLGetData Retrieves data for a single column in the result set. It can be called multiple times to retrieve variable-length data in parts. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetData( SQLHSTMT StatementHandle, SQLUSMALLINT Col_or_Param_Num, SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr, SQLLEN BufferLength, SQLLEN * StrLen_or_IndPtr); Arguments StatementHandle (input) Statement handle. Col_or_Param_Num (input) For retrieving column data, it is the number of the column for which to return data. Result set columns are numbered in increasing column order starting at 1. The bookmark column is column number 0; this can be specified only if bookmarks are enabled. For retrieving parameter data, it is the ordinal of the parameter, which starts at 1. TargetType (input) The type identifier of the C data type of the *TargetValuePtr buffer. For a list of valid C data types and type identifiers TargetValuePrt (output) Pointer to the buffer in which to return the data. BufferLength (input) Length of the *TargetValuePtr buffer in bytes. StrLen_or_IndPtr (output) Pointer to the buffer in which to return the length or indicator value. If this is a null pointer, no length or indicator value is returned. This returns an error when the data being fetched is NULL. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 88

89 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLGetData. RDM ODBC API Reference 89

90 SQLGetDescField Returns the current setting or value of a single field of a descriptor record. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDescField( SQLHDESC DescriptorHandle, SQLSMALLINT RecNumber, SQLSMALLINT FieldIdentifier, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER * StringLengthPtr); Arguments DescriptorHandle (input) Descriptor handle. RecNumber (input) Indicates the descriptor record from which the application seeks information. Descriptor records are numbered from 0, with record number 0 being the bookmark record. If the FieldIdentifier argument indicates a header field, RecNumber is ignored. If RecNumber is less than or equal to SQL_DESC_COUNT but the row does not contain data for a column or parameter, a call to SQLGetDescField will return the default values of the fields. FieldIdentifier (input) Indicates the field of the descriptor whose value is to be returned. ValuePtr (output) Pointer to a buffer in which to return the descriptor information. The data type depends on the value of FieldIdentifier. If ValuePtr is NULL, 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. BufferLength (input) If FieldIdentifier is an ODBC-defined field and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. If FieldIdentifier is an ODBC-defined field and *ValuePtr is an integer, BufferLength is ignored. StringLengthPtr (output) 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. Required Headers #include "sql.h" RDM ODBC API Reference 90

91 Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLGetDescField. RDM ODBC API Reference 91

92 SQLGetDescRec Returns the current settings or values of multiple fields of a descriptor record. The fields returned describe the name, data type, and storage of column or parameter data. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDescRec( SQLHDESC DescriptorHandle, SQLSMALLINT RecNumber, SQLCHAR * Name, SQLSMALLINT BufferLength, SQLSMALLINT * StringLengthPtr, SQLSMALLINT * TypePtr, SQLSMALLINT * SubTypePtr, SQLLEN * LengthPtr, SQLSMALLINT * PrecisionPtr, SQLSMALLINT * ScalePtr, SQLSMALLINT * NullablePtr); Arguments DescriptorHandle (input) Descriptor handle. RecNumber (input) Indicates the descriptor record from which the application seeks information. Descriptor records are numbered from 1, with record number 0 being the bookmark 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, a call to SQLGetDescRec will return the default values of the fields. Name (output) A pointer to a buffer in which to return the SQL_DESC_NAME field for the descriptor record. If Name is NULL, 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. BufferLength (input) Length of the *Name buffer, in characters. StringLengthPtr (output) A pointer to a buffer in which to return the number of characters of data available to return in the *Name buffer, excluding the null-termination character. If the number of characters was greater than or equal to BufferLength, the data in *Name is truncated to BufferLength minus the length of a null-termination character, and is null-terminated by the driver. TypePtr (output) A pointer to a buffer in which to return the value of the SQL_DESC_TYPE field for the descriptor record. SubTypePtr (output) For records whose type is SQL_DATETIME or SQL_INTERVAL, this is a pointer to a buffer in which to return the value of the SQL_DESC_DATETIME_INTERVAL_ RDM ODBC API Reference 92

93 CODE field. LengthPtr (output) A pointer to a buffer in which to return the value of the SQL_DESC_OCTET_ LENGTH field for the descriptor record. PrecisionPtr (output) A pointer to a buffer in which to return the value of the SQL_DESC_PRECISION field for the descriptor record. ScalePtr (output) A pointer to a buffer in which to return the value of the SQL_DESC_SCALE field for the descriptor record. NullablePtr (output) A pointer to a buffer in which to return the value of the SQL_DESC_NULLABLE field for the descriptor record. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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_NO_DATA is returned if RecNumber is greater than the current number of descriptor records. 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. For more information, reference MSDN documentation for SQLGetDescRec. RDM ODBC API Reference 93

94 SQLGetDiagField Retrieves current field value of a status record Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDiagField( SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLSMALLINT DiagIdentifier, SQLPOINTER DiagInfoPtr, SQLSMALLINT BufferLength, SQLSMALLINT * StringLengthPtr) Arguments HandleType (input) A handle type identifier that describes the type of handle for which diagnostics are required. Must be one of the following: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC Handle (input) A handle for the diagnostic data structure, of the type indicated by HandleType. RecNumber (input) Indicates the status record from which the application seeks information. Status records are numbered from 1. If the DiagIdentifier argument indicates any field of the diagnostics header, RecNumber is ignored. If not, it should be more than 0. DiagIdentifier (input) Indicates the field of the diagnostic whose value is to be returned. DiagInfoPtr (output) Pointer to a buffer in which to return the diagnostic information. The data type depends on the value of DiagIdentifier. If DiagInfoPtr is NULL, 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. BufferLength (input) If DiagIdentifier is an ODBC-defined diagnostic and DiagInfoPtr points to a character string or a binary buffer, this argument should be the length of *DiagInfoPtr. If DiagIdentifier is an ODBC-defined field and *DiagInfoPtr is an integer, BufferLength is ignored. StringLengthPtr (output) 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, for character data. If the number of bytes available to return is greater than or equal to BufferLength, the text in *DiagInfoPtr is truncated to BufferLength minus the length of a null-termination character. RDM ODBC API Reference 94

95 Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLGetDiagField. RDM ODBC API Reference 95

96 SQLGetDiagRec Retrieves current values of several common fields of a status record Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetDiagRec( SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLCHAR * SQLState, SQLINTEGER * NativeErrorPtr, SQLCHAR * MessageText, SQLSMALLINT BufferLength, SQLSMALLINT * TextLengthPtr) Arguments HandleType (input) A handle type identifier that describes the type of handle for which diagnostics are required. Must be one of the following: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC Handle (input) A handle for the diagnostic data structure, of the type indicated by HandleType. RecNumber (input) Indicates the status record from which the application seeks information. Status records are numbered from 1. SQLState (output) Pointer to a buffer in which to return a five-character SQLSTATE code (and terminating NULL) for the diagnostic record RecNumber. The first two characters indicate the class; the next three indicate the subclass. This information is contained in the SQL_DIAG_SQLSTATE diagnostic field. NativeErrorPtr (output) Pointer to a buffer in which to return the native error code, specific to the data source. This information is contained in the SQL_DIAG_NATIVE diagnostic field. MessageText (output) Pointer to a buffer in which to return the diagnostic message text string. This information is contained in the SQL_DIAG_MESSAGE_TEXT diagnostic field. BufferLength (input) Length of the *MessageText buffer in characters. There is no maximum length of the diagnostic message text. TextLengthPtr (output) 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. If the number of characters available to return is greater than BufferLength, the diagnostic message text in *MessageText is truncated to BufferLength minus the length of a null-termination character. RDM ODBC API Reference 96

97 Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLGetDiagRec. RDM ODBC API Reference 97

98 SQLGetEnvAttr Returns the current setting of an environment attribute. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetEnvAttr( SQLHENV EnvironmentHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER * StringLengthPtr) Arguments EnvironmentHandle (input) Environment handle. Attribute (input) Attribute to retrieve. ValuePtr (output) Pointer to a buffer in which to return the current value of the attribute specified by Attribute. If ValuePtr is NULL, 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. BufferLength (input) If ValuePtr points to a character string, this argument should be the length of *ValuePtr. If *ValuePtr is an integer, BufferLength is ignored. If the attribute value is not a character string, BufferLength is unused. StringLengthPtr (output) A pointer to a buffer in which to return the total number of bytes (excluding the nulltermination character) available to return in *ValuePtr. If ValuePtr is a null pointer, no length is returned. If the attribute value is a character string and the number of bytes available to return is greater than or equal to BufferLength, the data in *ValuePtr is truncated to BufferLength minus the length of a null-termination character and is null-terminated by the driver. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 98

99 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments The attributes accepted by SQLGetEnvAttr are listed under SQLSetEnvAttr. For more information, reference MSDN documentation for SQLGetEnvAttr. RDM ODBC API Reference 99

100 SQLGetFunctions Returns information about whether a driver supports a specific ODBC function. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetFunctions( SQLHDBC ConnectionHandle, SQLUSMALLINT FunctionId, SQLUSMALLINT * SupportedPtr) Arguments ConnectionHandle (input) Connection handle. FunctionId (input) A #define value that identifies the ODBC function of interest; SQL_API_ODBC3_ ALL_FUNCTIONS or SQL_API_ALL_FUNCTIONS. SupportedPtr (output) If FunctionId identifies a single ODBC function, SupportedPtr points to a single SQLUSMALLINT value that is SQL_TRUE if the specified function is supported by the driver, and SQL_FALSE if it is not supported. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR Function completed successfully. The application calls SQLGet- 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 SQLGet- RDM ODBC API Reference 100

101 SQL_INVALID_HANDLE DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLGetFunctions. RDM ODBC API Reference 101

102 SQLGetInfo Returns general information about the driver and data source associated with a connection. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetInfo( SQLHDBC ConnectionHandle, SQLUSMALLINT InfoType, SQLPOINTER InfoValuePtr, SQLSMALLINT BufferLength, SQLSMALLINT * StringLengthPtr) Arguments ConnectionHandle (input) Connection handle. InfoType (input) Type of information. InfoValuePtr (output) Pointer to a buffer in which to return the information. Depending on the InfoType requested, the information returned will be one of the following: a null-terminated character string, an SQLUSMALLINT value, an SQLUINTEGER bitmask, an SQLUINTEGER flag, or a SQLUINTEGER binary value. If the InfoType argument is SQL_DRIVER_HDESC or SQL_DRIVER_HSTMT, the InfoValuePtr argument is both input and output. (See the SQL_DRIVER_ HDESC or SQL_DRIVER_HSTMT descriptors later in this function description for more information.) If InfoValuePtr is NULL, 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. BufferLength (input) Length of the *InfoValuePtr buffer. If the value in *InfoValuePtr is not a character string or if InfoValuePtr is a null pointer,the BufferLength argument is ignored. The driver assumes that the size of *InfoValuePtr is SQLUS- MALLINT or SQLUINTEGER, based on the InfoType. StringLengthPtr (output) 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. For character data, if the number of bytes available to return is greater than or equal to BufferLength, the information in *InfoValuePtr is truncated to BufferLength bytes 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 *InfoValuePtr is SQLUSMALLINT or SQLUINTEGER, depending on the InfoType. RDM ODBC API Reference 102

103 Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLGetInfo. RDM ODBC API Reference 103

104 SQLGetStmtAttr Returns the current setting of a statement attribute. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetStmtAttr( SQLHSTMT StatementHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER * StringLengthPtr) Arguments StatementHandle (input) Statement handle. Attribute (input) Attribute to retrieve. ValuePtr (output) Pointer to a buffer in which to return the value of the attribute specified in Attribute. If ValuePtr is NULL, 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. BufferLength (input) If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. If Attribute is an ODBC-defined attribute and *ValuePtr is an integer, BufferLength is ignored StringLengthPtr (output) A pointer to a buffer in which to return the total number of bytes (excluding the nulltermination character) available to return in *ValuePtr. If ValuePtr is a null pointer, no length is returned. If the attribute value is a character string, and the number of bytes available to return is greater than or equal to BufferLength; the data in *ValuePtr is truncated to BufferLength minus the length of a null-termination character and is null-terminated by the driver. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 104

105 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments The attributes accepted by SQLGetStmtAttr are listed under SQLSetStmtAttr. For more information, reference MSDN documentation for SQLGetStmtAttr. RDM ODBC API Reference 105

106 SQLGetTypeInfo Returns information about data types supported by the data source. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLGetTypeInfo( SQLHSTMT StatementHandle, SQLSMALLINT DataType) Arguments StatementHandle (input) Statement handle. DataType (input) The SQL data type. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- RDM ODBC API Reference 106

107 DiagField. 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. For more information, reference MSDN documentation for SQLGetTypeInfo. RDM ODBC API Reference 107

108 SQLMoreResults Determines whether more results are available on a statement containing SELECT, UPDATE, INSERT, or DELETE statements and, if so, initializes processing for those results. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLMoreResults( SQLHSTMT StatementHandle) Arguments StatementHandle (input) Statement handle. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. This code is returned only when the handle is a null RDM ODBC API Reference 108

109 SQL_NO_DATA 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. For more information, reference MSDN documentation for SQLMoreResults. RDM ODBC API Reference 109

110 SQLNativeSql Returns the SQL string as modified by the driver. SQLNativeSql does not execute the SQL statement. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLNativeSql( SQLHDBC ConnectionHandle, const SQLCHAR * InStatementText, SQLINTEGER TextLength1, SQLCHAR * OutStatementText, SQLINTEGER BufferLength, SQLINTEGER * TextLength2Ptr) Arguments ConnectionHandle (input) Connection handle. InStatementText (input) SQL text string to be translated. TextLength1 (input) Length in characters of *InStatementText text string. OutStatementText (output) Pointer to a buffer in which to return the translated SQL string. If OutStatementText is NULL, 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. BufferLength (input) Number of characters in the *OutStatementText buffer. TextLength2 (output) Pointer to a buffer in which to return the total number of characters (excluding null-termination) available to return in *OutStatementText. If the number of characters available to return is greater than or equal to BufferLength, the translated SQL string in *OutStatementText is truncated to BufferLength minus the length of a null-termination character. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 110

111 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLNativeSql. RDM ODBC API Reference 111

112 SQLNumParams Determines the number of parameters in a prepared statement Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLNumParams( SQLHSTMT StatementHandle, SQLSMALLINT * ParameterCountPtr) Arguments StatementHandle (input) Statement handle. ParameterCountPtr (output) Pointer to a buffer in which to return the number of parameters in the statement. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- RDM ODBC API Reference 112

113 DiagField. 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. For more information, reference MSDN documentation for SQLNumParams. RDM ODBC API Reference 113

114 SQLNumResultCols Returns the number of columns in a result set. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLNumResultCols( SQLHSTMT StatementHandle, SQLSMALLINT * ColumnCountPtr) Arguments StatementHandle (input) Statement handle. ColumnCountPtr (output) Pointer to a buffer in which to return the number of columns in the result set. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- RDM ODBC API Reference 114

115 DiagField. 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. For more information, reference MSDN documentation for SQLNumResultsCol. RDM ODBC API Reference 115

116 SQLParamData SQLParamData is used together with SQLPutData to supply parameter data at statement execution time, and with SQLGetData to retrieve streamed output parameter data. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLParamData( SQLHSTMT StatementHandle, SQLPOINTER * ValuePtrPtr) Arguments StatementHandle (input) Statement handle. ValuePtrPtr (output) 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), as contained in the SQL_DESC_DATA_PTR descriptor record field. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField to retrieve additional information. The contents of any out- RDM ODBC API Reference 116

117 SQL_INVALID_HANDLE put 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLParamData. RDM ODBC API Reference 117

118 SQLPrepare Prepares an SQL string for execution. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLPrepare( SQLHSTMT StatementHandle, SQLCHAR * StatementText, SQLINTEGER TextLength); Arguments StatementHandle (input) Statement handle. StatementText (input) SQL text string. TextLength (input) Length of *StatementText in characters. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 RDM ODBC API Reference 118

119 For more information, reference MSDN documentation for SQLPrepare. descriptor handle. This indicates a programming error. No additional information is available from SQLGetDiagRec or SQLGet- DiagField. 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. RDM ODBC API Reference 119

120 SQLPrimaryKeys Returns the column names that make up the primary key for a table. The driver returns the information as a result set. This function does not support returning primary keys from multiple tables in a single call. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLPrimaryKeys( SQLHSTMT StatementHandle, SQLCHAR * CatalogName, SQLSMALLINT NameLength1, SQLCHAR * SchemaName, SQLSMALLINT NameLength2, SQLCHAR * TableName, SQLSMALLINT NameLength3); Arguments StatementHandle (input) Statement handle. CatalogName (input) Catalog name. CatalogName cannot contain a string search pattern. NameLength1 (input) Length in characters of *CatalogName. SchemaName (input) Schema name. SchemaName cannot contain a string search pattern. NameLength2 (input) Length in characters of *SchemaName. TableName (input) Table name. This argument cannot be a null pointer. TableName cannot contain a string search pattern. NameLength3 (input) Length in characters of *TableName. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 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 120

121 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLPrimaryKeys returns the information that pertains to the databases that are currently open. If no database is open on the data source, SQLPrimaryKeys returns an empty result set. For more information, reference MSDN documentation for SQLPrimaryKeys. RDM ODBC API Reference 121

122 SQLProcedureColumns Returns the parameter and column information about the specified procedures. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLProcedureColumns( SQLHSTMT StatementHandle, SQLCHAR * CatalogName, SQLSMALLINT NameLength1, SQLCHAR * SchemaName, SQLSMALLINT NameLength2, SQLCHAR * ProcName, SQLSMALLINT NameLength3, SQLCHAR * ColumnName, SQLSMALLINT NameLength4); Arguments StatementHandle (input) Statement handle. CatalogName (input) Procedure catalog name. CatalogName cannot contain a string search pattern. NameLength1 (input) Length in characters of *CatalogName. SchemaName (input) String search pattern for procedure schema names. NameLength2 (input) Length in characters of *SchemaName. ProcName (input) String search pattern for procedure names. NameLength3 (input) Length in characters of *ProcName. ColumnName (input) String search pattern for column names. NameLength4 (input) Length in characters of *ColumnName. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 122

123 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLProcedureColumns returns the information that pertains to the databases that are currently open. If no database is open on the data source, SQLProcedureColumns returns an empty result set. For more information, reference MSDN documentation for SQLProcedureColumns. RDM ODBC API Reference 123

124 SQLProcedures Returns the list of procedure names stored in a specific data source. Procedure is a generic term used to describe an executable object, or a named entity that can be invoked using input and output parameters. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLProcedures( SQLHSTMT StatementHandle, SQLCHAR * CatalogName, SQLSMALLINT NameLength1, SQLCHAR * SchemaName, SQLSMALLINT NameLength2, SQLCHAR * ProcName, SQLSMALLINT NameLength3); Arguments StatementHandle (input) Statement handle. CatalogName (input) Procedure catalog. NameLength1 (input) Length in characters of *CatalogName. SchemaName (input) String search pattern for procedure schema names. NameLength2 (input) Length in characters of *SchemaName. ProcName (input) String search pattern for procedure names. NameLength3 (input) Length in characters of *ProcName. Required Headers #include "sqlext.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS Function completed successfully. The application calls SQLGet- RDM ODBC API Reference 124

125 SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLProcedures returns the information that pertains to the databases that are currently open. If no database is open on the data source, SQLProcedures returns an empty result set. For more information, reference MSDN documentation for SQLProcedures. RDM ODBC API Reference 125

126 SQLPutData Allows an application to send data for a parameter or column to the driver at statement execution time. This function can be used to send character or binary data values in parts to a column with a character, binary, or data source specific data type (for example, parameters of the SQL_LONGVARBINARY or SQL_LONGVARCHAR types). Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLPutData( SQLHSTMT StatementHandle, SQLPOINTER DataPtr, SQLLEN StrLen_or_Ind); Arguments StatementHandle (input) Statement handle. DataPtr (input) Pointer to a buffer containing the actual data for the parameter or column. The data must be in the C data type specified in the ValueType argument of SQLBind- Parameter (for parameter data) or the TargetType argument of SQLBindCol (for column data). StrLen_or_Ind (input) Length of *DataPtr. Specifies the amount of data sent in a call to SQLPutData. The amount of data can vary with each call for a given parameter or column. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS Function completed successfully. The application calls SQLGet- DiagField to retrieve additional information from the header record. RDM ODBC API Reference 126

127 SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLPutData can only be called to insert or update column values. Calling SQLPutData on any other type of SQL statement returns a "data-at-exec params only allowed with INSERT VALUES/UPDATE" error (SQLSTATE "RX021"). Also, SQLPutData can only be used with columns of the following data types: SQL_LONGVARCHAR, SQL_ LONGWVARCHAR and SQL_LONGVARBINARY. Calling SQLPutData on a column of any other data type returns a "data-at-exec params only allowed for blob (long var...) columns" error ("SQLSTATE RX022"). For more information, reference MSDN documentation for SQLPutData. RDM ODBC API Reference 127

128 SQLRowCount Gets row count in a table following an INSERT, UPDATE, or DELETE Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLRowCount ( SQLHSTMT StatementHandle, SQLINTEGER *RowCount) Arguments StatementHandle (input) Statement handle. RowCount (output) Points to a buffer in which to return a row count. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- RDM ODBC API Reference 128

129 DiagField. 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. Comments If the last SQL statement executed was not an INSERT, UPDATE, DELETE, IMPORT or EXPORT, SQLRow- Count will return -1 to *RowCount. For more information, reference MSDN documentation for SQLRowCount. RDM ODBC API Reference 129

130 SQLSetConnectAttr Sets attributes that govern aspects of connections. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetConnectAttr( SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength); Arguments ConnectionHandle (input) Connection handle. Attribute (input) Attribute to set, listed in "Comments." ValuePtr (input) Pointer to the value to be associated with Attribute. Depending on the value of Attribute, ValuePtr will be a 32-bit unsigned integer value or will point to a nullterminated character string. Note that if the Attribute argument is a driver-specific value, the value in ValuePtr may be a signed integer. StringLength (input) If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. For character string data, this argument should contain the number of bytes in the string. If Attribute is an ODBC-defined attribute and ValuePtr is an integer, StringLength is ignored. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS Function completed successfully. The application calls SQLGet- RDM ODBC API Reference 130

131 SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments Attribute ODBC ValuePtr Contents SQL_ATTR_ACCESS_MODE [1][5] 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. SQL_ATTR_ASYNC_ENABLE 3.0 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. SQL_ATTR_AUTO_IPD 3.0 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- RDM ODBC API Reference 131

132 Attribute ODBC ValuePtr Contents ported. An application can set the SQL_ATTR_ENA- BLE_AUTO_IPD statement attribute to enable the automatic population of the IPD. This is a read-only attribute and cannot be set by SQLSetConnectAttr. SQL_ATTR_AUTOCOMMIT [2] 1.0 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. SQL_ATTR_CONNECTION_DEAD 3.5 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. SQL_ATTR_CONNECTION_TIMEOUT 1.0 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. SQL_ATTR_CURRENT_CATALOG [1] 2.0 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. SQL_ATTR_LOGIN_TIMEOUT 1.0 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: RDM ODBC API Reference 132

133 Attribute ODBC ValuePtr Contents 0 = there is no timeout. SQL_ATTR_METADATA_ID 3.0 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. SQL_ATTR_ODBC_CURSORS 2.0 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. SQL_ATTR_TXN_ISOLATION 1.0 An SQLUINTEGER value that indicates the transaction isolation level of the current connection. RDM supports the following values: 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. SQL_ATTR_RDM_DBCAT_COUNT SQL_ATTR_RDM_DEFER_BLOB 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- RDM ODBC API Reference 133

134 Attribute ODBC ValuePtr Contents umn is bound. A call to SQLGetData will simply copy the already-retrieved data into the application buffer. This is the default. SQL_ATTR_RDM_REMOTE_CONN [1][3] SQL_TRUE = the reading of BLOB data is deferred. It means the value of a BLOB column is not retrieved when the column is fetched but not bound. A call to SQLGetData will retrieve the actual column value. RDM An SQLUINTEGER value that indicates the type of connection an application makes with the RDM core engine. The following values are supported. SQL_CT_UNKNOWN = Whether RDM ODBC uses the embedded core engine or a remote server is unknown. This is the default. SQL_CT_LOCAL = the RDM ODBC Driver will use the embedded core engine. 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. SQL_ATTR_RDM_REMOTE_NAME [1] SQL_ATTR_RDM_RESERVE_BYTES [1] SQL_ATTR_RDM_TFS_PORT [1] SQL_ATTR_RDM_TFSINIT_DISKLESS [4] SQL_ATTR_RDM_TFSINIT_DOCROOT [4] SQL_ATTR_RDM_TFSINIT_LOGFILE [4] The name of the remote server can be specified with the SQL_ATTR_RDM_REMOTE_NAME attribute RDM A character string that indicates the name of the remote RDM host that the driver will connect to for database access. The default is "localhost." RDM An SQLUINTEGER value that indicates the number of bytes RDM SQL will reserve at connection time. The default value is 0. RDM An SQLUSMALLINT value that indicates the port number the target TFS is listening on. The default is RDM A 32-bit integer that indicates whether the embedded TFServer uses the "diskless" mode. If SQL_TRUE, the driver uses the "diskless" mode. If SQL_FALSE, the driver does not use the "diskless" mode. The default is SQL_FALSE. RDM A character string that contains the documentation root (docroot) of the embedded TFServer. If the value of this attribute is not set and the RDM_ DOCROOT environment variable is set, the value in RDM_DOCROOT will be used. If neither is set, the application's working directory will be used. RDM A character string that contains the name of the log file RDM ODBC API Reference 134

135 Attribute ODBC ValuePtr Contents where the activities of the embedded TFServer will be logged. The default is NULL, in which case activities will not be logged. SQL_ATTR_RDM_TFSINIT_PORT [4] RDM A 32-bit integer that contains the port number of the embedded TFServer. The default value is port SQL_ATTR_RDM_TFS_READONLY [4] RDM A 32-bit integer that indicates whether the embedded TFServer is in read-only mode. If SQL_TRUE, the embedded TFServer will only allow read operations on its databases. If SQL_FALSE, both read and write operations will be allowed. The default is SQL_FALSE. SQL_ATTR_RDM_TFSINIT_STDOUT [4] RDM A charater string that contains the name of the file the stdout of the embedded TFServer will be redirected to. The default is NULL, in which case the console output will be directed to stdout. SQL_ATTR_RDM_TFSINIT_TYPE RDM A 32-bit integer that indicates the type of the TFServer used with an application. RDM supports the following values: SQL_TFSTYPE_TFS = An embedded TFServer (TFST) will be used. SQL_TFSTYPE_RPC = A remote TFServer (TFSR) will be used. This option requires that an application have access to a running TFServer process. SQL_TFSTYPE_STANDALONE = A standalone TFServer (TFSS) will be used. SQL_TFSTYPE_DEFAULT = The default TFServer will be used. This is identical to SQL_TFSTYPE_TFS unless the RDM source code is modified and recompiled. SQL_ATTR_RDM_TFSINIT_VERBOSE [4] The default value is SQL_TFSTYPE_DEFAULT. RDM A 32-bit integer that indicates whether the verbose mode is enabled. If SQL_TRUE, 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). If SQL_FALSE, such detailed messages will not be displayed. The default is SQL_ FALSE. [1] Those attributes can be set before or after connecting to RDM SQL. However, the values set after a connection 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

136 [2] Those attributes can be set before and after connecting to RDM SQL. However, the values set or retrieved before a connection has been established may not reflect the value stored in the RDM SQL SQL engine. The application should always set/get those attribute values while the connection to the data source is on. [3] If the SQL_ATTR_RDM_CONN_TYPE attribute is set to SQL_CT_UNKNOWN at the time of connection, SQLConnect or SQLDriverConnect will determine the connection type by checking the values of SQL_ATTR_ RDM_REMOTE_NAME, SQL_ATTR_RDM_TFS_NAME, and in the case of SQLConnect, the value of first argument. Once the connection type has been determined, that type will be stored in the SQL_ATTR_RDM_CONN_ TYPE attribute. For details, see SQLConnect and SQLDriverConnect. [4] Values set with those attributes will have no effect if the application does not use an embedded TFServer ("tfss" or "tfst"). [5] In RDM ODBC, the processing of a SQL statement that is not read-only on a read-connection gives a STATE error at the statement preparation time. For more information, reference MSDN documentation for SQLSetConnectAttr. RDM ODBC API Reference 136

137 SQLSetCursorName Associates a cursor name with an active statement. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetCursorName ( SQLHSTMT StatementHandle, SQLCHAR *CursorName, SQLSMALLINT BufferLength) Arguments StatementHandle (input) Statement handle. CursorName (input) Cursor name. For efficient processing, the cursor name should not include any leading or trailing spaces in the cursor name, and if the cursor name includes a delimited identifier, the delimiter should be positioned as the first character in the cursor name. NameLength (input) Length in characters of *CursorName. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR Function completed successfully. The application calls SQLGet- 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 SQLGet- RDM ODBC API Reference 137

138 SQL_INVALID_HANDLE DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLCursorName. RDM ODBC API Reference 138

139 SQLSetDescField Sets the value of a single field of a descriptor record. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetDescField( SQLHDESC DescriptorHandle, SQLSMALLINT RecNumber, SQLSMALLINT FieldIdentifier, SQLPOINTER ValuePtr, SQLINTEGER BufferLength); Arguments DescriptorHandle (input) Descriptor handle. RecNumber (input) Indicates the descriptor record containing the field that the application seeks to set. Descriptor records are numbered from 0, with record number 0 being the bookmark record. The RecNumber argument is ignored for header fields. FieldIdentifier (input) Indicates the field of the descriptor whose value is to be set. ValuePtr (input) Pointer to a buffer containing the descriptor information, or a 4-byte value. The data type depends on the value of FieldIdentifier. If ValuePtr is a 4-byte value, either all four of the bytes are used or just two of the four are used, depending on the value of the FieldIdentifier argument. BufferLength (input) If FieldIdentifier is an ODBC-defined field and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. For character string data, this argument should contain the number of bytes in the string. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 139

140 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLSetDescField. RDM ODBC API Reference 140

141 SQLSetDescRec Sets multiple descriptor fields that affect the data type and buffer bound to a column or parameter data. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetDescRec( SQLHDESC DescriptorHandle, SQLSMALLINT RecNumber, SQLSMALLINT Type, SQLSMALLINT SubType, SQLLEN Length, SQLSMALLINT Precision, SQLSMALLINT Scale, SQLPOINTER DataPtr, SQLLEN * StringLengthPtr, SQLLEN * IndicatorPtr); Arguments DescriptorHandle (input) Descriptor handle. This must not be an IRD handle. RecNumber (input) Indicates the descriptor record that contains the fields to be set. Descriptor records are numbered from 0, with record number 0 being the bookmark record. This argument must be equal to or greater than 0. If RecNumber is greater than the value of SQL_DESC_COUNT, SQL_DESC_COUNTis changed to the value of RecNumber. Type (input) The value to which to set the SQL_DESC_TYPE field for the descriptor record. SubType (input) For records whose type is SQL_DATETIME or SQL_INTERVAL, this is the value to which to set the SQL_DESC_DATETIME_INTERVAL_CODE field. Length (input) The value to which to set the SQL_DESC_OCTET_LENGTH field for the descriptor record. Precision (input) The value to which to set the SQL_DESC_PRECISION field for the descriptor record. Scale (input) The value to which to set the SQL_DESC_SCALE field for the descriptor record. DataPtr (input/output) The value to which to set the SQL_DESC_OCTET_LENGTH_PTR 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. IndicatorPtr (input/output) The value to which to set the SQL_DESC_INDICATOR_PTR field for the descriptor record. IndicatorPtr can be set to a null pointer to set the SQL_DESC_INDICATOR_PTR field to a null pointer. RDM ODBC API Reference 141

142 Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. For more information, reference MSDN documentation for SQLSetDescRec. RDM ODBC API Reference 142

143 SQLSetEnvAttr Sets attributes that govern aspects of environments. Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetEnvAttr( SQLHENV EnvironmentHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength); Arguments EnvironmentHandle (input) Environment handle. Attribute (input) Attribute to set, listed in "Comments." ValuPtr (input) Pointer to the value to be associated with Attribute. Depending on the value of Attribute, ValuePtr will be a 32-bit integer value or point to a null-terminated character string. StringLength (input) If ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. For character string data, this argument should contain the number of bytes in the string. If ValuePtr is an integer, StringLength is ignored. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 Function completed successfully. The application calls SQLGet- DiagField to retrieve additional information from the header record. Function completed successfully, possibly with a nonfatal error (warn- RDM ODBC API Reference 143

144 SQL_ERROR SQL_INVALID_HANDLE ing). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information. Function failed. The application calls SQLGetDiagRec or SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments Attribute and ValuePtr RDM accepts the following attribute values. Attribute ODBC ValuePtr contents SQL_ATTR_CONNECTION_POOLING 3.0 A 32-bit SQLUINTEGER value that enables or disables connection pooling at the environment level. RDM accepts the following values: SQL_CP_OFF = Connection pooling is turned off. SQL_ATTR_CP_MATCH 3.0 A 32-bit SQLUINTEGER value that determines how a connection is chosen from a connection pool. RDM does not support setting this value since it does not support connection pooling. SQL_ATTR_ODBC_VERSION 3.0 A 32-bit integer that determines whether certain functionality exhibits ODBC 2.x behavior or ODBC 3.x behavior. RDM accepts the following values. SQL_OV_ODBC3 = The driver exhibits the following ODBC 3.x behavior: The driver returns and expects ODBC 3.x codes for date, time, and timestamp The driver returns ODBC 3.x SQLSTATE codes when SQLGetDiagField, or SQLGet- DiagRec is called The CatalogName argument in a call to SQLTables accepts a search pattern. The driver does not support C data type extensibility. RDM does not require that this attribute be explicitly set before an application calls other functions that have an SQLHENV argument. SQL_ATTR_OUTPUT_NTS 3.0 A 32-bit integer that determines how the driver returns RDM ODBC API Reference 144

145 Attribute ODBC ValuePtr contents string data. If SQL_TRUE, the driver returns string data null-terminated. If SQL_FALSE, the driver does not return string data null-terminated. For more information, reference MSDN documentation for SQLSetEnvAttr. RDM ODBC API Reference 145

146 SQLSetError Registers user-defined status/error handling functions. Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQLSetError( SQLSMALLINT HandleType, SQLHANDLE Handle, SQLRETURN ErrorCode, ECALLBACK ErrorHandler); Arguments HandleType (input) Handle type identifier. The following values are accepted. SQL_HANDLE_DBC SQL_HANDLE_DESC SQL_HANDLE_STMT Handle (input) The handle, of the type indicated by HandleType, indicating the scope of the transaction. ErrorCode (input) The ODBC error code for which to register the error handler. ErrorHandler (input) A pointer to the error handler function. (See Error Handler Prototype below). The application can specify NULL in order to unregister the error handler. Required Headers #include "sqlrext.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 146

147 Error Handler Prototype int32_t SQL_API errhandler( int16_t HandleType, SQLHANDLE Handle, SQLRETURN error_code); Return Codes Return Code SQL_SUCCESS SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- DiagField to retrieve additional information from the header record. Function failed. The application calls SQLGetDiagRec or SQLGet- DiagField 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 SQLGet- DiagField. 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. Diagnostics SQLSTATE Error HY001 Memory allocation error Either the ODBC driver or the SQL engine failed to allocate sufficient memory to complete the required operation. HY010 Function sequence error This function was called after SQLExecute or SQLExecDirect but before all the parameters were bound. RDM ODBC API Reference 147

148 SQLSetStmtAttr Sets attributes related to a statement Conformance Version Introduced: ODBC 3.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLSetStmtAttr( SQLHSTMT StatementHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength) Arguments StatementHandle (input) Statement handle. Attribute (input) Specifies the statement option type. Possible values are described in "Comments" below. ValuePtr (input) Pointer to the value to be associated with Attribute. Depending on the value of Attribute, ValuePtr will be a 32-bit unsigned integer value, or will point to a null-terminated character string. StringLength (input) If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. If Attribute is an ODBC-defined attribute and ValuePtr is an integer, StringLength is ignored. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS Function completed successfully. The application calls SQLGet- DiagField to retrieve additional information from the header record. RDM ODBC API Reference 148

149 SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments Attributes and ValuePtr RDM accepts the following attribute values. Attribute ODBC ValuePtr contents SQL_ATTR_APP_PARAM_DESC 3.0 The handle to the APD. The handle will replace the handle currently associated with the APD. SQL_NULL_ DESC can be specified to dissociate the current handle from the APD; in that case, the APD will revert to the implicitly allocated internal handle. This attribute cannot be set to an implicitly allocated handle except for the handle that was originally implicitly allocated for this APD. SQL_ATTR_APP_ROW_DESC 3.0 The handle to the ARD. The handle will replace the handle currently associated with the APD. SQL_ NULL_DESC can be specified to dissociate the current handle from the APD; in that case, the ARD will revert to the implicitly allocated internal handle. This attribute cannot be set to an implicitly allocated handle except for the handle that was originally implicitly allocated for this ARD. SQL_ATTR_ASYNC_ENABLE 3.0 An SQLULEN value that specifies whether functions on this statement handle are executed asynchronously. The possible values are: SQL_ASYNC_ENABLE_OFF = Disable statement-level asynchronous execution support (default). The following values are not supported: SQL_ASYNC_ENABLE_ON RDM ODBC API Reference 149

150 Attribute ODBC ValuePtr contents SQL_ATTR_CONCURRENCY 2.0 A SQLULEN value that specifies the cursor concurrency. The possible values are: SQL_CONCUR_READ_ONLY = Cursor is read-only; updates are not allowed (default). SQL_CONCUR_LOCK = Cursor uses the lowest-level locking necessary to perform updates. The following values are not supported: SQL_CONCUR_ROWVER SQL_CONCUR_VALUES If an unsupported value is specified, SQLSetStmtAttr substitutes SQL_CONCUR_LOCK for it and returns 01S02 ("option value changed") at execution time. SQL_ATTR_CURSOR_SCROLLABLE 3.0 An SQLULEN value that specifies whether the cursor is scrollable. The possible values are: SQL_NONSCROLLABLE = The cursor is not scrollable (default). Only SQL_FETCH_NEXT is supported for SQLFetchScroll. The following values are not supported: SQL_SCROLLABLE SQL_ATTR_CURSOR_SENSITIVITY 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 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). The following values are not supported: SQL_INSENSITIVE SQL_SENSITIVE SQL_ATTR_CURSOR_TYPE 2.0 An SQLULEN value that specifies the cursor type. The possible values are: SQL_CURSOR_FORWARD_ONLY = The cursor scrolls forward-only (default). The following values are not supported: SQL_CURSOR_STATIC SQL_CURSOR_KEYSET_DRIVEN SQL_CURSOR_DYNAMIC RDM ODBC API Reference 150

151 Attribute ODBC ValuePtr contents RDM ODBC only supports forward-only cursors. SQL_ATTR_ENABLE_AUTO_IPD 3.0 An SQLULEN value that specifies whether the IPD is populated automatically. The possible values are: SQL_TRUE = The IPD is automatically populated after SQLPrepare. SQL_FALSE = The IPD is not automatically populated after SQLPrepare(). The application should call SQLDescribeParam to obtain the IPD information (default). SQL_ATTR_FETCH_BOOKMARK_PTR 3.0 Not supported. Setting this attribute has no effect. SQL_ATTR_IMP_PARAM_DESC 3.0 The handle to the IPD. This is a read-only attribute. The application can call SQLGetStmtAttr to retrieve the value of the attribute. SQL_ATTR_IMP_ROW_DESC 3.0 The handle to the IRD. This is a read-only attribute. The application can call SQLGetStmtAttr to retrieve the value of the attribute. SQL_ATTR_KEYSET_SIZE 2.0 An SQLULEN value that specifies the number of rows in the keyset for a keyset-driven cursor.rdm does not support this attribute. Setting this attribute has no effect. SQL_ATTR_MAX_LENGTH 1.0 An SQLULEN value that specifies the maximum amount of data the RDM ODBC driver returns from a binary or character column. The default value is 0. In that case, RDM ODBC Driver attempts to return all available data. If the specified length is less than the length of the available data, the data is truncated and SQL_SUCCESS is returned. SQL_ATTR_MAX_ROWS 1.0 An SQLULEN value that specifies the maximum number of rows returned by a select statement. The default value is 0. In that case, RDM ODBC Driver attempts to return all rows. If set to non-zero, this value sets the maximum value for the cursor row count. SQL_ATTR_METADATA_ID 3.0 An SQLULEN value that specifies how the string arguments of catalog functions are treated. The possible values are: SQL_FALSE = the string arguments of catalog functions are not treated as identifiers. Arguments are case-sensitive and may contain a string search pattern (default). The following values are not supported: RDM ODBC API Reference 151

152 Attribute ODBC ValuePtr contents SQL_TRUE SQL_ATTR_NOSCAN 1.0 An SQLULEN value that indicates whether the RDM ODBC Driver should scan SQL strings for escape sequences. The possible values are: SQL_NOSCAN_OFF = SQL strings are scanned for escape sequences (default). SQL_NOSCAN_ON = SQL strings are not scanned for escape sequences. They are passed directly to the data source. SQL_ATTR_PARAM_BIND_OFFSET_PTR 3.0 An SQLULEN pointer that points to an offset value added to pointers to change dynamic parameter binding. If non-null, the pointer will be dereferenced, and the value contained will be added to each of the dereferenced fields in the APD. The affected fields are: SQL_DESC_DATA_PTR SQL_DESC_INDICATOR_PTR SQL_DESC_OCTET_LENGTH_PTR The default value is NULL. SQL_ATTR_PARAM_BIND_TYPE 3.0 An SQLULEN value that specifies the binding orientation to be used for dynamic parameters. The possible values are: SQL_PARAM_BIND_BY_COLUMN = Perform columnwise binding (default). Row-wise binding is not supported. SQL_ATTR_PARAM_OPERATION_PTR 3.0 Not supported. Setting this attribute has no effect. SQL_ATTR_PARAM_STATUS_PTR 3.0 Not supported. Setting this attribute has no effect. SQL_ATTR_PARAMS_PROCESSED_PTR 3.0 Not supported. Setting this attribute has no effect. SQL_ATTR_PARMSET_SIZE 3.0 Not supported. Setting this attribute has no effect. SQL_ATTR_QUERY_TIMEOUT An SQLULEN value that specifies the number of seconds RDM SQL uses in requesting locks on databases for statement execution. If locking is not granted within the specified timeout period, the statement execution returns with a "timeout expired " error (SQLSTATE "HYT00"). The default value for this attribute is 10 (seconds). It is different from the default value (0, or no timeout) specified by ODBC. SQL_ATTR_RETRIEVE_DATA 2.0 An SQULEN value that specifies whether SQLFetch 1 Although SQL_ATTR_QUERY_TIMEOUT is a statement attribute, the value is effective on the connection level in RDM ODBC. Changing the value of this attribute on one statement handle will affect all the other statement handles allocated from the same connection handle. RDM ODBC API Reference 152

153 Attribute ODBC ValuePtr contents and SQLFetchScroll retrieve data after it positions the cursor. The possible values are: SQL_RD_ON = Data are retrieved (default). The following values are not supported: SQL_RD_OFF SQL_ATTR_ROW_ARRAY_SIZE 3.0 An SQLULEN value that specifies the number of rows returned by each call to SQLFetch or SQLFetch- Scroll. The default value is 1. SQL_ATTR_ROW_BIND_OFFSET_PTR 3.0 An SQLULEN pointer that points to an offset value added to pointers to change column binding. If nonnull, the pointer will be dereferenced, and the value contained will be added to each of the dereferenced fields in the ARD. The affected fields are: SQL_DESC_DATA_PTR SQL_DESC_INDICATOR_PTR SQL_DESC_OCTET_LENGTH_PTR The default value is NULL. SQL_ATTR_ROW_BIND_TYPE 1.0 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). Row-wise binding is not supported. SQL_ATTR_ROW_NUMBER 2.0 An SQLULEN value that indicates the number of the current row in the entire result set. If the value cannot be determined or there is no current row, 0 will be returned. This is a read-only attribute. The application can call SQLGetStmtAttr to retrieve the value of the attribute. SQL_ATTR_ROW_OPERATION_PTR 3.0 Not supported. Setting this attribute has no effect. SQL_ATTR_ROW_STATUS_PTR 3.0 An SQLUSMALLINT pointer that points to an array of SQLUSMALLINT values that will contain the row status values after SQLFetch or SQLFetchScroll was called. The array has the same number of elements as the number of rows in the rowset. The default value of this attribute is NULL. In that case, row status values will not be returned to the application. SQL_ATTR_ROWS_FETCHED_PTR 3.0 An SQLULEN pointer that points to a buffer in which the number of rows fetched by SQLFetch or SQLFetch- Scroll is stored. RDM ODBC API Reference 153

154 Attribute ODBC ValuePtr contents The default value of this attribute is NULL. In that case, the number of result rows will not be returned to the application. SQL_ATTR_SIMULATE_CURSOR 2.0 An SQLULEN value that specifies whether RDM ODBC Driver guarantees positioned update and delete statements affect only one row. The possible values are: SQL_SC_NON_UNIQUE = The driver does not guarantee that simulated 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 = The driver guarantees that simulated positioned update and delete statements affect only one row (default). 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. Specifying SQL_SC_ TRY_UNIQUE or SQL_SC_NON_UNIQUE will return SQL_SUCCESS_WITH_INFO ("01S02"). SQL_ATTR_USE_BOOKMARKS 2.0 An SQLULEN value that specifies whether bookmarks are used with a cursor. The possible values are: SQL_UB_OFF = Off (default). The following values are not supported: SQL_UB_ON For more information, reference MSDN documentation for SQLSetStmtAttr. RDM ODBC API Reference 154

155 SQLSpecialColumns Returns the information about the set of columns that uniquely identifies a row in the table. Conformance Version Introduced: ODBC 1.0 Standards Compliance: Open Group Syntax SQLRETURN SQLSpecialColumns( SQLHSTMT StatementHandle, SQLSMALLINT IdentifierType, SQLCHAR * CatalogName, SQLSMALLINT NameLength1, SQLCHAR * SchemaName, SQLSMALLINT NameLength2, SQLCHAR * TableName, SQLSMALLINT NameLength3, SQLSMALLINT Scope, SQLSMALLINT Nullable); Arguments StatementHandle (input) Statement handle for retrieved results. IdentifierType (input) Type of column to return. Must be one of the following values: SQL_BEST_ROWID: Returns the optimal column or set of columns that, by retrieving values from the column or columns, allows any row in the specified table to be uniquely identified. 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. SQL_ROWVER: Returns the column or columns in the specified table, if any, 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). CatalogName (input) Catalog name for the table. 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 ("") denotes those tables that do not have catalogs. CatalogName cannot contain a string search pattern. NameLength1 (input) Length in characters of *CatalogName. SchemaName (input) Schema name for the table. 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 ("") denotes those tables that do not have schemas. SchemaName cannot contain a string search pattern. NameLength2 (input) Length in characters of *SchemaName. TableName (input) Table name. This argument cannot be a null pointer. TableName cannot contain a string search pattern. RDM ODBC API Reference 155

156 NameLenght3 (input) Length in characters of *TableName. Scope (input) Minimum required scope of the rowid. The returned rowid may be of greater scope. Must be one of the following: SQL_SCOPE_CURROW: The rowid is guaranteed to be valid only while positioned on that row. A later reselect using rowid may not return a row if the row was updated or deleted by another transaction. SQL_SCOPE_TRANSACTION: The rowid is guaranteed to be valid for the duration of the current transaction. SQL_SCOPE_SESSION: The rowid is guaranteed to be valid for the duration of the session (across transaction boundaries). Nullable (input) Determines whether to return special columns that can have a NULL value. Must be one of the following: SQL_NO_NULLS: Exclude special columns that can have NULL values. Some drivers cannot support SQL_NO_NULLS, and these drivers will return an empty result set if SQL_NO_NULLS was specified. Applications should be prepared for this case and request SQL_NO_NULLS only if it is absolutely required. SQL_NULLABLE: Return special columns even if they can have NULL values. Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 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 SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 RDM ODBC API Reference 156

157 information is available from SQLGetDiagRec or SQLGet- DiagField. 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. Comments SQLSpecialColumns returns the information that pertains to the databases that are currently open. If no database is open on the data source, SQLSpecialColumns returns an empty result set. For more information, reference MSDN documentation for SQLSpecialColumns. RDM ODBC API Reference 157

158 SQLStatistics Retrieves a list of statistics about a single table and the indexes associated with the table. The driver returns the information as a result set. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLStatistics( SQLHSTMT StatementHandle, SQLCHAR * CatalogName, SQLSMALLINT NameLength1, SQLCHAR * SchemaName, SQLSMALLINT NameLength2, SQLCHAR * TableName, SQLSMALLINT NameLength3, SQLUSMALLINT Unique, SQLUSMALLINT Reserved); Arguments StatementHandle (input) Statement handle for retrieved results. CatalogName (input) Catalog name. NameLength1 (input) Length in characters of *CatalogName. SchemaName (input) Schema name. 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. SchemaName cannot contain a string search pattern. NameLength2 (input) Length in characters of *SchemaName. TableName (input) Table name. This argument cannot be a null pointer. SchemaName cannot contain a string search pattern. NameLenght3 (input) Length in characters of *TableName. Unique (input) Type of index: SQL_INDEX_UNIQUE or SQL_INDEX_ALL. Reserved (input) Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library RDM ODBC API Reference 158

159 See Library Naming Conventions section for full library name and a list of library dependencies. Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLStatistics returns the information that pertains to the databases that are currently open. If no database is open on the data source, SQLStatistics returns an empty result set. For more information, reference MSDN documentation for SQLStatistics. RDM ODBC API Reference 159

160 SQLTables Returns the list of table, catalog, or schema names, and table types, stored in a specific data source. Conformance Version Introduced: ODBC 1.0 Standards Compliance: ISO 92 Syntax SQLRETURN SQLTables( SQLHSTMT StatementHandle, SQLCHAR * CatalogName, SQLSMALLINT NameLength1, SQLCHAR * SchemaName, SQLSMALLINT NameLength2, SQLCHAR * TableName, SQLSMALLINT NameLength3, SQLCHAR * TableType, SQLSMALLINT NameLength4); Arguments StatementHandle (input) Statement handle for retrieved results. CatalogName (input) Catalog name. NameLength1 (input) Length in characters of *CatalogName. SchemaName (input) String search pattern for schema names. NameLength2 (input) Length in characters of *SchemaName. TableName (input) String Search pattern for table names. NameLenght3 (input) Length in characters of *TableName. TableType (input) List of table types to match. NameLength4 (input) Length in characters of *TableType Required Headers #include "sql.h" Libraries Library Name rdmrdbc11 RDM ODBC API Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 160

161 Returns Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. Comments SQLTables returns the information that pertains to the databases that are currently open. If no database is open on the data source, SQLTables returns an empty result set. For more information, reference MSDN documentation for SQLTables. RDM ODBC API Reference 161

162 SQLTransactStatus Retrieves the type and status of the transaction possibly executed on the handle. Conformance Version Introduced: RDM ODBC API extension Syntax SQLRETURN SQL_API SQLTransactStatus( SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT *pactive) Arguments HandleType (input) Handle type identifier. The following values are accepted. Contains either SQL_ HANDLE_ENV (if Handle is an environment handle) or SQL_HANDLE_DBC (if Handle is a connection handle). Handle (input) The handle, of the type indicated by HandleType, indicating the scope of the transaction. pactive (output) The status of the transaction on the handle. For the possible return values for pactive, see the table in the Comments section below. Required Headers #include "sqlrext.h" Libraries Library Name rdmrdbc11 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 Function completed successfully. The application calls SQLGet- 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. RDM ODBC API Reference 162

163 SQL_ERROR SQL_INVALID_HANDLE Function failed. The application calls SQLGetDiagRec or SQLGet- DiagField 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 SQLGet- DiagField. 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. Diagnostics SQLSTATE Error Connection not open The Handle argument specifies a connection handle and is not connected to the data source. 25S01 Transaction state unknown The Handle argument specifies an environment handle, and one or more of the connection handles associated with it failed to retrieve the status of its transaction. HY009 Invalid use of null pointer A null pointer was specified for the pactive argument. Comments The following table describes the possible return values of the status of the transaction through the pactive argument. Value of pactive SQL_TXN_INACTIVE SQL_TXN_REGULAR SQL_TXN_READONLY No transaction is active on the specified handle. A regular (i.e. updatable) transaction is active on the specified handle. A read-only transaction (i.e. snapshot) is active on the specified handle. RDM ODBC API Reference 163

164 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 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

165 rdmsqlserver_init Start up a RDM SQL Server Prototype int32_t rdmsqlserver_init( const SQL_PARAMS *params, RDMSQL_CTX **sql_ctx) Parameters params (input) Parameters required for server operation. If NULL, defaults are used. sql_ctx (output) Handle used for running, stopping or terminating this server. Call rdmsqlserver_init to set up the RDM SQL server. This function must be called prior to any rdbc API function calls unless you relay on an external RDM SQL server. Any successful call to rdmsqlserver_init requires a corresponding call to rdmsqlserver_term before termination of the application. This function will also initialize the TFS unless one has already been started. SQL_PARAMS prototypes typedef struct { uint16_t port; uint32_t rd_only; uint32_t no_disk; uint16_t verbose; TFS_TYPE tfs_type; uint16_t no_tfsrun; const char *stdout_file; const char *docroot; } SQL_PARAMS; SQL_PARAMS structure definition Element Declaration port uint16_t TFS anchor port. Should match TFS -p port number (use if default). rd_only uint32_t Read-only device, TRUE or FALSE. no_disk uint32_t Diskless mode, TRUE or FALSE. verbose uint16_t Verbose, true or false. tfs_type TFS_TYPE The type of Transactional File Server to use no_tfsrun uint16_t Whether the tfserver should be started or not (listen) logfile const char * File name to open for logging. Can be NULL. stdout_file const char * The name of a file to write informational messages instead of displaying them to stdout. If the value is NULL or "stdout" the messages will be sent to RDM ODBC API Reference 165

166 Element Declaration stdout. If the value is an empty string ("") no messages will be displayed. Required Headers #include "rdmsqlserver.h" Libraries Library Name rdmsqlserver11 RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies. Return Codes Value Name 0 S_OKAY normal return, okay -225 S_TX_DOCROOT_USED The docroot is already in use -227 S_TX_INVTFSTYPE Invalid TFS type -904 S_NOMEMORY out of memory See Also rdmsqlserver_start rdmsqlserver_stop rdmsqlserver_term SQLConnect d_tfsinit, d_tfsinitex d_tfsrun Example static RDMSQL_CTX *sql_ctx = NULL; static uint16_t sql_finished = 0; SQL_PARAMS sparams; sparams.port= get_tfsport (); sparams.rd_only= get_tfsreadonly (); sparams.no_disk= get_tfsnodisk (); RDM ODBC API Reference 166

167 sparams.verbose= FALSE; sparams.stdout_file= NULL; sparams.docroot= get_tfsdocroot (); sparams.tfs_type= tfstype (); sparams.no_tfsrun= TRUE; sstatus = rdmsqlserver_init(&sparams, &sql_ctx); if (sstatus == S_OKAY) { sstatus = rdmsqlserver_run(sql_ctx, TRUE, &sql_finished); if (sstatus == S_OKAY) { /* The main part of your application */ } (void) rdmsqlserver_term(sql_ctx); } (void) rdmsqlserver_term(sql_ctx); RDM ODBC API Reference 167

168 rdmsqlserver_start Begin execution of RDM SQL server listening and connection threads Prototype int32_t rdmsqlserver_start( RDMSQL_CTX *sql_ctx, DB_BOOLEAN threaded uint16_t rep_done); Parameters sql_ctx (input) Handle returned from a successful rdmsqlserver_init threaded (input) If TRUE, start a new thread for processing utility functionality. rep_done (input) Set to TRUE when server thread has terminated and cleaned up. This function begins the execution of the RDM SQL server listening and connection threads, enabling the connection of other SQL clients in this process. 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. The handle, sql_ctx, must have been obtained through a rdmsqlserver_initcall. If threaded is TRUE, this function will return immediately. This allows the calling program to proceed with other calls to the SQL functions. To terminate the server cleanly at a later time, the rdmsqlserver_stopfunction must be used. When threaded is FALSE, this function will not return unless there is an error or the RDM SQL server has been externally signaled for termination. 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 an application to know when the TFS listening threads have terminated. This parameter may be NULL if it won't be used. Required Headers #include "rdmsqlserver.h" Libraries Library Name rdmsqlserver11 RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies. RDM ODBC API Reference 168

169 Return Codes Value Name 0 S_OKAY normal return, okay -43 S_INVREPHANDLE Invalid replication handle provided -200 S_TX_ERROR generic tx_ error -216 S_TX_LISTEN TCP/IP listen failure in TFS -904 S_NOMEMORY out of memory -924 S_INVNULL invalid NULL parameter See Also rdmsqlserver_init rdmsqlserver_stop rdmsqlserver_term SQLConnect d_tfsrun Example static RDMSQL_CTX *sql_ctx = NULL; static uint16_t sql_finished = 0; SQL_PARAMS sparams; sparams.port= get_tfsport (); sparams.rd_only= get_tfsreadonly (); sparams.no_disk= get_tfsnodisk (); sparams.verbose= FALSE; sparams.stdout_file= NULL; sparams.docroot= get_tfsdocroot (); sparams.tfs_type= tfstype (); sparams.no_tfsrun= TRUE; sstatus = rdmsqlserver_init(&sparams, &sql_ctx); if (sstatus == S_OKAY) { sstatus = rdmsqlserver_run(sql_ctx, TRUE, &sql_finished); if (sstatus == S_OKAY) { /* The main part of your application */ } (void) rdmsqlserver_term(sql_ctx); } (void) rdmsqlserver_term(sql_ctx); RDM ODBC API Reference 169

170 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 This function stops the execution of the RDM SQL server listening and connection threads, unless they have already been terminated. 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. Calling rdmsqlserver_start, if successful, requires a call to rdmsqlserver_stop. On successful termination all threads initiated by rdmsqlserver_start have been terminated. Required Headers #include "rdmsqlserver.h" Libraries Library Name rdmsqlserver11 RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies. Return Codes Value Name 0 S_OKAY normal return, okay See Also rdmsqlserver_start rdmsqlserver_term d_tfsstop RDM ODBC API Reference 170

171 Example static RDMSQL_CTX *sql_ctx = NULL; static uint16_t sql_finished = 0; SQL_PARAMS sparams; sparams.port= get_tfsport (); sparams.rd_only= get_tfsreadonly (); sparams.no_disk= get_tfsnodisk (); sparams.verbose= FALSE; sparams.stdout_file= NULL; sparams.docroot= get_tfsdocroot (); sparams.tfs_type= tfstype (); sparams.no_tfsrun= TRUE; sstatus = rdmsqlserver_init(&sparams, &sql_ctx); if (sstatus == S_OKAY) { sstatus = rdmsqlserver_run(sql_ctx, TRUE, &sql_finished); if (sstatus == S_OKAY) { /* The main part of your application */ } (void) rdmsqlserver_term(sql_ctx); } (void) rdmsqlserver_term(sql_ctx); RDM ODBC API Reference 171

172 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 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. 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. Required Headers #include "rdmsqlserver.h" Libraries Library Name rdmsqlserver11 RDM SQL Server Library See Library Naming Conventions section for full library name and a list of library dependencies. Return Codes Value Name 0 S_OKAY normal return, okay See Also rdmsqlserver_init rdmsqlserver_stop d_tfsterm RDM ODBC API Reference 172

173 Example static RDMSQL_CTX *sql_ctx = NULL; static uint16_t sql_finished = 0; SQL_PARAMS sparams; sparams.port= get_tfsport (); sparams.rd_only= get_tfsreadonly (); sparams.no_disk= get_tfsnodisk (); sparams.verbose= FALSE; sparams.stdout_file= NULL; sparams.docroot= get_tfsdocroot (); sparams.tfs_type= tfstype (); sparams.no_tfsrun= TRUE; sstatus = rdmsqlserver_init(&sparams, &sql_ctx); if (sstatus == S_OKAY) { sstatus = rdmsqlserver_run(sql_ctx, TRUE, &sql_finished); if (sstatus == S_OKAY) { /* The main part of your application */ } (void) rdmsqlserver_term(sql_ctx); } (void) rdmsqlserver_term(sql_ctx); RDM ODBC API Reference 173

174 Return Codes ODBC Each function in ODBC returns a code, known as its return code, which indicates the overall success or failure of the function. For example, the following code calls SQLFetch to retrieve the rows in a result set. It checks the return code of the function to determine if the end of the result set was reached (SQL_NO_DATA), if any warning information was returned (SQL_SUCCESS_WITH_INFO), or if an error occurred (SQL_ERROR). SQLRETURN SQLHSTMT rc; hstmt; while ((rc=sqlfetch(hstmt))!= SQL_NO_DATA) { if (rc == SQL_SUCCESS_WITH_INFO) { // Call function to display warning information. } else if (rc == SQL_ERROR) { // Call function to display error information. break; } // Process row. } The return code SQL_INVALID_HANDLE always indicates a programming error and should never be encountered at run time. All other return codes provide run-time information, although SQL_ERROR may indicate a programming error. The following table defines the return codes. Return Code SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR SQL_INVALID_HANDLE SQL_NO_DATA SQL_NEED_DATA Function completed successfully. The application calls SQLGet- 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 SQLGet- DiagField 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 SQLGet- DiagField. 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. More data is needed, such as when parameter data is sent at execution time or additional connection information is required. The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information, if any. Return Codes ODBC 174

175 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. It can also be specified by calling SQLSetDescField to set the SQL_DESC_CONCISE_TYPE field of an ARD or APD, or by calling SQLSet- DescRec with the Type argument (and the SubType argument if needed) and the DescriptorHandle argument set to the handle of an ARD or APD. The following table lists valid type identifiers for the C data types. The table also lists the ODBC C data type that corresponds to each identifier and the definition of this data type. C type identifier ODBC C typedef C type SQL_C_CHAR SQLCHAR * unsigned char * SQL_C_WCHAR SQLWCHAR * wchar_t * SQL_C_SSHORT SQLSMALLINT int16_t SQL_C_USHORT SQLUSMALLINT uint16_t SQL_C_SLONG SQLINTEGER int32_t SQL_C_ULONG SQLUINTEGER uint32_t SQL_C_FLOAT SQLREAL float SQL_C_DOUBLE SQLDOUBLE, SQLFLOAT double SQL_C_BIT SQLCHAR unsigned char SQL_C_STINYINT SQLSCHAR int8_t SQL_C_UTINYINT SQLCHAR uint8_t SQL_C_SBIGINT SQLBIGINT int64_t SQL_C_UBIGINT SQLUBIGINT uint64_t SQL_C_BINARY SQLCHAR * unsigned char * SQL_C_TYPE_DATE SQL_DATE_STRUCT struct tagdate_struct { SQLSMALLINT year; SQLUSMALLINT month; SQLUSMALLINT day; } DATE_STRUCT;[a] SQL_C_TYPE_TIME SQL_TIME_STRUCT struct tagtime_struct { SQLUSMALLINT hour; SQLUSMALLINT minute; SQLUSMALLINT second; } TIME_STRUCT;[a] SQL_C_TYPE_TIMESTAMP SQL_TIMESTAMP_STRUCT struct tagtimestamp_ STRUCT { SQLSMALLINT year; SQLUSMALLINT month; SQLUSMALLINT day; ODBC C Data Types 175

176 C type identifier ODBC C typedef C type SQLUSMALLINT hour; SQLUSMALLINT minute; SQLUSMALLINT second; SQLUINTEGER fraction;[b] } TIMESTAMP_STRUCT; [a] [a] The values of the year, month, day, hour, minute, and second fields in the datetime C data types must conform to the constraints of the Gregorian calendar. (See Constraints of the Gregorian Calendar later in this appendix.) [b] The value of the fraction field is the number of billionths of a second and ranges from 0 through 999,999,999 (1 less than 1 billion). For example, the value of the fraction field for a half-second is 500,000,000, for a thousandth of a second (one millisecond) is 1,000,000, for a millionth of a second (one microsecond) is 1,000, and for a billionth of a second (one nanosecond) is 1. ODBC C Data Types 176

177 Registering RDM ODBC Driver Overview On Microsoft Windows, the RDM ODBC Driver will be registered with Microsoft ODBC Driver Manager (ODBC DM). This allows any application built with the Microsoft ODBC libraries to access RDM databases through ODBC DM. The registration will be performed automatically as part of the product installation. The registration will create one default Data Source Name (DSN) entry for the RDM ODBC Driver. The user will be able to configure the default DSN entry or create one or more new DSN entries as necessary. Opening the ODBC Driver Manager To access the registered ODBC driver entries, take the following steps. Windows 7 is used for this purpose. 1. Click the Start Button on the Windows task bar. 2. Click "Control Panel." 3. Make sure your "View By" selection shows "Category." 4. Click "System and Security." 5. Click "Administrative Tools." 6. Double-click "Data Sources (ODBC)." A dialog box that looks like this should be displayed (Figure 1). Figure 1: ODBC Data Source Administrator Registering RDM ODBC Driver 177

178 Configuring the default DSN entry To configure the default DSN entry for RDM ODBC, highlight the entry named RDM on one of the DSN tabs ("User DSN," "System DSN" or "File DSN") and click "Configure." Each tab its own default entry for RDM. 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). Figure 2: ODBC RDM Setup Data Source Name Databases Options Data Source Name is a unique identifier of the DSN entry. The default value is "RDM". To change the value, type in the desired text in the edit box and click "OK." is a text description of the DSN entry. To change the value, type in the desired text in the edit box and click OK. The RDM ODBC Driver requires that one or more default databases be specified with ODBC DM. RDM ODBC will open the specified databases once it successfully connects to the RDM server. To add, modify or remove default databases, click "Databases." The "Database Configuration" dialog will be displayed (Figure 3). Click the "Options" button to configure the advanced options, such as the driver connection type. The "ODBC RDM Setup" dialog will expand as shown in Figure 5. Working with Default Databases Figure 3: Database Configuration Registering RDM ODBC Driver 178

179 Default Server Default Port Number Default Server is the default alias of the RDM TFServer the database is stored on. When you click "Add" to add a new default database, the value specified here will be used as the default server name. Default Port Number is the default TCP/IP port number the RDM TFServer is listening on. TFServer the database is stored on. When you click "Add" to add a new default database, the value specified here will be used as the default TCP/IP port number. To add a new database, click "Add." To modify an existing database, highlight the database to modify and click "Modify." To remove an existing database, highlight it and click "Remove." Clicking "Add" or "Modify" will display the "New/Modify Database" dialog box. The "New Database" dialog box will be displayed (Figure 4). Figure 4: New Database To add a new default database, type the desired name in the Name edit box. Modify the Server and Port Number values if necessary. When finished, click "OK." To modify an existing default database, modify the Name, Server and Port Number entries as necessary. When finished, click "OK." 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. The dialog box will expand as follows. Registering RDM ODBC Driver 179

180 Figure 5: ODBC RDM Setup with Advanced Options Connection Type Remote Server Use Database Name As The RDM ODBC Driver allows the application to access RDM databases locally through TFServer or remotely through our remote server (called rdmsqlserver). The default connection type is "Local." Change this option to "Remote" in order to connect to a remote server. Specify the name of the host where the remote server is running here when selecting the "Remote" connection type. This value is ignored when the connection type is "Local." The default value is "localhost." This option enables/disables the schema name support in the RDM ODBC Driver. Some third-party ODBC tools may require this option to be set one way or the other in order to access RDM databases. The support is disabled by default. We recommend that this option not be changed unless your ODBC tool does not correctly work with RDM ODBC with the default value. Adding a new DSN entry To add a new DSN entry for RDM ODBC, highlight the entry named "RDM" on one of the DSN tabs ("User DSN," "System DSN" or "File DSN") and click "Add." The "Create New Data Source" dialog box will be displayed (Figure 6). Registering RDM ODBC Driver 180

181 Figure 6: Create New Data Source Highlight "RDM" and click "Finish." The "ODBC RDM Setup" dialog box (Figure 2) will be displayed. See the Configuring the default DSN Entry section for details on the options. Removing an existing DSN entry To remove an existing DSN entry for RDM ODBC, highlight the entry you wish to remove on one of the DSN tabs ("User DSN," "System DSN" or "File DSN") and click "Remove." The confirmation dialog will be displayed (Figure 7). Figure 7: Confirmation Dialog Click "Yes" to remove the selected DSN entry. Registering RDM ODBC Driver 181

182 Using the ODBC Driver In order to use the RDM ODBC Driver, you must first start an instance of rdmsqlserver in the location of the document root, or by passing in the location with -d. Note that by default, rdmsqlserver will start it's own TFS internally. >cd database\ >start rdmsqlserver.exe or >start rdmsqlserver.exe -d c:\database\ Registering RDM ODBC Driver 182

183 Glossary B B-tree Also called a multiway tree, a B-tree is a fast data-indexing method that organizes the index into a multi-level set of nodes. Each node contains a sorted array of key values (the indexed data). 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, an identical number of nodes must be read in order to locate all keys at any given level in the tree). A well-organized B-tree will have only three or four levels. buffer An in-memory store of data read from a disk file, in which database operations are performed. C cache A set of buffers used to optimize database input and output operations. All RDM Embedded database input and output is performed using a cache. combine The concatenation of the members of two or more set types into one set type. commit The point at which database changes made during a single transaction are actually written to the database files. compound key A key field composed of any combination of fields (not necessarily contiguous) from a record. Each field of a compound key may be stored in ascending or descending order. connect The process of inserting a member record occurrence into a set occurrence. currency tables A table of database addresses maintained by the RDM Embedded runtime system for controlling record access and set navigation. The currency tables consist of the current member table, current owner table, and the current record. Glossary 183

184 current database The database that is currently accessible by the RDM Embedded runtime functions when multiple databases have been opened. The current database is changed by the database number function argument or by function d_setdb. current member Contains, for each set, the database address of a record occurrence that is a valid member of that set. Usually, the current member of a set is the last record accessed using a set navigation function (d_findfm, d_findlm, d_findnm, or d_findpm). current owner Contains for each set, the database address of a record occurrence that is a valid owner of that set. Usually, the current owner of a set is established using the set navigation function d_findco or by using a currency manipulation function. current record Contains the database address of the most recently accessed record instance. 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. A field has associated with it attributes such as name, type (for example, char or int), and length. Other terms used for field include: attribute, entity, or column. data file An RDM Embedded file defined in a DDL specification that contains occurrences of one or more record types. database An organized collection of related files. database address The location in the database of a record occurrence, frequently referred to as a DB_ADDR. Composed of two numbers: the file index and the slot within the file. Either 4 or 8 bytes long. database definition language A programming-like language used to define the structure and content of a database. RDM Embedded's Database Definition Language has been designed to be used with the C programming language. Glossary 184

185 DDL A programming-like language used to define the structure and content of a database. RDM Embedded's Database Definition Language has been designed to be used with the C programming language. 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. Sometimes called deadly embrace. delete chain A linked list containing deleted records or nodes to be reused when a new record or node is created. derived revision A revision that can be derived from a comparison of the source and destination database dictionary files. destimation database The db_revise-created database that stores the specified revisions. dictionary A repository containing a definition of the content and structure of a database. It is used by the RDM Embedded runtime library functions for accessing and manipulating information from that database. disconnect The process of removing a member record from a set occurrence. document root The path to the directory under which all files will be stored. Within the domain of one TFS, no files outside of this path may be accessed. domain name The "name" of a computer which has visibility to another computer. This may be a published name available on DNS servers and across the Internet, or an internal network name visible only within a workgroup. The "ping" utility must be able to locate the IP address associated with this name. In RDM Embedded, a server (tfserver, dbmirror, dbrep, or dbrepsql) may be located through the domain name of the computer it is running on, together with the port on which it is listening. A special domain name, "localhost" always refers to the same computer as the application is running on (IP address is always ). Glossary 185

186 E environment variable A programmer-specified operating system parameter that is used to identify configuration information to the runtime system. 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. A field has associated with it attributes such as name, type (for example, char or int), and length. Other terms used for field include: attribute, entity, or column. file H The primary physical storage unit into which a database is organized. In RDM Embedded, files are used to store records and keys. hierarchical database model A data representation in which the relationships between record types are formed from parent-child structures, such that a record type may have many child relationships but only one parent relationship. I index A set of key values through which rapid retrieval of a record is provided, similar to the index of a book. The term is often used synonymously with key file. J join The creation of one record type from a hierarchy of record types. K key A field through which rapid and/or sorted access to a record is desired. Glossary 186

187 key file A file that only contains keys. It may, in fact, contain more than one index because multiple key types can be contained in a single RDM Embedded key file. key scan The process of performing an ordered traversal through all (or a subset of all) occurrences of a given key field. L localhost A special Domain Name that always refers to the computer on which the application software is running. It is the default domain name used by RDM Embedded utilities and runtime library. lock A multi-user database synchronization mechanism, used to prevent simultaneous updates to shared data. Locks can be applied to the entire database or to files. logging The process of making a copy of the database changes made during a transaction prior to a commit. Logging is used to support the ability to perform a recovery in the event a failure occurs during a commit. M many-to-many relationship A relationship between two record types, A and B, such that for each occurrence of type A, there are many related occurrences of type B and, for each occurrence of type B, there are many related occurrences of type A. In RDM Embedded, many-to-many relationships can be implemented using two one-to-many sets through a third, intersection record type. member of set Specifies a one-to-many relationship between record types. One occurrence of the owner record type is related to many occurrences of a member record type. Also called a set type. member pointer Stores set membership linkage information. There is one member pointer stored with a record per set for which the record is a member. Each one contains the database addresses of the owner record, previous member in the set, and next member in the set. Glossary 187

188 N navigation The process of retrieving records from a database by moving through various navigational methods. Methods include set navigation, key scanning, and record-type scanning. network database model A data representation in which the relationships are explicitly defined and maintained through sets of owner/members, where any given record type may be the owner of multiple types of sets and the member of multiple types of sets. Multiple set membership distinguishes the Network database model from the Hierarchical database model. node A component of a B-tree, consisting of a page of sorted keys stored in a key file. normalize The elimination of redundant record instances that own a new set, resulting in a one-tomany relationship. O occurrence One record instance within a record type, specifically associated with record type scanning (d_recfrst, d_recnext, d_recprev, d_reclast), where the current occurrence of a record type is used to bookmark the position on a record type scan. Record occurrences are ordered by their physical appearance in a data file. The current occurrence is not the same as the current record, although the current record will also be set by the scanning functions. owner of set Specifies a one-to-many relationship between record types. One occurrence of the owner record type is related to many occurrences of a member record type. Also called a set type. P page Files are blocked into contiguous fixed-length segments called pages. A page is the unit of database I/O performed in RDM Embedded. path name The sequence of directories in a hierarchical file system that must be traversed to locate a particular file. Glossary 188

189 pointer In a database, a pointer is data stored in a record occurrence that provides the necessary information for locating related record occurrences. In a C program, a pointer is a variable that contains a memory address. port Together with an IP address, a port number uniquely identifies an endpoint by which a TCP/IP connection can be made to another program. In RDM Embedded, each server (tfserver, dbmirror, dbrep or dbrepsql) identifies the port number that should be used to locate it. The IP address is normally obtained through a domain name lookup (e.g. tfs.raima.com is a domain name, and its IP address is ). process An independently executing task or program. An individual execution of an RDM Embedded application program. projection The placement of fields from one record type into one or more new record types. Q queue A first-in-first-out waiting list. Lock requests for a locked resource will be placed at the end of a queue. When the locked resource becomes available, the first lock request on the queue will be granted. R record Used synonymously with record type or record occurrence depending on the context in which the term is used. record occurence One individual instance in a database of a record of a particular type. A database consists of many occurrences of many different record types. For example, an employee record type may consist of the fields name, employee_id, job_title, and pay. An employee record occurrence could be "name: Jones, Jim; employee_id: c87101, job_title: engr, pay: 3400". recovery The process of completing the transaction of a process that failed during a commit. Glossary 189

190 redundant data Identical data that is stored in multiple locations in a database. Typically used to form relationships between tables in a relational database management system. relational database model A data representation in which a database is viewed as consisting of two-dimensional tables, each composed of one or more columns. Inter-table relationships are defined through use of common column names and data. Tables and columns are analogous to RDM Embedded records and fields, respectively. remote procedure call A programming mechanism that makes a library call appear to operate in the program space of an application, even though the actual function exists in the program space of another program (called a "server"). A client application places a function identifier and parameter contents into a packet that is first transferred to the server, with results (return code, return parameter values) transferred back to the caller. Revision Definition Language The RDL supplies information to db_revise that cannot be derived from a comparison of the source and destination dictionary files. root node The top or start node of a B-tree. RPC A programming mechanism that makes a library call appear to operate in the program space of an application, even though the actual function exists in the program space of another program (called a "server"). A client application places a function identifier and parameter contents into a packet that is first transferred to the server, with results (return code, 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. S schema A conceptual model of the structure of a database that defines the data contents and relationships. A database definition language specification is an implementation of a particular schema. Glossary 190

191 set Specifies a one-to-many relationship between record types. One occurrence of the owner record type is related to many occurrences of a member record type. Also called a set type. set occurence An individual instance of a set in which one owner record occurrence has one or more member record occurrences connected to it. set pointer Stores set ownership linkage information. There is one set pointer stored with a record per set for which the record is an owner. Each one contains a count of the number of members in the set, the database address of the first member record occurrence, and the database address of the last member record occurrence in the set. set scan The process of performing an ordered traversal through all (or a subset of all) member record occurrences of a given set occurrence. slot A position in a data or key file for storage of a single record or key occurrence. source database The database containing the data that is to be revised. This database is used in a read-only manner. specified revision A revision requiring specification by an RDL statement. split The separation of a multiple-member set type into two or more set types. static revision A revision that can be performed without changing the existing database content or structure. synchronization The process of ensuring that, in a multi-user database environment, updates to shared data are performed serially, one user at a time. system record A special record type used to define the "top" record in a network database. There is only one occurrence of the system record in a database. It is defined by naming "system" as a set owner in one or more set definitions in the DDL. When a database is opened, the system Glossary 191

192 record, if it exists, is set as the current owner of all sets for which it is named as owner. It may not be a set member. T task In an RDM Embedded Application, a task is a block of allocated memory that stores the complete database context for a thread of execution. It must be allocated through the d_opentask function and closed through the d_closetask function. A task represents one user in a multi-user environment. A task can also represent one database transaction, with all locks and database updates associated with the transaction. TFS A software component within the RDM Embedded system that maintains safe multi-user transactional updates to a set of files, and responds to page requests. The tfserver utility links to the TFS to allow it to run as a separate utility. The TFS may also be linked directly into an application in order to avoid the RPC overhead of calling a separate server. thread An independent flow of control within a computer operating system. Differentiated from a Process in that a process may contain one or more threads. Threads within the same process share common (or global) data but have their own stacks, which keeps track of the thread's context. In RDM Embedded Applications, each thread must be associated with its own task variable, and is treated as a separate user in a multi-user environment. timeout An event that occurs when a lock request has waited on a queue longer than a pre-determined amount of time. It is used to avoid deadlock. transaction A group of related database changes that are written to the database as a single unit during a commit. The logical consistency of a database is maintained by placing all related updates within transactions. transactional file server A software component within the RDM Embedded system that maintains safe multi-user transactional updates to a set of files, and responds to page requests. The tfserver utility links to the TFS to allow it to run as a separate utility. The TFS may also be linked directly into an application in order to avoid the RPC overhead of calling a separate server. Glossary 192

193 W working database A temporary database created by db_revise for use only during the database revision process. db_revise removes the working database when the revision process is complete. Glossary 193

194 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

195 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

196 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