Previous Page TOC Index Next Page

SQLNativeSql (ODBC 1.0, Level 2)

SQLNativeSql returns the SQL string as translated by the driver.

Syntax

RETCODE SQLNativeSql(hdbc, szSqlStrIn, cbSqlStrIn, szSqlStr, cbSqlStrMax, pcbSqlStr)

The SQLNativeSql function accepts the following arguments:

Type

Argument

Use

Description

HDBC

hdbc

Input

Connection handle.

UCHAR FAR *

szSqlStrIn

Input

SQL text string to be translated.

SDWORD

cbSqlStrIn

Input

Length of szSqlStrIn text string.

UCHAR FAR *

szSqlStr

Output

Pointer to storage for the translated SQL string.

SDWORD

cbSqlStrMax

Input

Maximum length of the szSqlStr buffer.

SDWORD FAR *

pcbSqlStr

Output

The total number of bytes (excluding the null termination byte) available to return in szSqlStr. If the number of bytes available to return is greater than or equal to cbSqlStrMax, the translated SQL string in szSqlStr is truncated to cbSqlStrMax – 1 bytes.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLNativeSql returns either 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 SQLNativeSql 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.)

01004

Data truncated

The buffer szSqlStr was not large enough to return the entire SQL string, so the SQL string was truncated. The argument pcbSqlStr contains the length of the untruncated SQL string. (Function returns SQL_SUCCESS_WITH_INFO.)

08003

Connection not open

The hdbc was not in a connected state.

37000

Syntax error or access violation

The argument szSqlStrIn contained an SQL statement that was not preparable or contained a syntax error.

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

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

S1009

Invalid argument value

(DM) The argument szSqlStrIn was a null pointer.

S1090

Invalid string or buffer length

(DM) The argument cbSqlStrIn was less than 0, but not equal to SQL_NTS.



(DM) The argument cbSqlStrMax was less
than 0 and the argument szSqlStr was not a null pointer..

Comments

The following are examples of what SQLNativeSql might return for the following input SQL string containing the scalar function CONVERT. Assume that the column empid is of type INTEGER in the data source: 

SELECT { fn CONVERT (empid, SQL_SMALLINT) } FROM employee

A driver for SQL Server might return the following translated SQL string: 

SELECT convert (smallint, empid) FROM employee

A driver for ORACLE Server might return the following translated SQL string: 

SELECT to_number (empid) FROM employee

A driver for Ingres might return the following translated SQL string: 

SELECT int2 (empid) FROM employee

Related Functions

None.

SQLNumParams (ODBC 1.0, Level 2)

SQLNumParams returns the number of parameters in an SQL statement.

Syntax

RETCODE SQLNumParams(hstmt, pcpar)

The SQLNumParams function accepts the following arguments.

Type

Argument

Use

Description

HSTMT

hstmt

Input

Statement handle.

SWORD FAR *

pcpar

Output

Number of parameters in the statement.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLNumParams 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 SQLNumParams 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.

S1008

Operation canceled

Asynchronous processing was enabled for the hstmt. The function was called and before it completed execution, SQLCancel was called on the hstmt. Then the function was called again on the hstmt.

The function was called and, before it completed execution, SQLCancel was called on the hstmt from a different thread in a multithreaded application.

S1010

Function sequence error

(DM) The function was called prior to calling SQLPrepare or SQLExecDirect for the hstmt.

(DM) An asynchronously executing function (not this one) 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.

S1T00

Timeout expired

The timeout period expired before the data source returned the result set. The timeout period is set through SQLSetStmtOption, SQL_QUERY_TIMEOUT.

Comments

SQLNumParams can only be called after SQLPrepare has been called.

If the statement associated with hstmt does not contain parameters, SQLNumParams sets pcpar to 0.

Related Functions

For information about

See

Returning information about a parameter in a statement

SQLDescribeParam (extension)

Assigning storage for a parameter

SQLBindParameter

SQLNumResultCols (ODBC 1.0, Core)

SQLNumResultCols returns the number of columns in a result set.

