Функция 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
Дополнительные сведения см. в разделе "Прямое выполнение " и "Подготовленное выполнение".
Связанные функции
Нет.