Функция SQLNativeSql

Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: ODBC

Сводка
SQLNativeSql возвращает строку SQL, измененную драйвером. SQLNativeSql не выполняет инструкцию SQL.

Синтаксис

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

Аргументы

ConnectionHandle
[Input] Дескриптор подключения

InStatementText
[Входные данные] Текстовая строка SQL для перевода.

TextLength1
[Входные данные] Длина в символах текстовой строки *InStatementText .

OutStatementText
[Выходные данные] Указатель на буфер, в котором возвращается переведенная строка SQL.

Если Значение OutStatementText равно NULL, TextLength2Ptr по-прежнему возвращает общее количество символов (за исключением символа завершения null для символьных данных), доступное для возврата в буфер, на который указывает OutStatementText.

BufferLength
[Входные данные] Число символов в буфере *OutStatementText . Предыдущие версии этой документации ошибочно подразумевают, что это число символов должно быть даже в том случае, если значение, возвращаемое в *InStatementText , является строкой Юникода (при вызове SQLNativeSqlW). Такого ограничения нет. Чтобы обеспечить оптимальную совместимость, средства записи драйверов должны ожидать, что количество символов будет передано этой функции, в то время как записи приложений рекомендуется всегда использовать даже число.

TextLength2Ptr
[Выходные данные] Указатель на буфер, в котором возвращается общее количество символов (за исключением завершения null), доступное для возврата в *OutStatementText. Если число символов, доступных для возврата, больше или равно BufferLength, преобразованная строка SQL в *OutStatementText усечена в BufferLength минус длину символа завершения null.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Когда SQLNativeSql возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_DBC и handle of ConnectionHandle. В следующей таблице перечислены значения SQLSTATE, часто возвращаемые SQLNativeSql , и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004	Строковые данные, усеченные справа	Буфер *OutStatementText был недостаточно велик, чтобы вернуть всю строку SQL, поэтому строка SQL была усечена. Длина ненадежной строки SQL возвращается в *TextLength2Ptr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
08003	Подключение не открыто	ConnectionHandle не был в подключенном состоянии.
08S01	Сбой связи	Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции.
22007	Недопустимый формат datetime	*InStatementText содержит предложение escape с недопустимым значением даты, времени или метки времени.
24000	Недопустимое состояние курсора	Курсор, указанный в инструкции, был размещен до начала результирующий набор или после окончания результирующий набор. Эта ошибка может не быть возвращена драйвером с собственной реализацией курсора СУБД.
HY000	Общая ошибка	Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001	Ошибка выделения памяти	Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY009	Недопустимое использование указателя NULL	(DM) *InStatementText — это пустой указатель.
HY010	Ошибка последовательности функций	(DM) Асинхронно выполняющаяся функция была вызвана для ConnectionHandle и по-прежнему выполнялась при вызове этой функции.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090	Недопустимая длина строки или буфера	(DM) Аргумент TextLength1 был меньше 0, но не равен SQL_NTS.
		(DM) Аргумент BufferLength был меньше 0, и аргумент OutStatementText не был пустым указателем.
HY109	Недопустимое положение курсора	Текущая строка курсора была удалена или не была возвращена. Эта ошибка может не быть возвращена драйвером с собственной реализацией курсора СУБД.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, связанный с ConnectionHandle , не поддерживает функцию.

Комментарии

Ниже приведены примеры того, что SQLNativeSql может возвращать для следующей входной строки SQL, содержащей скалярную функцию CONVERT. Предположим, что эмпид столбца имеет тип INTEGER в источнике данных:

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

Драйвер Microsoft SQL Server может вернуть следующую переведенную строку SQL:

SELECT convert (smallint, empid) FROM employee  

Драйвер для ORACLE Server может вернуть следующую переведенную строку SQL:

SELECT to_number (empid) FROM employee  

Драйвер для входящего трафика может вернуть следующую переведенную строку SQL:

SELECT int2 (empid) FROM employee  

Дополнительные сведения см. в разделе "Прямое выполнение " и "Подготовленное выполнение".

Связанные функции

Нет.

См. также

Справочник по API ODBC
Файлы заголовков ODBC