Функция SQLSetDescField

Соответствие
Введенная версия: Соответствие стандартам ODBC 3.0: ISO 92

Сводка
SQLSetDescField задаёт значение одного поля записи дескриптора.

Syntax

SQLRETURN SQLSetDescField(  
     SQLHDESC      DescriptorHandle,  
     SQLSMALLINT   RecNumber,  
     SQLSMALLINT   FieldIdentifier,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    BufferLength);  

Arguments

DescriptorHandle
[Ввод] Дескрипторная ручка.

RecNumber
[Ввод] Указывает запись дескриптора, содержащая поле, которое приложение стремится завести. Записи Descriptor нумеруются начиная с 0, при этом запись нумеруется как запись с закладкой. Аргумент RecNumber игнорируется для полей заголовка.

FieldIdentifier
[Ввод] Указывает поле дескриптора, значение которого должно быть зададено. Для получения дополнительной информации см. раздел «Аргумент FieldIdentifier » в разделе «Комментарии».

ValuePtr
[Ввод] Указатель на буфер, содержащий информацию о дескрипторе, или на целое значение. Тип данных зависит от значения FieldIdentifier. Если ValuePtr является целочисленным значением, его можно рассматривать как 8 байт (SQLLEN), 4 байта (SQLINTEGER) или 2 байта (SQLSMALLINT), в зависимости от значения аргумента FieldIdentifier .

BufferLength
[Ввод] Если FieldIdentifier — это поле, определённое ODBC, и ValuePtr указывает на строку символа или бинарный буфер, этот аргумент должен быть длиной *ValuePtr. Для данных строк символов этот аргумент должен содержать количество байт в строке.

Если FieldIdentifier — это поле, определённое ODBC, а ValuePtr — целое число, BufferLength игнорируется.

Если FieldIdentifier — это поле, определяемое драйвером, приложение указывает природу поля Driver Manager, устанавливая аргумент BufferLength . BufferLength может иметь следующие значения:

• Если ValuePtr — это указатель на строку символа, то BufferLength — это длина строки или SQL_NTS.

• Если ValuePtr является указателем на двоичный буфер, то приложение помещает результат макроса SQL_LEN_BINARY_ATTR(length) в BufferLength. Это ставит отрицательное значение в BufferLength.

• Если ValuePtr — это указатель на значение, отличное от строки символа или бинарной строки, то BufferLength должен иметь значение SQL_IS_POINTER.

• Если ValuePtr содержит значение фиксированной длины, то BufferLength — это либо SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT или SQL_IS_USMALLINT, в зависимости от необходимости.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Diagnostics

Когда SQLSetDescField возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_DESC и HandleDescriptorHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращает SQLSetDescField , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

Comments

Приложение может вызвать SQLSetDescField для установки любого дескрипторного поля по одному. Один вызов SQLSetDescField задаёт одно поле в одном дескрипторе. Эту функцию можно вызвать для задания любого поля в любом типе дескриптора, при условии, что это поле может быть установлено. (См. таблицу ниже в этом разделе.)

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

Поля заголовков Descriptor задаются вызовом SQLSetDescField с соответствующим идентификатором поля. Многие поля заголовков также являются атрибутами операторов, поэтому их можно также задать вызовом SQLSetStmtAttr. Это позволяет приложениям задавать поле дескриптора без предварительного получения дескрипторного дескриптора. Когда SQLSetDescField вызывается для установки заголовочного поля, аргумент RecNumber игнорируется.

Для установки полей закладок используется RecNumber 0.

Последовательность полей дескрипторов настроек

При установке дескрипторных полей с помощью вызова SQLSetDescField приложение должно следовать определённой последовательности:

1. В приложении сначала должно быть указано поле SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE или SQL_DESC_DATETIME_INTERVAL_CODE.

2. После того как одно из этих полей установлено, приложение может задать атрибут типа данных, а драйвер устанавливает поля атрибутов типа данных на соответствующие значения по умолчанию для этого типа. Автоматическое удаление полей атрибутов типа по умолчанию гарантирует, что дескриптор всегда готов к использованию после того, как приложение определило тип данных. Если приложение явно устанавливает атрибут типа данных, оно переопределяет стандартный атрибут.

3. После того как одно из полей, указанных на шаге 1, и атрибуты типа данных установлены, приложение может установить SQL_DESC_DATA_PTR. Это вызывает проверку согласованности дескрипторных полей. Если приложение меняет тип данных или атрибуты после установки поля SQL_DESC_DATA_PTR, драйвер устанавливает SQL_DESC_DATA_PTR на нулевой указатель, развязывая запись. Это заставляет приложение выполнять правильные шаги последовательно, прежде чем запись дескриптора станет пригодна.

