Welcome  |  Sign In
 | 
Click to Rate and Give Feedback
MSDN
MSDN Library
API Reference
ODBC API Reference
 SQLNativeSql Function
SQLNativeSql Function

Conformance

Version Introduced: ODBC 1.0 Standards Compliance: ODBC

Summary

SQLNativeSql returns the SQL string as modified by the driver. SQLNativeSql does not execute the SQL statement.

SQLRETURN SQLNativeSql(
     SQLHDBC     ConnectionHandle,
     SQLCHAR *     InStatementText,
     SQLINTEGER     TextLength1,
     SQLCHAR *     OutStatementText,
     SQLINTEGER     BufferLength,
     SQLINTEGER *     TextLength2Ptr);
ConnectionHandle

[Input] Connection handle.

InStatementText

[Input] SQL text string to be translated.

TextLength1

[Input] Length in characters of *InStatementText text string.

OutStatementText

[Output] Pointer to a buffer in which to return the translated SQL string.

BufferLength

[Input] Number of characters in the *OutStatementText buffer. If the value returned in *InStatementText is a Unicode string (when calling SQLNativeSqlW), the BufferLength argument must be an even number.

TextLength2Ptr

[Output] Pointer to a buffer in which to return the total number of characters (excluding null-termination) available to return in *OutStatementText. If the number of characters available to return is greater than or equal to BufferLength, the translated SQL string in *OutStatementText is truncated to BufferLength minus the length of a null-termination character.

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

When SQLNativeSql returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_DBC and a Handle of ConnectionHandle. 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

String data, right truncated

The buffer *OutStatementText was not large enough to return the entire SQL string, so the SQL string was truncated. The length of the untruncated SQL string is returned in *TextLength2Ptr. (Function returns SQL_SUCCESS_WITH_INFO.)

08003

Connection does not exist

The ConnectionHandle was not in a connected state.

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.

22007

Invalid datetime format

*InStatementText contained an escape clause with an invalid date, time, or timestamp value.

24000

Invalid cursor state

The cursor referred to in the statement was positioned before the start of the result set or after the end of the result set. This error may not be returned by a driver having a native DBMS cursor implementation.

HY000

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 SQLGetDiagRec in the *MessageText buffer describes the error and its cause.

HY001

Memory allocation error

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

HY009

Invalid use of null pointer

(DM) *InStatementText was a null pointer.

HY013

Memory management error

The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.

HY090

Invalid string or buffer length

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

 

 

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

HY109

Invalid cursor position

The current row of the cursor had been deleted or had not been fetched. This error may not be returned by a driver having a native DBMS cursor implementation.

HYT01

Connection timeout expired

The connection timeout period expired before the data source responded to the request. The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.

IM001

Driver does not support this function

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

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 Microsoft 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

For more information, see Direct Execution and Prepared Execution.

None.

Concepts

ODBC Header Files

Other Resources

ODBC API Reference

© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker