Function Reference

FUNCTION REFERENCE

Function Descriptions

The following pages describe each function in alphabetic order. Each function is defined as a C programming language function. Descriptions include the following:

Purpose

ODBC version

Conformance level

Syntax

Arguments

Return values

Diagnostics

Comments about usage and implementation

Code example

References to related functions

Error handling is described in the SQLError function description. The text associated with SQLSTATE values is included to provide a description of the condition, but is not intended to prescribe specific text.

Arguments

All function arguments use a naming convention of the following form:

[[prefix]...]tag[qualifier][suffix]

Optional elements are enclosed in square brackets ([]). The following prefixes are used:

Prefix	Description
c	Count of
h	Handle of
I	Index of
p	Pointer to
rg	Range (array) of

The following tags are used:

Tag	Description
b	Byte
col	Column (of a result set)
dbc	Database connection
env	Environment
f	Flag (enumerated type)
par	Parameter (of an SQL statement)
row	Row (of a result set)
stmt	Statement
sz	Character string (array of characters, terminated by zero)
v	Value of unspecified type

Prefixes and tags combine to correspond roughly to the ODBC C types listed below. Flags (f) and byte counts (cb) do not distinguish between SWORD, UWORD, SDWORD, and UDWORD.

Combined	Prefix	Tag	ODBC C Type(s)	Description
cb	c	b	SWORD, SDWORD, UDWORD	Count of bytes
crow	c	row	SDWORD, UDWORD, UWORD	Count of rows
f	–	f	SWORD, UWORD	Flag
hdbc	h	dbc	HDBC	Connection handle
henv	h	env	HENV	Environment handle
hstmt	h	stmt	HSTMT	Statement handle
hwnd	h	wnd	HWND	Window handle
ib	i	b	SWORD	Byte index

icol	i	col	UWORD	Column index
ipar	i	par	UWORD	Parameter index
irow	i	row	SDWORD, UWORD	Row index
pcb	pc	b	SWORD FAR , SDWORD FAR , UDWORD FAR *	Pointer to byte count
pccol	pc	col	SWORD FAR *	Pointer to column count
pcpar	pc	par	SWORD FAR *	Pointer to parameter count
pcrow	pc	row	SDWORD FAR , UDWORD FAR	Pointer to row count
pf	p	f	SWORD, SDWORD, UWORD	Pointer to flag
phdbc	ph	dbc	HDBC FAR *	Pointer to connection handle
phenv	ph	env	HENV FAR *	Pointer to environment handle
phstmt	ph	stmt	HSTMT FAR *	Pointer to statement handle
pib	pi	b	SWORD FAR *	Pointer to byte index
pirow	pi	row	UDWORD FAR *	Pointer to row index
prgb	prg	b	PTR FAR *	Pointer to range (array) of bytes
pv	p	v	PTR	Pointer to value of unspecified type
rgb	rg	b	PTR	Range (array) of bytes
rgf	rg	f	UWORD FAR *	Range (array) of flags
sz	–	sz	UCHAR FAR *	String, zero terminated
v	–	v	UDWORD	Value of unspecified type

Qualifiers are used to distinguish specific variables of the same type. Qualifiers consist of the concatenation of one or more capitalized English words or abbreviations.

ODBC defines one value for the suffix Max, which denotes that the variable represents the largest value of its type for a given situation.

For example, the argument cbErrorMsgMax contains the largest possible byte count for an error message; in this case, the argument corresponds to the size in bytes of the argument szErrorMsg, a character string buffer. The argument pcbErrorMsg is a pointer to the count of bytes available to return in the argument szErrorMsg, not including the null termination character.

SOLID SQL API Include Files

The files CLI0CORE.H, CLI0DEFS.H, CLI0ENV.H and CLI0EXT1.H contain function prototypes for all of the SOLID SQL API functions. They also contain all type definitions and #define names used by SOLID SQL API.

ODBC Include Files

The files SQL.H and SQLEXT.H contain function prototypes for all of the ODBC functions. They also contain all type definitions and #define names used by ODBC.

Diagnostics

The diagnostics provided with each function list the SQLSTATEs that may be returned for the function by the Driver Manager or a driver. Drivers can, however, return additional SQLSTATEs arising out of implementation-specific situations.

The character string value returned for an SQLSTATE consists of a two-character class value followed by a three-character subclass value. A class value of "01" indicates a warning and is accompanied by a return code of SQL_SUCCESS_WITH_INFO. Class values other than "01", except for the class "IM", indicate an error and are accompanied by a return code of SQL_ERROR. The class "IM" is specific to warnings and errors that derive from the implementation of ODBC itself. The subclass value "000" in any class is for implementation-defined conditions within the given class. The assignment of class and subclass values is defined by ANSI SQL-92.

Tables and Views

In ODBC functions, tables and views are interchangeable. The term table is used for both tables and views, except where view is used explicitly.

Catalog Functions

ODBC supports a set of functions that return information about the data source’s system tables or catalog. These are sometimes referred to collectively as the catalog functions. For more information about catalog functions, see "Retrieving Information About the Data Source’s Catalog" in Chapter 6.

The catalog functions are:

SQLColumnPrivileges

SQLColumns

SQLForeignKeys

SQLPrimaryKeys

SQLProcedureColumns

SQLProcedures

SQLSpecialColumns

SQLStatistics

SQLTablePrivileges

SQLTables

Search Pattern Arguments

Each catalog function returns information in the form of a result set. The information returned by a function may be constrained by a search pattern passed as an argument to that function. These search patterns can contain the metacharacters underscore (_) and percent (%) and a driver-defined escape character as follows:

The underscore character represents any single character.

The percent character represents any sequence of zero or more characters.

The escape character permits the underscore and percent metacharacters to be used as literal characters in search patterns. To use a metacharacter as a literal character in the search pattern, precede it with the escape character. To use the escape character as a literal character in the search pattern, include it twice. To obtain the escape character for a driver, an application must call SQLGetInfo with the SQL_SEARCH_PATTERN_ESCAPE option.

All other characters represent themselves.

For example, if the search pattern for a table name is "%A%", the function will return all tables with names that contain the character "A". If the search pattern for a table name is "B__" ("B" followed by two underscores), the function will return all tables with names that are three characters long and start with the character "B". If the search pattern for a table name is "%", the function will return all tables.

Suppose the search pattern escape character for a driver is a backslash (\). If the search pattern for a table name is "ABC\%", the function will return the table named "ABC%." If the search pattern for a table name is " \\%", the function will return all tables with names that start with a backslash. Failing to precede a metacharacter used as a literal with an escape character may return more results than expected. For example, if a table identifier, "MY_TABLE" was returned as the result of a call to SQLTables and an application wanted to retrieve a list of columns for "MY_TABLE" using SQLColumns, SQLColumns would return all of the tables that matched MY_TABLE, such as MY_TABLE, MY1TABLE, MY2TABLE, and so on, unless the escape character precedes the underscore.

Note A zero-length search pattern matches the empty string. A search pattern argument that is a null pointer means the search will not be constrained for that argument. (A null pointer and a search string of "%" should return the same values.)