odbc api reference guide

RDMe ODBC API Reference Guide

1

Raima Database Manager 11.0

ODBC API Reference Guide


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


Contents 3

ContentsContents 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


SQLAllocHandle 32

SQLBindCol 34


Contents 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 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 6

rdmsqlserver_stop 170

rdmsqlserver_term 172




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


Introduction 7

IntroductionRDM 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. Appli-cations written using this API can be both directly-linked to the RDM database engine or can run as client pro-grams 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 func-tionality, 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 imple-mented 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.

ODBC API Function RSQL Function CommentsSQLAllocHandle 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. Data-

bases are opened through calls to rsqlOpenDB or rsqlO-penCat.

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

Table 2. ODBC to RDM SQL API Function Mapping

http://msdn.microsoft.com/en-us/library/ms710252(v=vs.85).aspx






Introduction 8

ODBC API Function RSQL Function CommentsSQLExecute 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

rsqlGetDateSeparator

rsqlGetDeferBlobMode

rsqlGetReadOnlyTrmode

Not all ODBC connection attributes have a RDM equivalent. Not all RDM connection attributes have an ODBC equivalent.

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

rsqlSetDateSeparator

rsqlSetDeferBlobMode

rsqlSetReadOnlyTrmode

Not all ODBC connection attributes have a RDM equivalent. Not all RDM connection attributes have an ODBC equivalent.

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 foot-print. However, ODBC is available and can certainly be used if DBMS independence and/or use of a standard SQL API is needed.


Introduction 9

Basic ODBC Application StepsAn 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 appli-cation.

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 param-eters 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 data-

bases, terminates the connection and frees the connection handle and all its associated dynamically


Introduction 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 han-

dle */

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

dle */

SQLExecDirect(hStmt, (SQLCHAR *) "INSERT INTO info(myChar) VALUES('Hello


Introduction 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 12

Allocating HandlesODBC 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 envi-ronment handle as the second in order to allocate a connection handle. An application must allocate a con-nection 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 imple-mentation 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 imple-mentation 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 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 appli-cation descriptors (APD and ARD) by calling SQLAllocHandle using SQL_HANDLE_DESC as the first argu-ment 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 imple-mentation 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);


/* Connect to the local data source. The code for

connectToDataSource is shown in the next

section */

rc = connectToDataSource(hDbc);


/* 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 14

Connecting to a Data SourceAn 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" con-nection, 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 con-nection 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 net-work 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).

Figure 2. Remote Data Source

See the rdmsqlserver section for more information.


Introduction 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 con-nection.

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 con-nection) 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, "local-host" will be used as the local data source name.


Introduction 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 estab-lished. SQLConnect returns SQL_ERROR when an error occurs, or SQL_SUCCESS_WITH_INFO if the oper-ation 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);


/* 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



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);


/* 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 17

rc = SQLConnect(hDbc, NULL, 0, NULL, 0, NULL, 0);

}

return rc;

}

Example 4 Using SQLConnect



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. SQLDriv-erConnect 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 18

Executing an SQL StatementOnce 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 SQLAl-locHandle, passing SQL_HANDLE_STMT to the first argument and an existing connection handle to the sec-ond. 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 execut-ing 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 19

rc = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, &hStmt);


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 state-ment, 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"


SQLHDBC hDbc)

{

SQLRETURN rc;

SQLHSTMT hStmt;

const char *pszStmt = "INSERT INTO person VALUES "

"'Houglum, Bill', 'M', '1'";





SQL_NTS);


/* Execute an INSERT statement */

rc = SQLExecDirect(hStmt,

(SQLCHAR *) pszStmt, SQL_NTS);


/* INSERT successful; commit the change */

(void) SQLEndTran(SQL_HANDLE_DBC, hDbc,


Introduction 20

SQL_COMMIT);

}

else {

/* INSERT failed; abort the change */

(void) SQLEndTran(SQL_HANDLE_DBC, hDbc,

SQL_ROLLBACK);

}

}


}

return rc;

}


Introduction 21

Retrieving the Result SetSQL 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"


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;




/* Open the NSFAWARDS database first */


SQL_NTS);


Introduction 22


/* Execute a SELECT statement */




/* Bind all the 3 columns */

(void) SQLBindCol(hStmt 1, SQL_C_CHAR,

szName, sizeof(szName), &cb1);


szGender, sizeof(szGender), &cb2);


szJob, sizeof(szJob), &cb3);

do {

/* Fetch as many rows as there are */

rc = SQLFetch(hStmt);


if (cb1 != SQL_NULL_DATA)

printf("Name = %s\n", szName);


printf("Gender = %s\n", szGender);


printf("Jobclass = %s\n", szJob);

}

} while (SQL_SUCCEEDED(rc));

/* This means fetch completed successfully */

if (rc == SQL_NO_DATA)

rc = SQL_SUCCESS;

}

}


}

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.


Advanced Topics 23

Advanced Topics

Working with ParametersOftentimes 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 iden-tical, it saves an application time if the identical portion of the statements can be prepared just once, and the inser-tion 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 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);


/* Bind parameters for the three parameter markers */

(void) SQLBindParameter(hStmt, 1, SQL_PARAM_INPUT,

SQL_C_CHAR, SQL_CHAR, 35, 0, szName, 0, &cb1);


SQL_C_CHAR, SQL_CHAR, 1, 0, szGender, 0, &cb2);


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 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 OnceSQLFetch retrieves one row of the result set at a time. It can be a significant network overhead for an appli-cation 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 car-dinality should match the number of rows to retrieve. For instance, if 10 rows are to be fetched at a time, the var-iable 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 car-dinality 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 */


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 szJob[ROW_ARRAY_SIZE][2];

SQLLEN cb1[ROW_ARRAY_SIZE],

cb2[ROW_ARRAY_SIZE],

cb3[ROW_ARRAY_SIZE];


Advanced Topics 26

SQLULEN ucbFetchedRows;

SQLULEN ii;




/* Open the NSFAWARDS database first */


SQL_NTS);


/* 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 */




/* Bind all the 3 columns; note that the length

argument (arg. 5) is the size of one element

of the bound variable */


szName, sizeof(szName[0]), cb1);


szGender, sizeof(szGender[0]), &cb2);


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]);

}

}

}

}

}



Advanced Topics 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 PartsBinding 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 col-umn 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 func-tion 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);


