Previous Page TOC Index Next Page



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:

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:

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

Previous Page TOC Index Next Page

Copyright © 1992-1997 Solid Information Technology Ltd All rights reserved.