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.
Syntax
SQLRETURN SQLNativeSql(
SQLHDBCConnectionHandle,
SQLCHAR *InStatementText,
SQLINTEGERTextLength1,
SQLCHAR *OutStatementText,
SQLINTEGERBufferLength,
SQLINTEGER *TextLength2Ptr);
Arguments
ConnectionHandle
[Input]
Connection handle.
InStatementText
[Input]
SQL text string to be translated.
TextLength1
[Input]
Length of *InStatementText text string.
OutStatementText
[Output]
Pointer to a buffer in which to return the translated SQL string.
BufferLength
[Input]
Length of 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 bytes (excluding the null-termination byte) available to return in *OutStatementText. If the number of bytes 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.
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 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. |
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 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” in Chapter 9, “Executing Statements.”
Related Functions
None.