Инициализация полей дескриптора

Когда выделен дескриптор, поля в дескрипторе могут быть инициализованы по умолчанию, инициализированы без стандартного значения или не определёнными для типа дескриптора. Следующие таблицы показывают инициализацию каждого поля для каждого типа дескриптора: «D» означает, что поле инициализовано по умолчанию, а «ND» — что поле инициализовано без стандартного значения. Если отображается число, значение поля по умолчанию — это именно это число. Таблицы также указывают, является ли поле чтением/записью (R/W) или только для чтения (R).

Поля IRD имеют значение по умолчанию только после того, как оператор был подготовлен или выполнен и IRD заполнен, а не после выделения оператора или дескриптора. Пока IRD не будет заполнен, любая попытка получить доступ к полю IRD приведёт к ошибке.

Некоторые дескрипторные поля определяются для одного или нескольких, но не всех типов дескрипторов (ARD и IRD, APD и IPD). Когда поле не определёно для типа дескриптора, оно не требуется ни одной из функций, использующих этот дескриптор.

Поля, доступные через SQLGetDescField , не обязательно устанавливаются SQLSetDescField. Поля, которые могут быть установлены SQLSetDescField , перечислены в следующих таблицах.

Инициализация полей заголовков изложена в приведённой ниже таблице.

[1] Эти поля определяются только тогда, когда IPD автоматически заполняется драйвером. Если нет, они не определены. Если приложение пытается задать эти поля, будет возвращен SQLSTATE HY091 (Invalid descriptor field identifier).

Инициализация полей записи показана в следующей таблице.

[1] Эти поля определяются только тогда, когда IPD автоматически заполняется драйвером. Если нет, они не определены. Если приложение пытается задать эти поля, будет возвращен SQLSTATE HY091 (Invalid descriptor field identifier).

[2] Поле SQL_DESC_DATA_PTR в IPD можно настроить так, чтобы принудительно провести проверку согласованности. В последующем вызове SQLGetDescField или SQLGetDescRec драйвер не обязан возвращать значение, которое SQL_DESC_DATA_PTR было установлено.

Аргумент идентификатора поля

Аргумент FieldIdentifier указывает на задающее дескрипторное поле. Дескриптор содержит заголовок дескриптора, состоящий из полей заголовка, описанных в следующем разделе «Поля заголовка», и нуля или более записей дескрипторов, состоящих из полей записей, описанных в разделе после раздела «Поля заголовка».

Заголовочные поля

Каждый дескриптор имеет заголовок, состоящий из следующих полей:

SQL_DESC_ALLOC_TYPE [Все]
Это поле заголовка SQLSMALLINT только для чтения указывает, был ли дескриптор выделен автоматически драйвером или явно приложением. Приложение может получить, но не изменять это поле. Поле задаётся SQL_DESC_ALLOC_AUTO драйвером, если дескриптор был автоматически выделен драйвером. Драйвер устанавливает SQL_DESC_ALLOC_USER, если дескриптор был явно выделен приложением.

SQL_DESC_ARRAY_SIZE [Дескрипторы применения]
В ARD это поле заголовка 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. Массив содержит столько элементов, сколько и строк в наборе рядов. Приложение должно выделить массив SQLUSMALLINT и установить это поле так, чтобы оно указывало на массивы. По умолчанию поле установлено как нулевой указатель. Драйвер заполняет массив — если только поле SQL_DESC_ARRAY_STATUS_PTR не установлено на нулевой указатель, тогда значения статуса не генерируются и массив не заполняется.

Массив изначально заполняется вызовом 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, содержимое массива, на которое указывает это поле, остаётся неопределённым. Приложение должно выделить массив SQLUSMALLINT и установить это поле так, чтобы оно указывало на массивы. Драйвер заполняет массив — если только поле SQL_DESC_ARRAY_STATUS_PTR не установлено на нулевой указатель, тогда значения статуса не генерируются и массив не заполняется. Элементы массива могут содержать следующие значения:

• 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.

Если элементы массива не установлены, все строки включаются в операцию bulk. Если значение в поле SQL_DESC_ARRAY_STATUS_PTR ARD является нулевым указателем, все строки включаются в операцию bulk; Интерпретация такая же, как если бы указатель указывал на действительный массив и все элементы массива были 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 * указывает на смещение связывания. По умолчанию он установлен на нулевой указатель. Если это поле не является нулевым указателем, драйвер дедеферирует указатель и добавляет дедеференцированное значение каждому из отложенных полей, которые имеют ненулевые значения в записи дескриптора (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 задаёт ориентацию связки для привязки либо столбцов, либо параметров.

В ARD это поле задаёт ориентацию связки, когда 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 на нулевой указатель, или SQLBindParameter с аргументом ParameterValuePtr , установленным на нулевой указатель), 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.