while ((rc = SQLFetch(hStmt)) != SQL_NO_DATA) {

do {


Advanced Topics 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.



RDM ODBC API ReferenceThe topics in this section describe each ODBC function in alphabetical order. Each function is defined as a C pro-gramming language function. Descriptions include the following:

l Purpose l Conformance l Syntax l Arguments l Return values

All of the following APIs conform to the ODBC 3.51 specification unless otherwise noted. RDM specific exten-sions 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 DescriptionSQLAllocHandle Allocates an environment, connection, statement, or descriptor handleSQLBindCol Binds application data buffers to columns in the result set.SQLBindParameter Binds a buffer to a parameter marker in an SQL statement.SQLCancel Cancels the processing on a statement.SQLCloseCursor Closes a cursor that has been opened on a statement and discards pending results.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.

SQLColumns Returns the list of column names in specified tables. The driver returns this infor-mation as a result set on the specified StatementHandle.

SQLConnect Establishes connections to RDM databases via RDM ODBC.SQLCopyDesc Copies descriptor information from one descriptor handle to another.SQLDescribeCol Retrieves the basic result data set for a columnSQLDescribeParam Retrieves description of a parameter markerSQLDescribeStmt Retrieves the type of the SQL statement executed on the handle.SQLDisconnect Closes the connection associated with a specified handleSQLDriverConnect Establishes connections to RDM databases via RDM ODBC. Accepts more con-

nection options than SQLConnect.SQLEndTran Requests a commit or rollback for active transactions



Function Name DescriptionSQLExecDirect Prepares and executes an SQL statementSQLExecute Executes a previously prepared SQL statementSQLExtendedTran Performs a transaction operationSQLFetch Fetches data from a bound column to an application variableSQLFetchScroll Fetches the specified rowset of data from the result set and returns data for all

bound columns.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) 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.

SQLFreeHandle Frees resources associated with a specific environment, connection, statement, or descriptor handle.

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.

SQLGetConnectAttr Returns the current setting of a connection attribute.SQLGetCursorName Retrieves the cursor name of an SQL statement handleSQLGetData Retrieves data for a single column in the result set. It can be called multiple times to

retrieve variable-length data in parts.SQLGetDescField Returns the current setting or value of a single field of a descriptor record.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.

SQLGetDiagField Retrieves current field value of a status recordSQLGetDiagRec Retrieves current values of several common fields of a status recordSQLGetEnvAttr Returns the current setting of an environment attribute.SQLGetFunctions Returns information about whether a driver supports a specific ODBC function.SQLGetInfo Returns general information about the driver and data source associated with a con-

nection.SQLGetStmtAttr Returns the current setting of a statement attribute.SQLGetTypeInfo Returns information about data types supported by the data source.SQLMoreResults Determines whether more results are available on a statement containing

SELECT, UPDATE, INSERT, or DELETE statements and, if so, initializes proc-essing for those results.

SQLNativeSql Returns the SQL string as modified by the driver. SQLNativeSql does not execute the SQL statement.

SQLNumParams Determines the number of parameters in a prepared statementSQLNumResultCols Returns the number of columns in a result set.SQLParamData SQLParamData is used together with SQLPutData to supply parameter data at

statement execution time, and with SQLGetData to retrieve streamed output parameter data.

SQLPrepare Prepares an SQL string for execution.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 pri-mary keys from multiple tables in a single call.



Function Name DescriptionSQLProcedureColumns 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 state-ment 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 DELETESQLSetConnectAttr 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 statementSQLSpecialColumns 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 spe-

cific data source.SQLTransactStatus Retrieves the type and status of the transaction possibly executed on the handle.



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)

ArgumentsHandleType (input) The type of handle to be allocated by SQLAllocHandle. Must be one of the fol-

lowing values:

l SQL_HANDLE_ENV l SQL_HANDLE_DBC l SQL_HANDLE_STMT l SQL_HANDLE_DESC

InputHandle (input) The input handle in whose context the new handle is to be allocated. If Han-dleType 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 Descriptionrdmrdbc11 RDM ODBC API Library

See Library Naming Conventions section for full library name and a list of library dependencies.

Returns

Return Code Description



SQL_SUCCESS Function completed successfully. The application calls SQLGet-DiagField to retrieve additional information from the header record.

SQL_SUCCESS_WITH_INFO Function completed successfully, possibly with a nonfatal error (warn-ing). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.

SQL_ERROR Function failed. The application calls SQLGetDiagRec or SQLGet-DiagField to retrieve additional information. The contents of any out-put arguments to the function are undefined.

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.

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.

http://msdn.microsoft.com/en-us/library/ms712455(v=VS.85).aspx



SQLBindCol

Binds application data buffers to columns in the result set.

Conformance


Syntax

SQLRETURN SQL_API SQLBindCol(

SQLHSTMT StatementHandle,

SQLUSMALLINT ColumnNumber,

SQLSMALLINT TargetType,

SQLPOINTER TargetValue,

SQLLEN BufferLength,

SQLLEN *StrLen_or_Ind)

ArgumentsStatementHandle (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 col-umn 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





Returns

Return Code DescriptionSQL_SUCCESS Function completed successfully. The application calls SQLGet-

DiagField to retrieve additional information from the header record. SQL_SUCCESS_WITH_INFO Function completed successfully, possibly with a nonfatal error (warn-

ing). The application calls SQLGetDiagRec or SQLGetDiagField to retrieve additional information.



Comments

This function binds application data buffers to columns in the result set.

For more information, reference MSDN documentation for SQLBindCol.




SQLBindParameter

Binds a buffer to a parameter marker in an SQL statement.

Conformance

Version Introduced: ODBC 2.0 Standards Compliance: ODBC

Syntax

SQLRETURN SQLBindParameter(


SQLUSMALLINT ParameterNumber,

SQLSMALLINT InputOutputType,

SQLSMALLINT ValueType,

SQLSMALLINT ParameterType,

SQLULEN ColumnSize,

SQLSMALLINT DecimalDigits,

SQLPOINTER ParameterValuePtr,


SQLLEN * StrLen_or_IndPtr)

ArgumentsStatementHandle (input) Statement handle. ParameterNumber (input) Parameter number, ordered sequentially in increasing parameter order, start-

ing 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

input)

A pointer to a buffer for the parameter's data.

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"



Libraries



Returns






For more information, reference MSDN documentation for SQLBindParameter.




SQLCancel

Cancels the processing on a statement.

Conformance


Syntax

SQLRETURN SQL_API SQLCancel(

SQLHSTMT StatementHandle)

ArgumentsStatementHandle (input) Statement handle.

Required Headers

#include "sql.h"

Libraries



Returns





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.

Comments

On RDM, SQLCancel supports the following type of processing.

l A function on a statement that needs data.

The following types of processing are not supported due to the driver limitations.

l A function running asynchronously on a statement. l A function running on the statement on another thread.

For more information, reference MSDN documentation for SQLCancel.




SQLCloseCursor

Closes a cursor that has been opened on a statement and discards pending results.

Conformance


Syntax

