SQLNativeSql function (CLI) - Get native SQL text
Specification:
- CLI 2.1
- ODBC 1.0
Syntax
SQLRETURN SQLNativeSql (
SQLHDBC ConnectionHandle, /* hdbc */
SQLCHAR *InStatementText, /* szSqlStrIn */
SQLINTEGER TextLength1, /* cbSqlStrIn */
SQLCHAR *OutStatementText, /* szSqlStr */
SQLINTEGER BufferLength, /* cbSqlStrMax */
SQLINTEGER *TextLength2Ptr); /* pcbSqlStr */
Function arguments
Data type | Argument | Use | Description |
---|---|---|---|
SQLHDBC | ConnectionHandle | input | Connection Handle |
SQLCHAR * | InStatementText | input | Input SQL string |
SQLINTEGER | TextLength1 | input | Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store InStatementText. |
SQLCHAR * | OutStatementText | output | Pointer to buffer for the transformed output string |
SQLINTEGER | BufferLength | input | Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store OutStatementText. |
SQLINTEGER * | TextLength2Ptr | output | The total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-terminator, available to return in OutStatementText. If the number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) available to return is greater than or equal to BufferLength, the output SQL string in OutStatementText is truncated to BufferLength - 1 SQLCHAR or SQLWCHAR elements. |
Usage
This function is called when the application wishes to examine or display the transformed SQL string that would be passed to the data source by CLI. Translation (mapping) would only occur if the input SQL statement string contains vendor escape clause sequences.
CLI can only detect vendor escape clause syntax errors when SQLNativeSql() is called. Because CLI does not pass the transformed SQL string to the data source for preparation, syntax errors that are detected by the DBMS are not generated at this time. (The statement is not passed to the data source for preparation because the preparation may potentially cause the initiation of a transaction.)
Return codes
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
Diagnostics
SQLSTATE | Description | Explanation |
---|---|---|
01004 | Data truncated. | The buffer OutStatementText was not large enough to contain the entire SQL string, so truncation occurred. The argument TextLength2Ptr contains the total length of the untruncated SQL string. (Function returns with SQL_SUCCESS_WITH_INFO) |
08003 | Connection is closed. | The ConnectionHandle does not reference an open database connection. |
37000 | Invalid SQL syntax. | The input SQL string in InStatementText contained a syntax error. |
HY001 | Memory allocation failure. | Db2® CLI is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations. |
HY009 | Invalid argument value. | The argument InStatementText is a
NULL pointer. The argument OutStatementText is a NULL pointer. |
HY090 | Invalid string or buffer length. | The argument TextLength1 was less
than 0, but not equal to SQL_NTS. The argument BufferLength was less than 0. |
Restrictions
None.