Previous Page TOC Index Next Page



SQLAllocConnect (ODBC 1.0, Core)

SQLAllocConnect allocates memory for a connection handle within the environment identified by henv.

Syntax

RETCODE SQLAllocConnect(henv, phdbc)

The SQLAllocConnect function accepts the following arguments.

Type

Argument

Use

Description

HENV

henv

Input

Environment handle.

HDBC FAR *

phdbc

Output

Pointer to storage for the connection handle.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

If SQLAllocConnect returns SQL_ERROR, it will set the hdbc referenced by phdbc to SQL_NULL_HDBC. To obtain additional information, the application can call SQLError with the specified henv and with hdbc and hstmt set to SQL_NULL_HDBC and SQL_NULL_HSTMT, respectively.

Diagnostics

When SQLAllocConnect returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLAllocConnect and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATE

Error

Description

01000

General warning

Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)

S1000

General error

An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause.

S1001

Memory allocation failure

(DM) The Driver Manager was unable to allocate memory for the connection handle.

The driver was unable to allocate memory for the connection handle.

S1009

Invalid argument value

(DM) The argument phdbc was a null pointer.

Comments

A connection handle references information such as the valid statement handles on the connection and whether a transaction is currently open. To request a connection handle, an application passes the address of an hdbc to SQLAllocConnect. The driver allocates memory for the connection information and stores the value of the associated handle in the hdbc. On operating systems that support multiple threads, applications can use the same hdbc on different threads and drivers must therefore support safe, multithreaded access to this information. The application passes the hdbc value in all subsequent calls that require an hdbc.

The Driver Manager processes the SQLAllocConnect function and calls the driver’s SQLAllocConnect function when the application calls SQLConnect, SQLBrowseConnect, or SQLDriverConnect. (For more information, see the description of the SQLConnect function.)

If the application calls SQLAllocConnect with a pointer to a valid hdbc, the driver overwrites the hdbc without regard to its previous contents.

Code Example

See SQLBrowseConnect and SQLConnect.

Related Functions

For information about

See

Connecting to a data source

SQLConnect

Freeing a connection handle

SQLFreeConnect

SQLAllocEnv (ODBC 1.0, Core)

SQLAllocEnv allocates memory for an environment handle and initializes the ODBC call level interface for use by an application. An application must call SQLAllocEnv prior to calling any other ODBC function.

Syntax

RETCODE SQLAllocEnv(phenv)

The SQLAllocEnv function accepts the following argument.

Type

Argument

Use

Description

HENV FAR *

phenv

Output

Pointer to storage for the environment handle.

Returns

SQL_SUCCESS or SQL_ERROR.

If SQLAllocEnv returns SQL_ERROR, it will set the henv referenced by phenv to SQL_NULL_HENV. In this case, the application can assume that the error was a memory allocation error.

Diagnostics

A driver cannot return SQLSTATE values directly after the call to SQLAllocEnv, since no valid handle will exist with which to call SQLError.

There are two levels of SQLAllocEnv functions, one within the Driver Manager and one within each driver. The Driver Manager does not call the driver-level function until the application calls SQLConnect, SQLBrowseConnect, or SQLDriverConnect. If an error occurs in the driver-level SQLAllocEnv function, then the Driver Manager – level SQLConnect, SQLBrowseConnect, or SQLDriverConnect function returns SQL_ERROR. A subsequent call to SQLError with henv, SQL_NULL_HDBC, and SQL_NULL_HSTMT returns SQLSTATE IM004 (Driver’s SQLAllocEnv failed), followed by one of the following errors from the driver:

For additional information about the flow of function calls between the Driver Manager and a driver, see the SQLConnect function description.

Comments

An environment handle references global information such as valid connection handles and active connection handles. To request an environment handle, an application passes the address of an henv to SQLAllocEnv. The driver allocates memory for the environment information and stores the value of the associated handle in the henv. On operating systems that support multiple threads, applications can use the same henv on different threads and drivers must therefore support safe, multithreaded access to this information. The application passes the henv value in all subsequent calls that require an henv.

