Функция SQLSetDescField
Соответствия
Представлена версия: соответствие стандартам ODBC 3.0: ISO 92
Сводка
SQLSetDescField задает значение одного поля записи дескриптора.
Синтаксис
SQLRETURN SQLSetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength);
Аргументы
DescriptorHandle
[Входные данные] Дескриптор дескриптор.
RecNumber
[Входные данные] Указывает запись дескриптора, содержащую поле, которое приложение ищет для задания. Записи дескриптора нумеруются от 0, при этом запись записи 0 является записью закладки. Аргумент RecNumber игнорируется для полей заголовка.
FieldIdentifier
[Входные данные] Указывает поле дескриптора, значение которого необходимо задать. Дополнительные сведения см. в разделе "Аргумент FieldIdentifier " в разделе "Комментарии".
ValuePtr
[Входные данные] Указатель на буфер, содержащий сведения дескриптора или целочисленное значение. Тип данных зависит от значения FieldIdentifier. Если Значение ValuePtr является целым значением, оно может рассматриваться как 8 байт (SQLLEN), 4 байта (SQLINTEGER) или 2 байта (SQLSMALLINT), в зависимости от значения аргумента FieldIdentifier .
BufferLength
[Входные данные] Если FieldIdentifier является полем, определяемым ODBC, и ValuePtr указывает на символьную строку или двоичный буфер, этот аргумент должен быть длиной *ValuePtr. Для символьных строковых данных этот аргумент должен содержать количество байтов в строке.
Если FieldIdentifier является полем, определяемым ODBC, и ValuePtr является целым числом, bufferLength игнорируется.
Если FieldIdentifier является определяемым драйвером полем, приложение указывает характер поля диспетчеру драйверов, задав аргумент BufferLength . BufferLength может иметь следующие значения:
Если ЗначениеPtr является указателем на символьную строку, буферLength — это длина строки или SQL_NTS.
Если ЗначениеPtr является указателем на двоичный буфер, приложение помещает результат макроса SQL_LEN_BINARY_ATTR(длина) в BufferLength. Это помещает отрицательное значение в BufferLength.
Если ValuePtr является указателем на значение, отличное от символьной строки или двоичной строки, буферLength должен иметь значение SQL_IS_POINTER.
Если Значение ValuePtr содержит значение фиксированной длины, буферLength имеет значение SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT или SQL_IS_USMALLINT соответствующим образом.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLSetDescField возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_DESC и дескриптораHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLSetDescField и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Изменено значение параметра | Драйвер не поддерживал значение, указанное в *ValuePtr (если ЗначениеPtr было указателем) или значением в ValuePtr (если ЗначениеPtr было целым значением), или *ValuePtr было недопустимым из-за условий выполнения, поэтому драйвер заменил аналогичное значение. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07009 | Недопустимый индекс дескриптора | Аргумент FieldIdentifier был полем записи, аргумент RecNumber был 0, а аргумент DescriptorHandle ссылается на дескриптор IPD. Аргумент RecNumber был меньше 0, а аргумент DescriptorHandle ссылается на ARD или APD. Аргумент RecNumber был больше максимального числа столбцов или параметров, которые может поддерживать источник данных, и аргумент DescriptorHandle , называемый APD или ARD. (DM) Аргумент FieldIdentifier был SQL_DESC_COUNT, а аргумент *ValuePtr меньше 0. Аргумент RecNumber равен 0, а аргумент DescriptorHandle ссылается на неявно выделенный APD. (Эта ошибка не возникает с явно выделенным дескриптором приложения, так как неизвестно, является ли дескриптор приложения явным образом выделенным apiD или ARD до времени выполнения.) |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 22001 | Строковые данные, усеченные справа | Аргумент FieldIdentifier был SQL_DESC_NAME, а аргумент BufferLength был значением, превышающим SQL_MAX_IDENTIFIER_LEN. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY010 | Ошибка последовательности функций | (DM) ДескрипторHandle был связан с ОператорОмHandle, для которого асинхронно выполняющаяся функция (не эта) была вызвана и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos был вызван для ОператораHandle, с которым был связан дескрипторHandle и возвращен SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ДескрипторHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLSetDescField . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для одного из дескрипторов инструкций, связанных с ДескрипторомHandle и возвращенных SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY016 | Не удается изменить дескриптор строки реализации | Аргумент DescriptorHandle связан с IRD, а аргумент FieldIdentifier не был SQL_DESC_ARRAY_STATUS_PTR или SQL_DESC_ROWS_PROCESSED_PTR. |
| HY021 | Несогласованные сведения о дескрипторе | Поля SQL_DESC_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE не образуют допустимый тип ODBC SQL или допустимый тип SQL для конкретного драйвера (для IPD) или допустимый тип ODBC C (для APD или ARD). Сведения дескриптора, проверяемые во время проверки согласованности, не согласованы. (См. раздел "Проверка согласованности" SQLSetDescRec.) |
| HY090 | Недопустимая длина строки или буфера | (DM) *ValuePtr — это символьная строка, а BufferLength меньше нуля, но не равно SQL_NTS. (DM) Драйвером был драйвер ODBC 2*.x*, дескриптор был ARD, аргумент ColumnNumber был равен 0, а значение, указанное для аргумента BufferLength , не равно 4. |
| HY091 | Недопустимый идентификатор поля дескриптора | Значение, указанное для аргумента FieldIdentifier , не было определяемым ODBC полем и не было определяемым реализацией значением. Аргумент FieldIdentifier недопустим для аргумента DescriptorHandle. Аргумент FieldIdentifier — это поле, доступное только для чтения, определяемое ODBC. |
| HY092 | Недопустимый идентификатор атрибута или параметра | Значение в *ValuePtr недопустимо для аргумента FieldIdentifier . Аргумент FieldIdentifier был SQL_DESC_UNNAMED, и ЗначениеPtr было SQL_NAMED. |
| HY105 | Недопустимый тип параметра | (DM) Значение, указанное для поля SQL_DESC_PARAMETER_TYPE, было недопустимым. (Дополнительные сведения см. в разделе ""Раздел "Аргумент InputOutputType " в SQLBindParameter.) |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | Дополнительные сведения о приостановленном состоянии см. в статье "Новые возможности" в ODBC 3.8. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с ДескрипторHandle , не поддерживает функцию. |
Комментарии
Приложение может вызывать SQLSetDescField , чтобы задать любое поле дескриптора по одному за раз. Один вызов SQLSetDescField задает одно поле в одном дескрипторе. Эту функцию можно вызвать, чтобы задать любое поле в любом типе дескриптора, если это поле можно задать. (См. таблицу далее в этом разделе.)
Заметка
Если вызов SQLSetDescField завершается ошибкой, содержимое записи дескриптора, определяемой аргументом RecNumber , не определено.
Другие функции можно вызывать для задания нескольких полей дескриптора с одним вызовом функции. Функция SQLSetDescRec задает различные поля, влияющие на тип данных и буфер, привязанные к столбцу или параметру (поля SQL_DESC_TYPE, SQL_DESC_DATETIME_INTERVAL_CODE, SQL_DESC_OCTET_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR и SQL_DESC_INDICATOR_PTR). SQLBindCol или SQLBindParameter можно использовать для выполнения полной спецификации привязки столбца или параметра. Эти функции задают определенную группу полей дескриптора с одним вызовом функции.
SqlSetDescField можно вызвать для изменения буферов привязки, добавив смещение в указатели привязки (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR или SQL_DESC_OCTET_LENGTH_PTR). Это изменяет буферы привязки без вызова SQLBindCol или SQLBindParameter, что позволяет приложению изменять SQL_DESC_DATA_PTR без изменения других полей, таких как SQL_DESC_DATA_TYPE.
Если приложение вызывает SQLSetDescField , чтобы задать любое поле, отличное от SQL_DESC_COUNT или отложенных полей, SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR или SQL_DESC_INDICATOR_PTR, запись становится несвязанной.
Поля заголовка дескриптора задаются путем вызова SQLSetDescField с соответствующим FieldIdentifier. Многие поля заголовка также являются атрибутами инструкций, поэтому их также можно задать вызовом SQLSetStmtAttr. Это позволяет приложениям задавать поле дескриптора без первого получения дескриптора дескриптора. При вызове SQLSetDescField для задания поля заголовка аргумент RecNumber игнорируется.
Значение RecNumber 0 используется для задания полей закладки.
Заметка
Атрибут инструкции SQL_ATTR_USE_BOOKMARKS всегда должен быть задан перед вызовом SQLSetDescField для задания полей закладки. Хотя это не обязательно, настоятельно рекомендуется.
Последовательность полей дескриптора параметров
При задании полей дескриптора путем вызова SQLSetDescField приложение должно соответствовать определенной последовательности:
Приложение должно сначала задать поле SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE или SQL_DESC_DATETIME_INTERVAL_CODE.
После установки одного из этих полей приложение может задать атрибут типа данных, а драйвер задает поля атрибута типа данных соответствующим значениям по умолчанию для типа данных. Автоматическое использование полей атрибутов типа гарантирует, что дескриптор всегда готов к использованию после того, как приложение указало тип данных. Если приложение явно задает атрибут типа данных, он переопределяет атрибут по умолчанию.
После установки одного из полей, перечисленных на шаге 1, и атрибуты типа данных заданы, приложение может задать SQL_DESC_DATA_PTR. Это запрашивает проверку согласованности полей дескриптора. Если приложение изменяет тип данных или атрибуты после настройки поля SQL_DESC_DATA_PTR, драйвер устанавливает SQL_DESC_DATA_PTR на указатель null, отменив привязку записи. Это заставляет приложение выполнять правильные шаги в последовательности, прежде чем запись дескриптора подходит для использования.
Инициализация полей дескриптора
При выделении дескриптора поля дескриптора можно инициализировать в значение по умолчанию, инициализировать без значения по умолчанию или быть неопределенными для типа дескриптора. В следующих таблицах указывается инициализация каждого поля для каждого типа дескриптора с "D", указывающее, что поле инициализировано по умолчанию, и "ND", указывающее, что поле инициализировано без значения по умолчанию. Если отображается число, значение поля по умолчанию — это число. Таблицы также указывают, является ли поле чтением и записью (R/W) или доступно только для чтения (R).
Поля IRD имеют значение по умолчанию только после подготовки или выполнения инструкции и заполнения IRD, а не при выделении дескриптора инструкции или дескриптора. До заполнения IRD любая попытка получить доступ к полю IRD вернет ошибку.
Некоторые поля дескриптора определяются для одного или нескольких типов дескриптора (ARD и IRD, а также APD и IPD). Если поле не определено для типа дескриптора, оно не требуется ни одной из функций, использующих дескриптор.
Поля, к которым можно получить доступ с помощью SQLGetDescField , не обязательно задаются SQLSetDescField. Поля, которые можно задать с помощью SQLSetDescField , перечислены в следующих таблицах.
Инициализация полей заголовка описана в следующей таблице.
| Имя поля заголовка | Вид | Чтение-запись | По умолчанию. |
|---|---|---|---|
| SQL_DESC_ALLOC_TYPE | SQLSMALLINT | ARD: R APD: R IRD: R IPD: R | ARD: SQL_DESC_ALLOC_AUTO для неявных или SQL_DESC_ALLOC_USER для явного APD: SQL_DESC_ALLOC_AUTO для неявных или SQL_DESC_ALLOC_USER для явного IRD: SQL_DESC_ALLOC_AUTO IPD: SQL_DESC_ALLOC_AUTO |
| SQL_DESC_ARRAY_SIZE | SQLULEN | ARD: R/W APD: R/W IRD: Unused IPD: Unused | ARD:[1] APD:[1] IRD: Unused IPD: Unused |
| SQL_DESC_ARRAY_STATUS_PTR | SQLUSMALLINT* | ARD: R/W APD: R/W IRD: R/W IPD: R/W | ARD: NULL ptr APD: Null ptr IRD: Null ptr IPD: Null ptr |
| SQL_DESC_BIND_OFFSET_PTR | SQLLEN* | ARD: R/W APD: R/W IRD: Unused IPD: Unused | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused |
| SQL_DESC_BIND_TYPE | SQLINTEGER | ARD: R/W APD: R/W IRD: Unused IPD: Unused | ARD: SQL_BIND_BY_COLUMN APD: SQL_BIND_BY_COLUMN IRD: неиспользуемый IPD: неиспользуемый |
| SQL_DESC_COUNT | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: 0 APD: 0 IRD: D IPD: 0 |
| SQL_DESC_ROWS_PROCESSED_PTR | SQLULEN* | ARD: Unused APD: Unused IRD: R/W IPD: R/W | ARD: Unused APD: Unused IRD: Null ptr IPD: Null ptr |
[1] Эти поля определяются только в том случае, если IPD автоматически заполняется драйвером. Если нет, они не определены. Если приложение пытается задать эти поля, возвращается SQLSTATE HY091 (недопустимый идентификатор поля дескриптора).
Инициализация полей записи, как показано в следующей таблице.
| Имя поля записи | Вид | Чтение-запись | По умолчанию. |
|---|---|---|---|
| SQL_DESC_AUTO_UNIQUE_VALUE | SQLINTEGER | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_BASE_COLUMN_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_BASE_TABLE_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_CASE_SENSITIVE | SQLINTEGER | ARD: Unused APD: Unused IRD: R IPD: R | ARD: Unused APD: Unused IRD: D IPD: D[1] |
| SQL_DESC_CATALOG_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_CONCISE_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_ APD ПО УМОЛЧАНИЮ: SQL_C_ IRD: D IPD: ND |
| SQL_DESC_DATA_PTR | SQLPOINTER | ARD: R/W APD: R/W IRD: Unused IPD: Unused | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused[2] |
| SQL_DESC_DATETIME_INTERVAL_CODE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DATETIME_INTERVAL_PRECISION | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DISPLAY_SIZE | SQLLEN | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_FIXED_PREC_SCALE | SQLSMALLINT | ARD: Unused APD: Unused IRD: R IPD: R | ARD: Unused APD: Unused IRD: D IPD: D[1] |
| SQL_DESC_INDICATOR_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: Unused IPD: Unused | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused |
| SQL_DESC_LABEL | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_LENGTH | SQLULEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_LITERAL_PREFIX | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_LITERAL_SUFFIX | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_LOCAL_TYPE_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: R | ARD: Unused APD: Unused IRD: D IPD: D[1] |
| SQL_DESC_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NULLABLE | SQLSMALLINT | ARD: Unused APD: Unused IRD: R IPD: R | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NUM_PREC_RADIX | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH | SQLLEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: Unused IPD: Unused | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused |
| SQL_DESC_PARAMETER_TYPE | SQLSMALLINT | ARD: Unused APD: Unused IRD: Unused IPD: R/W | ARD: Unused APD: Unused IRD: Unused IPD: D=SQL_PARAM_INPUT |
| SQL_DESC_PRECISION | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_ROWVER | SQLSMALLINT | ARD: неиспользуемый APD: неиспользуемые IRD: R IPD: R |
ARD: неиспользуемый APD: неиспользуемые IRD: ND IPD: ND |
| SQL_DESC_SCALE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_SCHEMA_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_SEARCHABLE | SQLSMALLINT | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_TABLE_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
| SQL_DESC_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND |
| SQL_DESC_TYPE_NAME | SQLCHAR * | ARD: Unused APD: Unused IRD: R IPD: R | ARD: Unused APD: Unused IRD: D IPD: D[1] |
| SQL_DESC_UNNAMED | SQLSMALLINT | ARD: Unused APD: Unused IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_UNSIGNED | SQLSMALLINT | ARD: Unused APD: Unused IRD: R IPD: R | ARD: Unused APD: Unused IRD: D IPD: D[1] |
| SQL_DESC_UPDATABLE | SQLSMALLINT | ARD: Unused APD: Unused IRD: R IPD: Unused | ARD: Unused APD: Unused IRD: D IPD: Unused |
[1] Эти поля определяются только в том случае, если IPD автоматически заполняется драйвером. Если нет, они не определены. Если приложение пытается задать эти поля, возвращается SQLSTATE HY091 (недопустимый идентификатор поля дескриптора).
[2] Поле SQL_DESC_DATA_PTR в IPD можно задать для принудительной проверки согласованности. В последующем вызове SQLGetDescField или SQLGetDescRec драйвер не требуется для возврата значения, для SQL_DESC_DATA_PTR заданного значения.
Аргумент FieldIdentifier
Аргумент FieldIdentifier указывает поле дескриптора, которое необходимо задать. Дескриптор содержит заголовок дескриптора, состоящий из полей заголовков, описанных в следующем разделе, "Поля заголовка" и ноль или более записей дескриптора, состоящих из полей записей, описанных в разделе ниже раздела "Поля заголовка".
Поля заголовка
Каждый дескриптор содержит заголовок, состоящий из следующих полей:
SQL_DESC_ALLOC_TYPE [Все]
Это поле заголовка SQLSMALLINT только для чтения указывает, был ли дескриптор выделен автоматически драйвером или явным образом приложением. Приложение может получить, но не изменить это поле. Для поля задано значение SQL_DESC_ALLOC_AUTO драйвером, если дескриптор был автоматически выделен драйвером. Для драйвера задано значение SQL_DESC_ALLOC_USER, если дескриптор был явно выделен приложением.
SQL_DESC_ARRAY_SIZE [дескрипторы приложений]
В arDs это поле заголовка SQLULEN указывает количество строк в наборе строк. Это число строк, возвращаемых вызовом SQLFetch или SQLFetchScroll или с помощью вызова SQLBulkOperations или SQLSetPos.
В APD это поле заголовка SQLULEN указывает количество значений для каждого параметра.
Значение по умолчанию этого поля равно 1. Если SQL_DESC_ARRAY_SIZE больше 1, SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR APD или ARD указывают на массивы. Кратность каждого массива равна значению этого поля.
Это поле в ARD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_ROW_ARRAY_SIZE. Это поле в APD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAMSET_SIZE.
SQL_DESC_ARRAY_STATUS_PTR [Все]
Для каждого типа дескриптора этот поле заголовка SQLUSMALLINT * указывает на массив значений SQLUSMALLINT. Эти массивы называются следующим образом: массив состояния строк (IRD), массив состояния параметров (IPD), массив операций строк (ARD) и массив операций параметров (APD).
В IRD это поле заголовка указывает на массив состояния строки, содержащий значения состояния после вызова SQLBulkOperations, SQLFetch, SQLFetchScroll или SQLSetPos. Массив содержит столько элементов, сколько строк в наборе строк. Приложение должно выделить массив SQLUSMALLINTs и задать для этого поля указатель на массив. Поле по умолчанию имеет значение NULL- указателя. Драйвер заполняет массив, если в поле SQL_DESC_ARRAY_STATUS_PTR не задано значение NULL, в этом случае значения состояния не создаются и массив не заполняется.
Внимание
Поведение драйвера не определено, если приложение задает элементы массива состояния строки, на которое указывает SQL_DESC_ARRAY_STATUS_PTR поле IRD.
Массив изначально заполняется вызовом SQLBulkOperations, SQLFetch, SQLFetchScroll или SQLSetPos. Если вызов не вернул SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, содержимое массива, на которое указывает это поле, не определено. Элементы в массиве могут содержать следующие значения:
SQL_ROW_SUCCESS: строка успешно извлекалась и не изменилась с момента последнего получения.
SQL_ROW_SUCCESS_WITH_INFO: строка успешно извлекалась и не изменилась с момента последнего получения. Однако предупреждение было возвращено о строке.
SQL_ROW_ERROR: произошла ошибка при выборе строки.
SQL_ROW_UPDATED: строка успешно извлекалась и была обновлена с момента последнего получения. Если строка снова извлекается, его состояние SQL_ROW_SUCCESS.
SQL_ROW_DELETED: строка была удалена с момента последнего получения.
SQL_ROW_ADDED: строка была вставлена SQLBulkOperations. Если строка снова извлекается, его состояние SQL_ROW_SUCCESS.
SQL_ROW_NOROW. Набор строк перекрывал конец результирующий набор, и строка не была возвращена, соответствующая этому элементу массива состояния строки.
Это поле в IRD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_ROW_STATUS_PTR.
Поле SQL_DESC_ARRAY_STATUS_PTR IRD допустимо только после возврата SQL_SUCCESS или SQL_SUCCESS_WITH_INFO. Если возвращаемый код не является одним из них, расположение, на которое указывает SQL_DESC_ROWS_PROCESSED_PTR, не определено.
В IPD это поле заголовка указывает на массив состояния параметра, содержащий сведения о состоянии для каждого набора значений параметров после вызова SQLExecute или SQLExecDirect. Если вызов SQLExecute или SQLExecDirect не вернул SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, содержимое массива, на которое указывает это поле, не определено. Приложение должно выделить массив SQLUSMALLINTs и задать для этого поля указатель на массив. Драйвер заполняет массив, если в поле SQL_DESC_ARRAY_STATUS_PTR не задано значение NULL, в этом случае значения состояния не создаются и массив не заполняется. Элементы в массиве могут содержать следующие значения:
SQL_PARAM_SUCCESS. Инструкция SQL успешно выполнена для этого набора параметров.
SQL_PARAM_SUCCESS_WITH_INFO: инструкция SQL успешно выполнена для этого набора параметров; Однако сведения о предупреждении доступны в структуре данных диагностики.
SQL_PARAM_ERROR: произошла ошибка при обработке этого набора параметров. Дополнительные сведения об ошибках доступны в структуре данных диагностики.
SQL_PARAM_UNUSED: этот набор параметров не использовался, возможно, из-за того, что некоторый предыдущий набор параметров вызвал ошибку, прерванную дальнейшую обработку или так как SQL_PARAM_IGNORE был задан для этого набора параметров в массиве, заданном полем SQL_DESC_ARRAY_STATUS_PTR APD.
SQL_PARAM_DIAG_UNAVAILABLE: диагностические сведения недоступны. Примером этого является то, что драйвер обрабатывает массивы параметров как монолитную единицу и поэтому не создает такой уровень сведений об ошибках.
Это поле в IPD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAM_STATUS_PTR.
В ARD это поле заголовка указывает на массив операций строки значений, которые можно задать приложением, чтобы указать, следует ли игнорировать эту строку для операций SQLSetPos . Элементы в массиве могут содержать следующие значения:
SQL_ROW_PROCEED. Строка включается в массовую операцию с помощью SQLSetPos. (Этот параметр не гарантирует, что операция будет выполняться в строке. Если строка имеет состояние SQL_ROW_ERROR в массиве состояния строки IRD, драйвер может не выполнить операцию в строке.)
SQL_ROW_IGNORE. Строка исключается из массовой операции с помощью SQLSetPos.
Если элементы массива не заданы, все строки включаются в массовую операцию. Если значение в поле SQL_DESC_ARRAY_STATUS_PTR ARD является пустым указателем, все строки включаются в массовую операцию; интерпретация совпадает с тем, что указатель указывает на допустимый массив, а все элементы массива SQL_ROW_PROCEED. Если элемент в массиве имеет значение SQL_ROW_IGNORE, значение в массиве состояния строки для игнорируемой строки не изменяется.
Это поле в ARD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_ROW_OPERATION_PTR.
В APD это поле заголовка указывает на массив операций параметров значений, которые можно задать приложением, чтобы указать, следует ли игнорировать этот набор параметров при вызове SQLExecute или SQLExecDirect . Элементы в массиве могут содержать следующие значения:
SQL_PARAM_PROCEED. Набор параметров включается в вызов SQLExecute или SQLExecDirect .
SQL_PARAM_IGNORE. Набор параметров исключается из вызова SQLExecute или SQLExecDirect .
Если элементы массива не заданы, все наборы параметров в массиве используются в вызовах SQLExecute или SQLExecDirect . Если значение в поле SQL_DESC_ARRAY_STATUS_PTR APD является пустым указателем, используются все наборы параметров; интерпретация совпадает с тем, что указатель указывает на допустимый массив, а все элементы массива SQL_PARAM_PROCEED.
Это поле в APD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAM_OPERATION_PTR.
SQL_DESC_BIND_OFFSET_PTR [дескрипторы приложений]
Это поле заголовка SQLLEN * указывает на смещение привязки. По умолчанию для него задано значение NULL-указателя. Если это поле не является пустым указателем, драйвер разыменовывает указатель и добавляет разыменованное значение к каждому из отложенных полей, имеющих ненулевое значение в записи дескриптора (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR) во время получения и использует новые значения указателя при привязке.
Смещение привязки всегда добавляется непосредственно к значениям в полях SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR. Если смещение изменяется на другое значение, новое значение по-прежнему добавляется непосредственно в значение в каждом поле дескриптора. Новое смещение не добавляется в значение поля плюс любое более раннее смещение.
Это поле является отложенным полем: оно не используется во время его установки, но используется в дальнейшем драйвером, когда он должен определить адреса для буферов данных.
Это поле в ARD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_ROW_BIND_OFFSET_PTR. Это поле в ARD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAM_BIND_OFFSET_PTR.
Дополнительные сведения см. в описании привязки по строкам в SQLFetchScroll и SQLBindParameter.
SQL_DESC_BIND_TYPE [дескрипторы приложений]
Это поле заголовка SQLUINTEGER задает ориентацию привязки для привязки столбцов или параметров.
В arDs это поле указывает ориентацию привязки при вызове SQLFetchScroll или SQLFetch в связанном дескрипторе инструкции.
Чтобы выбрать привязку по столбцам, это поле имеет значение SQL_BIND_BY_COLUMN (по умолчанию).
Это поле в ARD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_ROW_BIND_TYPE.
В APD это поле указывает ориентацию привязки, которая будет использоваться для динамических параметров.
Чтобы выбрать привязку столбцов для параметров, это поле имеет значение SQL_BIND_BY_COLUMN (по умолчанию).
Это поле в APD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAM_BIND_TYPE.
SQL_DESC_COUNT [Все]
Это поле заголовка SQLSMALLINT указывает 1-й индекс самой нумероемой записи, содержащей данные. Когда драйвер задает структуру данных для дескриптора, он также должен задать поле SQL_DESC_COUNT, чтобы показать, сколько записей является значительным. Если приложение выделяет экземпляр этой структуры данных, ему не нужно указывать количество записей, для которых требуется резервировать место. Как приложение указывает содержимое записей, драйвер принимает любое необходимое действие, чтобы убедиться, что дескриптор дескриптора ссылается на структуру данных соответствующего размера.
SQL_DESC_COUNT не является числом всех столбцов данных, привязанных (если поле находится в ARD) или всех параметров, привязанных (если поле находится в APD), но число самой многочисленной записи. Если столбец или параметр с наибольшим числом не подключен, SQL_DESC_COUNT изменится на число следующего столбца или параметра с наибольшим числом. Если столбец или параметр с числом меньше числа столбца с наибольшим числом (вызывая SQLBindCol с аргументом TargetValuePtr значение null, или SQLBindParameter с аргументом ParameterValuePtr задано значение NULL), SQL_DESC_COUNT не изменяется. Если дополнительные столбцы или параметры привязаны к числам, превышающим числовой записи, содержащей данные, драйвер автоматически увеличивает значение в поле SQL_DESC_COUNT. Если все столбцы не связаны путем вызова SQLFreeStmt с параметром SQL_UNBIND, для полей SQL_DESC_COUNT в ARD и IRD задано значение 0. Если SQLFreeStmt вызывается с параметром SQL_RESET_PARAMS, для полей SQL_DESC_COUNT в APD и IPD задано значение 0.
Значение в SQL_DESC_COUNT можно задать явным образом приложением, вызвав SQLSetDescField. Если значение в SQL_DESC_COUNT явно уменьшается, все записи с числами, превышающими новое значение в SQL_DESC_COUNT, будут эффективно удалены. Если значение в SQL_DESC_COUNT явно задано значение 0, а поле находится в ARD, все буферы данных, кроме привязанного столбца закладки, освобождаются.
Количество записей в этом поле ARD не включает связанный столбец закладки. Единственным способом отмены привязки столбца закладки является установка поля SQL_DESC_DATA_PTR на пустой указатель.
SQL_DESC_ROWS_PROCESSED_PTR [дескрипторы реализации]
В IRD это поле заголовка SQLULEN * указывает на буфер, содержащий количество строк, извлекаемых после вызова SQLFetch или SQLFetchScroll, или количество строк, затронутых в массовой операции, выполняемой вызовом SQLBulkOperations или SQLSetPos, включая строки ошибок.
В IPD это поле заголовка SQLUINTEGER * указывает на буфер, содержащий количество наборов обработанных параметров, включая наборы ошибок. Число не будет возвращено, если это пустой указатель.
SQL_DESC_ROWS_PROCESSED_PTR действительна только после возврата SQL_SUCCESS или SQL_SUCCESS_WITH_INFO после вызова SQLFetch или SQLFetchScroll (для поля IRD) или SQLExecute, SQLExecDirect или SQLParamData (для поля IPD). Если вызов, который заполняется буфером, на который указывает это поле, не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, содержимое буфера не определено, если он не возвращает SQL_NO_DATA, в этом случае значение в буфере равно 0.
Это поле в ARD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_ROWS_FETCHED_PTR. Это поле в APD также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAMS_PROCESSED_PTR.
Буфер, на который указывает это поле, выделяется приложением. Это отложенный выходной буфер, заданный драйвером. По умолчанию для него задано значение NULL-указателя.
Поля записи
Каждый дескриптор содержит одну или несколько записей, состоящих из полей, определяющих данные столбца или динамические параметры в зависимости от типа дескриптора. Каждая запись представляет собой полное определение одного столбца или параметра.
SQL_DESC_AUTO_UNIQUE_VALUE [IRDs]
Это поле записи только для чтения SQLINTEGER содержит SQL_TRUE, если столбец является автоматическим добавочным столбцом или SQL_FALSE, если столбец не является столбцом автоматического увеличения. Это поле доступно только для чтения, но базовый столбец автоматического увеличения не обязательно доступен только для чтения.
SQL_DESC_BASE_COLUMN_NAME [IRDs]
Это поле записи SQLCHAR только для чтения * содержит имя базового столбца для столбца результирующих наборов. Если имя базового столбца не существует (как в случае столбцов, которые являются выражениями), эта переменная содержит пустую строку.
SQL_DESC_BASE_TABLE_NAME [IRDs]
Это поле записи SQLCHAR только для чтения * содержит имя базовой таблицы для столбца результирующих наборов. Если имя базовой таблицы не может быть определено или неприменимо, эта переменная содержит пустую строку.
SQL_DESC_CASE_SENSITIVE [дескрипторы реализации]
Это поле записи только для чтения SQLINTEGER содержит SQL_TRUE если столбец или параметр обрабатывается как регистр для параметров сортировки и сравнения, или SQL_FALSE, если столбец не учитывается как регистр для параметров сортировки и сравнения, или если он является нехарактерным столбцом.
SQL_DESC_CATALOG_NAME [IRDs]
Это поле записи SQLCHAR только для чтения * содержит каталог базовой таблицы, содержащей столбец. Возвращаемое значение зависит от драйвера, если столбец является выражением или если столбец является частью представления. Если источник данных не поддерживает каталоги или каталог не может быть определен, эта переменная содержит пустую строку.
SQL_DESC_CONCISE_TYPE [Все]
Это поле заголовка SQLSMALLINT указывает краткий тип данных для всех типов данных, включая типы данных datetime и интервала.
Значения полей SQL_DESC_CONCISE_TYPE, SQL_DESC_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE являются взаимозависимыми. Каждый раз, когда задано одно из полей, другое также должно быть задано. SQL_DESC_CONCISE_TYPE можно задать путем вызова SQLBindCol или SQLBindParameter или SQLSetDescField. SQL_DESC_TYPE можно задать путем вызова SQLSetDescField или SQLSetDescRec.
Если для SQL_DESC_CONCISE_TYPE задан краткий тип данных, отличный от типа данных интервала или даты и времени, поле SQL_DESC_TYPE имеет то же значение, а поле SQL_DESC_DATETIME_INTERVAL_CODE имеет значение 0.
Если SQL_DESC_CONCISE_TYPE задано для краткого типа данных datetime или интервала, поле SQL_DESC_TYPE имеет соответствующий подробный тип (SQL_DATETIME или SQL_INTERVAL), а для поля SQL_DESC_DATETIME_INTERVAL_CODE задан соответствующий подкод.
SQL_DESC_DATA_PTR [дескрипторы приложений и IPD]
Это поле записи SQLPOINTER указывает на переменную, содержащую значение параметра (для APD) или значение столбца (для ARD). Это поле является отложенным полем. Он не используется во время установки, но используется в дальнейшем драйвером для получения данных.
Столбец, указанный полем SQL_DESC_DATA_PTR ARD, не является исходящим, если аргумент TargetValuePtr в вызове SQLBindCol является пустым указателем или если поле SQL_DESC_DATA_PTR в ARD устанавливается вызовом SQLSetDescField или SQLSetDescRec на указатель null. Другие поля не затрагиваются, если для поля SQL_DESC_DATA_PTR задано значение NULL-указателя.
Если вызов SQLFetch или SQLFetchScroll , который заполняет буфер, на который указывает это поле, не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, содержимое буфера не определено.
Всякий раз, когда задано SQL_DESC_DATA_PTR поле APD, ARD или IPD, драйвер проверяет, что значение в поле SQL_DESC_TYPE содержит один из допустимых типов данных ODBC C или типа данных, зависящих от драйвера, и что все остальные поля, влияющие на типы данных, согласованы. Запрос проверки согласованности — это единственное использование поля SQL_DESC_DATA_PTR IPD. В частности, если приложение задает поле SQL_DESC_DATA_PTR IPD и более поздних вызовов SQLGetDescField в этом поле, оно не обязательно возвращает заданное значение. Дополнительные сведения см. в разделе "Проверки согласованности" в SQLSetDescRec.
SQL_DESC_DATETIME_INTERVAL_CODE [Все]
Это поле записи SQLSMALLINT содержит подкод для конкретного типа данных datetime или интервала, если поле SQL_DESC_TYPE SQL_DATETIME или SQL_INTERVAL. Это верно для типов данных SQL и C. Код состоит из имени типа данных с "CODE", заменяемого типом "TYPE" или "C_TYPE" (для типов datetime), или "CODE", заменяемых "INTERVAL" или "C_INTERVAL" (для типов интервалов).
Если SQL_DESC_TYPE и SQL_DESC_CONCISE_TYPE в дескрипторе приложения заданы SQL_C_DEFAULT, а дескриптор не связан с дескриптором инструкции, содержимое SQL_DESC_DATETIME_INTERVAL_CODE не определено.
Это поле можно задать для типов данных datetime, перечисленных в следующей таблице.
| Типы даты и времени | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_TYPE_DATE/SQL_C_TYPE_DATE | SQL_CODE_DATE |
| SQL_TYPE_TIME/SQL_C_TYPE_TIME | SQL_CODE_TIME |
| SQL_TYPE_TIMESTAMP/ SQL_C_TYPE_TIMESTAMP | SQL_CODE_TIMESTAMP |
Это поле можно задать для типов данных интервала, перечисленных в следующей таблице.
| Тип интервала | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_INTERVAL_DAY/ SQL_C_INTERVAL_DAY | SQL_CODE_DAY |
| SQL_INTERVAL_DAY_TO_HOUR/ SQL_C_INTERVAL_DAY_TO_HOUR | SQL_CODE_DAY_TO_HOUR |
| SQL_INTERVAL_DAY_TO_MINUTE/ SQL_C_INTERVAL_DAY_TO_MINUTE | SQL_CODE_DAY_TO_MINUTE |
| SQL_INTERVAL_DAY_TO_SECOND/ SQL_C_INTERVAL_DAY_TO_SECOND | SQL_CODE_DAY_TO_SECOND |
| SQL_INTERVAL_HOUR/ SQL_C_INTERVAL_HOUR | SQL_CODE_HOUR |
| SQL_INTERVAL_HOUR_TO_MINUTE/ SQL_C_INTERVAL_HOUR_TO_MINUTE | SQL_CODE_HOUR_TO_MINUTE |
| SQL_INTERVAL_HOUR_TO_SECOND/ SQL_C_INTERVAL_HOUR_TO_SECOND | SQL_CODE_HOUR_TO_SECOND |
| SQL_INTERVAL_MINUTE/ SQL_C_INTERVAL_MINUTE | SQL_CODE_MINUTE |
| SQL_INTERVAL_MINUTE_TO_SECOND/ SQL_C_INTERVAL_MINUTE_TO_SECOND | SQL_CODE_MINUTE_TO_SECOND |
| SQL_INTERVAL_MONTH/ SQL_C_INTERVAL_MONTH | SQL_CODE_MONTH |
| SQL_INTERVAL_SECOND/ SQL_C_INTERVAL_SECOND | SQL_CODE_SECOND |
| SQL_INTERVAL_YEAR/ SQL_C_INTERVAL_YEAR | SQL_CODE_YEAR |
| SQL_INTERVAL_YEAR_TO_MONTH/ SQL_C_INTERVAL_YEAR_TO_MONTH | SQL_CODE_YEAR_TO_MONTH |
Дополнительные сведения о интервалах данных и этом поле см. в разделе "Идентификаторы типов данных" и "Дескрипторы".
SQL_DESC_DATETIME_INTERVAL_PRECISION [Все]
Это поле записи SQLINTEGER содержит интервал начальной точности, если поле SQL_DESC_TYPE SQL_INTERVAL. Если для поля SQL_DESC_DATETIME_INTERVAL_CODE задан тип данных интервала, это поле устанавливается в качестве интервала по умолчанию для начальной точности.
SQL_DESC_DISPLAY_SIZE [IRDs]
Это поле записи только для чтения SQLINTEGER содержит максимальное количество символов, необходимых для отображения данных из столбца.
SQL_DESC_FIXED_PREC_SCALE [дескрипторы реализации]
Это поле записи SQLSMALLINT только для чтения имеет значение SQL_TRUE если столбец является точным числовым столбцом и имеет фиксированную точность и ненулевое масштабирование, или SQL_FALSE, если столбец не является точным числовым столбцом с фиксированной точностью и масштабом.
SQL_DESC_INDICATOR_PTR [дескрипторы приложений]
В ARD это поле записи SQLLEN * указывает на переменную индикатора. Эта переменная содержит SQL_NULL_DATA, если значение столбца равно NULL. Для APD переменная индикатора имеет значение SQL_NULL_DATA для указания динамических аргументов NULL. В противном случае переменная равна нулю (если значения в SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR совпадают с указателем).
Если поле SQL_DESC_INDICATOR_PTR в ARD является указателем null, драйвер не может возвращать сведения о том, имеет ли столбец ЗНАЧЕНИЕ NULL или нет. Если столбец имеет значение NULL и SQL_DESC_INDICATOR_PTR является пустым указателем, SQLSTATE 22002 (переменная индикатора, требуемая, но не указана), возвращается, когда драйвер пытается заполнить буфер после вызова SQLFetch или SQLFetchScroll. Если вызов SQLFetch или SQLFetchScroll не вернул SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, содержимое буфера не определено.
Поле SQL_DESC_INDICATOR_PTR определяет, задано ли поле, на которое указывает SQL_DESC_OCTET_LENGTH_PTR. Если значение данных для столбца равно NULL, драйвер задает переменную индикатора SQL_NULL_DATA. Поле, на которое указывает SQL_DESC_OCTET_LENGTH_PTR, затем не задано. Если значение NULL не встречается во время получения, буфер, на который указывает SQL_DESC_INDICATOR_PTR, равно нулю, а буфер, на который указывает SQL_DESC_OCTET_LENGTH_PTR, имеет длину данных.
Если поле SQL_DESC_INDICATOR_PTR в APD является указателем NULL, приложение не может использовать эту запись дескриптора для указания аргументов NULL.
Это поле является отложенным полем: оно не используется во время его установки, но используется в последующее время драйвером, чтобы указать значение NULL (для ARD) или определить значение NULL (для APD).
SQL_DESC_LABEL [IRDs]
Это поле записи только для чтения SQLCHAR * содержит метку столбца или заголовок. Если столбец не имеет метки, эта переменная содержит имя столбца. Если столбец неназван и не помечен, эта переменная содержит пустую строку.
SQL_DESC_LENGTH [Все]
Это поле записи SQLULEN — это максимальная или фактическая длина символьной строки в символах или двоичном типе данных в байтах. Это максимальная длина типа данных фиксированной длины или фактической длины для типа данных переменной длины. Его значение всегда исключает символ завершения null, заканчивающий строку символа. Для значений, тип которых SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP или одного из типов данных интервала SQL, это поле имеет длину в символах символьного строкового представления значения даты и интервала.
Значение в этом поле может отличаться от значения "длина", как определено в ODBC 2*.x*. Дополнительные сведения см. в приложении D: Типы данных.
SQL_DESC_LITERAL_PREFIX [IRDs]
Это поле записи только для чтения SQLCHAR * содержит символ или символы, которые драйвер распознает как префикс для литерала этого типа данных. Эта переменная содержит пустую строку для типа данных, для которого не применяется префикс литерала.
SQL_DESC_LITERAL_SUFFIX [IRDs]
Это поле записи SQLCHAR только для чтения * содержит символ или символы, которые драйвер распознает как суффикс для литерала этого типа данных. Эта переменная содержит пустую строку для типа данных, для которого не применяется литеральный суффикс.
SQL_DESC_LOCAL_TYPE_NAME [дескрипторы реализации]
Это поле записи sqlCHAR только для чтения * содержит любое локализованное (машинное имя) для типа данных, который может отличаться от регулярного имени типа данных. Если локализованное имя отсутствует, возвращается пустая строка. Это поле предназначено только для отображения.
SQL_DESC_NAME [дескрипторы реализации]
Это поле записи SQLCHAR * в дескрипторе строки содержит псевдоним столбца, если он применяется. Если псевдоним столбца не применяется, возвращается имя столбца. В любом случае драйвер задает поле SQL_DESC_UNNAMED для SQL_NAMED при установке поля SQL_DESC_NAME. Если имя столбца или псевдоним столбца отсутствует, драйвер возвращает пустую строку в поле SQL_DESC_NAME и задает для поля SQL_DESC_UNNAMED значение SQL_UNNAMED.
Приложение может задать для поля SQL_DESC_NAME IPD имя параметра или псевдоним, чтобы указать параметры хранимой процедуры по имени. (Дополнительные сведения см. в разделе Привязка параметров по имени (именованные параметры).) Поле SQL_DESC_NAME IRD — это поле только для чтения; SQLSTATE HY091 (недопустимый идентификатор поля дескриптора) будет возвращен, если приложение пытается задать его.
В IPD это поле не определено, если драйвер не поддерживает именованные параметры. Если драйвер поддерживает именованные параметры и способен описывать параметры, имя параметра возвращается в этом поле.
SQL_DESC_NULLABLE [дескрипторы реализации]
В IRD это поле записи SQLSMALLINT только для чтения SQL_NULLABLE, если столбец может иметь значения NULL, SQL_NO_NULLS, если столбец не имеет значений NULL, или SQL_NULLABLE_UNKNOWN, если столбец принимает значения NULL. Это поле относится к столбцу результирующих наборов, а не к базовому столбцу.
В IPD это поле всегда имеет значение SQL_NULLABLE, так как динамические параметры всегда имеют значение NULL и не могут быть заданы приложением.
SQL_DESC_NUM_PREC_RADIX [Все]
Это поле SQLINTEGER содержит значение 2, если тип данных в поле SQL_DESC_TYPE является приблизительным числовым типом данных, так как поле SQL_DESC_PRECISION содержит количество битов. Это поле содержит значение 10, если тип данных в поле SQL_DESC_TYPE является точным числовым типом данных, так как поле SQL_DESC_PRECISION содержит число десятичных цифр. Это поле имеет значение 0 для всех нечисловых типов данных.
SQL_DESC_OCTET_LENGTH [Все]
Это поле записи SQLLEN содержит длину в байтах символьной строки или двоичного типа данных. Для символов фиксированной длины или двоичных типов это фактическая длина в байтах. Для символов переменной длины или двоичных типов это максимальная длина в байтах. Это значение всегда исключает пробел для символа завершения null для дескрипторов реализации и всегда включает пробел для символа завершения null для дескрипторов приложений. Для данных приложения это поле содержит размер буфера. Для APD это поле определяется только для выходных или входных и выходных параметров.
SQL_DESC_OCTET_LENGTH_PTR [дескрипторы приложений]
Это поле записи SQLLEN * указывает на переменную, содержащую общую длину в байтах динамического аргумента (для дескрипторов параметров) или связанного значения столбца (для дескрипторов строк).
Для APD это значение игнорируется для всех аргументов, кроме строки символов и двоичного файла; Если это поле указывает на SQL_NTS, динамический аргумент должен быть прерван. Чтобы указать, что привязанный параметр будет параметром данных во время выполнения, приложение задает это поле в соответствующей записи APD переменной, которая во время выполнения будет содержать значение SQL_DATA_AT_EXEC или результат макроса SQL_LEN_DATA_AT_EXEC. Если существует несколько таких полей, SQL_DESC_DATA_PTR можно задать значение, однозначно определяющее параметр, чтобы помочь приложению определить, какой параметр запрашивается.
Если поле OCTET_LENGTH_PTR ARD является пустым указателем, драйвер не возвращает сведения о длине столбца. Если поле SQL_DESC_OCTET_LENGTH_PTR APD является пустым указателем, драйвер предполагает, что строки символов и двоичные значения прерваны null. (Двоичные значения не должны быть прерваны null, но следует указать длину, чтобы избежать усечения.)
Если вызов SQLFetch или SQLFetchScroll , который заполняет буфер, на который указывает это поле, не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, содержимое буфера не определено. Это поле является отложенным полем. Он не используется во время установки, но используется в дальнейшем драйвером для определения или указания длины октета данных.
SQL_DESC_PARAMETER_TYPE [IPD]
Это поле записи SQLSMALLINT имеет значение SQL_PARAM_INPUT для входного параметра, SQL_PARAM_INPUT_OUTPUT для входного и выходного параметра, SQL_PARAM_OUTPUT для выходного параметра, SQL_PARAM_INPUT_OUTPUT_STREAM для входного или выходного потока или SQL_PARAM_OUTPUT_STREAM для выходного потока. По умолчанию для него задано значение SQL_PARAM_INPUT.
Для IPD поле по умолчанию SQL_PARAM_INPUT, если IPD не заполняется драйвером (атрибут инструкции SQL_ATTR_ENABLE_AUTO_IPD SQL_FALSE). Приложение должно задать это поле в IPD для параметров, которые не являются входными параметрами.
SQL_DESC_PRECISION [Все]
Это поле записи SQLSMALLINT содержит число цифр для точного числового типа, количество битов в мантиссе (двоичная точность) для приблизительного числового типа или числа цифр в компоненте дробных секунд для типа данных SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP или SQL_INTERVAL_SECOND типа данных. Это поле не определено для всех других типов данных.
Значение в этом поле может отличаться от значения точности, как определено в ODBC 2*.x*. Дополнительные сведения см. в приложении D: Типы данных.
SQL_DESC_ROWVER [дескрипторы реализации]
Это поле SQLSMALLINTrecord указывает, будет ли столбец автоматически изменяться СУБД при обновлении строки (например, столбец типа "метка времени" в SQL Server). Значение этого поля записи имеет значение SQL_TRUE, если столбец является столбцом управления версиями строк и SQL_FALSE в противном случае. Этот атрибут столбца аналогичен вызову SQLSpecialColumns с идентификатором идентификатора SQL_ROWVER, чтобы определить, обновляется ли столбец автоматически.
SQL_DESC_SCALE [Все]
Это поле записи SQLSMALLINT содержит определенный масштаб для десятичных и числовых типов данных. Поле не определено для всех других типов данных.
Значение в этом поле может отличаться от значения "scale", как определено в ODBC 2*.x*. Дополнительные сведения см. в приложении D: Типы данных.
SQL_DESC_SCHEMA_NAME [IRDs]
Это поле записи SQLCHAR только для чтения * содержит имя схемы базовой таблицы, содержащей столбец. Возвращаемое значение зависит от драйвера, если столбец является выражением или если столбец является частью представления. Если источник данных не поддерживает схемы или имя схемы невозможно определить, эта переменная содержит пустую строку.
SQL_DESC_SEARCHABLE [IRDs]
Это поле записи SQLSMALLINT только для чтения имеет одно из следующих значений:
SQL_PRED_NONE, если столбец не может использоваться в предложении WHERE . (Это же значение SQL_UNSEARCHABLE в ODBC 2*.x*.)
SQL_PRED_CHAR, если столбец можно использовать в предложении WHERE , но только с предикатом LIKE . (Это же значение SQL_LIKE_ONLY в ODBC 2*.x*.)
SQL_PRED_BASIC, если столбец можно использовать в предложении WHERE со всеми операторами сравнения, кроме LIKE. (Это же значение SQL_EXCEPT_LIKE в ODBC 2*.x*.)
SQL_PRED_SEARCHABLE, если столбец можно использовать в предложении WHERE с любым оператором сравнения.
SQL_DESC_TABLE_NAME [IRDs]
Это поле записи SQLCHAR только для чтения * содержит имя базовой таблицы, содержащей этот столбец. Возвращаемое значение зависит от драйвера, если столбец является выражением или если столбец является частью представления.
SQL_DESC_TYPE [Все]
Это поле записи SQLSMALLINT указывает краткий тип данных SQL или C для всех типов данных, кроме типов данных даты и интервала. Для типов данных datetime и интервала в этом поле указывается подробный тип данных, который SQL_DATETIME или SQL_INTERVAL.
Если это поле содержит SQL_DATETIME или SQL_INTERVAL, поле SQL_DESC_DATETIME_INTERVAL_CODE должно содержать соответствующий подкод для краткого типа. Для типов данных datetime SQL_DESC_TYPE содержит SQL_DATETIME, а поле SQL_DESC_DATETIME_INTERVAL_CODE содержит подкод для конкретного типа данных datetime. Для типов данных интервала SQL_DESC_TYPE содержит SQL_INTERVAL, а поле SQL_DESC_DATETIME_INTERVAL_CODE содержит подкод для определенного типа данных интервала.
Значения полей SQL_DESC_TYPE и SQL_DESC_CONCISE_TYPE являются взаимозависимыми. Каждый раз, когда задано одно из полей, другое также должно быть задано. SQL_DESC_TYPE можно задать путем вызова SQLSetDescField или SQLSetDescRec. SQL_DESC_CONCISE_TYPE можно задать путем вызова SQLBindCol или SQLBindParameter или SQLSetDescField.
Если для SQL_DESC_TYPE задан краткий тип данных, отличный от интервала или типа данных datetime, поле SQL_DESC_CONCISE_TYPE имеет то же значение, а поле SQL_DESC_DATETIME_INTERVAL_CODE имеет значение 0.
Если для SQL_DESC_TYPE задан подробный тип данных datetime или интервала (SQL_DATETIME или SQL_INTERVAL), а для поля SQL_DESC_DATETIME_INTERVAL_CODE задан соответствующий вложенный код, поле SQL_DESC_CONCISE TYPE имеет соответствующий краткий тип. При попытке задать SQL_DESC_TYPE один из кратких типов даты и интервала возвращается SQLSTATE HY021 (несогласованные сведения о дескрипторе).
Если поле SQL_DESC_TYPE задано вызовом SQLBindCol, SQLBindParameter или SQLSetDescField, для следующих полей заданы следующие значения по умолчанию, как показано в таблице ниже. Значения оставшихся полей одной записи не определены.
| Значение SQL_DESC_TYPE | Другие поля неявно заданы |
|---|---|
| SQL_CHAR, SQL_VARCHAR, SQL_C_CHAR, SQL_C_VARCHAR | SQL_DESC_LENGTH имеет значение 1. SQL_DESC_PRECISION имеет значение 0. |
| SQL_DATETIME | Если SQL_DESC_DATETIME_INTERVAL_CODE задано значение SQL_CODE_DATE или SQL_CODE_TIME, SQL_DESC_PRECISION имеет значение 0. Если для него задано значение SQL_DESC_TIMESTAMP, SQL_DESC_PRECISION имеет значение 6. |
| SQL_DECIMAL, SQL_NUMERIC, SQL_C_NUMERIC | SQL_DESC_SCALE имеет значение 0. SQL_DESC_PRECISION задана точность, определяемая реализацией для соответствующего типа данных. Сведения о том, как вручную привязать значение SQL_C_NUMERIC, см . в sql to C: Numeric . |
| SQL_FLOAT, SQL_C_FLOAT | SQL_DESC_PRECISION задана точность по умолчанию по умолчанию для SQL_FLOAT. |
| SQL_INTERVAL | Если для SQL_DESC_DATETIME_INTERVAL_CODE задан тип данных интервала, SQL_DESC_DATETIME_INTERVAL_PRECISION имеет значение 2 (по умолчанию — начальная точность интервала по умолчанию). Если интервал имеет компонент секунд, SQL_DESC_PRECISION имеет значение 6 (точность интервала по умолчанию). |
Когда приложение вызывает SQLSetDescField для задания полей дескриптора, а не вызова SQLSetDescRec, приложение должно сначала объявить тип данных. При этом другие поля, указанные в предыдущей таблице, неявно задаются. Если любое из значений неявно задано неприемлемо, приложение может вызвать SQLSetDescField или SQLSetDescRec , чтобы задать недопустимое значение явным образом.
SQL_DESC_TYPE_NAME [дескрипторы реализации]
Это поле записи SQLCHAR только для чтения * содержит имя типа, зависяющего от источника данных (например, CHAR, VARCHAR и т. д.). Если имя типа данных неизвестно, эта переменная содержит пустую строку.
SQL_DESC_UNNAMED [дескрипторы реализации]
Это поле записи SQLSMALLINT в дескрипторе строк устанавливается драйвером как SQL_NAMED, так и SQL_UNNAMED при установке поля SQL_DESC_NAME. Если поле SQL_DESC_NAME содержит псевдоним столбца или если псевдоним столбца не применяется, драйвер задает поле SQL_DESC_UNNAMED для SQL_NAMED. Если приложение задает для SQL_DESC_NAME поля IPD имя или псевдоним параметра, драйвер задает SQL_DESC_UNNAMED поле IPD SQL_NAMED. Если имя столбца или псевдоним столбца отсутствует, драйвер задает для SQL_UNNAMED поле SQL_DESC_UNNAMED.
Приложение может задать для SQL_DESC_UNNAMED поля IPD значение SQL_UNNAMED. Драйвер возвращает SQLSTATE HY091 (недопустимый идентификатор поля дескриптора), если приложение пытается задать для SQL_DESC_UNNAMED поля IPD значение SQL_NAMED. Поле SQL_DESC_UNNAMED IRD доступно только для чтения; SQLSTATE HY091 (недопустимый идентификатор поля дескриптора) будет возвращен, если приложение пытается задать его.
SQL_DESC_UNSIGNED [дескрипторы реализации]
Это поле записи SQLSMALLINT только для чтения имеет значение SQL_TRUE если тип столбца незначен или не является числовым, или SQL_FALSE, если тип столбца подписан.
SQL_DESC_UPDATABLE [IRDs]
Это поле записи SQLSMALLINT только для чтения имеет одно из следующих значений:
SQL_ATTR_READ_ONLY, если столбец результирующих наборов доступен только для чтения.
SQL_ATTR_WRITE, если столбец результирующих наборов является чтением и записью.
SQL_ATTR_READWRITE_UNKNOWN, если не известно, является ли столбец результирующих наборов обновляемым или нет.
SQL_DESC_UPDATABLE описывает обновляемость столбца в результирующем наборе, а не столбца в базовой таблице. Обновляемость столбца в базовой таблице, на которой основан этот столбец результирующий набор, может отличаться от значения в этом поле. Может ли столбец обновляться на основе типа данных, привилегий пользователей и определения самого результирующий набор. Если неясно, является ли столбец обновляемым, SQL_ATTR_READWRITE_UNKNOWN следует вернуть.
Проверки согласованности
Проверка согласованности выполняется драйвером автоматически, когда приложение передает значение для поля SQL_DESC_DATA_PTR ARD, APD или IPD. Если любое из полей не соответствует другим полям, SQLSetDescField вернет SQLSTATE HY021 (несогласованные сведения о дескрипторе). Дополнительные сведения см. в разделе "Проверка согласованности" в SQLSetDescRec.
Связанные функции
| Сведения | Раздел |
|---|---|
| Привязка столбца | Функция SQLBindCol |
| Привязка параметра | Функция SQLBindParameter |
| Получение поля дескриптора | Функция SQLGetDescField |
| Получение нескольких полей дескриптора | Функция SQLGetDescRec |
| Настройка нескольких полей дескриптора | Функция SQLSetDescRec |