Syntax

RETCODE SQLNumResultCols(hstmt, pccol)

The SQLNumResultCols function accepts the following arguments.

Type

Argument

Use

Description

HSTMT

hstmt

Input

Statement handle.

SWORD FAR *

pccol

Output

Number of columns in the result set.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLNumResultCols 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 SQLNumResultCols 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.

S1008

Operation canceled

Asynchronous processing was enabled for the hstmt. The function was called and before it completed execution, SQLCancel was called on the hstmt. Then the function was called again on the hstmt.

The function was called and, before it completed execution, SQLCancel was called on the hstmt from a different thread in a multithreaded application.

S1010

Function sequence error

(DM) The function was called prior to calling SQLPrepare or SQLExecDirect for the hstmt.

(DM) An asynchronously executing function (not this one) 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.

S1T00

Timeout expired

The timeout period expired before the data source returned the result set. The timeout period is set through SQLSetStmtOption, SQL_QUERY_TIMEOUT.

SQLNumResultCols can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when called after SQLPrepare and before SQLExecute depending on when the data source evaluates the SQL statement associated with the hstmt.

Comments

SQLNumResultCols can be called successfully only when the hstmt is in the prepared, executed, or positioned state.

If the statement associated with hstmt does not return columns, SQLNumResultCols sets pccol to 0.

Related Functions

For information about

See

Assigning storage for a column in a result set

SQLBindCol

Canceling statement processing

SQLCancel

Returning information about a column in a result set

SQLColAttributes

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

Fetching part or all of a column of data

SQLGetData (extension)

Setting cursor scrolling options

SQLSetScrollOptions (extension)

SQLParamData (ODBC 1.0, Level 1)

SQLParamData is used in conjunction with SQLPutData to supply parameter data at statement execution time.

Syntax

RETCODE SQLParamData(hstmt, prgbValue)

The SQLParamData function accepts the following arguments.

Type

Argument

Use

Description

HSTMT

hstmt

Input

Statement handle.

PTR FAR *

prgbValue

Output

Pointer to storage for the value specified for the rgbValue argument in SQLBindParameter (for parameter data) or the address of the rgbValue buffer specified in SQLBindCol (for column data).

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

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

08S01

Communication link failure

The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.

22026

String data, length mismatch

The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo was "Y" and less data was sent for a long parameter (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or a long, data source–specific data type) than was specified with the pcbValue argument in SQLBindParameter.

The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo was "Y" and less data was sent for a long column (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or a long, data source–specific data type) than was specified in the length buffer corresponding to a column in a row of data that was added or updated with SQLSetPos.

IM001

Driver does not support this function

(DM) The driver that corresponds 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.

S1008

Operation canceled

Asynchronous processing was enabled for the hstmt. The function was called and before it completed execution, SQLCancel was called on the hstmt. Then the function was called again on the hstmt.

The function was called and, before it completed execution, SQLCancel was called on the hstmt from a different thread in a multithreaded application.

SQLExecute, SQLExecDirect, or SQLSetPos was called for the hstmt and returned SQL_NEED_DATA. SQLCancel was called before data was sent for all data-at-execution parameters or columns.

S1010

Function sequence error

(DM) The previous function call was not a call to SQLExecDirect, SQLExecute, or SQLSetPos where the return code was SQL_NEED_DATA or a call to SQLPutData.

The previous function call was a call to SQLParamData.

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

S1T00

Timeout expired

The timeout period expired before the data source completed processing the parameter value. The timeout period is set through SQLSetStmtOption, SQL_QUERY_TIMEOUT.

If SQLParamData is called while sending data for a parameter in an SQL statement, it can return any SQLSTATE that can be returned by the function called to execute the statement (SQLExecute or SQLExecDirect). If it is called while sending data for a column being updated or added with SQLSetPos, it can return any SQLSTATE that can be returned by SQLSetPos.

Comments

For an explanation of how data-at-execution parameter data is passed at statement execution time, see "Passing Parameter Values" in SQLBindParameter. For an explanation of how data-at-execution column data is updated or added, see "Using SQLSetPos" in SQLSetPos.