There should never be more than one henv allocated at one time and the application should not call SQLAllocEnv when there is a current valid henv. If the application calls SQLAllocEnv with a pointer to a valid henv, the driver overwrites the henv without regard to its previous contents.

When the Driver Manager processes the SQLAllocEnv function, it checks the Trace keyword in the [ODBC] section of the ODBC.INI file or the ODBC subkey in the registry. If it is set to 1, the Driver Manager enables tracing for all applications on Windows 3.1 or for the current application on Windows NT and Windows 95.

Code Example

See SQLBrowseConnect and SQLConnect.

Related Functions

For information about

See

Allocating a connection handle

SQLAllocConnect

Connecting to a data source

SQLConnect

Freeing an environment handle

SQLFreeEnv

SQLAllocStmt (ODBC 1.0, Core)

SQLAllocStmt allocates memory for a statement handle and associates the statement handle with the connection specified by hdbc.

An application must call SQLAllocStmt prior to submitting SQL statements.

Syntax

RETCODE SQLAllocStmt(hdbc, phstmt)

The SQLAllocStmt function accepts the following arguments.

Type

Argument

Use

Description

HDBC

hdbc

Input

Connection handle.

HSTMT FAR *

phstmt

Output

Pointer to storage for the statement handle.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE, or SQL_ERROR.

If SQLAllocStmt returns SQL_ERROR, it will set the hstmt referenced by phstmt to SQL_NULL_HSTMT. The application can then obtain additional information by calling SQLError with the hdbc and SQL_NULL_HSTMT.

Diagnostics

When SQLAllocStmt returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLAllocStmt and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATE

Error

Description

01000

General warning

Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)

08003

Connection not open

(DM) The connection specified by the hdbc argument was not open. The connection process must be completed successfully (and the connection must be open) for the driver to allocate an hstmt.

IM001

Driver does not support this function

(DM) The driver associated with the hdbc does not support the function.

S1000

General error

An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause.

S1001

Memory allocation failure

(DM) The Driver Manager was unable to allocate memory for the statement handle.

The driver was unable to allocate memory for the statement handle.

S1009

Invalid argument value

(DM) The argument phstmt was a null pointer.

Comments

A statement handle references statement information, such as network information, SQLSTATE values and error messages, cursor name, number of result set columns, and status information for SQL statement processing.

To request a statement handle, an application connects to a data source and then passes the address of an hstmt to SQLAllocStmt. The driver allocates memory for the statement information and stores the value of the associated handle in the hstmt. On operating systems that support multiple threads, applications can use the same hstmt on different threads and drivers must therefore support safe, multithreaded access to this information. The application passes the hstmt value in all subsequent calls that require an hstmt.

If the application calls SQLAllocStmt with a pointer to a valid hstmt, the driver overwrites the hstmt without regard to its previous contents.

Code Example

See SQLBrowseConnect, SQLConnect, and SQLSetCursorName.

Related Functions

For information about

See

Executing an SQL statement

SQLExecDirect

Executing a prepared SQL statement

SQLExecute

Freeing a statement handle

SQLFreeStmt

Preparing a statement for execution

SQLPrepare

SQLBindCol (ODBC 1.0, Core)

SQLBindCol assigns the storage and data type for a column in a result set, including:

Syntax

RETCODE SQLBindCol(hstmt, icol, fCType, rgbValue, cbValueMax, pcbValue)

The SQLBindCol function accepts the following arguments.

Type

Argument

Use

Description

HSTMT

hstmt

Input

Statement handle.

UWORD

icol

Input

Column number of result data, ordered sequentially left to right, starting at 1. A column number of 0 is used to retrieve a bookmark for the row.

SWORD

fCType

Input

The C data type of the result data. This must be one of the following values:

SQL_C_BINARY
SQL_C_BIT
SQL_C_BOOKMARK
SQL_C_CHAR
SQL_C_DATE
SQL_C_DEFAULT
SQL_C_DOUBLE
SQL_C_FLOAT
SQL_C_SLONG
SQL_C_SSHORT
SQL_C_STINYINT
SQL_C_TIME
SQL_C_TIMESTAMP
SQL_C_ULONG
SQL_C_USHORT
SQL_C_UTINYINT

