ODBC Interface

Overview

CQL++ implements all of the ODBC level 1 API and portions of the level 2 API. This chapter describes each function and notes any special considerations when using the function with CQL++. More detailed information about the ODBC API can be found in the Microsoft ODBC reference manual (Programmer's Reference, Microsoft Open Database Connectivity Software Development Kit, Microsoft Corporation).

Many ODBC functions are processed by the Microsoft ODBC driver manager before being routed to the target ODBC driver. We do not describe the driver manager functionality here. The user is again referred to the ODBC documentation.

The ODBC interface is defined for Windows, and is implemented as a Microsoft Windows DLL. It is possible to use the CQL++ ODBC interface on client platforms other than Microsoft Windows (for example, UNIX or OS/2). Technically, this is not a complete implementation of ODBC, because the driver manager functions provided by the Microsoft ODBC driver manager are not available except on platforms supported by Microsoft (currently Windows and MacIntosh). The primary task of the driver manager is to manage client connections to multiple databases. Thus, unless the user provides an equivalent of the driver manager, only one database connection would be possible on clients not supported by Microsoft.

CQL++ implements the ODBC functionality in the SQL engine (the server for client/server versions). The Windows DLL does little more than pass requests to the SQL engine and pass responses to the client. Certain ODBC functions, such as those which return information about system capabilities, are implemented in the Windows DLL. All functions related to processing of SQL statements are implemented in the SQL engine.

ODBC Types and Parameters

The types used in the ODBC functions are windows typedefs. The user can find the definitions in the include files provided with Microsoft Visual C++. To compile, the user needs the header files "sql.h" and "sqlext.h" provided by Microsoft with the ODBC SDK. The symbol constants for the ODBC function return codes are also defined in these header files.

Error processing in ODBC involves the function SQLError. For most functions, SQL_ERROR is returned when an error occurs. The application then calls SQLError to obtain the value of SQLSTATE, which describes the error. The mechanism is analagous to the errno variable in C. Unlike errno, the SQLSTATE is a string of five characters. Where appropriate, a string description of the error may be provided using the szErrorMsg argument of SQLError.

There is a special SQLSTATE value, S1000, which is used for errors where no specific ODBC SQLSTATE value is defined for the error that occurs. In this case, the error is described by szErrorMsg. In the function descriptions which follow, only those SQLSTATE codes which may be returned by CQL++ are described. The complete list of SQLSTATE values defined by ODBC can be found in the ODBC SDK documentation.

Example of ODBC Function Usage

This section shows a typical sequence for using the ODBC interface. Details about each ODBC function are on the manual pages later in this chapter.

To access CQL++ through ODBC, the following functions are called:

SQLAllocEnv
Allocates an environment handle. The Microsoft driver manager requires this handle. It is not used by the CQL++ driver.
SQLAllocConnect
Allocates a connection handle.
SQLConnect
Establishes a connection with the database and logs the user into the database.
At this point, the user is ready to make SQL requests. There are two methods of executing SQL statements. The first method is to use function SQLExecDirect. If the SQL statement does not have parameters, the statement is executed and the results are ready to be retrieved using SQLFetch. The second method is to make a call to SQLPrepare, followed by a call to SQLExecute. The second method is preferred if the statement is to be execute many times.

If the SQL statement includes parameters, these parameters must be provided to the driver. There are two classes of ODBC parameters. For the first class, the application supplies values for the parameters. Pointers to these values must be provided to the driver using SQLSetParam before the call to SQLExecDirect or SQLExecute. The application needs to ensure that the data for these pointers is valid at execute time.

The second parameter class has the attribute SQL_DATA_AT_EXEC. In this case, instead of a pointer, the pointer parameter in SQLSetParam is treated as an identifier. This identifier may or may not be a pointer; ODBC does not care what it is. When SQLExecute or SQLExecDirect is called for a statement with SQL_DATA_AT_EXEC parameters, the return value is SQL_NEED_DATA. The application must then supply data for the SQL_DATA_AT_EXEC parameters. For each such parameter, the application makes a call to SQLParamData, which returns the identifier for the parameter that was specified on the SQLSetParam call. The application uses the identifier value to identify the parameter being requested, and provides a value for that parameter using SQLPutData. The return value of SQLParamData is either SQL_NEED_DATA or SQL_SUCCESS (assuming no error occured). When SQLParamData returns SQL_SUCCESS, all parameter data has been provided.

The SQLPrepare function is analogous to the ANSI DECLARE CURSOR statement. The SQLExecute function is analogous to the ANSI OPEN cursor statement. The SQLExecDirect function is essentially equivalent to SQLPrepare followed by SQLExecute. However, statements prepared using SQLPrepare can be executed multiple times, while SQLExecDirect can only execute a statement once.

Data is fetched using function SQLFetch or SQLGetData. To use SQLFetch, the application must first bind each result column to a C variable, using function SQLBindCol. The bind operation specifies a pointer, length, and type for result columns. When SQLFetch is called, data is written into these locations.

An alternate method for fetching data involves the SQLGetData function. This function is called after SQLFetch, and returns data for one column in the most recently fetched row. SQLGetData can return data for large columns in more than one operation, if a sufficiently large enough buffer is not available.

Generally, data is fetched until SQLFetch returns SQL_NO_DATA. The statement is then cleaned up by calling SQLFreeStmt. If any updates occured, the application needs to call SQLTransact to commit the transaction (or roll it back).

Information Retrieval Functions

ODBC has several functions used to retrieve information about database tables and columns. Each of these functions returns a result set. The result set is then accessed in the same manner as the results of an SQLExecute or SQLExecDirect functions. The column definitions for each function are given on the man page for the function.

ODBC Parameter Descriptions

INTRODUCTION

ODBC functions use a number of parameters which are common to several functions. There are also conventions for describing input and result variables. These common parameters and specification conventions are described here.

Whenever a string parameter (UCHAR FAR *) is provided to an ODBC function, it is followed by a length parameter (SWORD). For example, when a table name is specified, there are two parameters: 

UCHAR FAR *szTableName,
SWORD cbTableName,
...
Here, cbTableName specifies the number of characters referenced by szTableName. The ODBC parameter names follow the Hungarian notation convention, where the first two characters of the parameter specify the type. A special value, SQL_NTS, is defined to specify that the sz parameter points to a null terminated string.

When an ODBC function returns data, it is either returned to a 32 bit integer, or to an area of storage referenced by a void pointer. In the first case, the output result size is fixed, and there is no length parameter. In the second case, there are three parameters: The user buffer pointer, the length of the user's buffer, and a pointer to an integer to hold the length of the data available for return by the function. If the user's buffer is too small for the data, the ODBC function returns SQL_SUCCESS_WITH_INFO, and the application can use the returned length value to allocate a bigger buffer. Here is an example of a set of three parameters describing a user buffer: 

...
PTR rgbDesc,
SWORD cbDescMax,
SWORD FAR *pcbDesc
...
When specifying a table, ODBC function have three specifiers, a table qualifier, a table owner, and a table name. CQL++ does not currently use the table qualifier.

The following list describes parameter names and types used in may ODBC functions.

cbValueMax
32 bit signed integer specifying the size of a parameter or result C variable.
fCType
C data type. Must be one of the following values (defined in ODBC header files sql.h and sqlext.h):
SQL_C_BINARY
array of unsigned char for binary data.
SQL_C_BIT
unsigned char to hold a boolean value.
SQL_C_CHAR
array of character for string data.
SQL_C_DATE
date structure.
SQL_C_DEFAULT
specifies the default type for the parameter or result column. Each ODBC column type has a default C type for parameters and results.
SQL_C_DOUBLE
double.
SQL_C_FLOAT
float.
SQL_C_LONG
32 bit signed integer.
SQL_C_SHORT
16 bit signed integer.
SQL_C_TIME
time structure.
SQL_C_TIMESTAMP
timestamp structure.
SQL_C_TINYINT
8 bit signed integer.
fDescType
Descriptor type. Used for specifying the type of information on a request which retrieves information describing result set data. Must be one of the following values:
SQL_COLUMN_COUNT
The number of result set columns.
SQL_COLUMN_NAME
A result set column name.
SQL_COLUMN_TYPE
An ODBC data type. The data type values are described for parameter fSqlType.
SQL_COLUMN_LENGTH
The amount of data which will be transferred to a local C variable for a result set column.
SQL_COLUMN_PRECISION
The precision of the column. This value is obtained from the database server. It is either a result specified during a CREATE TABLE or a precision determined by the database server for a numeric calculation.
SQL_COLUMN_SCALE
The scale of the column.
SQL_COLUMN_DISPLAY_SIZE
The display width of the column value.
SQL_COLUMN_NULLABLE
Specifies whether column was declared NOT NULL. Return value is either SQL_NO_NULLS or SQL_NULLABLE. ODBC defines a third value, SQL_NULLABLE_UNKNOWN, which is never returned by CQL++.
SQL_COLUMN_UNSIGNED
Always returns FALSE for CQL++.
SQL_COLUMN_MONEY
Always returns FALSE for CQL++.
SQL_COLUMN_UPDATABLE
Returns either SQL_ATTR_READONLY or SQL_ATTR_WRITE. This depends on the user's privileges for the column.
SQL_COLUMN_AUTO_INCREMENT
Always returns FALSE for CQL++.
SQL_COLUMN_CASE_SENSITIVE
For CQL++, returns TRUE for character columns and FALSE for other columns.
SQL_COLUMN_SEARCHABLE
For CQL++, always returns SQL_SEARCHABLE which means that there are no type sensitive restrictions.
SQL_COLUMN_TYPE_NAME
The type of the column as known to the database server.
fSqlType
The SQL type of a column. Allowable values are:
SQL_BIGINT
8 byte signed integer.
SQL_BINARY
Fixed length binary, length <= 255
SQL_BIT
1 bit boolean.
SQL_CHAR
Fixed length character, length <= 255
SQL_DATE
Date structure, defined in header file cqcolumn.h.
SQL_DECIMAL
Decimal structure, defined in header file cqcolumn.h.
SQL_DOUBLE
8 byte float.
SQL_FLOAT
8 byte float (synonym for SQL_DOUBLE).
SQL_INTEGER
32 bit signed integer.
SQL_LONGVARBINARY
Variable length binary, length >= 256 and length <= 65535.
SQL_LONGVARCHAR
Null terminated variable length string, length >= 256 and length <= 65535.
SQL_NUMERIC
Synonym for SQL_DECIMAL.
SQL_REAL
4 byte float.
SQL_SMALLINT
16 bit signed integer.
SQL_TIME
Time structure, defined in header file cqcolumn.h.
SQL_TIMESTAMP
Timestamp structure, define in header file cqcolumn.h.
SQL_TINYINT
8 bit signed integer.
SQL_VARBINARY
Variable length binary, length <= 254.
SQL_VARCHAR
Variable length null terminated string, length <= 255.
hdbc
Database handle. Used on calls which do not use a statement handle.
henv
Environment handle. Used on call to SQLAllocConnect.
hstmt
Statement handle. Allocated by SQLAllocStmt and used as the first argument for most ODBC functions.
icol
Column number. May refer to the retrieved column number or the parameterized argument number of an SQL statement.
pcbValue
32 bit signed integer pointer to C variable used by an ODBC function to return the length of a result column. If the result column is null, the C variable will contain SQL_NULL_DATA.
rgbDesc
Pointer to data area for returning descriptor names.
rgbValue
Pointer to result or parameter C variable.

Manual Pages

The function descriptions which follow are in a format similar to the UNIX man page format. The following function descriptions are available:
SQLAllocConnect
SQLAllocEnv
SQLAllocStmt
SQLBindCol
SQLCancel
SQLColAttributes
SQLColumns
SQLConnect
SQLDescribeCol
SQLDisconnect
SQLDriverConnect
SQLError
SQLExecDirect
SQLExecute
SQLFetch
SQLForeignKeys
SQLFreeConnect
SQLFreeEnv
SQLFreeStmt
SQLGetConnectOption
SQLGetCursorName
SQLGetData
SQLGetFunctions
SQLGetInfo
SQLGetStmtOption
SQLGetTypeInfo
SQLNumResultCols
SQLParamData
SQLPrepare
SQLPutData
SQLRowCount
SQLSetConnectOption
SQLSetCursorName
SQLSetParam
SQLSetStmtOption
SQLSpecialColumns
SQLStatistics
SQLTables
SQLTransact

SQLAllocConnect

NAME
SQLAllocConnect
SHORT DESCRIPTION
SQL Allocate Connection Handle
SYNOPSIS 
RETCODE SQLAllocConnect(
HENV henv,
HDBC FAR *phdbc
)
DESCRIPTION
SQLAllocConnect allocates a connection handle. The connection handle is used as the first argument to most of the other ODBC functions. SQLAllocConnect does not establish the database connection.
RETURN VALUES
On success, SQL_SUCCESS is returned. If henv is invalid, SQL_INVALID_HANDLE is returned. If any other error occurs, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1001
Memory allocation failure.
S1009
phdbc was null.
SEE ALSO
  • SQLConnect
  • SQLFreeConnect

SQLAllocEnv

NAME
SQLAllocEnv
SHORT DESCRIPTION
SQL Allocate Environment Handle
SYNOPSIS 
RETCODE SQLAllocEnv(
HENV FAR * phenv
)
DESCRIPTION
SQLAllocEnv is the first function called by an application using the ODBC interface. In CQL++, SQLAllocEnv does nothing. All the resource allocation occurs on SQLAllocConnect and SQLConnect. However, the function must still be called, to satisfy the requirements of the driver manager and to obtain an environment handle for those functions which require one.

There are actually two SQLAllocEnv functions, one in the Microsoft driver manager and one in the CQL++ ODBC driver. Refer to the ODBC documentation for information about the behavior of the Microsoft driver manager.

RETURN VALUES
On success, SQL_SUCCESS is returned. If an error occurs, SQL_ERROR is returned.
SEE ALSO

SQLAllocStmt

NAME
SQLAllocStmt
SHORT DESCRIPTION
Allocate SQL statement handle
SYNOPSIS 
RETCODE SQLAllocStmt(
HDBC hdbc,
HSTMT FAR *phstmt
)
DESCRIPTION
SQLAllocStmt allocates a statement handle. The statement handle is required for ODBC functions which process statements. The ODBC statement is roughly analogous to the ANSI SQL cursor.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hdbc is invalid, SQL_INVALID_HANDLE is returned. If any other error occurs, SQL_ERROR is returned.
SQLSTATE VALUES
08003
hdbc does not refer to an open connection.
S1000
General error.
S1001
Memory allocatino failure.
S1009
phstmt was a null pointer.
SEE ALSO
  • SQLExecDirect
  • SQLExecute
  • SQLFreeStmt
  • SQLPrepare

SQLBindCol

NAME
SQLBindCol
SHORT DESCRIPTION
Bind C variable to SQL statement
SYNOPSIS 
RETCODE SQLBindCol(
HSTMT hstmt,			// statement handle
UWORD icol,				// column number
SWORD fCType,			// C variable type
PTR rgbValue,			// pointer to address of C variable
SDWORD cbValueMax,		// length of area pointer to by rgbValue
SDWORD FAR *pcbValue	// Null indicator/length of result
)
DESCRIPTION
SQLBindCol is used specify the address of a C variable. The C variable my be receiving a result value, or it may be specifying a parameter value. SQLBindCol supplies a type for the result or parameter, and CQL++ performs any allowable data type conversions. After SQLBindCol completes, the 32 bit integer pointed to by cbValueMax contains the length of the result or SQL_NULL_DATA.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1001
Memory allocation failure.
S1002
Invalid column number.
S1003
Invalid fCType type for parameter or result.
S1009
rgbValue was null.
S1090
Negative value specified for cbValueMax.
SEE ALSO
  • SQLDescribeColumn
  • SQLFetch
  • SQLFreeStmt
  • SQLGetData
  • SQLNumResultCols

SQLCancel

NAME
SQLCancel
SHORT DESCRIPTION
Cancel Asynchronous Processing
SYNOPSIS 
RETCODE SQLCancel( HSTMT hstmt )
DESCRIPTION
SQLCancel terminates processing for an SQL request which was started asynchronously. This can occur only with the client server version. CQL++ opens a second TCP/IP connection to the server, and requests termination of the appropriate statement processing. A constant stored within the CQL++ ODBC driver contains an identifier by which the statement is known to the database server.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
70100
The cancel request was not processed by the database server. Either the database server had already completed processing before the cancel request was received, or the ODBC driver was unable to establish an additional TCP/IP connection to the server.
S1000
General error.
S1001
Memory allocation failure.
SEE ALSO
  • SQLLExecDirect
  • SQLExecute
  • SQLFreeStmt

SQLColAttributes

NAME
SQLColAttributes
SHORT DESCRIPTION
Return column descriptor information
SYNOPSIS 
RETCODE SQLColAttributes(
HSTMT hstmt,			//  statement handle
UWORD icol,				//  column number
UWORD fDescType,		//  descriptor type
PTR rgbDesc,			//  data area for descriptor information
SWORD cbDescMax,		//  length of descriptor area
SWORD FAR * pcbDesc,	//  return data length
SDWORD FAR *pfDesc		//  Pointer to integer results
)
DESCRIPTION
SQLColAttributes returns information about a result set column. Data is returned in either the data area pointed to by rgbDesc, in the 32 bit integer pointed to by pfDesc. The following list specifies the type of information returned by each allowable fDescType value.
SQL_COLUMN_COUNT
rgbDesc
Not used
pfDesc
Number of result set columns
SQL_COLUMN_NAME
rgbDesc
Column name
pfDesc
Not used
SQL_COLUMN_TYPE
rgbDesc
Not used
pfDesc
ODBC SQL data type
SQL_COLUMN_LENGTH
rgbDesc
Not used
pfDesc
Transfer size of result
SQL_COLUMN_PRECISION
rgbDesc
Not used
pfDesc
The precision of the column
SQL_COLUMN_SCALE
rgbDesc
Not used
pfDesc
The scale of the column
SQL_COLUMN_DISPLAY_SIZE
rgbDesc
Not used
pfDesc
Maximum display size
SQL_COLUMN_NULLABLE
rgbDesc
Not used
pfDesc
SQL_NO_NULLS or SQL_NULLABLE
SQL_COLUMN_UNSIGNED
rgbDesc
Not used
pfDesc
Always FALSE for CQL++
CQL_COLUMN_MONEY
rgbDesc
Not used
pfDesc
Always FALSE for CQL++
SQL_COLUMN_TYPE_NAME
rgbDesc
CQL type name
pfDesc
Not used
SQL_COLUMN_UPDATABLE
rgbDesc
Not used
pfDesc
SQL_ATTR_READONLY or SQL_ATTR_WRITE
SQL_COLUMN_AUTO_INCREMENT
rgbDesc
Not used
pfDesc
always FALSE for CQL++
SQL_COLUMN_CASE_SENSITIVE
rgbDesc
Not used
pfDesc
TRUE for character types, FALSE otherwise
SQL_COLUMN_SEARCHABLE
rgbDesc
Not used
pfDesc
SQL_UNSEARCHABLE for LONGVARCHAR and binary types, SQL_SEARCHABLE for other types
RETURN VALUES
On success, SQL_SUCCESS is returned. If only part of the result data is written (the area pointed to by rgbDesc is not big enough), SQL_SUCCESS_WITH_INFO is returned. For asynchronous requests that have not completed, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01004
Data truncated.
24000
No result set for hstmt.
S1000
General error.
S1001
Memory allocation failure.
S1002
Invalid column number.
S1008
Operation canceled.
S1010
Invalid statement state (statement not prepared or executed).
S1090
Invalid buffer length (cbDescMax less than 0).
S1091
fDescType value invalid.
S1T00
Timeout.
SEE ALSO
  • SQLPrepare
  • SQLExecute
  • SQLBindCol
  • SQLCancel
  • SQLDescCol
  • SQLFetch
Note: If a statement is prepared but no fetch has yet occured, any SQLSTATE value returned by SQLExecute can also be returned by SQLColAttributes.

SQLColumns

NAME
SQLColumns
SHORT DESCRIPTION
Retrieve list of column names
SYNOPSIS 
RETCODE SQLColumns(
HSTMT hstmt,
UCHAR FAR *szTableQualifier,
SWORD cbTableQualifier,
UCHAR FAR *szTableOwner,
SWORD cbTableOwner,
UCHAR FAR *szTableName,
SWORD cbTableName,
UCHAR FAR *szColumnName,
SWORD cbColumnName
)
DESCRIPTION
SQLColumns returns a list of columns which satisfy the input conditions. The input specifications can include wild cards (in the style used for the SQL LIKE operator). This function is converted to a SELECT on the system tables which contain information about tables and columns. The following columns are returned:
TABLE_QUALIFIER
VARCHAR(128). NULL for CQL
TABLE_OWNER
VARCHAR(128). Authorization identifier
TABLE_NAME
VARCHAR(128) NOT NULL. Table identifier
DATA_TYPE
SMALLINT NOT NULL. ODBC SQL data type
TYPE_NAME
VARCHAR(128) NOT NULL. CQL data type
PRECISION
INTEGER. Column precision
LENGTH
INTEGER. Transfer size. This may be different than the size of the actual data in the table
SCALE
SMALLINT. Column scale
RADIX
SMALLINT. Base of precision and scale. Always 10 for CQL
NULLABLE
SMALLINT NOT NULL. SQL_NO_NULLS or SQL_NULLABLE
REMARKS
VARCHAR(254). Always NULL for CQL

SQLColumns performs the equivalent of an SQLExecDirect for this imaginary table. The application uses one of the ODBC fetch functions to retrieve the data.

RETURN VALUES
On success, SQL_SUCCESS is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
24000
hstmt state invalid.
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1010
Asynchronous processing protocol error.
S1090
Length parameter less than zero and not SQL_NTS
S1T00
Timeout
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLFetch
  • SQLStatistics
  • SQLTables

SQLConnect

NAME
SQLConnect
SHORT DESCRIPTION
Connect to the database server
SYNOPSIS 
RETCODE SQLConnect(
HDBC hdbc,				// database handle
UCHAR FAR *szDSN,		// data source name
SWORD cbDSN,
UCHAR FAR *szUID,		// user identifier
SWORD cbUID,
UCHAR FAR *szAuthStr,	// password
SWORD cbAuthStr
)
DESCRIPTION
Establishes a connection to the database server, and validates the user ID and password (Release 8.1 of CQL++ does not validate the password). For the client server version, a TCP/IP connection is established with the database server, and initialization is performed. The single user version performs the same initialization. Because the single user version is a library and not a server, there is no need to actually establish a connection. For ODBC purposes, however, the SQLConnect function is used to log on to the database.
RETURN VALUES
On success, SQL_SUCCESS is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08001
Unable to establish connection to database server.
08002
Connection already exists for hdbc.
08S01
Connection established and then lost.
S1000
General error.
S1001
Memory allocation failure.
S1090
Length parameter less than 0 and not SQL_NTS.
S1T00
Timeout.
SEE ALSO
  • SQLAllocConnect
  • SQLAllocStmt
  • SQLDisconnect
  • SQLDriverConnect

SQLDescribeCol

NAME
SQLDescribeCol
SHORT DESCRIPTION
Get column name, type, and length
SYNOPSIS 
RETCODE SQLDescribeCol(
HSTMT hstmt,				// statement handle
UWORD icol,					// column number
UCHAR FAR *szColName,		// column name (output)
SWORD cbColNameMax,			// space for column name
SWORD FAR *pcbColName,		// actual column name length
SWORD FAR *pfSqlType,		// ODBC SQL data type (output)
UDWORD FAR *pcbColDef,		// Column precision (output)
SWORD FAR *pibScale,		// Column scale (output)
SWORD FAR *pfNullable
)
DESCRIPTION
SQLDescribeCol returns values in szColName, pfSqlType, pcbColDef, pibScale, and pfNullable for a result set column.
RETURN VALUES
On success, SQL_SUCCESS is returned. If the space for writing the column name is too small, SQL_SUCCESS_WITH_INFO is returned. If called asynchronously, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01004
Data truncated. The space for writing the column name is too small.
24000
hstmt does not refer to a statement handle with a result set.
S1000
General error.
S1001
Memory allocation failure.
S1002
Invalid column number (less than zero or too high).
S1008
Operation canceled.
S1010
Neither SQLPrepare nor SQLExecDirect was called for hstmt.
S1090
cbColNameMax less than 0.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLColAttributes
  • SQLFetch
  • SQLPrepare

SQLDisconnect

NAME
SQLDisconnect
SHORT DESCRIPTION
close the connection to the database
SYNOPSIS 
RETCODE SQLDisconnect( HDBC hdbc )
DESCRIPTION
Sends a termination message to the database server and closes the connection.
RETURN VALUES
On success, SQL_SUCCESS is returned. If an error occurs, but the disconnect succeeds, SQL_SUCCESS_WITH_INFO is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01002
Disconnect error, but disconnect succeeded.
08003
Connection not open.
25000
Transaction in progress. Disconnect fails and transaction continues.
S1000
General error.
S1001
Memory allocation failure.
S1010
Asynchronous function executing. Execution continues and disconnect fails.
SEE ALSO
  • SQLAllocConnect
  • SQLConnect
  • SQLDriverConnect
  • SQLFreeConnect
  • SQLTransact

SQLDriverConnect

NAME
SQLDriverConnect
SHORT DESCRIPTION
Alternative connection function.
SYNOPSIS 
RETCODE SQLDriverConnect(
HDBC hdbc;					// connection handle
HWND hwnd;					// window handle
UCHAR FAR *szConnStrIn,		// connection string
SWORD cbConnStrIn,
UCHAR FAR *szConnStrOut,	// output connection string
SWORD cbConnStrOutMax,
SWORD FAR *pcbConnStrOut,
UWORD fDriverCompletion		// protocol control
)
DESCRIPTION
SQLDriverConnect is an alternative to SQLConnect for connecting to a database. SQLDriverConnect is specific to Microsoft windows, and (optionally) creates a window for inputting the the user ID and password. If used, the window is added as a child to the window whose handle is provided in hwnd.

Parameter fDriverCompletion controls the behavior of the driver manager. Refer to the Microsoft ODBC SDK documentation for details.

The user can specify that the CQL++ driver use szConnStrIn for connection information. The syntax of the string is:
"DSN=value;UID=value;PWD=value"
If a value is missing a dialog box is used to prompt the user for the value. CQL++ does not currently use the password value.

RETURN VALUES
On success, SQL_SUCCESS is returned. If the operation succeeds, but the space pointed to by szConnStrOut is too small, SQL_SUCCESS_WITH_INFO is returned. If the data source is not found by the driver manager, SQL_NO_DATA_FOUND is returned. If hdbc is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01004
Data truncated. The space pointed to by szConnStrOut is too small.
01S00
Invalid connection string keyword.
08001
Unable to connect to data source.
08002
hdbc is in use for an active connection.
08004
Data source rejected connection.
08S01
Communication failure.
28000
Invalid authorization identifier.
S1000
General error.
S1001
Memory allocation failure.
S1090
Length parameter was less than 0 and was not SQL_NTS.
S1110
Invalid value of fDriverCompletion.
S1T00
Timeout.
SEE ALSO
  • SQLAllocConnect
  • SQLConnect
  • SQLDisconnect
  • SQLFreeConnect

SQLError

NAME
SQLError
SHORT DESCRIPTION
Retrieve error information
SYNOPSIS 
RETCODE SQLError(
HENV henv,					// environment handle
HDBC hdbc,					// connection handle
HSTMT hstmt,				// statement handle
UCHAR FAR *szSqlState,		// value of SQLSTATE
SDWORD FAR *pfNativeError,	// CQL position code
UCHAR FAR *szErrorMsg,		// error message text
SWORD cbErrorMsgMax,
SWORD FAR *pcbErrorMessage
)
DESCRIPTION
SQLError returns the most recent error information associated with henv, hdbc, or hstmt. If hstmt is not null, error information is returned for hstmt and hdbc and henv are ignored. If hstmt is SQL_NULL_HSTMT and hdbc is not SQL_NULL_HDBC, error information is returned for hdbc and henv is ignored. If hstmt is SQL_NULL_HSTMT and hdbc is SQL_NULL_HDBC, error information is returned for the environment.

Error information is associated with the handle used on a particular ODBC call that returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO. The application then calls SQLError with the appropriate handle arguments to retrieve the state. The CQL++ position code is returned in pNativeError. In some cases, a CQL++ error description is returned in szErrorMsg.

Some errors are processed entirely by the Microsoft driver manager. Refer to the Microsoft ODBC SDK documentation for more information.

RETURN VALUES
On success, SQL_SUCCESS is returned. If there is not enough room to write the error message string, SQL_SUCCESS_WITH_INFO is returned. If there was no error on the most recent call using the supplied handle, SQL_NO_DATA_FOUND is returned. If an invalid handle was supplied, SQL_INVALID_HANDLE is returned. If SQLError fails, you cannot use a subsequent call to SQLError to obtain information about the failure. The only information available about SQLError status is the return code.

SQLExecDirect

NAME
SQLExecDirect
SHORT DESCRIPTION
Execute a dynamic SQL statement.
SYNOPSIS 
RETCODE SQLExecDirect(
HSTMT hstmt,			// statement handle
UCHAR FAR *szSqlStr,	// SQL statement
SDWORD cbSqlStr
)
DESCRIPTION
SQLExecDirect executes an SQL statement. szSqlStr points to the statement. SQLExecDirect is essentially equal to executing SQLPrepare followed by SQLExecute. However, SQLExecDirect only executes a statement once. Following SQLPrepare, the statement can be executed more than once with varying parameters.
RETURN VALUES
On success, SQL_SUCCESS is returned. If the function is asynchronous and is not yet completed, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. If the SQL statement contains parameter markers and the values for the parameter markers have not been set, SQL_NEED_DATA is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01006
REVOKE statement processed, user does not have required privileges.
07001
Mismatch between SQLSetParam and the number of parameter markers in the SQL statement.
08S01
Communication link failure.
21S01
INSERT statement processed, incorrect number of values supplied.
24000
hstmt has results pending from a previous operation.
34000
SQL statement references cursor which is not open.
40001
Deadlock error, statement not executed.
42000
Syntax error or user does not have required privileges.
S0001
CREATE statement for object that already exists.
21S02
CREATE view, view column to referenced table column mismatch.
22001
Maximum length value exceeded.
22003
Numeric value out of range.
22005
Type mismatch in assignment.
22008
Invalid date, time, or timestamp value.
22012
Division by zero.
23000
Integrity constraint violation.
S0002
Table or view not found.
S0011
CREATE INDEX, index name already exists.
S0012
DROP INDEX, index not found.
S0021
ALTER TABLE, attempt to add column with the same name as an existing column.
S0022
Column name does not exist.
S1000
General error
S1001
Memory allocation error.
S1008
Operation cancelled.
S1009
szSqlStr was null or invalid.
S1010
hstmt involved in incomplete asynchronously executing operation.
S1090
Parameter specification error. One of the following situations:
  • Parameter pointer is null and length does not equal SQL_NULL_DATA.
  • Parameter is not null and length is equal to SQL_NULL_DATA.
  • Parameter is not null, length is negative, length is not equal to SQL_NULL_DATA, and length is not equal to SQL_NTS.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLExecute
  • SQLFetch
  • SQLGetCursorName
  • SQLGetData
  • SQLParamData
  • SQLPrepare
  • SQLPutData
  • SQLSetCursorName
  • SQLSetCursorName
  • SQLTransact

SQLExecute

NAME
SQLExecute
SHORT DESCRIPTION
Execute prepared SQL statement
SYNOPSIS 
RETCODE SQLExecute( HSTMT hstmt )
DESCRIPTION
SQLExecute executes an SQL statement. This statement must be prepared before SQLExecute is called. After the statement is prepared, the application can call SQLExecute repeatedly. Before any call to SQLExecute, data from a previous SQLExecute must be retrieved until SQL_NO_DATA_FOUND is returned. Multiple calls to SQLExecute are useful with parameterized SQL statements.
RETURN VALUES
On success, SQL_SUCCESS is returned. If data is needed for statement parameters, SQL_NEED_DATA is returned. If the statement is executing asynchronously and execution is not complete, SQL_STILL_EXECUTING is returned. If an attempt is made to revoke a privilege and the user does not have the required privileges, SQL_SUCCESS_WITH_INFO is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01006
REVOKE statement, user lacks required privileges.
07001
Number of parameters specified with SQLSetParam does not match the number of parameter markers in the prepared SQL statement.
08S01
Communication line failure.
22001
Provided parameter exceeds length of column.
22003
Numeric value out of range.
22005
Error in assignment.
22008
Date, time, or timestamp value invalid.
22012
Division by zero.
23000
Integrity constraint violation.
24000
Invalid cursor state.
40001
Deadlock detected, execution aborted.
42000
Syntax error or user does not have required privileges.
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1010
Statement not prepared.
S1090
Invalid string or buffer length. One of the following situations:
  • Parameter pointer is null and length does not equal SQL_NULL_DATA.
  • Parameter is not null and length is equal to SQL_NULL_DATA.
  • Parameter is not null, length is negative, length is not equal to SQL_NULL_DATA, and length is not equal to SQL_NTS.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLExecute
  • SQLFetch
  • SQLFreeStmt
  • (SQLGetData
  • SQLParamData
  • SQLPrepare
  • SQLPutData
  • SQLSetCursorName
  • SQLSetStmtOption
  • SQLTransact

SQLFetch

NAME
SQLFetch
SHORT DESCRIPTION
fetch result data row
SYNOPSIS 
RETCODE SQLFetch( HSTMT hstmt )
DESCRIPTION
SQLFetch stores data from one result row in the parameters specified by the application using SQLBindCol. Binding must be completed before SQLFetch is called. SQLFetch does not require that all result set columns are bound to C variables. In fact, it doesn't require that any result set columns are bound. Data not bound to a C variable is discarded.

When a column value is NULL, SQLFetch stores SQL_NULL_DATA in the location pointed to by pcbValue.

RETURN VALUES
On success, SQL_SUCCESS is returned. If output data is truncated, SQL_SUCCESS_WITH_INFO is returned. If there are no more result rows, SQL_NO_DATA_FOUND is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. If the fetch is executing asynchronously and is not yet complete, SQL_STILL_EXECUTING is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01004
Operating completed successfully, but one or more output columns received truncated data.
07006
Invalid type conversion requested.
08S01
Communication failure.
22003
Numeric value out of range. The bound column is too small to hold the result. The bound column may be a string or numeric type. Even if the bound column is a string type, an error occurs for numeric variables which cannot be displayed in the length of the string. Numeric values that are converted to strings are not truncated.
22012
Division by zero.
24000
Invalid cursor state.
S1000
General error.
S1001
Memory allocation failure.
S1002
Invalid column number.
S1008
Operation canceled.
S1010
Function sequence error. Call to SQLFetch was not preceeded by call to SQLExecute or SQLExecDirect.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLDescribeCol
  • SQLExecDirect
  • SQLExecute
  • SQLFreeStmt
  • SQLGetData
  • SQLNumResultCols
  • SQLPrepare

SQLForeignKeys

NAME
SQLForeignKeys
SHORT DESCRIPTION
Get foreign key descriptions.
SYNOPSIS 
RETCODE SQLForeignKeys(
HSTMT hstmt,					// statement handle
UCHAR FAR *szPkTableQualifier,	// always empty for CQL++
SWORD cbPkTableQualifier,
UCHAR FAR *szPkTableOwner,		// primary key table owner
SWORD cbPkTableOwner,
UCHAR FAR *szPkTableName,		// primary key table name
SWORD cbPkTableName,
UCHAR FAR *szFkTableQualifier,	// always empty for CQL++
SWORD cbFkTableQualifier,
UCHAR FAR *szFkTableOwner,		// foreign key table owner
SWORD cbFkTableOwner,
UCHAR FAR *szFkTableName,		// foreign key table name
SWORD cbFkTableName
)
DESCRIPTION
The behavior of SQLForeignKeys varies depending on the arguments provided. There are three cases. For case 1, the primary key table name and owner name are provided and the foreign key table name and owner name are not provided. For case 2, the foreign key table name and owner name are provided, and the primary key table name and owner name are not provided. For case 3, both the primary key table and owner names and the foreign key table and owner names are provided.

For case 1, where only the primary key table is identified, SQLForeignKeys returns a result set consisting of the table and column names for all tables defining a foreign key corresponding to the primary key of the identified table.

For case 2, where only the foreign key table is identified, SQLForeignKeys returns a result set consisting of the table and column names for which the identified table has created foreign keys.

For case 3, where both the foreign key and the primary key are identified, SQLForeignKeys returns a result set consisting of the description of the keys in the foreign key table that are related to the primary key of the primary key table. In this case, the result set has either 0 or 1 row.

The result set returned by SQLForeignKeys has the following structure:

PKTABLE_QUALIFIER
VARCHAR(128). NULL for CQL++
PKTABLE_OWNER
VARCHAR(128). Owner of primary key table
PKTABLE_NAME
VARCHAR(128) NOT NULL. Name of primary key table
PKCOLUMN_NAME
VARCHAR(128) NOT NULL. Primary key column name
FKTABLE_QUALIFIER
VARCHAR(128). NULL for CQL++
FKTABLE_OWNER
VARCHAR(128). Owner of foreign key table
FKTABLE_NAME
VARCHAR(128) NOT NULL. Name of foreign key table
FKCOLUMN_NAME
VARCHAR(128) NOT NULL. Foreign key column name
KEY_SEQ
SMALLINT NOT NULL
Column sequence number in key (key column numbering starts with 1).
UPDATE_RULE
SMALLINT. Rule for updates. See also the description of the UPDATE SQL statement.
DELETE_RULE
SMALLINT. Rule for deletes. See also the description of the DELETE SQL statement.
RETURN VALUES
On success, SQL_SUCCESS is returned. If executed asynchronously and execution is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
24000
Invalid cursor state (results pending on hstmt).
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1009
Invalid argument value. Both foreign key table name and primary key table name pointers were null.
S1010
Function sequence error. There is an asynchronous operation in progress for hstmt.
S1090
Invalid length parameter. Either a length was less than 0 and not equal to SQL_NTS, or a length was too long.
S1T00
Timeout.
SEE ALSO

SQLFreeConnect

NAME
SQLFreeConnect
SHORT DESCRIPTION
free resources associated with a connect handle.
SYNOPSIS 
RETCODE SQLFreeConnect( HDBC hdbc )
DESCRIPTION
SQLFreeConnect frees resources associated with a connection handle. Note that this function does not close the connection and log off the database. The application must call SQLDisconnect(2-ODBC) before calling this function.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hdbc is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1010
SQLDisconnect not called before SQLFreeConnect
SEE ALSO
  • SQLAllocConnect
  • SQLConnect
  • SQLDisconnect

SQLFreeEnv

NAME
SQLFreeEnv
SHORT DESCRIPTION
free environment resources
SYNOPSIS 
RETCODE SQLFreeEnv( HENV henv )
DESCRIPTION
SQLFreeEnv frees resources associated with an environment handle.
RETURN VALUES
On success, SQL_SUCCESS is returned. If henv is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1010
At least one connection handle associated with henv is still allocated or connected.
SEE ALSO
  • SQLAllocEnv
  • SQLFreeConnect
  • SQLDisconnect
SQLFreeStmt
NAME
SQLFreeStmt
SHORT DESCRIPTION
Terminate statement and release statement resources
SYNOPSIS 
SQLFreeStmt( HSTMT hstmt, UWORD fOption )
DESCRIPTION
SQLFreeStmt is used to terminate processing of the statement. Depending on the value of fOption, resources associated with the statement handle may be freed. The possible values of fOption are:
SQL_CLOSE
If hstmt is associated with a cursor, close the cursor and discard any pending results. The cursor can be executed again (provided it was not executed by SQLExecDirect), possibly with different parameter values.
SQL_DROP
If hstmt is associated with a cursor, close the cursor and discard any pending results. Then release all resources associated with hstmt. After this, hstmt is no longer a valid statement handle.
SQL_UNBIND
Release buffers and cancel binding for any columns which were bound to local C variables using SQLBindCol.
SQL_RESET_PARAMS
Reverse the effects of any calls to SQLSetParam associated with hstmt.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1001
Memory allocation failure.
S1010
An asynchronous operating is in progress for hstmt
S1092
fOption value was invalid (not SQL_CLOSE, SQL_DROP, SQL_UNBIND, or SQL_RESET_PARAMS)
SEE ALSO
  • SQLAllocStmt
  • SQLCancel
  • SQLSetCursorName

SQLGetConnectOption

NAME
SQLGetConnectOption
SHORT DESCRIPTION
Returns the current value of a connect option
SYNOPSIS 
RETCODE SQLGetConnectOption(
HDBC hdbc,					// connection handle
UWORD fOption,				// option selector
PTR pvParam					// result data
)
DESCRIPTION
SQLGetConnectOption gets the current value of the option specified by parameter fOption. fOption values are described on the man page for SQLSetConnectOption.
RETURN VALUES
On success, SQL_SUCCESS is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08003
Connection not open.
S1000
General error.
S1001
Memory allocation failure.
S1010
There is an asynchronously executing operation on a hstmt associated with this hdbc.
S1092
Invalid value of fOption (see SQLSetConnectOption).
SEE ALSO
  • SQLGetStmtOption
  • SQLSetConnectOption
  • SQLSetStmtOption
SQLGetCursorName
NAME
SQLGetCursorName
SHORT DESCRIPTION
Gets the name of a cursor associated with a statement handle.
SYNOPSIS RETCODE SQLGetCursorName( HSTMT hstmt, UCHAR FAR *szCursor, SWORD cbCursorMax, SWORD FAR *pcbCursor )
DESCRIPTION
SQLGetCursorName returns the name of a cursor associated with hstmt. This is the name which can be used in a positioned delete (DELETE ... WHERE CURRENT OF cursorName) or in a positioned update (UPDATE ... WHERE CURRENT OF cursorName).
RETURN VALUES
On success, SQL_SUCCESS is returned. If cbCursorMax is too small for the cursor name, SQL_SUCCESS_WITH_INFO is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned. For ODBC, the string SQL_CUR is prepended to the name, which cannot exceed 18 characters. The FIPS requirements specify that the maximum length of a cursor name if 18 characters. Therefore, you should either begin each cursor name with SQL_CUR, or limit names to 14 characters.
SQLSTATE VALUES
01004
Data truncated. The buffer size (cbCursorMax) was too small to copy the entire cursor name.
S1000
General error.
S1001
Memory allocation failure.
S1010
An asynchronous operation is in progress for hstmt.
S1015
Cursor name not available at this time.
S1090
cbCursorMax was less than 0.
SEE ALSO
  • SQLExecDirect
  • SQLExecute
  • SQLPrepare
  • SQLSetCursorName

SQLGetData

NAME
SQLGetData
SHORT DESCRIPTION
Get the result data for one column of a result set
SYNOPSIS 
RETCODE SQLGetData(
HSTMT hstmt,
UWORD icol,
SWORD fCType,
PTR rgbValue,
SDWORD cbValueMax,
SDWORD FAR *pcbValue
)
DESCRIPTION
SQLGetData fetches data for one column of the current row associated with hstmt. This is an alternative to using SQLBindCol with SQLFetch (both methods can be used simultaneously if desired). The application calls SQLFetch, and then calls SQLGetData for each result column. The application is not required to fetch data for all, or even any, columns.

SQLGetData can be used to retrieve SQL_LONGVARBINARY and SQL_LONGVARCHAR values which may exceed the size of the buffer which is used to retrieve SQL data. If the buffer is not large enough, the driver writes as many characters as possible into the buffer and returns SQL_SUCCESS_WITH_INFO. The application can then make additional calls to SQLGetData using the same icol value. All data has been fetched when SQLGetData returns SQL_SUCCESS.

If there are bound columns associated with hstmt, the ODBC specification requires that SQLGetData fail for columns whose icol value is less than the icol value for the highest bound column. Also, the ODBC specification requires that, once SQLGetData is called for a value of icol, no subsequent call to SQLGetData may occur with a lower value of icol. CQL++ does not enforce these restrictions. However, if you are concerned about keeping your application 100% ODBC compliant, you should follow these restrictions.

The allowable values for fCType are listed in ODBC Parameters(2-ODBC).

RETURN VALUES
On success, SQL_SUCCESS is returned. If there is not enough room to return all the data for icol, SQL_SUCCESS_WITH_INFO is returned. If the preceding fetch returned SQL_NO_DATA_FOUND, SQL_NO_DATA_FOUND is returned. If the function is called asynchronously and processing is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
01004
Data truncated. The application can make additional calls to SQLGetData to retrieve the rest of the data.
07006
The value of the column cannot be converted to type fCType.
08S01
Communication failure.
22003
Numeric value out of range, cannot be converted to type fCType without losing data. Truncation of the fractional part of a real number does not cause this error.
24000
Invalid cursor state. Either hstmt is not associated with a SELECT, or the associated cursor is not positioned on a row.
S1000
General error.
S1001
Memory allocation failure.
S1002
Invalid column number.
S1003
Invalid value in fCType.
S1008
Operation canceled.
S1009
rgbValue was null.
S1010
The statement associated with hstmt is not in an executed state.
S1090
cbValueMax was less than 0.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLExecute
  • SQLFetch
  • SQLPutData
SQLGetFunctions
NAME
SQLGetFunctions
SHORT DESCRIPTION
Query availability of a function.
SYNOPSIS 
RETCODE SQLGetFunctions(
HDBC hdbc,
UWORD fFunction,
UWORD FAR *pfExists
)
DESCRIPTION
This function is implemented in the Microsoft driver manager. The return values depend on whether the driver identifies itself as core, level 1, or level 2 compliant. The CQL++ driver identifies itself as level 1 compliant, because only some of the level 2 functionality is present. However, CQL++ implements the level 1 and level 2 functions.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hdbc is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1001
Memory allocation failure.
S1010
Connection is not established.
S1095
Invalid fFunction value.
SEE ALSO
  • SQLGetConnectOption
  • SQLGetInfo
  • SQLGetStmtOption

SQLGetInfo

NAME
SQLGetInfo
SHORT DESCRIPTION
Returns information about the CQL++ ODBC driver and SQL engine.
SYNOPSIS 
RETCODE SQLGetInfo(
HDBC hdbc,
UWORD fInfoType,
PTR rgbInfoValue,
SWORD cbInfoValueMax,
SWORD FAR *pcbInfoValue
)
DESCRIPTION
SQLGetInfo returns information about the CQL++ ODBC driver and SQL engine. One piece of information is returned for each call. Parameter fInfoType specifies the information which is returned.

The information returned can be a 16 bit integer, a 32 bit integer, a bitmask (32 bit unsigned integer), or a character string. The data is written to rgbInfoValue, and the data length is written to pcbInfoValue.

For some values of fInfoType, parameter rgbInfoValue is used as an input parameter.

In the following list, each value of fInfoType is described. In cases where the information does not vary for CQL++, the fixed value is described. Complete information about all possible return values can be found in the Microsoft ODBC SDK documentation.

SQL_ACTIVE_CONNECTIONS
0 (no limit).
SQL_ACTIVE_STATEMENTS
0 (no limit).
SQL_DATA_SOURCE_NAME
CQL++ (the data source name).
SQL_DRIVER_HENV
The driver's environment handle. Determined from argument hdbc.
SQL_DRIVER_HDBC
The connection handle.
SQL_DRIVER_HSTMT
Expects an ODBC statement handle in the buffer pointed to by rdbInfoValue. Returns the driver's statement handle.
SQL_DRIVER_NAME
Returns the name of the CQL++ ODBC driver (usually CQLODBC.DLL)
SQL_DRIVER_VER
Driver version number in the form ##.##.####.
SQL_FETCH_DIRECTION
SQL_FD_FETCH_NEXT | SQL_FD_FETCH_FIRST | SQL_FD_FETCH_LAST | SQL_FD_FETCH_PREV | SQL_FD_FETCH_ABSOLUTE. The value formed by ORing these values together describes the fetch capabilities of CQL++.
SQL_ODBC_API_CONFORMANCE
1 (level one supported).
SQL_ODBC_SAG_CLI_CONFORMANCE
1 (SAG compliant).
SQL_ODBC_SQL_CONFORMANCE
1 (core grammar supported). Much, but not all, of the extended grammer is supported. This should not be confused with the API conformance. There are three levels of API conformance, core, level 1, and level 2. The CQL++ driver supports level 1 and some of level 2. There are three levels of grammer conformance, minimum, core, and extended. The CQL++ driver supports the core grammer and some of the extended grammer.
SQL_ODBC_VER
2.01 (ODBC version to which driver conforms).
SQL_PROCEDURES
"N" (does not support stored procedures).
SQL_ROW_UPDATES
"Y" (SQL engine can detect row modifications and guarantee repeatable reads).
SQL_SEARCH_PATTERN_ESCAPE
"\" (backslash is default escape character). CQL++ also supports the ANSI ESCAPE sub-clause of a LIKE condition which allows the user to specify the escape character used for a particular search.
SQL_SERVER_NAME
"CQL++".
SQL_DEFAULT_TXN_ISOLATION
SQL_TXN_SERIALIZABLE
SQL_EXPRESSIONS_IN_ORDERBY
"Y" (Expressions in ORDER BY supported).
SQL_IDENTIFIER_CASE
4 (names are not case sensitive).
SQL_IDENTIFIER_QUOTE_CHAR
" " (delimited identifiers not supported).
SQL_MAX_COLUMN_NAME_LEN
18
SQL_MAX_CURSOR_NAME_LEN
18
SQL_MAX_OWNER_NAME_LEN
18
SQL_MAX_PROCEDURE_NAME_LEN
0 (procedures not supported).
SQL_MAX_QUALIFIER_NAME_LEN
0 (qualifiers not supported).
SQL_MAX_TABLE_NAME_LEN
18
SQL_MULT_RESULT_SETS
"Y" (supports multiple result sets).
SQL_MULTIPLE_ACTIVE_TXN
"Y" (supports multiple transactions)
SQL_OUTER_JOINS
"Y" (supports outer joins).
SQL_OWNER_TERM
"Authorization ID"
SQL_PROCEDURE_TERM
"" (procedures not supported).
SQL_QUALIFIER_NAME_SEPARATOR
"" (qualifiers not supported).
SQL_QUALIFIER_TERM
"" (qualifiers not supported).
SQL_SCROLL_CONCURRENCY
SQL_SCCO_LOCK
SQL_SCROLL_OPTIONS
SQLSQL_SO_MIXED
SQL_TABLE_TERM
"TABLE"
SQL_TXN_CAPABLE
2 (transactions supported for DDL and DML statements).
SQL_TXN_ISOLATION_OPTIONS
SQL_TXN_SERIALIZABLE
SQL_USER_NAME
Returns current authorization identifier
SQL_CONVERT_FUNCTIONS
SQL_FN_CVT_CONVERT
SQL_NUMERIC_FUNCTIONS
SQL_FN_NUM_ABS | SQL_FN_NUM_ACOS | SQL_FN_NUM_ASIN | SQL_FN_NUM_ATAN | SQL_FN_NUM_ATAN2 | SQL_FN_NUM_CEILING | SQL_FN_NUM_COS | SQL_FN_NUM_COT | SQL_FN_NUM_EXP | SQL_FN_NUM_FLOOR | SQL_FN_NUM_LOG | SQL_FN_NUM_MOD | SQL_FN_NUM_RAND | SQL_FN_NUM_PI | SQL_FN_NUM_SIGN | SQL_FN_NUM_SIN | SQL_FN_NUM_SQRT | SQL_FN_NUM_TAN
SQL_STRING_FUNCTIONS
SQL_FN_STR_ASCII | SQL_FN_STR_CHAR | SQL_FN_STR_CONCAT | SQL_FN_STR_INSERT | SQL_FN_STR_LEFT | SQL_FN_STR_LTRIM | SQL_FN_STR_LENGTH | SQL_FN_STR_LOCATE | SQL_FN_STR_LCASE | SQL_FN_STR_REPEAT | SQL_FN_STR_REPLACE | SQL_FN_STR_RIGHT | SQL_FN_STR_RTRIM | SQL_FN_STR_SUBSTRING | SQL_FN_STR_UCASE
SQL_SYSTEM_FUNCTIONS
SQL_FN_SYS_USERNAME | SQL_FN_SYS_DBNAME | SQL_FN_SYS_IFNULL
SQL_TIMEDATE_FUNCTIONS
SQL_FN_TD_NOW | SQL_FN_TD_CURDATE | SQL_FN_TD_DAYOFMONTH | SQL_FN_TD_DAYOFWEEK | SQL_FN_TD_DAYOFYEAR | SQL_FN_TD_MONTH | SQL_FN_TD_QUARTER | SQL_FN_TD_WEEK | SQL_FN_TD_YEAR | SQL_FN_TD_CURTIME | SQL_FN_TD_HOUR | SQL_FN_TD_MINUTE | SQL_FN_TD_SECOND
SQL_CONVERT_BIGINT
SQL_CVT_BIGINT | SQL_CVT_DECIMAL | SQL_CVT_NUMERIC | SQL_CVT_DOUBLE | SQL_CVT_FLOAT | SQL_CVT_REAL
SQL_CONVERT_BINARY
SQL_CVT_BINARY | SQL_CVT_VARBINARY | SQL_CVT_LONGVARBINARY
SQL_CONVERT_BIT
SQL_CVT_BIT | SQL_CVT_DECIMAL | SQL_CVT_DOUBLE
| SQL_CVT_FLOAT | SQL_CVT_INTEGER | SQL_CVT_NUMERIC | SQL_CVT_REAL | SQL_CVT_SMALLINT | SQL_CVT_TINYINT
SQL_CONVERT_CHAR
SQL_CVT_LONGVARCHAR | SQL_CVT_VARCHAR
SQL_CONVERT_DATE
SQL_CVT_DATE | SQL_CVT_TIMESTAMP
SQL_CONVERT_DECIMAL
SQL_CVT_DECIMAL | SQL_CVT_DOUBLE | SQL_CVT_FLOAT | SQL_CVT_NUMERIC | SQL_CVT_REAL
SQL_CONVERT_DOUBLE
SQL_CVT_DOUBLE | SQL_CVT_DECIMAL | SQL_CVT_NUMERIC
SQL_CONVERT_FLOAT
SQL_CVT_FLOAT | SQL_CVT_DOUBLE | SQL_CVT_DECIMAL | SQL_CVT_NUMERIC | SQL_CVT_REAL
SQL_CONVERT_INTEGER
SQL_CVT_DECIMAL | SQL_CVT_DOUBLE | SQL_CVT_FLOAT | SQL_CVT_INTEGER | SQL_CVT_NUMERIC | SQL_CVT_REAL
SQL_CONVERT_LONGVARBINARY
SQL_CVT_LONGVARBINARY
SQL_CONVERT_LONGVARCHAR
SQL_CVT_LONGVARCHAR
SQL_CONVERT_NUMERIC
SQL_CVT_DECIMAL | SQL_CVT_DOUBLE | SQL_CVT_FLOAT | SQL_CVT_NUMERIC | SQL_CVT_REAL
SQL_CONVERT_REAL
SQL_CVT_DOUBLE | SQL_CVT_FLOAT | SQL_CVT_DECIMAL | SQL_CVT_NUMERIC | SQL_CVT_REAL
SQL_CONVERT_SMALLINT
SQL_CVT_BIGINT | SQL_CVT_DECIMAL | SQL_CVT_DOUBLE | SQL_CVT_FLOAT | SQL_CVT_INTEGER | SQL_CVT_NUMERIC | SQL_CVT_REAL | SQL_CVT_SMALLINT
SQL_CONVERT_TIME
SQL_CVT_TIME | SQL_CVT_TIMESTAMP
SQL_CONVERT_TIMESTAMP
SQL_CVT_TIMESTAMP
SQL_CONVERT_TINYINT
SQL_CVT_DECIMAL | SQL_CVT_DOUBLE | SQL_CVT_FLOAT | SQL_CVT_INTEGER | SQL_CVT_NUMERIC | SQL_CVT_REAL | SQL_CVT_SMALLINT | SQL_CVT_TINYINT
SQL_CONVERT_VARBINARY
SQL_CVT_LONGVARBINARY | SQL_CVT_VARBINARY
SQL_CONVERT_VARCHAR
SQL_CVT_LONGVARCHAR | SQL_CVT_VARCHAR
RETURN VALUES
On success, SQL_SUCCESS is returned. If more than cbInfoValueMax bytes are required to write the result, SQL_SUCCESS_WITH_INFO is returned. If hdbc is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES>
01004
Data truncated. Not enough space in result buffer.
08003
Not connected.
22003
Numeric value could not be returned without truncation.
S1000
General error.
S1001
Memory allocation failure.
S1009
Value expected in the buffer pointed to by rgbInfoValue was invalid
S1010
There is an asynchronous operating in progress for an hstmt associated with hdbc.
S1090
cbInfoValueMax was less than 0.
S1096Invalid fInfoType.
S1T00
Timeout.
SEE ALSO

SQLGetStmtOption

NAME
SQLGetStmtOption
SHORT DESCRIPTION
Get option associated with a statement handle
SYNOPSIS 
RETCODE SQLGetStmtOption(
HSTMT hstmt,
UWORD fOption,
PTR pvParam
)
DESCRIPTION
SQLGetStmtOption returns an option value associated with a particular statement handle (hstmt). The allowable values of fOption can be found in the manual page for SQLSetStmtOption. The result value is written to the data area pointed to by pvParam.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1001
Memory allocation failure.
S1010
hstmt is involved in an incomplete asynchronously executing request.
S1092
Invalid value of fOption.
SEE ALSO
  • SQLGetConnectOption
  • SQLSetConnectOption
  • SQLSetStmtOption

SQLGetTypeInfo

NAME
SQLGetTypeInfo
SHORT DESCRIPTION
Get information about supported data types
SYNOPSIS 
RETCODE SQLGetTypeInfo(
HSTMT hstmt,
SWORD fSqlType
)
DESCRIPTION
SQLGetTypeInfo returns information about whether or not a particular type is supported. CQL++ supports all the ODBC types. The allowable values for fSqlType are listed in the manual page for ODBC parameters(2-ODBC). The type information is returned in a result set which has the following structure:
TYPE_NAME
VARCHAR(128) NOT NULL. Name of type for CQL++. The names are listed in the table which follows this structure description.
DATA_TYPE
SMALLINT NOT NULL. ODBC data type.
PRECISION
INTEGER. Maximum precision for the type.
LITERAL_PREFIX
VARCHAR(128). Single quote (') for CHAR, VARCHAR, and LONGVARCHAR, NULL for other types.
LITERAL_SUFFIX
VARCHAR(128). Single quote (') for CHAR, VARCHAR, and LONGVARCHAR, NULL for other types.
CREATE_PARAMS
VARCHAR(128). One of: "precision.scale", "max length", or NULL
NULLABLE
SMALLINT NOT NULL. Always SQL_NULLABLE for CQL++
CASE_SENSITIVE
SMALLINT NOT NULL. TRUE for character types, FALSE for numeric or date/time types.
SEARCHABLE
SMALLINT NOT NULL. SQL_UNSEARCHABLE for SQL_BIT, SQL_LONGVARCHAR, SQL_LONGVARBINARY, SQL_BINARY, and SQL_VARBINARY; SQL_SEARCHABLE for all other types.
UNSIGNED_ATTRIBUTE
SMALLINT. FALSE for numeric types, NULL for string and date/time types.
MONEY
SMALLINT NOT NULL. Always FALSE for CQL++.
AUTO_INCREMENT
SMALLINT. Always FALSE for CQL++.
LOCAL_TYPE_NAME
VARCHAR(128). Always NULL for CQL++.
RETURN VALUES
On success, SQL_SUCCESS is returned. If executed asynchronously and execution is not complete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
24000
hstmt is involved in a SELECT operation and the associated cursor has not been closed.
S1000
General error.
S1001
Memory allocation failure.
S1004
Invalid fSqlType value.
S1008
Operation canceled.
S1010
hstmt is involved in an asynchronous operation which has not completed.
S1T00
Timeout.
SEE ALSO

SQLNumResultCols

NAME
SQLNumResultCols
SHORT DESCRIPTION
Retrieve the number of columns in a result set
SYNOPSIS 
RETCODE SQLNumResultCols(
HSTMT hstmt,
SWORD FAR *pccol
)
DESCRIPTION
SQLNumResultCols returns the number of columns in a result set. This information is not available until after SQLPrepare or SQLExecDirect is called for hstmt. The number of columns is written to pccol.
RETURN VALUES
On success, SQL_SUCCESS is returned. If the statement is executing asynchronously and execution is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1010
Neither SQLPrepare nor SQLExecDirect was called for hstmt.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLColAttributes
  • SQLDescribeCol
  • SQLFetch
  • SQLGetData

SQLParamData

NAME
SQLParamData
SHORT DESCRIPTION
Supply parameter data at runtime.
SYNOPSIS 
RETCODE SQLParamData( HSTMT hstmt, PTR FAR * prgbValue )
DESCRIPTION
SQLParamData is used to fetch information about SQL_DATA_AT_EXEC parameters. Usage of SQLParamData is described in the Example of ODBC Function Usage earlier in this chapter.
RETURN VALUES
On success, if there are no more SQL_DATA_AT_EXEC parameters, SQL_SUCCESS is returned. If the current SQL_DATA_AT_EXEC parameter is not the final one for hstmt, SQL_NEED_DATA is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. If SQLParamData is executing asynchronously and execution is not complete, SQL_STILL_EXECUTING is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1010
SQLParamData not called after a call to SQLExecute or SQLExecDirect.
S1DE0
No SQL_DATA_AT_EXEC parameters.
S1T00
Timeout.
SEE ALSO
  • SQLCancel
  • SQLExecDirect
  • SQLExecute
  • SQLPutData
  • SQLSetParam

SQLPrepare

NAME
SQLPrepare
SHORT DESCRIPTION
Prepare an SQL statement for execution
SYNOPSIS 
RETCODE SQLPrepare(
HSTMT hstmt,
UCHAR FAR *szSqlStr,
SDWORD cbSqlStr
)
DESCRIPTION
SQLPrepare prepares an SQL statement string for execution. It is roughly equivalent to the ANSI DECLARE CURSOR statement.
RETURN VALUES
On success, SQL_SUCCESS is returned. If SQLPrepare is executing asynchronously and execution is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
21S01
Insert value list does not match insert column list.
21S02
CREATE VIEW statement, number of columns mismatch.
22005
Data type specified for INSERT or UPDATE cannot be converted to the required type.
24000
hstmt refers to an open cursor.
34000
The SQL statement contains a WHERE CURRENT OF cursorName clause, and the SQL engine did not find the cursor.
37000
Syntax error.
42000
User does not have required privileges.
S0001
CREATE TABLE or CREATE VIEW references table/view name which already exists.
S0002
A referenced base table does not exist.
S0011
CREATE INDEX uses index name which already exists.
S0012
DROP INDEX uses index name not found by SQL engine.
S0021
ALTER TABLE uses a column name which already exists for the table.
S0022
A column name was not found.
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1009
szSqlStrIn was a null pointer.
S1010
hstmt is associated with an asynchronously executing command which is still executing.
S1090
cbSqlStr was less than 0 and not equal to SQL_NTS.
S1T00
Timeout.
SEE ALSO
  • SQLAllocStmt
  • SQLBindCol
  • SQLCancel
  • SQLExecDirect
  • SQLExecute
  • SQLRowCount
  • SQLSetCursorName
  • SQLSetParam
  • SQLTransact

SQLPutData

NAME
SQLPutData
SHORT DESCRIPTION
Send parameter data at execution time
SYNOPSIS 
RETCODE SQLPutData(
HSTMT hstmt,
PTR rgbValue,
SDWORD cbValue
)
DESCRIPTION
SQLPutData is used to supply parameter data at run time. The use of SQLParamData and SQLPutData are described in The Example of ODBC Function Usage earlier in this chapter.
RETURN VALUES
On success, SQL_SUCCESS is returned. If SQLPutData is executing asynchronously and execution is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
22001
Supplied data is longer than maximum allowable size.
22003
Numeric value could not be converted to the target type.
22008
Date, time, or timestamp value invalid.
22026
Data sent is too short.
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1009
rgbValue was null, and cbValue was neither 0 nor SQL_NULL_DATA.
S1010
Call to SQLPutData does not follow call to either SQLParamData or SQLPutData.
S1090
rgbValue was not a null pointer and cbValue was less than 0 and not equal to SQL_NTS.
S1DE0
No SQL_DATA_AT_EXEC parameters.
S1T00
Timeout.
SEE ALSO
  • SQLCancel
  • SQLExecDirect
  • SQLExecute
  • SQLParamData
  • SQLSetParam

SQLRowCount

NAME
SQLRowCount
SHORT DESCRIPTION
Number of rows affected by UPDATE, INSERT, or DELETE
SYNOPSIS 
RETCODE SQLRowCount( HSTMT hstmt, SDWORD FAR *pcrow )
DESCRIPTION
SQLRowCount returns the number of rows affected by an UPDATE, INSERT, or DELETE statement associated with hstmt.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
S1000
General error.
S1001
Memory allocation failure.
S1010
Not called following SQLExecute or SQLExecDirect.
SEE ALSO
  • SQLExecDirect
  • SQLExecute

SQLSetConnectOption

NAME
SQLSetConnectOption
SHORT DESCRIPTION
Sets options associate with connection
SYNOPSIS 
RETCODE SQLSetConnectOption(
HDBC hdbc,
UWORD fOption,
UDWORD vParam
)
DESCRIPTION
SQLSetConnectOption is used to specify parameters about a connection. The parameter to be set is specified by fOption, and the parameter value is specified by vParam.

The following list shows the allowable values for fOption:

SQL_ACCESS_MODE
SQL_MODE_READ_ONLY or SQL_MODE_READ_WRITE.
SQL_AUTOCOMMIT
0 turns autocommit off, 1 turns autocommit on. Default is autocommit on.
SQL_LOGIN_TIMEOUT
Number of seconds to wait before giving up on a connect request.
SQL_OPT_TRACE
0 means tracing off (the default). 1 means enable tracing. If tracing is on, the driver manager writes each SQL statement to a log file. If a log file name has not been specified (see SQL_OPT_TRACEFILE), the driver manager writes to "SQL.LOG".
SQL_OPT_TRACEFILE
The name of a trace file to use is SQL_OPT_TRACE turns tracing on.
SQL_TRANSLATE_DLL
CQL++ Version 7.0 does not support data translation.
SQL_TRANSLATE_OPTION
CQL++ Version 7.0 does not support data translation.
SQL_TXN_ISOLATION
Only SQL_TXN_SERIALIZABLE is supported by CQL++ Version 8.1
RETURN VALUES
On success, SQL_SUCCESS is returned. If hdbc is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08003
Connection not open.
08S01
Communication failure.
S1000
General error.
S1001
Memory allocation failure.
S1009
Invalid value specified in vparam.
S1010
hstmt is involved in an asynchronously executing operation which is not complete.
S1092
fOption value invalid.
SEE ALSO
  • SQLGetConnectOption
  • SQLGetStmtOption
  • SQLSetStmtOption

SQLSetCursorName

NAME
SQLSetCursorName
SHORT DESCRIPTION
Associate a name with a cursor
SYNOPSIS 
RETCODE SQLSetCursorName(
HSTMT hstmt,
UCHAR FAR *szCursor,
SWORD cbCursor
)
DESCRIPTION
SQLSetCursorName is used to associate a cursor name with a cursor. It overrides the default cursor name generated by the SQL engine.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
24000
Results pending for hstmt.
3C000
Cursor already exists with name szCursor.
34000
Cursor name invalid, usually too long.
S1000
General error.
S1001
General error.
S1009
szCursor was a null pointer.
S1010
hstmt is associate with an asynchronously executing function.
S1090
cbCursor was less than 0 and was not equal to SQL_NTS.
SEE ALSO
  • SQLExecDirect
  • SQLExecute
  • SQLGetCursorName

SQLSetParam

NAME
SQLSetParam
SHORT DESCRIPTION
Specify storage for a parameter.
SYNOPSIS 
RETCODE SQLSetParam(
HSTMT hstmt,			// statement handle
UWORD ipar,				// parameter number
SWORD fCType,			// parameter type
SWORD fSqlType,			// ODBC SQL type
UDWORD cbColDef,		// precision of parameter in SQL statement
SWORD ibScale,			// the scale of the parameter in SQL statement
PTR rgbValue,			// storage location (see description)
SDWORD FAR *pcbValue	// length of data pointed to by rgbValue
)
DESCRIPTION
SQLSetParam does one of two things: Either it specifies a parameter value for use in executing an SQL statement, or it specifies that the value will be provided at execution time. The "Example of ODBC Function Usage" earlier in this chapter provides more details.

If pcbValue points to a value greater than zero, then a value is being supplied in rgbValue. If pcbValue points to SQL_NULL_DATA, a null value is supplied for the parameter. If pcbValue points to SQL_DATA_AT_EXEC, the specification of the parameter value is being delayed until execution time. If pcbValue points to SQL_DATA_AT_EXEC, then rgbValue is defined by the ODBC specification as an identifier to be supplied to the application on a call to SQLParamData. Typically this is the address of a variable, but it can be any 32 bit value.

Allowable values for fCType and fSqlType are listed in the ODBC Parameters section.

RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
07006
Type specified by fCType cannot be converted to the type specified by fSqlType.
S1000
General error.
S1001
Memory allocation failure.
S1003
fCType value invalid.
S1004
fSqlType invalid.
S1009
rgbValue and pcbValue were both null pointers.
S1010
hstmt is involved in an incomplete asynchronously executing function.
S1093
ipar less than 1 or greater than the number of parameters in the SQL statement.
S1094
ibScale value less than 0.
SEE ALSO

SQLSetStmtOption

NAME
SQLSetStmtOption
SHORT DESCRIPTION
Set statement option
SYNOPSIS 
RETCODE SQLSetStmtOption(
HSTMT hstmt,
UWORD fOption,
UDWORD vParam
)
DESCRIPTION
SQLSetStmtOption sets the option specified by fOption to the value specified by vParam. The values of fOption are:
SQL_ASYNC_ENABLE
Enables asynchronous processing for hstmt.
SQL_BIND_TYPE
Ignored by CQL++ driver.
SQL_MAX_LENGTH
If this value is specified, the driver does not return SQL_SUCCES_WITH_INFO when truncating longer data to the specified length.
SQL_NOSCAN
If TRUE, prevents driver scanning of SQL statement for escape clauses.
SQL_QUERY_TIMEOUT
Specifies a maximum amount of time to wait for an SQL statement to execute. The default is to wait forever.
SQL_MAX_ROWS
The default is to return all rows. If this parameter is set, the driver will only return this number of rows. Meaningless until the driver implements SQLExtendedFetch.
RETURN VALUES
On success, SQL_SUCCESS is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
S1000
General error.
S1001
Memory allocation failure.
S1009
Invalid vParam value for the specified fOption value.
S1010
hstmt is involved in an incomplete asynchronously executing function.
S1092
Invalid fOption value.
S1C00
Driver not capable. Returned for SQL_BIND_TYPE and SQL_MAX_ROWS.
SEE ALSO
  • SQLCancel
  • SQLGetConnectOption
  • SQLGetStmtOption
  • SQLSetConnectOption

SQLSpecialColumns

NAME
SQLSpecialColumns
SHORT DESCRIPTION
Retrieves information about special columns in a table
SYNOPSIS 
RETCODE SQLSpecialColumns(
HSTMT hstmt,					// statement handle
UWORD fColType,					// specifies type of information desired
UCHAR FAR *szTableQualifier,	// qualifier not used by CQL++
SWORD cbTableQualifier,
UCHAR FAR *szTableOwner,		// table owner
SWORD cbTableOwner,
UCHAR FAR *szTableName,			// table name
SWORD cbTableName,
UWORD fScope,					// required scope (see description)
UWORD fNullable					// controls selection of nullable columns
)
DESCRIPTION
SQLSpecialColumns returns one of two types of information. The first type is a set of columns that can be used to uniquely identify a row. fColType value SQL_BEST_ROWID selects this information, typically the columns which make up a key which does not allow duplicates. The second type, which is always empty for CQL++, is a set of columns that are automatically updated by any modification to a row. fColType value SQL_ROWVER selects this information.

Parameter fScope specifies the period for which the information is being requested. That is, for how long can the application assume that the data returned by SQLSpecialColumns is valid? There are three allowable values for fScope: SQL_SCOPE_CURROW, SQL_SCOPE_TRANSACTION, and SQL_SCOPE_SESSION. The information returned by the CQL++ driver is always valid for the transaction; the same information is returned for fScope values SQL_SCOPE_CURROW and SQL_SCOPE_TRANSACTION. If the application specifies SQL_SCOPE_SESSION, an error is returned.

Parameter fNullable is used to specify whether or not the columns returned can allow null values. If columns which allow null values are to be rejected, fNullable is set to SQL_NO_NULLS. If columns which allow null values are to be accepted, fNullable is set to SQL_NULLABLE.

SQLSpecialColumns returns a result set with the following structure:

SCOPE
SMALLINT NOT NULL. SQL_SCOPE_CURROW, SQL_SCOPE_TRANSACTION, SQL_SCOPE_SESSION
COLUMN_NAME
VARCHAR 128 NOT NULL. Column name
DATA_TYPE
SMALLINT NOT NULL. ODBC SQL data type.
TYPE_NAME
VARCHAR(128) NOT NULL. CQL++ type name.
PRECISION
INTEGER. The precision of the column, or NULL for columns which do not have a precision attribute.
LENGTH
INTEGER. Length of column. For VARCHAR columns, value is the maximum length.
SCALE
SMALLINT. Scale of column or NULL for columns which do not have a scale attribute.
RETURN VALUES
If successfully completed, SQL_SUCCESS is returned. If SQLSpecialColumns is executing asynchronously, and execution is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
24000
Results pending for hstmt.
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1010
hstmt is involved in an incomplete asynchronously executing function.
S1090
One of the length arguments was less than 0 and not equal to SQL_NTS, or one of the length arguments exceeded the maximum length.
S1097
Invalid fColType value.
S1098
Invalid fScope value.
S1099
Invalid fNullable value.
S1C00
Table qualifier specified. CQL++ does not support table qualifiers.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLColumns
  • SQLFetch

SQLStatistics

NAME
SQLStatistics
SHORT DESCRIPTION
Return statistics about a base table
SYNOPSIS 
RETCODE SQLStatistics(
HSTMT hstmt,
UCHAR FAR *szTableQualifier,	// qualifier not used by CQL++
SWORD cbTableQualifier,
UCHAR FAR *szTableOwner,		// table owner
SWORD cbTableOwner,
UCHAR FAR *szTableName,			// table name
SWORD cbTableName,
UWORD fUnique,
UWORD fAccuracy
)
DESCRIPTION
SQLStatistics is used to retrieve a data set describing information about the indices associated with a base table. Parameter fUnique specifies whether to return information about all indices (value SQL_INDEX_ALL) or to return information only about indices which do not allow duplicates (value SQL_INDEX_UNIQUE). Parameter fAccuracy specifies the required accuracy of the CARDINALITY and PAGES columns of the result set. If fAccuracy is set to SQL_ENSURE, the values are always retrieved and are guaranteed to be accurate. If fAccuracy is set to SQL_QUICK, the values may not be retrieved, and their accuracy is not guaranteed. For CQL++, the information is always readily available, and the result set is identical regardless of the value of fAccuracy.

The result set also includes a row which describes the table itself rather than one of its indices. The result set column TYPE specifies the type of row being returned.

The result set has the following structure:

TABLE_QUALIFIER
VARCHAR(128). Always NULL.
TABLE_OWNER
VARCHAR(128). The authorization identifier.
TABLE_NAME
VARCHAR(128) NOT NULL. Table name.
NON_UNIQUE
SMALLINT. TRUE if index allows duplicates. FALSE if it does not allow duplicates.
INDEX_QUALIFIER
VARCHAR(128). Always NULL.
INDEX_NAME
VARCHAR(128). The index name. NULL if TYPE is SQL_TABLE_STAT.
TYPE
SMALLINT NOT NULL. Either SQL_TABLE_STAT or SQL_INDEX_OTHER.
SEQ_IN_INDEX
SMALLINT. The column number within the index. The first column is 1. NULL if TYPE is SQL_TABLE_STAT.
COLUMN_NAME
VARCHAR(128). Column name or NULL if TYPE is SQL_TABLE_STAT.
COLLATION
CHAR(1). "A". ALL CQL++ columns colate in ascending order.
CARDINALITY
INTEGER. The number of rows in the table if TYPE is SQL_TABLE_STAT. The number of entries in the index if TYPE is not SQL_TABLE_STAT.
PAGES
INTEGER. Number of pages used for table or index.
RETURN VALUES
On success, SQL_SUCCESS is returned. If SQLStatistics is executing asynchronously and execution is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
24000
Results pending for hstmt.
S1000
General error.
S1001
Memory allocatino failure.
S1008
Operation canceled.
S1010
hstmt is involved with an asynchronously executing function.
S1090
Length value was less than zero and not equal to SQL_NTS, or, length value was greater than the maximum allowable value.
S1100
Invalid fUnique value.
S1101
Invalid fAccuracy value.
S1C00
A table or index qualifier name was specified.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLFetch

SQLTables

NAME
SQLTables
SHORT DESCRIPTION
Retrieves table information
SYNOPSIS 
RETCODE SQLTables(
HSTMT hstmt,
UCHAR FAR *szTableQualifier,	// qualifier not used by CQL++
SWORD cbTableQualifier,
UCHAR FAR *szTableOwner,		// table owner
SWORD cbTableOwner,
UCHAR FAR *szTableName,			// table name
SWORD cbTableName,
UCHAR FAR *szTableType,			// table type
SWORD cbTableType
)
DESCRIPTION
SQLTables returns a result set describing the tables in a data source. szTableOwner and szTableName may include wild cards in the style used for the SQL LIKE operator. If szTableType is null, information is returned about all columns. If szTableType is not null, it is a list of one or more of the following values:
  • TABLE
  • VIEW
  • SYSTEM TABLE
  • ALIAS
  • SYNONYM

For CQL++ only TABLE, VIEW, and SYSTEM TABLE types exist in the SQL engine. The szTableType string requires single quotes around the elements of the list. For example: " 'TABLE', 'VIEW' "

The result set has the following structure:

TABLE_QUALIFIER
VARCHAR(128). Always NULL
TABLE_OWNER
VARCHAR(128). Authorization ID
TABLE_NAME
VARCHAR(128). Table name.
TABLE_TYPE
VARCHAR(128). One of: ``TABLE", "VIEW", or "SYSTEM TABLE".
REMARKS
VARCHAR(254). Always NULL
RETURN VALUES
On success, SQL_SUCCESS is returned. If SQLTables is executed asynchronously and execution is incomplete, SQL_STILL_EXECUTING is returned. If hstmt is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08S01
Communication failure.
24000
Results pending for hstmt.
S1000
General error.
S1001
Memory allocation failure.
S1008
Operation canceled.
S1010
hstmt involved with asynchronously executing function.
S1090
Length argument invalid. Either less than 0 and not equal to SQL_NTS, or too large.
S1102
Invalid fTableType value.
S1C00
Table qualifier specified.
S1T00
Timeout.
SEE ALSO
  • SQLBindCol
  • SQLCancel
  • SQLColumns
  • SQLFetch
  • SQLStatistics

SQLTransact

NAME
SQLTransact
SHORT DESCRIPTION
Commit or rollback a transaction
SYNOPSIS 
RETCODE SQLTransact(
HENV henv,		//  environment handle
HDBC hdbc,		//  connection handle
UWORD fType		//  operation code
)
DESCRIPTION
SQLTransact is used to commit or rollback a transaction. Parameter fType specifies the desired operation. To commit a transaction, fType is set to SQL_COMMIT. To rollback a transaction, fType is set to SQL_ROLLBACK.
RETURN VALUES
On success, SQL_SUCCESS is returned. If either henv or hdbc is invalid, SQL_INVALID_HANDLE is returned. On any other error, SQL_ERROR is returned.
SQLSTATE VALUES
08003
Connection not open.
08007
Connection failed during transaction.
S1000
General error.
S1001
Memory allocation failure.
S1010
There exists an hstmt associated with hdbc which is involved in an incomplete asynchronously executing function.
S1012
Invalid fType value.
SEE ALSO
  • SQLGetInfo
  • SQLFreeStmt