Функция 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