SQL_C_DEFAULT specifies that data be transferred to its default C data type.

Note Drivers must also support the following values of fCType from ODBC 1.0. Applications must use these values, rather than the ODBC 2.0 values, when calling an ODBC 1.0 driver:

SQL_C_LONG

SQL_C_SHORT,

SQL_C_TINYINT

For more information, see "ODBC 1.0 C Data Types" in Appendix D, "Data Types."

For information about how data is converted, see "Converting Data from SQL to C Data Types" in Appendix D, "Data Types."

PTR

rgbValue

Input

Pointer to storage for the data. If rgbValue is a null pointer, the driver unbinds the column. (To unbind all columns, an application calls SQLFreeStmt with the SQL_UNBIND option.)

SDWORD

cbValueMax

Input

Maximum length of the rgbValue buffer. For character data, rgbValue must also include space for the null-termination byte. For more information about length, see "Precision, Scale, Length, and Display Size" in Appendix D, "Data Types."

SDWORD FAR *

pcbValue

Input

SQL_NULL_DATA or the number of bytes (excluding the null termination byte for character data) available to return in rgbValue prior to calling SQLExtendedFetch or SQLFetch, or SQL_NO_TOTAL if the number of available bytes cannot be determined.

For character data, if the number of bytes available to return is SQL_NO_TOTAL or is greater than or equal to cbValueMax, the data in rgbValue is truncated to cbValueMax – 1 bytes and is null-terminated by the driver.

For binary data, if the number of bytes available to return is SQL_NO_TOTAL or is greater than cbValueMax, the data in rgbValue is truncated to cbValueMax bytes.

For all other data types, the value of cbValueMax is ignored and the driver assumes the size of rgbValue is the size of the C data type specified with fCType.

For more information about the value returned in pcbValue for each fCType, see "Converting Data from SQL to C Data Types" in Appendix D, "Data Types."

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLBindCol returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLBindCol and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATE

Error

Description

01000

General warning

Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)

IM001

Driver does not support this function

(DM) The driver associated with the hstmt does not support the function.

S1000

General error

An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause.

S1001

Memory allocation failure

The driver was unable to allocate memory required to support execution or completion of the function.

S1002

Invalid column number

The value specified for the argument icol exceeded the maximum number of columns supported by the data source.

S1003

Program type out of range

(DM) The argument fCType was not a valid data type or SQL_C_DEFAULT.

The argument icol was 0 and the argument fCType was not SQL_C_BOOKMARK.

S1010

Function sequence error

(DM) An asynchronously executing function was called for the hstmt and was still executing when this function was called.

(DM) SQLExecute, SQLExecDirect, or SQLSetPos was called for the hstmt and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.

S1090

Invalid string or buffer length

(DM) The value specified for the argument cbValueMax was less than 0.

S1C00

Driver not capable

The driver does not support the data type specified in the argument fCType.

The argument icol was 0 and the driver does not support bookmarks.

Comments

The ODBC interface provides two ways to retrieve a column of data:

An application may choose to bind every column with SQLBindCol, to do no binding and retrieve data only with SQLGetData, or to use a combination of the two. However, unless the driver provides extended functionality, SQLGetData can only be used to retrieve data from columns that occur after the last bound column.

An application calls SQLBindCol to pass the pointer to the storage buffer for a column of data to the driver and to specify how or if the data will be converted. It is the application’s responsibility to allocate enough storage for the data. If the buffer will contain variable length data, the application must allocate as much storage as the maximum length of the bound column or the data may be truncated. For a list of valid data conversion types, see "Converting Data from SQL to C Data Types" in Appendix D, "Data Types."

At fetch time, the driver processes the data for each bound column according to the arguments specified in SQLBindCol. First, it converts the data according to the argument fCType. Next, it fills the buffer pointed to by rgbValue. Finally, it stores the available number of bytes in pcbValue; this is the number of bytes available prior to calling SQLFetch or SQLExtendedFetch.