Буфер, на который указывает это поле, выделяется приложением. Это буфер с отложенным выходом, который устанавливается драйвером. По умолчанию он установлен на нулевой указатель.

Рекордные поля

Каждый дескриптор содержит одну или несколько записей, состоящих из полей, определяющих либо столбцовые данные, либо динамические параметры в зависимости от типа дескриптора. Каждая запись — это полное определение одного столбца или параметра.

SQL_DESC_AUTO_UNIQUE_VALUE [IRDs]
Это поле записи SQLINTEGER только для чтения содержит SQL_TRUE, является ли столбец авто-инкрементующимся, или SQL_FALSE, если столбец не является авто-инкрементующимся. Это поле только для чтения, но столбец автоувеличения не обязательно является только для чтения.

SQL_DESC_BASE_COLUMN_NAME [IRDs]
Это поле записи SQLCHAR * только для чтения содержит базовое имя столбца для столбца набора результатов. Если имя базового столбца не существует (как в случае столбцов, являющихся выражениями), эта переменная содержит пустую строку.

SQL_DESC_BASE_TABLE_NAME [IRD]
Это поле записи SQLCHAR * только для чтения содержит базовое название таблицы столбца набора результатов. Если имя базовой таблицы невозможно определить или не применимо, эта переменная содержит пустую строку.

SQL_DESC_CASE_SENSITIVE [Дескрипторы реализации]
Это поле записи SQLINTEGER, предназначенное только для чтения, содержит SQL_TRUE, считается ли столбец или параметр чувствительным к регистру при сближениях и сравнениях, или SQL_FALSE, если столбец не считается чувствительным к регистру для сравнений и сравнений или если это несимвольный столбец.

SQL_DESC_CATALOG_NAME [IRD]
Это поле записи SQLCHAR * только для чтения содержит каталог базовой таблицы, содержащей столбец. Возвращаемое значение зависит от драйвера, является ли столбец выражением или если столбец является частью представления. Если источник данных не поддерживает каталоги или каталог не может быть определен, эта переменная содержит пустую строку.

SQL_DESC_CONCISE_TYPE [Все]
Это поле заголовка SQLSMALLINT определяет краткий тип данных для всех типов данных, включая типы данных datetime и interval data.

Значения в полях 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 установлен на краткий тип данных времени или интервала, поле 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 нулевого указателя. Другие поля не затрагиваются, если поле SQL_DESC_DATA_PTR установлено на нулевой указатель.

Если вызов 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 содержит подкод для конкретного типа данных времени или интервала, когда поле 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, указанных в следующей таблице.

Это поле можно задать для типов интервальных данных, указанных в следующей таблице.

Для получения дополнительной информации о интервалах данных и этом поле см. раздел «Идентификаторы и дескрипторы типов данных».

SQL_DESC_DATETIME_INTERVAL_PRECISION [Все]
Это поле записи SQLINTEGER содержит интервальную точность лидера, если поле SQL_DESC_TYPE SQL_INTERVAL. Когда поле SQL_DESC_DATETIME_INTERVAL_CODE устанавливается на тип интервальных данных, это поле устанавливается с точностью по умолчанию с интервалом ведущей.

SQL_DESC_DISPLAY_SIZE [IRD]
Это поле записи 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, а SQL_DESC_INDICATOR_PTR — нулевой указатель, SQLSTATE 22002 (Indicator variable required, но не предоставляется) возвращается, когда драйвер пытается заполнить буфер после вызова 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 аргументов.

Это поле является отложенным полем: оно не используется в момент установки, а позже используется драйвером для обозначения нулевости (для ARD) или для определения нулевости (для APD).

SQL_DESC_LABEL [ИРД]
Это поле записи SQLCHAR * только для чтения содержит метку или заголовок столбца. Если столбец не имеет метки, эта переменная содержит имя столбца. Если столбец не имеет имени и не имеет меток, эта переменная содержит пустую строку.

SQL_DESC_LENGTH [Все]
Это поле записи SQLULEN — это либо максимальная, либо фактическая длина строки символа в символах, либо бинарный тип данных в байтах. Это максимальная длина для типа данных с фиксированной длиной или фактическая длина для типа данных с переменной длиной. Его значение всегда исключает символ нулевой терминации, заканчивающий строку символа. Для значений, типы которых — SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP или один из типов данных интервала SQL, это поле имеет длину в символах значения значения datetime или interval в символах.

Значение в этом поле может отличаться от значения «длины», определённого в ODBC 2*.x*. Для получения дополнительной информации см. Приложение D: Типы данных.