Code Example

See SQLPutData.

Related Functions

For information about

See

Canceling statement processing

SQLCancel

Returning information about a parameter in a statement

SQLDescribeParam (extension)

Executing an SQL statement

SQLExecDirect

Executing a prepared SQL statement

SQLExecute

Sending parameter data at execution time

SQLPutData (extension)

Assigning storage for a parameter

SQLBindParameter

SQLParamOptions (ODBC 1.0, Level 2)

SQLParamOptions allows an application to specify multiple values for the set of parameters assigned by SQLBindParameter. The ability to specify multiple values for a set of parameters is useful for bulk inserts and other work that requires the data source to process the same SQL statement multiple times with various parameter values. An application can, for example, specify three sets of values for the set of parameters associated with an INSERT statement, and then execute the INSERT statement once to perform the three insert operations.

Syntax

RETCODE SQLParamOptions(hstmt, crow, pirow)

The SQLParamOptions function accepts the following arguments:

Type

Argument

Use

Description

HSTMT

hstmt

Input

Statement handle.

UDWORD

crow

Input

Number of values for each parameter. If crow is greater than 1, the rgbValue argument in SQLBindParameter points to an array of parameter values and pcbValue points to an array of lengths.

UDWORD FAR *

pirow

Input

Pointer to storage for the current row number. As each row of parameter values is processed, pirow is set to the number of that row. No row number will be returned if pirow is set to a null pointer.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLParamOptions 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 SQLParamOptions 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.

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.

S1107

Row value out of range

(DM) The value specified for the argument crow was equal to 0.

Comments

As a statement executes, the driver sets pirow to the number of the current row of parameter values; the first row is row number 1. The contents of pirow can be used as follows:

Code Example

In the following example, an application specifies an array of parameter values with SQLBindParameter and SQLParamOptions. It then inserts those values into a table with a single INSERT statement and checks for any errors. If the first row fails, the application rolls back all changes. If any other row fails, the application commits the transaction, skips the failed row, rebinds the remaining parameters, and continues processing. (Note that irow is 1-based and szData[ ] is 0-based, so the irow entry of szData[ ] is skipped by rebinding at szData[irow].) 

#define CITY_LEN 256
SDWORD cbValue[ ] = {SQL_NTS, SQL_NTS, SQL_NTS, SQL_NTS, SQL_NTS};
UCHAR  szData[ ][CITY_LEN] = {"Boston","New York","Keokuk","Seattle",

                              "Eugene"};
UDWORD irow;
SQLSetConnectOption(hdbc, SQL_AUTOCOMMIT, 0);
SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_DEFAULT, SQL_CHAR,

                 CITY_LEN, 0, szData, 0, cbValue);
SQLPrepare(hstmt, "INSERT INTO CITIES VALUES (?)", SQL_NTS);
SQLParamOptions(hstmt, 5, &irow);
while (TRUE) {
   retcode = SQLExecute(hstmt);
   /* Done if execution was successful */
   if (retcode != SQL_ERROR) {
      break;
   }
   /* On an error, print the error.  If the error is in row 1, roll */
   /* back the transaction and quit.  If the error is in another    */
   /* row, commit the transaction and, unless the error is in the   */
   /* last row, rebind to the next row and continue processing.     */
   show_error();
   if (irow == 1) {
      SQLTransact(henv, hstmt, SQL_ROLLBACK);
      break;
   } else {
      SQLTransact(henv, hstmt, SQL_COMMIT);
      if (irow == 5) {
         break;
      } else {
         SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT,

                          SQL_C_DEFAULT, SQL_CHAR, CITY_LEN, 0,

                          szData[irow], 0, cbValue[irow]);
         SQLParamOptions(hstmt, 5-irow, &irow);
      }
   }
}

Related Functions

For information about

See

Returning information about a parameter in a statement

SQLDescribeParam (extension)

Assigning storage for a parameter

SQLBindParameter

Previous Page TOC Index Next Page

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