Note The SQL_MAX_LENGTH statement option is intended to reduce network traffic and may not be supported by all drivers. To guarantee that data is truncated, an application should allocate a buffer of the desired size and specify this size in the cbValueMax argument.

When an application uses SQLExtendedFetch to retrieve more than one row of data, it only needs to call SQLBindCol once for each column of the result set (just as when it binds a column in order to retrieve a single row of data with SQLFetch). The SQLExtendedFetch function coordinates the placement of each row of data into subsequent locations in the rowset buffers. For additional information about binding rowset buffers, see the "Comments" topic for SQLExtendedFetch.

An application can call SQLBindCol to bind a column to a new storage location, regardless of whether data has already been fetched. The new binding replaces the old binding. Note that the new binding does not apply to data already fetched; the next time data is fetched, the data will be placed in the new storage location.

To unbind a single bound column, an application calls SQLBindCol and specifies a null pointer for rgbValue; if rgbValue is a null pointer and the column is not bound, SQLBindCol returns SQL_SUCCESS. To unbind all bound columns, an application calls SQLFreeStmt with the SQL_UNBIND option.

Code Example

In the following example, an application executes a SELECT statement to return a result set of the employee names, ages, and birthdays, which is sorted by birthday. It then calls SQLBindCol to bind the columns of data to local storage locations. Finally, the application fetches each row of data with SQLFetch and prints each employee’s name, age, and birthday.

For more code examples, see SQLColumns, SQLExtendedFetch, and SQLSetPos.

#define NAME_LEN 30
#define BDAY_LEN 11
UCHAR  szName[NAME_LEN], szBirthday[BDAY_LEN];
SWORD  sAge;
SDWORD cbName, cbAge, cbBirthday;
retcode = SQLExecDirect(hstmt,

"SELECT NAME, AGE, BIRTHDAY FROM EMPLOYEE ORDER BY 3, 2, 1", SQL_NTS); if (retcode == SQL_SUCCESS) { /* Bind columns 1, 2, and 3 */ SQLBindCol(hstmt, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName); SQLBindCol(hstmt, 2, SQL_C_SSHORT, &sAge, 0, &cbAge); SQLBindCol(hstmt, 3, SQL_C_CHAR, szBirthday, BDAY_LEN, &cbBirthday); /* Fetch and print each row of data. On */ /* an error, display a message and exit. */ while (TRUE) { retcode = SQLFetch(hstmt); if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) { show_error(); } if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){ fprintf(out, "%-*s %-2d %*s", NAME_LEN-1, szName,
sAge, BDAY_LEN-1, szBirthday); } else { break; } } }

Related Functions

For information about

See

Returning information about a column in a result set

SQLDescribeCol

Fetching a block of data or scrolling through a result set

SQLExtendedFetch (extension)

Fetching a row of data

SQLFetch

Freeing a statement handle

SQLFreeStmt

Fetching part or all of a column of data

SQLGetData (extension)

Returning the number of result set columns

SQLNumResultCols

SQLBindParameter (ODBC 2.0, Level 1)

SQLBindParameter binds a buffer to a parameter marker in an SQL statement.


Note This function replaces the ODBC 1.0 function SQLSetParam. For more information, see "Comments."

Syntax

RETCODE SQLBindParameter(hstmt, ipar, fParamType, fCType, fSqlType, cbColDef, ibScale, rgbValue, cbValueMax, pcbValue)

The SQLBindParameter function accepts the following arguments.

Type

Argument

Use

Description

HSTMT

hstmt

Input

Statement handle.

UWORD

ipar

Input

Parameter number, ordered sequentially left to right, starting at 1.

SWORD

fParamType

Input

The type of the parameter. For more information, see "fParamType Argument" in "Comments."

SWORD

fCType

Input

The C data type of the parameter. For more information, see "fCType Argument" in "Comments."

SWORD

fSqlType

Input

The SQL data type of the parameter. For more information, see "fSqlType Argument" in "Comments."

UDWORD

cbColDef

Input

The precision of the column or expression of the corresponding parameter marker. For more information, see "cbColDef Argument" in "Comments."

