Функция SQLSetDescRec

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

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

Синтаксис

  
SQLRETURN SQLSetDescRec(  
      SQLHDESC      DescriptorHandle,  
      SQLSMALLINT   RecNumber,  
      SQLSMALLINT   Type,  
      SQLSMALLINT   SubType,  
      SQLLEN        Length,  
      SQLSMALLINT   Precision,  
      SQLSMALLINT   Scale,  
      SQLPOINTER    DataPtr,  
      SQLLEN *      StringLengthPtr,  
      SQLLEN *      IndicatorPtr);  

Аргументы

DescriptorHandle
[Входные данные] Дескриптор дескриптор. Это не должен быть дескриптор IRD.

RecNumber
[Входные данные] Указывает запись дескриптора, содержащую заданные поля. Записи дескриптора нумеруются от 0, при этом запись записи 0 является записью закладки. Этот аргумент должен быть равен или больше 0. Если recNumber больше значения SQL_DESC_COUNT, SQL_DESC_COUNTis изменено на значение RecNumber.

типа
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_TYPE для записи дескриптора.

подтипа
[Входные данные] Для записей, тип которых SQL_DATETIME или SQL_INTERVAL, это значение, для которого необходимо задать поле SQL_DESC_DATETIME_INTERVAL_CODE.

длина
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_OCTET_LENGTH для записи дескриптора.

точности
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_PRECISION для записи дескриптора.

масштабирование
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_SCALE для записи дескриптора.

DataPtr
[Отложенные входные или выходные данные] Значение, для которого необходимо задать поле SQL_DESC_DATA_PTR для записи дескриптора. DataPtr можно задать для указателя NULL.

Аргумент DataPtr можно задать для указателя NULL, чтобы задать для поля SQL_DESC_DATA_PTR значение null указателя. Если дескриптор в аргументе DescriptorHandle связан с ARD, это отменяет привязку столбца.

StringLengthPtr
[Отложенные входные или выходные данные] Значение, для которого необходимо задать поле SQL_DESC_OCTET_LENGTH_PTR для записи дескриптора. StringLengthPtr можно задать для указателя NULL, чтобы задать для поля SQL_DESC_OCTET_LENGTH_PTR значение null указателя.

индикатора
[Отложенные входные или выходные данные] Значение, для которого необходимо задать поле SQL_DESC_INDICATOR_PTR для записи дескриптора. индикатор индикатора можно задать для указателя NULL, чтобы задать поле SQL_DESC_INDICATOR_PTR значение null указателя.

Возвращает

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

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

Комментарии

Приложение может вызывать SQLSetDescRec, чтобы задать следующие поля для одного столбца или параметра:

• SQL_DESC_TYPE

• SQL_DESC_DATETIME_INTERVAL_CODE (для записей, тип которых SQL_DATETIME или SQL_INTERVAL)

• SQL_DESC_OCTET_LENGTH

• SQL_DESC_PRECISION

• SQL_DESC_SCALE

• SQL_DESC_DATA_PTR

• SQL_DESC_OCTET_LENGTH_PTR

• SQL_DESC_INDICATOR_PTR

При привязке столбца или параметра SQLSetDescRec позволяет изменять несколько полей, влияющих на привязку, не вызывая SQLBindCol или SQLBindParameter или выполняя несколько вызовов SQLSetDescField. SQLSetDescRec может задавать поля в дескрипторе, не связанном с инструкцией. Обратите внимание, что SQLBindParameter задает больше полей, чем SQLSetDescRec, может задавать поля как в APD, так и IPD в одном вызове и не требует дескриптора.

Проверки согласованности

Проверка согласованности выполняется драйвером автоматически, когда приложение устанавливает SQL_DESC_DATA_PTR поле APD, ARD или IPD. Если любой из полей не согласуется с другими полями, SQLSetDescRec вернет sqlSTATE HY021 (несогласованные сведения о дескрипторе).

Всякий раз, когда приложение задает SQL_DESC_DATA_PTR поле APD, ARD или IPD, драйвер проверяет, что значение поля SQL_DESC_TYPE и значения, применимые к данному полю SQL_DESC_TYPE, являются допустимыми и согласованными. Эта проверка всегда выполняется при вызове SQLBindParameter или SQLBindCol или при вызове SQLSetDescRec для APD, ARD или IPD. Эта проверка согласованности включает следующие проверки полей дескриптора:

• Поле SQL_DESC_TYPE должно быть одним из допустимых типов ODBC C или SQL или типа SQL для конкретного драйвера. Поле SQL_DESC_CONCISE_TYPE должно быть одним из допустимых типов ODBC C или SQL или типа драйвера C или SQL, включая краткие типы даты и интервалов.

• Если поле записи SQL_DESC_TYPE SQL_DATETIME или SQL_INTERVAL, поле SQL_DESC_DATETIME_INTERVAL_CODE должно быть одним из допустимых кодов даты или интервала. (См. описание поля SQL_DESC_DATETIME_INTERVAL_CODE в SQLSetDescField.)

• Если поле SQL_DESC_TYPE указывает числовой тип, SQL_DESC_PRECISION и SQL_DESC_SCALE поля проверяются как допустимые.

• Если поле SQL_DESC_CONCISE_TYPE является типом данных time или timestamp, тип интервала с компонентом секунд или одним из типов данных интервала с компонентом времени, то поле SQL_DESC_PRECISION проверяется, что это допустимая точность секунд.

• Если SQL_DESC_CONCISE_TYPE является типом данных интервала, поле SQL_DESC_DATETIME_INTERVAL_PRECISION проверяется как допустимое значение максимальной точности интервала.

Поле SQL_DESC_DATA_PTR IPD обычно не задано; однако приложение может сделать это, чтобы принудительно проверить согласованность полей IPD. Проверка согласованности не может выполняться в IRD. Значение, для которого задано поле SQL_DESC_DATA_PTR IPD, не сохраняется и не может быть извлечено вызовом SQLGetDescField или SQLGetDescRec; Параметр выполняется только для принудительной проверки согласованности.

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

См. также

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