SQLRETURN SQL_API SQLCloseCursor(



Required Headers

#include "sql.h"

Libraries



Returns









For more information, reference MSDN documentation for SQLCloseCursor.




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


Syntax

SQLRETURN SQLColAttribute (



SQLUSMALLINT FieldIdentifier,

SQLPOINTER CharacterAttributePtr,

SQLSMALLINT BufferLength,

SQLSMALLINT * StringLengthPtr,

SQLPOINTER NumericAttributePtr)

ArgumentsStatementHandle (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 que-ried (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 Char-acterAttributePtr.

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 *Cha-racterAttributePtr. If FieldIdentifier is an ODBC-defined field and *Cha-racterAttributePtr 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 fol-lowing values:

l If CharacterAttributePtr is a pointer to a pointer, BufferLength should have the value SQL_IS_POINTER.



l If CharacterAttributePtr is a pointer to a character string, the Buff-erLength is the length of the buffer.

l If CharacterAttributePtr is a pointer to a binary buffer, the application places the result of the SQL_LEN_BINARY_ATTR(length) macro in BufferLength. This places a negative value in BufferLength.

l If CharacterAttributePtr is a pointer to a fixed-length data type, Buff-erLength 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 *Cha-racterAttributePtr. For character data, if the number of bytes available to return is greater than or equal to BufferLength, the descriptor information in *Cha-racterAttributePtr is truncated to BufferLength minus the length of a null-ter-mination 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



Returns









For more information, reference MSDN documentation for SQLColAttribute.




SQLColumns

Returns the list of column names in specified tables. The driver returns this information as a result set on the spec-ified StatementHandle.

Conformance


Syntax

SQLRETURN SQL_API SQLColumns(


SQLCHAR *CatalogName,

SQLSMALLINT NameLength1,

SQLCHAR *SchemaName,


SQLCHAR *TableName,


SQLCHAR *ColumnName,

SQLSMALLINT NameLength4)

ArgumentsStatementHandle (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 ("") indi-cates 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"



Libraries



Returns






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.




SQLConnect

Establishes connections to RDM databases via RDM ODBC.

Conformance


Syntax

SQLRETURN SQL_API SQLConnect(

SQLHDBC ConnectionHandle,

const SQLCHAR *ServerName,


const SQLCHAR *UserName,


const SQLCHAR *Authentication,

SQLSMALLINT NameLength3)

ArgumentsConnectionHandle (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 null-

terminated string. UserName (input) This parameter is not used.NameLength2 (input) Length of *UserName in characters. Specify SQL_NTS if UserName is a null-ter-

minated string. Authentication (input) This parameter is not used.NameLength3 (input) Length of *Authentication in characters. Specify SQL_NTS if Authen-

tication is a null-terminated string.

Required Headers

#include "sql.h"

Libraries



Returns








Diagnostics

SQLSTATE Error Description01S02 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.

08001 Unable to connect. The RDM ODBC driver was not able to connect to the data source.

08002 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-of-memory 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.

ServerNameConnection Type

Actual Con-nection

Actual Server Names

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

RemoteSQL_ATTR_RDM_REMOTE_NAME



ServerNameConnection Type

Actual Con-nection

Actual Server Names

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.




SQLCopyDesc

Copies descriptor information from one descriptor handle to another.

Conformance


Syntax

SQLRETURN SQLCopyDesc(

SQLHDESC SourceDescHandle,

SQLHDESC TargetDescHandle);

ArgumentsSourceDescHandle (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 imple-mentation row descriptor).

Required Headers

#include "sql.h"

Libraries



Returns








For more information, reference MSDN documentation for SQLCopyDesc.




SQLDescribeCol

Retrieves the basic result data set for a column

Conformance


Syntax

SQLRETURN SQL_API SQLDescribeCol(



SQLCHAR *ColumnName,


SQLSMALLINT *NameLengthPtr,

SQLSMALLINT *DataTypePtr,

SQLULEN *ColumnSizePtr,

SQLSMALLINT *DecimalDigitsPtr,

SQLSMALLINT *NullablePtr)

ArgumentsStatementHandle (input) Statement handle. ColumnNumber (input) Column number of result data, ordered sequentially in increasing column order, start-

ing 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 char-acters (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 *Co-lumnName is truncated to BufferLength minus the length of a null-termination char-acter.

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 appli-cable, the driver returns 0.



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:

l SQL_NO_NULLS: The column does not allow NULL values. l SQL_NULLABLE: The column allows NULL values. l SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column

allows NULL values.

Required Headers

#include "sql.h"

Libraries



Returns






For more information, reference MSDN documentation for SQLDescribeCol.




SQLDescribeParam

Retrieves description of a parameter marker

Conformance


Syntax

SQLRETURN SQL_API SQLDescribeParam(


SQLUSMALLINT ParameterNumber,

SQLSMALLINT *DataTypePtr,

SQLULEN *ParameterSizePtr,

SQLSMALLINT *DecimalDigitsPtr,

SQLSMALLINT *NullablePtr)

ArgumentsStatementHandle (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 expres-

sion 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



Returns








For more information, reference MSDN documentation for SQLDescribeParam.




SQLDescribeStmt

Retrieves the type of the SQL statement executed on the handle.

Conformance

Version Introduced: RDM ODBC API extension

Syntax

SQLRETURN SQL_API SQLDescribeStmt(


SQLUSMALLINT *pStmtType)

ArgumentsStatementHandle (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



Returns


DiagField to retrieve additional information from the header record. SQL_ERROR Function failed. The application calls SQLGetDiagRec or SQLGet-

DiagField to retrieve additional information. The contents of any out-put arguments to the function are undefined.





Diagnostics

SQLSTATE Error DescriptionHY009 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 state-ment type returned to this function through pStmtType.

SQL statement executed Value of pStmtType

OPEN [ DATABASE ] <database> SQL_RDM_STMT_OPEN

OPEN [ DATABASE ] <database-union> SQL_RDM_STMT_DBUNION

CLOSE [ DATABASE ] <database> SQL_RDM_STMT_CLOSE

SELECT SQL_RDM_STMT_SELECT

INSERT SQL_RDM_STMT_INSERT

UPDATE SQL_RDM_STMT_UPDATE

DELETE SQL_RDM_STMT_DELETE

BEGIN [ WORK ] SQL_RDM_STMT_START

COMMIT [ WORK ] SQL_RDM_STMT_COMMIT

SAVEPOINT <trans-id> SQL_RDM_STMT_SAVEPOINT

RELEASE SAVEPOINT <trans-id> SQL_RDM_STMT_RELEASE

ROLLBACK [ WORK ] SQL_RDM_STMT_ROLLBACK

CREATE PROCEDURE <procedure> SQL_RDM_STMT_CRPROC

DROP PROCEDURE <procedure> SQL_RDM_STMT_DRPROC

EXECUTE <procedure> SQL_RDM_STMT_EXECUTE

SET SQL_RDM_STMT_SET

SET COLUMN STATS SQL_RDM_STMT_SETCOLUMN

LOCK TABLE <table> SQL_RDM_STMT_LOCK

UNLOCK TABLE <table> SQL_RDM_STMT_UNLOCK

INITIALIZE [ DATABASE ] <database> SQL_RDM_STMT_INITDB

CREATE CATALOG FOR <id> SQL_RDM_STMT_CRCAT

IMPORT SQL_RDM_STMT_IMPORT

EXPORT SQL_RDM_STMT_EXPORT

Dynamic DDL statement[1] SQL_RDM_STMT_DDL



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



SQLDisconnect

Closes the connection associated with a specified handle

Conformance


Syntax

SQLRETURN SQL_API SQLDisconnect(

SQLHDBC ConnectionHandle)

ArgumentsConnectionHandle (input) Connection handle.

Required Headers

#include "sql.h"

Libraries



Returns









For more information, reference MSDN documentation for SQLDisconnect.




SQLDriverConnect

Establishes connections to RDM databases via RDM ODBC. Accepts more connection options than SQLCon-nect.

Conformance


Syntax

SQLRETURN SQL_API SQLDriverConnect(


SQLHWND WindowHandle,

const SQLCHAR *InConnectionString,

SQLSMALLINT StringLength1,

SQLCHAR *OutConnectionString,


SQLSMALLINT *StringLength2Ptr,

SQLUSMALLINT DriverCompletion)

ArgumentsConnectionHandle (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 con-

nection 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 Buff-erLength, the completed connection string in *OutConnectionString is trun-cated 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 con-nection information

Required Headers

#include "sqlext.h"



Libraries



Returns






SQL_NO_DATA 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 Attribute Value DescriptionDSN When the application accesses the RDM ODBC Driver through Micro-

soft 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.

PORT TCP/IP port number the TFServer is listening on. If PORT is not spec-ified, RDM will use the default value (21553).

TFS[1] 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 ("local-host").

REMOST_HOST[1] Name of the remote server. If REMOTE_HOST is not specified, RDM will use its default remote server name ("localhost").



Keyword Attribute Value DescriptionDATABASE Name of the database to open upon successful connection to the data

source.

For more information, reference MSDN documentation for SQLDriverConnect.




SQLEndTran

Requests a commit or rollback for active transactions

Conformance


Syntax

SQLRETURN SQLEndTran(


SQLHANDLE Handle,

SQLSMALLINT CompletionType)

ArgumentsHandleType (input) Handle type identifier. Contains either SQL_HANDLE_ENV (if Handle is an envi-

ronment 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 trans-

action.CompletionType (input) One of the following two values:

l SQL_COMMIT l SQL_ROLLBACK

Required Headers

#include "sql.h"

Libraries



Returns








For more information, reference MSDN documentation for SQLEndTran.




SQLExecDirect

Prepares and executes an SQL statement

Conformance


Syntax

SQLRETURN SQL_API SQLExecDirect(


const SQLCHAR *StatementText,

SQLINTEGER TextLength)

ArgumentsStatementHandle (input) Statement handle. StatementText (input) SQL statement to be executed. TextLength (input) Length of *StatementText in characters.

Required Headers

#include "sql.h"

Libraries



Returns





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.

SQL_NEED_DATA 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.


For more information, reference MSDN documentation for SQLExecDirect.




SQLExecute

Executes a previously prepared SQL statement

Conformance


Syntax

SQLRETURN SQLExecute(

SQLHSTMT StatementHandle);


Required Headers

#include "sql.h"

Libraries



Returns








passed for an argument that requires a connection handle. SQL_NEED_DATA 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.


For more information, reference MSDN documentation for SQLExecute.




SQLExtendedTran

Performs a transaction operation

Conformance


Syntax

SQLRETURN SQL_API SQLExtendedTran(


SQLHANDLE Handle,

SQLSMALLINT TransType,

SQLSMALLINT ReadOnly,

const SQLCHAR *TransactionID,

SQLSMALLINT StringLengthPtr)

ArgumentsHandleType (input) Handle type identifier. Contains either SQL_HANDLE_ENV (if Handle is an envi-

ronment 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 trans-

action.OperationType (input) One of the following operation types:

l SQL_START -Start a transaction l SQL_SAVEPOINT -Create a save point in a transaction l SQL_RELEASE Release a save point in a transaction l SQL_COMMIT -Commit a transaction l SQL_ROLLBACK -Rollback a transaction

ReadOnly (input) Read-only mode, as follows:

l SQL_TRUE Transaction is read-only. l 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 Oper-ation 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.



Required Headers


Libraries



Returns






Diagnostics

SQLSTATE Error Description01000 General warning General error returned from the RDM ODBC driver. The func-

tion returns SQL_SUCCESS_WITH_INFO.08003 Connection not open The RDM ODBC driver is not connected to a data source.25000 Transaction already active SQL_START is specified for OperationType and a trans-

action is already active on the connection associated with Han-dle.

25001 Read-only transaction already active

SQL_START, SQL_SAVEPOINT or SQL_RELEASE is spec-ified 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 suf-ficient memory to complete the required operation.

HY010 Function sequence error This function was called after SQLExecute or SQLEx-



ecDirect but before all the parameters were bound.HY012 Invalid transaction operation

codeThe value in OperationType is not one of the following:

l SQL_START l SQL_SAVEPOINT l SQL_RELEASE l SQL_COMMIT l 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:

l SQL_HANDLE_ENV l SQL_HANDLE_DBC

Comments

SQLExtendedTran allows an RDM ODBC application to start a transaction, create a save point inside the cur-rent transaction, and roll back to the last save point, as well as committing and rolling back a transaction.

Starting 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, spec-ify 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

Creating a save point SQLExtendedTran can be used to create a save point in the current read-write 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.

Releasing a save point An application can manually release, or discard, any of the save points it created by calling SQLExtendedTran specifying SQL_RELEASE for Oper-ationType 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 auto-matically release all the save points created after that save point.

Rolling back to a 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.

Committing a transaction An application can commit all changes in a transaction by calling SQLEndTran or SQLExtendedTran specifying SQL_COMMIT. All save points inside the



transaction will be released. If no transaction is active, SQL_SUCCESS will be returned.

Aborting a transaction 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.



SQLFetch

Fetches data from a bound column to an application variable

Conformance


Syntax

SQLRETURN SQLFetch(

SQLHSTMT StatementHandle);


Required Headers

#include "sql.h"

Libraries



Returns









For more information, reference MSDN documentation for SQLFetch.




SQLFetchScroll

Fetches the specified rowset of data from the result set and returns data for all bound columns.

Conformance


Syntax

SQLRETURN SQLFetchScroll(


SQLSMALLINT FetchOrientation,

SQLLEN FetchOffset);

ArgumentsStatementHandle (input) Statement handle. FetchOrientation (input) Type of fetch:

l SQL_FETCH_NEXT l SQL_FETCH_PRIOR l SQL_FETCH_FIRST l SQL_FETCH_LAST l SQL_FETCH_ABSOLUTE l SQL_FETCH_RELATIVE l 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



Returns









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.




SQLForeignKeys

SQLForeignKeys can return:

l A list of foreign keys in the specified table (columns in the specified table that refer to primary keys in other tables).

l A list of foreign keys in other tables that refer to the primary key in the specified table.

The driver returns each list as a result set on the specified statement.

Conformance


Syntax

SQLRETURN SQLForeignKeys(


SQLCHAR * PKCatalogName,


SQLCHAR * PKSchemaName,


SQLCHAR * PKTableName,


SQLCHAR * FKCatalogName,


SQLCHAR * FKSchemaName,


SQLCHAR * FKTableName,

SQLSMALLINT NameLength6);

ArgumentsStatementHandle (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.



NameLength6 (input) Length of *FKTableName, in characters.

Required Headers

#include "sqlext.h"

Libraries



Returns






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.




SQLFreeHandle

Frees resources associated with a specific environment, connection, statement, or descriptor handle.

Conformance


Syntax

SQLRETURN SQLFreeHandle(


SQLHANDLE Handle);

ArgumentsHandleType (input) The type of handle to be freed by SQLFreeHandle. Must be one of the following

values:

l SQL_HANDLE_DBC l SQL_HANDLE_DESC l SQL_HANDLE_ENV l SQL_HANDLE_STMT

If HandleType is not one of these values, SQLFreeHandle returns SQL_INVALID_HANDLE.

Handle (input) The handle to be freed.

Required Headers

#include "sql.h"

Libraries



Returns







For more information, reference MSDN documentation for SQLFreeHandle.




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


Syntax

SQLRETURN SQLFreeStmt(


SQLUSMALLINT Option);

ArgumentsStatementHandle (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 oper-ation 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 State-mentHandle. 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.



Required Headers

#include "sql.h"

Libraries



Returns






For more information, reference MSDN documentation for SQLFreeStmt.




SQLGetConnectAttr

Returns the current setting of a connection attribute.

Conformance


Syntax

SQLRETURN SQLGetConnectAttr(


SQLINTEGER Attribute,

SQLPOINTER ValuePtr,

SQLINTEGER BufferLength,

SQLINTEGER * StringLengthPtr);

ArgumentsConnectionHandle (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 null-termination 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 Buff-erLength minus the length of the null-termination character and is null-terminated by the driver.

Required Headers

#include "sql.h"

Libraries





Returns






Comments

The attributes accepted by SQLGetConnectAttr are listed under SQLSetConnectAttr.

For more information, reference MSDN documentation for SQLGetConnectAttr.




SQLGetCursorName

Retrieves the cursor name of an SQL statement handle

Conformance


Syntax

SQLRETURN SQLGetCursorName(


SQLCHAR * CursorName,


SQLSMALLINT * NameLengthPtr);

ArgumentsStatementHandle (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



Returns




SQL_ERROR Function failed. The application calls SQLGetDiagRec or SQLGet-





For more information, reference MSDN documentation for SQLGetCursorName.




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


Syntax

SQLRETURN SQLGetData(


SQLUSMALLINT Col_or_Param_Num,

SQLSMALLINT TargetType,

SQLPOINTER TargetValuePtr,


SQLLEN * StrLen_or_IndPtr);

ArgumentsStatementHandle (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 book-mark column is column number 0; this can be specified only if bookmarks are ena-bled. 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





Returns






For more information, reference MSDN documentation for SQLGetData.




SQLGetDescField

Returns the current setting or value of a single field of a descriptor record.

Conformance


Syntax

SQLRETURN SQLGetDescField(

SQLHDESC DescriptorHandle,

SQLSMALLINT RecNumber,

SQLSMALLINT FieldIdentifier,



SQLINTEGER * StringLengthPtr);

ArgumentsDescriptorHandle (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, Strin-gLengthPtr will still return the total number of bytes (excluding the null-ter-mination 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 char-acter 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, Buff-erLength 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"



Libraries



Returns






For more information, reference MSDN documentation for SQLGetDescField.




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


Syntax

SQLRETURN SQLGetDescRec(



SQLCHAR * Name,


SQLSMALLINT * StringLengthPtr,

SQLSMALLINT * TypePtr,

SQLSMALLINT * SubTypePtr,

SQLLEN * LengthPtr,

SQLSMALLINT * PrecisionPtr,

SQLSMALLINT * ScalePtr,

SQLSMALLINT * NullablePtr);

ArgumentsDescriptorHandle (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 trun-cated 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_



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



Returns







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.




SQLGetDiagField

Retrieves current field value of a status record

Conformance


Syntax

SQLRETURN SQLGetDiagField(


SQLHANDLE Handle,


SQLSMALLINT DiagIdentifier,

SQLPOINTER DiagInfoPtr,


SQLSMALLINT * StringLengthPtr)

ArgumentsHandleType (input) A handle type identifier that describes the type of handle for which diagnostics are

required. Must be one of the following:


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

ords 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 *Di-agInfoPtr. 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 *Di-agInfoPtr, 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 Buff-erLength minus the length of a null-termination character.



Required Headers

#include "sql.h"

Libraries



Returns






For more information, reference MSDN documentation for SQLGetDiagField.




SQLGetDiagRec

Retrieves current values of several common fields of a status record

Conformance


Syntax

SQLRETURN SQLGetDiagRec(


SQLHANDLE Handle,


SQLCHAR * SQLState,

SQLINTEGER * NativeErrorPtr,

SQLCHAR * MessageText,


SQLSMALLINT * TextLengthPtr)

ArgumentsHandleType (input) A handle type identifier that describes the type of handle for which diagnostics are

required. Must be one of the following:


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

ords are numbered from 1. SQLState (output) Pointer to a buffer in which to return a five-character SQLSTATE code (and ter-

minating NULL) for the diagnostic record RecNumber. The first two characters indi-cate 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 infor-mation 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.



Required Headers

#include "sql.h"

Libraries



Returns






For more information, reference MSDN documentation for SQLGetDiagRec.




SQLGetEnvAttr

Returns the current setting of an environment attribute.

Conformance


Syntax

SQLRETURN SQLGetEnvAttr(

SQLHENV EnvironmentHandle,




SQLINTEGER * StringLengthPtr)

ArgumentsEnvironmentHandle (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 attrib-ute 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 null-termination 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-ter-mination character and is null-terminated by the driver.

Required Headers

#include "sql.h"

Libraries





Returns






Comments

The attributes accepted by SQLGetEnvAttr are listed under SQLSetEnvAttr.

For more information, reference MSDN documentation for SQLGetEnvAttr.




SQLGetFunctions

Returns information about whether a driver supports a specific ODBC function.

Conformance


Syntax

SQLRETURN SQLGetFunctions(


SQLUSMALLINT FunctionId,

SQLUSMALLINT * SupportedPtr)

ArgumentsConnectionHandle (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 sin-

gle 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



Returns









For more information, reference MSDN documentation for SQLGetFunctions.




SQLGetInfo

Returns general information about the driver and data source associated with a connection.

Conformance


Syntax

SQLRETURN SQLGetInfo(


SQLUSMALLINT InfoType,

SQLPOINTER InfoValuePtr,


SQLSMALLINT * StringLengthPtr)

ArgumentsConnectionHandle (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-ter-mination 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 Buff-erLength bytes minus the length of a null-termination character and is null-ter-minated 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.



Required Headers

#include "sql.h"

Libraries



Returns






For more information, reference MSDN documentation for SQLGetInfo.




SQLGetStmtAttr

Returns the current setting of a statement attribute.

Conformance


Syntax

SQLRETURN SQLGetStmtAttr(





SQLINTEGER * StringLengthPtr)

ArgumentsStatementHandle (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, Buff-erLength is ignored

StringLengthPtr (output) A pointer to a buffer in which to return the total number of bytes (excluding the null-termination 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-ter-mination character and is null-terminated by the driver.

Required Headers

#include "sql.h"

Libraries





Returns






Comments

The attributes accepted by SQLGetStmtAttr are listed under SQLSetStmtAttr.

For more information, reference MSDN documentation for SQLGetStmtAttr.




SQLGetTypeInfo

Returns information about data types supported by the data source.

Conformance


Syntax

SQLRETURN SQLGetTypeInfo(


SQLSMALLINT DataType)

ArgumentsStatementHandle (input) Statement handle. DataType (input) The SQL data type.

Required Headers

#include "sql.h"

Libraries



Returns





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 SQLGetTypeInfo.




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


Syntax

SQLRETURN SQLMoreResults(



Required Headers

#include "sqlext.h"

Libraries



Returns





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 SQLMoreResults.




SQLNativeSql

Returns the SQL string as modified by the driver. SQLNativeSql does not execute the SQL statement.

Conformance


Syntax

SQLRETURN SQLNativeSql(


const SQLCHAR * InStatementText,

SQLINTEGER TextLength1,

SQLCHAR * OutStatementText,


SQLINTEGER * TextLength2Ptr)

ArgumentsConnectionHandle (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-ter-

mination) 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





Returns






For more information, reference MSDN documentation for SQLNativeSql.




SQLNumParams

Determines the number of parameters in a prepared statement

Conformance


Syntax

SQLRETURN SQLNumParams(


SQLSMALLINT * ParameterCountPtr)

ArgumentsStatementHandle (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



Returns









For more information, reference MSDN documentation for SQLNumParams.




SQLNumResultCols

Returns the number of columns in a result set.

Conformance


Syntax

SQLRETURN SQLNumResultCols(


SQLSMALLINT * ColumnCountPtr)

ArgumentsStatementHandle (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



Returns









For more information, reference MSDN documentation for SQLNumResultsCol.




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


Syntax

SQLRETURN SQLParamData(


SQLPOINTER * ValuePtrPtr)

ArgumentsStatementHandle (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



Returns




SQL_ERROR Function failed. The application calls SQLGetDiagRec or SQLGet-DiagField to retrieve additional information. The contents of any out-



put arguments to the function are undefined. SQL_INVALID_HANDLE Function failed due to an invalid environment, connection, statement, or


For more information, reference MSDN documentation for SQLParamData.




SQLPrepare

Prepares an SQL string for execution.

Conformance


Syntax

SQLRETURN SQLPrepare(


SQLCHAR * StatementText,

SQLINTEGER TextLength);

ArgumentsStatementHandle (input) Statement handle. StatementText (input) SQL text string. TextLength (input) Length of *StatementText in characters.

Required Headers

#include "sql.h"

Libraries



Returns





SQL_INVALID_HANDLE Function failed due to an invalid environment, connection, statement, or




For more information, reference MSDN documentation for SQLPrepare.




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


Syntax

SQLRETURN SQLPrimaryKeys(


SQLCHAR * CatalogName,


SQLCHAR * SchemaName,


SQLCHAR * TableName,


ArgumentsStatementHandle (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



Returns








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.




SQLProcedureColumns

Returns the parameter and column information about the specified procedures.

Conformance


Syntax

SQLRETURN SQLProcedureColumns(






SQLCHAR * ProcName,


SQLCHAR * ColumnName,


ArgumentsStatementHandle (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





Returns






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.




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


Syntax

SQLRETURN SQLProcedures(






SQLCHAR * ProcName,


ArgumentsStatementHandle (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



Returns








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.




SQLPutData

Allows an application to send data for a parameter or column to the driver at statement execution time. This func-tion 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


Syntax

SQLRETURN SQLPutData(


SQLPOINTER DataPtr,

SQLLEN StrLen_or_Ind);

ArgumentsStatementHandle (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



Returns


DiagField to retrieve additional information from the header record.






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.




SQLRowCount

Gets row count in a table following an INSERT, UPDATE, or DELETE

Conformance


Syntax

SQLRETURN SQLRowCount (


SQLINTEGER *RowCount)

ArgumentsStatementHandle (input) Statement handle. RowCount (output) Points to a buffer in which to return a row count.

Required Headers

#include "sql.h"

Libraries



Returns









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.




SQLSetConnectAttr

Sets attributes that govern aspects of connections.

Conformance


Syntax

SQLRETURN SQLSetConnectAttr(




SQLINTEGER StringLength);

ArgumentsConnectionHandle (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 null-terminated character string. Note that if the Attribute argument is a driver-spe-cific 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, Strin-gLength is ignored.

Required Headers

#include "sql.h"

Libraries



Returns









Comments

Attribute ODBC ValuePtr ContentsSQL_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 spec-ifying "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 connection-level asynchronous execution support. RDM supports the following values:

SQL_ASYNC_ENABLE_OFF = Connection-level asyn-chronous 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 imple-mentation parameter descriptor (IPD) is supported. RDM supports the following values:

SQL_TRUE = Automatic population of the IPD is sup-



Attribute ODBC ValuePtr Contentsported. An application can set the SQL_ATTR_ENA-BLE_AUTO_IPD statement attribute to enable the auto-matic 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 trans-actions 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 run-time engine has been terminated.

Note that the returned value of this attribute may not accurately indicate a "lost" connection.


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

bases 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 fol-lowing values:



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 sup-ports the following values:

SQL_CUR_USE_DRIVER = use the RDM ODBC driv-er'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_TXN_SERIALIZABLE = transactions are serial-izable. Dirty reads, non-repeatable reads and phan-toms are not allowed.

SQL_ATTR_RDM_DBCAT[1] RDM A SQLPOINTER value that specifies the pointer to the RDM database catalog buffer. More than catalog buff-ers can be specified.

Calling SQLSetConnectAttr with this attribute multiple times will append the specified value to the existing cat-alog buffer list.

SQLGetConnectAttr with this attribute will return the catalog buffer list. The number of pointers in the list can be retrieved by using the SQL_ATTR_RDM_DBCAT_COUNT attribute.

SQL_ATTR_RDM_DBCAT_COUNT RDM A read-only SQLUINTEGR value that indicates the number of catalog buffer pointers stored in the catalog buffer list.


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



Attribute ODBC ValuePtr Contentsumn is bound. A call to SQLGetData will simply copy the already-retrieved data into the application buffer. This is the default.

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.

SQL_ATTR_RDM_REMOTE_CONN[1][3] RDM An SQLUINTEGER value that indicates the type of con-nection 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.

The name of the remote server can be specified with the SQL_ATTR_RDM_REMOTE_NAME attribute

SQL_ATTR_RDM_REMOTE_NAME[1] RDM A character string that indicates the name of the remote RDM host that the driver will connect to for data-base access. The default is "localhost."

SQL_ATTR_RDM_RESERVE_BYTES[1] RDM An SQLUINTEGER value that indicates the number of bytes RDM SQL will reserve at connection time. The default value is 0.

SQL_ATTR_RDM_TFS_PORT[1] RDM An SQLUSMALLINT value that indicates the port number the target TFS is listening on. The default is 21553.

SQL_ATTR_RDM_TFSINIT_DISKLESS[4] 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.

SQL_ATTR_RDM_TFSINIT_DOCROOT[4] 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 appli-cation's working directory will be used.

SQL_ATTR_RDM_TFSINIT_LOGFILE[4] RDM A character string that contains the name of the log file



Attribute ODBC ValuePtr Contentswhere 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 21553.

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 oper-ations 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 out-put 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 recom-piled.

The default value is SQL_TFSTYPE_DEFAULT. SQL_ATTR_RDM_TFSINIT_VERBOSE[4] RDM A 32-bit integer that indicates whether the verbose

mode is enabled. If SQL_TRUE, more detailed mes-sage 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 mes-sages 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 con-nection has been established will not take effect until the existing connection has been closed and a new one has been established.



[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 argu-ment. 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 42000 error at the statement preparation time.

For more information, reference MSDN documentation for SQLSetConnectAttr.




SQLSetCursorName

Associates a cursor name with an active statement.

Conformance


Syntax

SQLRETURN SQLSetCursorName (


SQLCHAR *CursorName,

SQLSMALLINT BufferLength)

ArgumentsStatementHandle (input) Statement handle. CursorName (input) Cursor name. For efficient processing, the cursor name should not include any lead-

ing 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



Returns









For more information, reference MSDN documentation for SQLCursorName.




SQLSetDescField

Sets the value of a single field of a descriptor record.

Conformance


Syntax

SQLRETURN SQLSetDescField(



SQLSMALLINT FieldIdentifier,


SQLINTEGER BufferLength);

ArgumentsDescriptorHandle (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 char-acter 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





Returns






For more information, reference MSDN documentation for SQLSetDescField.




SQLSetDescRec

Sets multiple descriptor fields that affect the data type and buffer bound to a column or parameter data.

Conformance


Syntax

SQLRETURN SQLSetDescRec(



SQLSMALLINT Type,

SQLSMALLINT SubType,

SQLLEN Length,

SQLSMALLINT Precision,

SQLSMALLINT Scale,

SQLPOINTER DataPtr,

SQLLEN * StringLengthPtr,

SQLLEN * IndicatorPtr);

ArgumentsDescriptorHandle (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 rec-ord. 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 rec-ord.

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 descrip-tor record.

Scale (input) The value to which to set the SQL_DESC_SCALE field for the descriptor rec-ord.

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.



Required Headers

#include "sql.h"

Libraries



Returns






For more information, reference MSDN documentation for SQLSetDescRec.




SQLSetEnvAttr

Sets attributes that govern aspects of environments.

Conformance


Syntax

SQLRETURN SQLSetEnvAttr(

SQLHENV EnvironmentHandle,



SQLINTEGER StringLength);

ArgumentsEnvironmentHandle (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



Returns








Comments

Attribute and ValuePtr

RDM accepts the following attribute values.

Attribute ODBC ValuePtr contentsSQL_ATTR_CONNECTION_POOLING 3.0 A 32-bit SQLUINTEGER value that enables or dis-

ables 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 sup-port connection pooling.

SQL_ATTR_ODBC_VERSION 3.0 A 32-bit integer that determines whether certain func-tionality 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:

l The driver returns and expects ODBC 3.x codes for date, time, and timestamp

l The driver returns ODBC 3.x SQLSTATE codes when SQLGetDiagField, or SQLGet-DiagRec is called

l The CatalogName argument in a call to SQLTa-bles accepts a search pattern.

l The driver does not support C data type exten-sibility.

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



Attribute ODBC ValuePtr contentsstring 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.




SQLSetError

Registers user-defined status/error handling functions.

Conformance


Syntax

SQLRETURN SQLSetError(


SQLHANDLE Handle,

SQLRETURN ErrorCode,

ECALLBACK ErrorHandler);

ArgumentsHandleType (input) Handle type identifier. The following values are accepted.

l SQL_HANDLE_DBC l SQL_HANDLE_DESC l SQL_HANDLE_STMT

Handle (input) The handle, of the type indicated by HandleType, indicating the scope of the trans-action.

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


Libraries





Error Handler Prototype

int32_t SQL_API errHandler(

int16_t HandleType,

SQLHANDLE Handle,

SQLRETURN error_code);

Return Codes





Diagnostics

SQLSTATE Error DescriptionHY001 Memory allocation error Either the ODBC driver or the SQL engine failed to allocate suf-

ficient memory to complete the required operation.HY010 Function sequence error This function was called after SQLExecute or SQLEx-

ecDirect but before all the parameters were bound.



SQLSetStmtAttr

Sets attributes related to a statement

Conformance


Syntax

SQLRETURN SQLSetStmtAttr(




SQLINTEGER StringLength)

ArgumentsStatementHandle (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



Returns


DiagField to retrieve additional information from the header record.






Comments

Attributes and ValuePtr

RDM accepts the following attribute values.

Attribute ODBC ValuePtr contentsSQL_ATTR_APP_PARAM_DESC 3.0 The handle to the APD. The handle will replace the han-

dle 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 implic-itly 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 implic-itly 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



Attribute ODBC ValuePtr contentsSQL_ATTR_CONCURRENCY 2.0 A SQLULEN value that specifies the cursor con-

currency. 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.


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.


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).


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).


SQL_CURSOR_STATIC

SQL_CURSOR_KEYSET_DRIVEN

SQL_CURSOR_DYNAMIC



Attribute ODBC ValuePtr contentsRDM 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 avail-able 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 argu-ments of catalog functions are treated. The possible values are:

SQL_FALSE = the string arguments of catalog func-tions are not treated as identifiers. Arguments are case-sensitive and may contain a string search pattern (default).




Attribute ODBC ValuePtr contentsSQL_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 bind-ing. If non-null, the pointer will be dereferenced, and the value contained will be added to each of the deref-erenced 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 orien-

tation to be used for dynamic parameters. The possible values are:

SQL_PARAM_BIND_BY_COLUMN = Perform column-wise 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_TIMEOUT1 1.0 An SQLULEN value that specifies the number of sec-

onds 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) spec-ified by ODBC.

SQL_ATTR_RETRIEVE_DATA 2.0 An SQULEN value that specifies whether SQLFetch

1Although 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.



Attribute ODBC ValuePtr contentsand SQLFetchScroll retrieve data after it positions the cursor. The possible values are:

SQL_RD_ON = Data are retrieved (default).


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 non-null, the pointer will be dereferenced, and the value con-tained 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 orien-

tation to be used for column binding The possible values are:

SQL_BIND_BY_COLUMN = Perform column-wise bind-ing (default).

Row-wise binding is not supported.SQL_ATTR_ROW_NUMBER 2.0 An SQLULEN value that indicates the number of the cur-

rent 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 attrib-ute.

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.



Attribute ODBC ValuePtr contentsThe 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 state-ments affect only one row. The possible values are:

SQL_SC_NON_UNIQUE = The driver does not guar-antee that simulated positioned update and delete statements affect only one row.

SQL_SC_TRY_UNIQUE = The driver tries to guar-antee that simulated positioned update and delete statements affect only one row.

SQL_SC_UNIQUE = The driver guarantees that sim-ulated 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 guar-antees 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).


SQL_UB_ON

For more information, reference MSDN documentation for SQLSetStmtAttr.




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(


SQLSMALLINT IdentifierType,







SQLSMALLINT Scope,

SQLSMALLINT Nullable);

ArgumentsStatementHandle (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 retriev-ing 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 con-tain 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.



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 driv-ers 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



Returns





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.

Comments

SQLSpecialColumns returns the information that pertains to the databases that are currently open. If no data-base is open on the data source, SQLSpecialColumns returns an empty result set.

For more information, reference MSDN documentation for SQLSpecialColumns.




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


Syntax

SQLRETURN SQLStatistics(








SQLUSMALLINT Unique,

SQLUSMALLINT Reserved);

ArgumentsStatementHandle (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 ("") indi-cates 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





Returns






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.




SQLTables

Returns the list of table, catalog, or schema names, and table types, stored in a specific data source.

Conformance


Syntax

SQLRETURN SQLTables(








SQLCHAR * TableType,


ArgumentsStatementHandle (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





Returns






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.




SQLTransactStatus

Retrieves the type and status of the transaction possibly executed on the handle.

Conformance


Syntax

SQLRETURN SQL_API SQLTransactStatus(


SQLHANDLE Handle,

SQLSMALLINT *pActive)

ArgumentsHandleType (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 trans-action.

pActive (output) The status of the transaction on the handle. For the possible return values for pAc-tive, see the table in the Comments section below.

Required Headers


Libraries



Returns








Diagnostics

SQLSTATE Error Description08003 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 DescriptionSQL_TXN_INACTIVE No transaction is active on the specified handle.SQL_TXN_REGULAR A regular (i.e. updatable) transaction is active on the specified handle.SQL_TXN_READONLY A read-only transaction (i.e. snapshot) is active on the specified handle.



Summary Listing of RDM SQL Server API FunctionsThe following table lists alphabetically the functions used to initialize the RDM SQL Server in various con-figurations.

Function Descriptionrdmsqlserver_init Provide RDM SQL with parameters to start up as a serverrdmsqlserver_start Begin running connections from rdbcrdmsqlserver_stop Stop running connections from rdbcrdmsqlserver_term Terminate the use of the RDM SQL Server, releasing resources



rdmsqlserver_init

Start up a RDM SQL Server

Prototype

int32_t rdmsqlserver_init(

const SQL_PARAMS *params,

RDMSQL_CTX **sql_ctx)

Parametersparams (input) Parameters required for server operation. If NULL, defaults are used. sql_ctx (output) Handle used for running, stopping or terminating this server.

Description

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;

Element Declaration Descriptionport uint16_t TFS anchor port. Should match TFS -p port number (use 21553 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 useno_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

SQL_PARAMS structure definition



Element Declaration Descriptionstdout. If the value is an empty string ("") no messages will be displayed.

Required Headers

#include "rdmsqlserver.h"

Libraries

Library Name Descriptionrdmsqlserver11 RDM SQL Server Library


Return Codes

Value Name Description0 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 ();



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);


/* The main part of your application */

(void) rdmsqlserver_term(sql_ctx);

}


}



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);

Parameterssql_ctx (input) Handle returned from a successful rdmsqlserver_initthreaded (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.

Description

This function begins the execution of the RDM SQL server listening and connection threads, enabling the con-nection 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 lis-tening threads have terminated. This parameter may be NULL if it won't be used.

Required Headers


Libraries





Return Codes

Value Name Description0 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



SQL_PARAMS sparams;















}


}



rdmsqlserver_stop

Terminate RDM SQL Server listening and connection threads

Prototype

int32_t rdmsqlserver_stop(

RDMSQL_CTX *sql_ctx)

Parameterssql_ctx (input) Handle returned from a successful rdmsqlserver_init

Description

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 ter-mination all threads initiated by rdmsqlserver_start have been terminated.

Required Headers


Libraries



Return Codes

Value Name Description0 S_OKAY normal return, okay

See Also

rdmsqlserver_start

rdmsqlserver_term

d_tfsstop



Example



SQL_PARAMS sparams;















}


}



rdmsqlserver_term

Terminate a RDM SQL Server

Prototype

int32_t rdmsqlserver_term(

RDMSQL_CTX *sql_ctx)

Parameterssql_ctx (input) Handle returned from a successful rdmsqlserver_init

Description

Call rdmsqlserver_term to terminate a RDM SQL server that was previously started with rdmsqlserver_initThis function must be called prior to termination but after any rdbc API function calls if rdmsqlserver_init was called. 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


Libraries



Return Codes

Value Name Description0 S_OKAY normal return, okay

See Also

rdmsqlserver_init

rdmsqlserver_stop

d_tfsterm



Example



SQL_PARAMS sparams;















}


}



Return Codes ODBCEach 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 rc;

SQLHSTMT 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 encoun-tered at run time. All other return codes provide run-time information, although SQL_ERROR may indicate a pro-gramming error.

The following table defines the return codes.







SQL_NEED_DATA 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.



ODBC C Data TypesThe 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 argu-ment 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 typeSQL_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 min-

ute;

SQLUSMALLINT sec-

ond;

} TIME_STRUCT;[a]

SQL_C_TYPE_TIMESTAMP SQL_TIMESTAMP_STRUCT struct tagTIMESTAMP_

STRUCT {

SQLSMALLINT year;

SQLUSMALLINT

month;

SQLUSMALLINT day;



C type identifier ODBC C typedef C type SQLUSMALLINT

hour;

SQLUSMALLINT min-

ute;

SQLUSMALLINT sec-

ond;

SQLUINTEGER frac-

tion;[b]

} TIMESTAMP_STRUCT;

[a]

[a] The values of the year, month, day, hour, minute, and second fields in the datetime C data types must con-form to the constraints of the Gregorian calendar. (See Constraints of the Gregorian Calendar later in this appen-dix.)

[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 thou-sandth 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.



Registering RDM ODBC Driver

OverviewOn 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 con-figure the default DSN entry or create one or more new DSN entries as necessary.

Opening the ODBC Driver ManagerTo 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



Configuring the default DSN entryTo 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 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."

Description Description is a text description of the DSN entry. To change the value, type in the desired text in the edit box and click “OK.”

Databases 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).

Options Click the "Options" button to configure the advanced options, such as the driver con-nection type. The "ODBC RDM Setup" dialog will expand as shown in Figure 5.

Working with Default Databases

Figure 3: Database Configuration



Default Server 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 Default Port Number is the default TCP/IP port number the RDM TFServer is lis-tening 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.



Figure 5: ODBC RDM Setup with Advanced Options

Connection Type The RDM ODBC Driver allows the application to access RDM databases locally through TFServer or remotely through our remote server (called rdmsqlserver). The default connection type is "Local." Change this option to "Remote" in order to connect to a remote server.

Remote Server Specify the name of the host where the remote server is running here when select-ing the "Remote" connection type. This value is ignored when the connection type is "Local." The default value is "localhost."

Use Database Name As 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 rec-ommend 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 entryTo 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 dis-played (Figure 6).



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 entryTo 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.



Using the ODBC DriverIn order to use the RDM ODBC Driver, you must first start an instance of rdmsqlserver in the location of the doc-ument root, or by passing in the location with -d. Note that by default, rdmsqlserver will start it's own TFS inter-nally.

>cd database\

>start rdmsqlserver.exe

or

>start rdmsqlserver.exe -d c:\database\


Glossary 183

Glossary

B

B-treeAlso 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.

bufferAn in-memory store of data read from a disk file, in which database operations are per-formed.

C

cacheA set of buffers used to optimize database input and output operations. All RDM Embedded database input and output is performed using a cache.

combineThe concatenation of the members of two or more set types into one set type.

commitThe point at which database changes made during a single transaction are actually written to the database files.

compound keyA key field composed of any combination of fields (not necessarily contiguous) from a rec-ord. Each field of a compound key may be stored in ascending or descending order.

connectThe process of inserting a member record occurrence into a set occurrence.

currency tablesA table of database addresses maintained by the RDM Embedded runtime system for con-trolling record access and set navigation. The currency tables consist of the current member table, current owner table, and the current record.


Glossary 184

current databaseThe 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 memberContains, 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 navi-gation function (d_findfm, d_findlm, d_findnm, or d_findpm).

current ownerContains 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 recordContains the database address of the most recently accessed record instance.

D

data fieldA 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 col-umn.

data fileAn RDM Embedded file defined in a DDL specification that contains occurrences of one or more record types.

databaseAn organized collection of related files.

database addressThe 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 languageA 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 pro-gramming language.


Glossary 185

DDLA 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 pro-gramming language.

deadlockA 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 chainA linked list containing deleted records or nodes to be reused when a new record or node is created.

derived revisionA revision that can be derived from a comparison of the source and destination database dic-tionary files.

destimation databaseThe db_REVISE-created database that stores the specified revisions.

dictionaryA 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.

disconnectThe process of removing a member record from a set occurrence.

document rootThe 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 nameThe "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 127.0.0.1).


Glossary 186

E

environment variableA programmer-specified operating system parameter that is used to identify configuration information to the runtime system.

F

fieldA 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 col-umn.

fileThe primary physical storage unit into which a database is organized. In RDM Embedded, files are used to store records and keys.

H

hierarchical database modelA data representation in which the relationships between record types are formed from par-ent-child structures, such that a record type may have many child relationships but only one parent relationship.

I

indexA 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

joinThe creation of one record type from a hierarchy of record types.

K

keyA field through which rapid and/or sorted access to a record is desired.


Glossary 187

key fileA 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 scanThe process of performing an ordered traversal through all (or a subset of all) occurrences of a given key field.

L

localhostA special Domain Name that always refers to the computer on which the application soft-ware is running. It is the default domain name used by RDM Embedded utilities and runtime library.

lockA multi-user database synchronization mechanism, used to prevent simultaneous updates to shared data. Locks can be applied to the entire database or to files.

loggingThe 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 relationshipA 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 setSpecifies 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 pointerStores set membership linkage information. There is one member pointer stored with a rec-ord 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 188

N

navigationThe 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 modelA 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 dis-tinguishes the Network database model from the Hierarchical database model.

nodeA component of a B-tree, consisting of a page of sorted keys stored in a key file.

normalizeThe elimination of redundant record instances that own a new set, resulting in a one-to-many relationship.

O

occurrenceOne 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 cur-rent record, although the current record will also be set by the scanning functions.

owner of setSpecifies 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

pageFiles are blocked into contiguous fixed-length segments called pages. A page is the unit of database I/O performed in RDM Embedded.

path nameThe sequence of directories in a hierarchical file system that must be traversed to locate a particular file.


Glossary 189

pointerIn 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.

portTogether 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 198.168.140.200).

processAn independently executing task or program. An individual execution of an RDM Embedded application program.

projectionThe placement of fields from one record type into one or more new record types.

Q

queueA 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

recordUsed synonymously with record type or record occurrence depending on the context in which the term is used.

record occurenceOne 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 occur-rence could be "name: Jones, Jim; employee_id: c87101, job_title: engr, pay: 3400".

recoveryThe process of completing the transaction of a process that failed during a commit.


Glossary 190

redundant dataIdentical data that is stored in multiple locations in a database. Typically used to form rela-tionships between tables in a relational database management system.

relational database modelA 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 callA 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 pro-gram (called a "server"). A client application places a function identifier and parameter con-tents into a packet that is first transferred to the server, with results (return code, return parameter values) transferred back to the caller.

Revision Definition LanguageThe RDL supplies information to db_REVISE that cannot be derived from a comparison of the source and destination dictionary files.

root nodeThe top or start node of a B-tree.

RPCA 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 pro-gram (called a "server"). A client application places a function identifier and parameter con-tents into a packet that is first transferred to the server, with results (return code, return parameter values) transferred back to the caller.

runtime systemThe RDM Embedded C language library functions that perform all of the database access required by an application program while it is executing.

S

schemaA conceptual model of the structure of a database that defines the data contents and rela-tionships. A database definition language specification is an implementation of a particular schema.


Glossary 191

setSpecifies 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 occurenceAn individual instance of a set in which one owner record occurrence has one or more member record occurrences connected to it.

set pointerStores 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 scanThe process of performing an ordered traversal through all (or a subset of all) member rec-ord occurrences of a given set occurrence.

slotA position in a data or key file for storage of a single record or key occurrence.

source databaseThe database containing the data that is to be revised. This database is used in a read-only manner.

specified revisionA revision requiring specification by an RDL statement.

splitThe separation of a multiple-member set type into two or more set types.

static revisionA revision that can be performed without changing the existing database content or struc-ture.

synchronizationThe process of ensuring that, in a multi-user database environment, updates to shared data are performed serially, one user at a time.

system recordA 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 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

taskIn an RDM Embedded Application, a task is a block of allocated memory that stores the com-plete database context for a thread of execution. It must be allocated through the d_open-task 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.

TFSA 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.

threadAn 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 proc-ess 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.

timeoutAn event that occurs when a lock request has waited on a queue longer than a pre-deter-mined amount of time. It is used to avoid deadlock.

transactionA 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 serverA 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 193

W

working databaseA 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 com-plete.


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

odbc api reference guide

Documents

rdm odbc api reference

odbc driver manager

registering rdm odbc

return codes odbc

odbc c data types

basic odbc application

native rsql api

rdm server