SWORD

ibScale

Input

The scale of the column or expression of the corresponding parameter marker. For further information concerning scale, see "Precision, Scale, Length, and Display Size," in Appendix D, "Data Types."

PTR

rgbValue

Input/
Output

A pointer to a buffer for the parameter’s data. For more information, see "rgbValue Argument" in "Comments."

SDWORD

cbValueMax

Input

Maximum length of the rgbValue buffer. For more information, see "cbValueMax Argument" in "Comments."

SDWORD FAR *

pcbValue

Input/
Output

A pointer to a buffer for the parameter’s length. For more information, see "pcbValue Argument" in "Comments."

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLBindParameter returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLBindParameter and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATE

Error

Description

01000

General warning

Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)

07006

Restricted data type attribute violation

The data value identified by the fCType argument cannot be converted to the data type identified by the fSqlType argument.

IM001

Driver does not support this function

(DM) The driver associated with the hstmt does not support the function.

S1000

General error

An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause.

S1001

Memory allocation failure

The driver was unable to allocate memory required to support execution or completion of the function.

S1003

Program type out of range

(DM) The value specified by the argument fCType was not a valid data type or SQL_C_DEFAULT.

S1004

SQL data type out of range

(DM) The value specified for the argument fSqlType was in the block of numbers reserved for ODBC SQL data type indicators but was not a valid ODBC SQL data type indicator.

S1009

Invalid argument value

(DM) The argument rgbValue was a null pointer, the argument pcbValue was a null pointer, and the argument fParamType was not SQL_PARAM_OUTPUT.

S1010

Function sequence error

(DM) An asynchronously executing function was called for the hstmt and was still executing when this function was called.

(DM) SQLExecute, SQLExecDirect, or SQLSetPos was called for the hstmt and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.

S1090

Invalid string or buffer length

(DM) The value specified for the argument cbValueMax was less than 0.

S1093

Invalid parameter number

(DM) The value specified for the argument ipar was less than 1.

The value specified for the argument ipar was greater than the maximum number of parameters supported by the data source.

S1094

Invalid scale value

The value specified for the argument ibScale was outside the range of values supported by the data source for a column of the SQL data type specified by the fSqlType argument.

S1104

Invalid precision value

The value specified for the argument cbColDef was outside the range of values supported by the data source for a column of the SQL data type specified by the fSqlType argument.

S1105

Invalid parameter type

(DM) The value specified for the argument fParamType was invalid (see "Comments").

The value specified for the argument fParamType was SQL_PARAM_OUTPUT and the parameter did not mark a return value from a procedure or a procedure parameter.

The value specified for the argument fParamType was SQL_PARAM_INPUT and the parameter marked the return value from a procedure.

S1C00

Driver not capable

The driver or data source does not support the conversion specified by the combination of the value specified for the argument fCType and the driver-specific value specified for the argument fSqlType.

The value specified for the argument fSqlType was a valid ODBC SQL data type indicator for the version of ODBC supported by the driver, but was not supported by the driver or data source.

The value specified for the argument fSqlType was in the range of numbers reserved for driver-specific SQL data type indicators, but was not supported by the driver or data source.

Comments

An application calls SQLBindParameter to bind each parameter marker in an SQL statement. Bindings remain in effect until the application calls SQLBindParameter again or until the application calls SQLFreeStmt with the SQL_DROP or SQL_RESET_PARAMS option.

For more information concerning parameter data types and parameter markers, see "Parameter Data Types" and "Parameter Markers" in Appendix C, "SQL Grammar."

fParamType Argument

The fParamType argument specifies the type of the parameter. All parameters in SQL statements that do not call procedures, such as INSERT statements, are input parameters. Parameters in procedure calls can be input, input/output, or output parameters. (An application calls SQLProcedureColumns to determine the type of a parameter in a procedure call; parameters in procedure calls whose type cannot be determined are assumed to be input parameters.)

The fParamType argument is one of the following values:


Note When an ODBC 1.0 application calls SQLSetParam in an ODBC 2.0 driver, the Driver Manager converts this to a call to SQLBindParameter in which the fParamType argument is set to SQL_PARAM_INPUT_OUTPUT.