SQL_DESC_LITERAL_PREFIX [ИРД]
Это поле записи SQLCHAR * только для чтения содержит символ или символы, которые драйвер распознаёт как префикс для литерала этого типа данных. Эта переменная содержит пустую строку для типа данных, для которого не применим литеральный префикс.

SQL_DESC_LITERAL_SUFFIX [IRD]
Это поле записи 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, поскольку динамические параметры всегда обнулены и не могут быть зададены приложением.

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 содержит длину в байтах строки символа или бинарного типа данных. Для типов символов фиксированной длины или двоичных типов это фактическая длина в байтах. Для типов символов или двоичных типов переменной длины это максимальная длина в байтах. Это значение всегда исключает пространство для символа нулевой терминации для дескрипторов реализации и всегда включает место для символа нулевой терминации для дескрипторов приложений. Для данных приложений это поле содержит размер буфера. Для 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 является нулевым указателем, драйвер предполагает, что строки символов и бинарные значения являются нулевыми терминами. (Бинарные значения не должны быть нулевыми терминированными, но им следует присваивать длину, чтобы избежать усечения.)

Если вызов 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, если драйвер не заполняется автоматически (атрибут оператора 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 показывает, изменяется ли столбец автоматически СУБД при обновлении строки (например, столбец типа «timestamp» в SQL Server). Значение этого поля записи устанавливается как SQL_TRUE, если столбец является столбцем версии строки, и SQL_FALSE в противном случае. Этот атрибут столбца похож на вызов SQLSpecialColumns с IdentifierType SQL_ROWVER для определения автоматического обновления столбца.

SQL_DESC_SCALE [Все]
Это поле записи SQLSMALLINT содержит определённый масштаб для десятичных и числовых типов данных. Это поле не определено для всех остальных типов данных.

Значение в этом поле может отличаться от значения «масштаба», определённого в ODBC 2*.x*. Для получения дополнительной информации см. Приложение D: Типы данных.

SQL_DESC_SCHEMA_NAME [IRDs]
Это поле записи SQLCHAR * только для чтения содержит имя схемы базовой таблицы, содержащей столбец. Возвращаемое значение зависит от драйвера, является ли столбец выражением или если столбец является частью представления. Если источник данных не поддерживает схемы или имя схемы невозможно определить, эта переменная содержит пустую строку.

SQL_DESC_SEARCHABLE [ИРД]
Это поле записи 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 clause со всеми операторами сравнения, кроме LIKE. (Это то же самое, что и SQL_EXCEPT_LIKE в ODBC 2*.x*.)

• SQL_PRED_SEARCHABLE можно ли использовать столбец в WHERE clause с любым оператором сравнения.

SQL_DESC_TABLE_NAME [IRD]
Это поле записи SQLCHAR * только для чтения содержит название базовой таблицы, содержащей этот столбец. Возвращаемое значение зависит от драйвера, является ли столбец выражением или если столбец является частью представления.

SQL_DESC_TYPE [Все]
Это поле записи SQLSMALLINT определяет краткий тип данных SQL или C для всех типов данных, кроме типов данных datetime и interval data. Для типов данных datetime и interval это поле задаёт многословный тип данных, который равен SQL_DATETIME или SQL_INTERVAL.

Всякий раз, когда это поле содержит SQL_DATETIME или SQL_INTERVAL, поле SQL_DESC_DATETIME_INTERVAL_CODE должно содержать соответствующий подкод для лаконичного типа. Для типов данных времени времени SQL_DESC_TYPE содержит SQL_DATETIME, а поле SQL_DESC_DATETIME_INTERVAL_CODE содержит подкод для конкретного типа данных времени даты. Для интервальных типов данных 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 установлен на краткий тип данных, отличный от интервала или типа времени времени, поле SQL_DESC_CONCISE_TYPE устанавливается на то же значение, а поле SQL_DESC_DATETIME_INTERVAL_CODE — в 0.

Если SQL_DESC_TYPE установлен на подробный тип данных datetime или interval (SQL_DATETIME или SQL_INTERVAL), а поле SQL_DESC_DATETIME_INTERVAL_CODE установить соответствующий подкод, поле SQL_DESC_CONCISE TYPE устанавливается на соответствующий лаконичный тип. Попытка установить SQL_DESC_TYPE на один из лаконичных типов времени или интервалов вернёт SQLSTATE HY021 (Несогласованная информация о описании).

Когда поле SQL_DESC_TYPE задаётся вызовом SQLBindCol, SQLBindParameter или SQLSetDescField, следующие поля устанавливаются на следующие значения по умолчанию, как показано в таблице ниже. Значения оставшихся полей той же записи не определены.

Когда приложение вызывает 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_DESC_UNNAMED в SQL_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.

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

См. также

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