fCType Argument

The C data type of the parameter. This must be one of the following values:

SQL_C_BINARY

SQL_C_BIT

SQL_C_CHAR

SQL_C_DATE

SQL_C_DEFAULT

SQL_C_DOUBLE

SQL_C_FLOAT

SQL_C_SLONG

SQL_C_SSHORT

SQL_C_STINYINT

SQL_C_TIME

SQL_C_TIMESTAMP

SQL_C_ULONG

SQL_C_USHORT

SQL_C_UTINYINT

SQL_C_DEFAULT specifies that the parameter value be transferred from the default C data type for the SQL data type specified with fSqlType.

For more information, see "Default C Data Types" and "Converting Data from C to SQL Data Types" and "Converting Data from SQL to C Data Types" in Appendix D, "Data Types."


Note Drivers must also support the following values of fCType from ODBC 1.0. Applications must use these values, instead of the ODBC 2.0 values, when calling an ODBC 1.0 driver:

SQL_C_LONG
SQL_C_SHORT
SQL_C_TINYINT

For more information, see "ODBC 1.0 C Data Types" in Appendix D, "Data Types."

fSqlType Argument

This must be one of the following values:

SQL_BIGINT

SQL_BINARY

SQL_BIT

SQL_CHAR

SQL_DATE

SQL_DECIMAL

SQL_DOUBLE

SQL_FLOAT

SQL_INTEGER

SQL_LONGVARBINARY

SQL_LONGVARCHAR

SQL_NUMERIC

SQL_REAL

SQL_SMALLINT

SQL_TIME

SQL_TIMESTAMP

SQL_TINYINT

SQL_VARBINARY

SQL_VARCHAR

or a driver-specific value. Values greater than SQL_TYPE_DRIVER_START are reserved by ODBC; values less than or equal to SQL_TYPE_DRIVER_START are driver-specific.

For information about how data is converted, see "Converting Data from C to SQL Data Types" and "Converting Data from SQL to C Data Types" in Appendix D, "Data Types."

cbColDef Argument

The cbColDef argument specifies the precision of the column or expression corresponding to the parameter marker, unless all of the following are true:

In this case, the cbColDef argument contains the total number of bytes that will be sent for the parameter. For more information, see "Passing Parameter Values" and SQL_DATA_AT_EXEC in "pcbValue Argument."

rgbValue Argument

The rgbValue argument points to a buffer that, when SQLExecute or SQLExecDirect is called, contains the actual data for the parameter. The data must be in the form specified by the fCType argument.

If rgbValue points to a character string that contains a literal quote character ( ' ), the driver ensures that each literal quote is translated into the form required by the data source. For example, if the data source required that embedded literal quotes be doubled, the driver would replace each quote character ( ' ) with two quote characters ( ' ' ).

If pcbValue is the result of the SQL_LEN_DATA_AT_EXEC(length) macro or SQL_DATA_AT_EXEC, then rgbValue is an application-defined 32-bit value that is associated with the parameter. It is returned to the application through SQLParamData. For example, rgbValue might be a token such as a parameter number, a pointer to data, or a pointer to a structure that the application used to bind input parameters. Note, however, that if the parameter is an input/output parameter, rgbValue must be a pointer to a buffer where the output value will be stored. If SQLParamOptions was called to specify multiple values for the parameter, the application can use the value of the pirow argument in SQLParamOptions in conjunction with the rgbValue. For example, rgbValue might point to an array of values and the application might use pirow to retrieve the correct value from the array. For more information, see "Passing Parameter Values."

If the fParamType argument is SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT, rgbValue points to a buffer in which the driver returns the output value. If the procedure returns one or more result sets, the rgbValue buffer is not guaranteed to be set until all results have been fetched. (If fParamType is SQL_PARAM_OUTPUT and rgbValue and pcbValue are both null pointers, the driver discards the output value.)

If the application calls SQLParamOptions to specify multiple values for each parameter, rgbValue points to an array. A single SQL statement processes the entire array of input values for an input or input/output parameter and returns an array of output values for an input/output or output parameter.

cbValueMax Argument

For character and binary C data, the cbValueMax argument specifies the length of the rgbValue buffer (if it is a single element) or the length of an element in the rgbValue array (if the application calls SQLParamOptions to specify multiple values for each parameter). If the application specifies multiple values, cbValueMax is used to determine the location of values in the rgbValue array, both on input and on output. For input/output and output parameters, it is used to determine whether to truncate character and binary C data on output:

For all other types of C data, the cbValueMax argument is ignored. The length of the rgbValue buffer (if it is a single element) or the length of an element in the rgbValue array (if the application calls SQLParamOptions to specify multiple values for each parameter) is assumed to be the length of the C data type.


Note When an ODBC 1.0 application calls SQLSetParam in an ODBC 2.0 driver, the Driver Manager converts this to a call to SQLBindParameter in which the cbValueMax argument is always SQL_SETPARAM_VALUE_MAX. Because the Driver Manager returns an error if an ODBC 2.0 application sets cbValueMax to SQL_SETPARAM_VALUE_MAX, an ODBC 2.0 driver can use this to determine when it is called by an ODBC 1.0 application.

In SQLSetParam, the way in which an application specifies the length of the rgbValue buffer so that the driver can return character or binary data and the way in which an application sends an array of character or binary parameter values to the driver are driver-defined.

pcbValue Argument

The pcbValue argument points to a buffer that, when SQLExecute or SQLExecDirect is called, contains one of the following:


Note This value was introduced in ODBC 2.0.

Note This macro was introduced in ODBC 2.0.

If pcbValue is a null pointer, the driver assumes that all input parameter values are non-NULL and that character and binary data are null-terminated. If fParamType is SQL_PARAM_OUTPUT and rgbValue and pcbValue are both null pointers, the driver discards the output value.


Note Application developers are strongly discouraged from specifying a null pointer for pcbValue when the data type of the parameter is SQL_C_BINARY. For SQL_C_BINARY data, a driver sends only the data preceding an occurrence of the null-termination character, 0x00. To ensure that a driver does not unexpectedly truncate SQL_C_BINARY data, pcbValue should contain a pointer to a valid length value.

If the fParamType argument is SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT, pcbValue points to a buffer in which the driver returns SQL_NULL_DATA, the number of bytes available to return in rgbValue (excluding the null termination byte of character data), or SQL_NO_TOTAL if the number of bytes available to return cannot be determined. If the procedure returns one or more result sets, the pcbValue buffer is not guaranteed to be set until all results have been fetched.

If the application calls SQLParamOptions to specify multiple values for each parameter, pcbValue points to an array of SDWORD values. These can be any of the values listed earlier in this section and are processed with a single SQL statement.

Passing Parameter Values

An application can pass the value for a parameter either in the rgbValue buffer or with one or more calls to SQLPutData. Parameters whose data is passed with SQLPutData are known as data-at-execution parameters. These are commonly used to send data for SQL_LONGVARBINARY and SQL_LONGVARCHAR parameters and can be mixed with other parameters.

To pass parameter values, an application:


Note Although data-at-execution parameters are similar to data-at-execution columns, the value returned by SQLParamData is different for each.

Data-at-execution parameters are parameters in an SQL statement for which data will be sent with SQLPutData when the statement is executed with SQLExecDirect or SQLExecute. They are bound with SQLBindParameter. The value returned by SQLParamData is a 32-bit value passed to SQLBindParameter in the rgbValue argument.

Data-at-execution columns are columns in a rowset for which data will be sent with SQLPutData when a row is updated or added with SQLSetPos. They are bound with SQLBindCol. The value returned by SQLParamData is the address of the row in the rgbValue buffer that is being processed.

After SQLExecute or SQLExecDirect returns SQL_NEED_DATA, and before data is sent for all data-at-execution parameters, the statement is canceled, or an error occurs in SQLParamData or SQLPutData, the application can only call SQLCancel, SQLGetFunctions, SQLParamData, or SQLPutData with the hstmt or the hdbc associated with the hstmt. If it calls any other function with the hstmt or the hdbc associated with the hstmt, the function returns SQL_ERROR and SQLSTATE S1010 (Function sequence error).

If the application calls SQLCancel while the driver still needs data for data-at-execution parameters, the driver cancels statement execution; the application can then call SQLExecute or SQLExecDirect again. If the application calls SQLParamData or SQLPutData after canceling the statement, the function returns SQL_ERROR and SQLSTATE S1008 (Operation canceled).

Conversion of Calls to and from SQLSetParam

When an ODBC 1.0 application calls SQLSetParam in an ODBC 2.0 driver, the ODBC 2.0 Driver Manager maps the call as follows:

Call by ODBC 1.0 Application

Call to ODBC 2.0 Driver

SQLSetParam(
hstmt, ipar,
fCType, fSqlType, cbColDef, ibScale,
rgbValue,
pcbValue);

SQLBindParameter(
hstmt, ipar, SQL_PARAM_INPUT_OUTPUT,
fCType, fSqlType, cbColDef, ibScale,
rgbValue, SQL_SETPARAM_VALUE_MAX,
pcbValue);

When an ODBC 2.0 application calls SQLBindParameter in an ODBC 1.0 driver, the ODBC 2.0 Driver Manager maps the calls as follows:

Call by ODBC 2.0 Application

Call to ODBC 1.0 Driver

SQLBindParameter(
hstmt, ipar, fParamType,
fCType, fSqlType, cbColDef, ibScale,
rgbValue, cbValueMax, pcbValue);

SQLSetParam(
hstmt, ipar,
fCType, fSqlType, cbColDef, ibScale,
rgbValue, pcbValue);

Code Example

In the following example, an application prepares an SQL statement to insert data into the EMPLOYEE table. The SQL statement contains parameters for the NAME, AGE, and BIRTHDAY columns. For each parameter in the statement, the application calls SQLBindParameter to specify the ODBC C data type and the SQL data type of the parameter and to bind a buffer to each parameter. For each row of data, the application assigns data values to each parameter and calls SQLExecute to execute the statement.

For more code examples, see SQLParamOptions, SQLProcedures, SQLPutData, and SQLSetPos.

#define NAME_LEN 30

UCHAR       szName[NAME_LEN];
SWORD       sAge;
SDWORD      cbName = SQL_NTS, cbAge = 0, cbBirthday = 0;
DATE_STRUCT dsBirthday;
retcode = SQLPrepare(hstmt,

"INSERT INTO EMPLOYEE (NAME, AGE, BIRTHDAY) VALUES (?, ?, ?)",
SQL_NTS); if (retcode == SQL_SUCCESS) { /* Specify data types and buffers. */ /* for Name, Age, Birthday parameter data. */ SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR,
SQL_CHAR, NAME_LEN, 0, szName, 0, &cbName); SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT,
SQL_SMALLINT, 0, 0, &sAge, 0, &cbAge); SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_DATE,
SQL_DATE, 0, 0, &dsBirthday, 0, &cbBirthday); strcpy(szName, "Smith, John D."); /* Specify first row of */ sAge = 40; /* parameter data */ dsBirthday.year = 1952; dsBirthday.month = 2; dsBirthday.day = 29; retcode = SQLExecute(hstmt); /* Execute statement with */ /* first row */ strcpy(szName, "Jones, Bob K."); /* Specify second row of */ sAge = 52; /* parameter data */ dsBirthday.year = 1940; dsBirthday.month = 3; dsBirthday.day = 31; SQLExecute(hstmt); /* Execute statement with */ /* second row */ }

Related Functions

For information about

See

Returning information about a parameter in a statement

SQLDescribeParam (extension)

Executing an SQL statement

SQLExecDirect

Executing a prepared SQL statement

SQLExecute

Returning the number of statement parameters

SQLNumParams (extension)

Returning the next parameter to send data for

SQLParamData (extension)

Specifying multiple parameter values

SQLParamOptions (extension)

Sending parameter data at execution time

SQLPutData (extension)

Previous Page TOC Index Next Page

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