Функция SQLSpecialColumns

Соответствие
Введенная версия: Соответствие стандартам ODBC 1.0: Open Group

Сводка
SQLSpecialColumns получает следующую информацию о столбцах в заданной таблице:

  • Оптимальный набор столбцов, который уникально идентифицирует строку в таблице.

  • Столбцы, которые автоматически обновляются, когда любое значение в строке обновляется транзакцией.

Syntax

  
SQLRETURN SQLSpecialColumns(  
     SQLHSTMT      StatementHandle,  
     SQLSMALLINT   IdentifierType,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     TableName,  
     SQLSMALLINT   NameLength3,  
     SQLSMALLINT   Scope,  
     SQLSMALLINT   Nullable);

Arguments

ОператорHandle
[Входные данные] Дескриптор инструкции.

Тип идентификатора
[Ввод] Тип столбца для возврата. Необходимо установить одно из следующих значений.

SQL_BEST_ROWID: Возвращает оптимальный столбец или набор столбцов, который, получая значения из столбца или столбцов, позволяет уникально идентифицировать любую строку в указанной таблице. Столбец может быть либо псевдостолбцом, специально разработанным для этой цели (как в Oracle ROWID или Ingres TID), либо столбцем или столбцами любого уникального индекса для таблицы.

SQL_ROWVER: Возвращает столбцы или столбцы в указанной таблице, если таковые есть, которые автоматически обновляются источником данных, когда любое значение в строке обновляется любой транзакцией (как в SQLBase ROWID или Sybase TIMESTAMP).

Имя каталога
[Ввод] Название таблицы в каталоге. Если драйвер поддерживает каталоги для одних таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, пустая строка («») обозначает те таблицы, в которых нет каталогов. CatalogName не может содержать шаблон поиска по строкам.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, CatalogName рассматривается как идентификатор, и его падеж не является значимым. Если это SQL_FALSE, то CatalogName — это обычный аргумент; Это воспринимается буквально, и его дело значимо. Дополнительные сведения см. в разделе "Аргументы" в функциях каталога.

NameLength1
[Ввод] Длина в символах *CatalogName.

SchemaName (Имя схемы)
[Ввод] Схема для стола. Если драйвер поддерживает схемы для одних таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, пустая строка ("") обозначает таблицы без схем. SchemaName не может содержать шаблон поиска по строкам.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, SchemaName рассматривается как идентификатор, и его падеж не имеет значения. Если это SQL_FALSE, то SchemaName — это обычный аргумент; Это воспринимается буквально, и его дело значимо.

NameLength2
[Ввод] Длина в символах *SchemaName.

TableName
[Входные данные] Имя таблицы. Этот аргумент не может быть нулевым указателем. TableName не может содержать шаблон поиска по строкам.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, TableName рассматривается как идентификатор, и его падеж не является значимым. Если это SQL_FALSE, то TableName — это обычный аргумент; Это воспринимается буквально, и его дело значимо.

NameLength3
[Ввод] Длина в символах *TableName.

Scope
[Ввод] Минимальный требуемый обхват rowid. Возвращённый rowid может быть более масштабным. Должно быть одним из следующих элементов:

SQL_SCOPE_CURROW: Rowid гарантированно действителен только тогда, когда он расположен на этой строке. Последующий повторный выбор с помощью rowid может не вернуть строку, если строка была обновлена или удалена другой транзакцией.

SQL_SCOPE_TRANSACTION: Rowid гарантированно действителен на протяжении всей текущей транзакции.

SQL_SCOPE_SESSION: Rowid гарантированно действителен на протяжении всей сессии (через границы транзакций).

Nullable
[Ввод] Определяет, возвращать ли специальные столбцы, которые могут иметь значение NULL. Должно быть одним из следующих элементов:

SQL_NO_NULLS: Исключить специальные столбцы, которые могут иметь значения NULL. Некоторые драйверы не поддерживают SQL_NO_NULLS, и если SQL_NO_NULLS было указано, они возвращают пустой набор результатов. Заявки должны быть подготовлены для этого случая и просить SQL_NO_NULLS только в случае крайней необходимости.

SQL_NULLABLE: Возвращать специальные столбцы, даже если они могут иметь значения NULL.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.

Diagnostics

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

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
08S01 Сбой связи Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции.
24000 Недопустимое состояние курсора На StatementHandle был открыт курсор, и был вызван SQLFetch или SQLFetchScroll . Эта ошибка возвращается менеджером драйверов, если SQLFetch или SQLFetchScroll не вернули SQL_NO_DATA, и возвращается драйвером, если SQLFetch или SQLFetchScroll вернули SQL_NO_DATA.

Курсор был открыт на StatementHandle, но SQLFetch или SQLFetchScroll не были вызваны.
40001 Сбой сериализации Транзакция была откатена из-за взаимоблокировки ресурсов с другой транзакцией.
40003 Неизвестное завершение инструкции Связанное соединение завершилось сбоем во время выполнения этой функции, и состояние транзакции невозможно определить.
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY008 Операция отменена Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция снова была вызвана на ОператорHandle.

Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении.
HY009 Недопустимое использование указателя NULL Аргумент TableName был пустым указателем.

Атрибут оператора SQL_ATTR_METADATA_ID был установлен в SQL_TRUE, аргумент CatalogName был нулевой указателем, а SQL_CATALOG_NAME InfoType возвращал, что имена каталогов поддерживаются.

(DM) Атрибут оператора SQL_ATTR_METADATA_ID был установлен в SQL_TRUE, а аргумент SchemaName стал нулевой указателем.
HY010 Ошибка последовательности функций (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта функция всё ещё выполнялась, когда был вызван SQLSpecialColumns .

(DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров.

(DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090 Недопустимая длина строки или буфера (DM) Значение одного из аргументов длины было меньше 0, но не равно SQL_NTS.

Значение одного из аргументов длины превышало максимальное значение длины для соответствующего имени. Максимальную длину каждого имени можно получить, вызвав SQLGetInfo с значениями InfoType : SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN или SQL_MAX_TABLE_NAME_LEN.
HY097 Тип колонки вне зоны действия (DM) Было указано недопустимое значение IdentifierType .
HY098 Тип прицела вне зоны действия (DM) Было указано недопустимое значение Scope .
HY099 Обнулируемый тип вне зоны действия (DM) Было указано недопустимое значение Nullable .
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00 Необязательный компонент не реализован Был указан каталог, и драйвер или источник данных не поддерживает каталоги.

Была задана схема, и драйвер или источник данных не поддерживают схемы.

Сочетание текущих параметров SQL_ATTR_CONCURRENCY и атрибутов инструкции SQL_ATTR_CURSOR_TYPE не поддерживается драйвером или источником данных.

Для атрибута инструкции SQL_ATTR_USE_BOOKMARKS задано значение SQL_UB_VARIABLE, а для атрибута инструкции SQL_ATTR_CURSOR_TYPE задан тип курсора, для которого драйвер не поддерживает закладки.
HYT00 Время ожидания истекло. Срок ожидания запроса истек до того, как источник данных вернул запрошенный результирующий набор. Период времени ожидания задается через SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Время ожидания для подключения истекло Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Драйвер не поддерживает эту функцию (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию.
IM017 Опрос отключен в асинхронном режиме уведомлений При использовании модели уведомлений опрос отключается.
IM018 SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции.

Comments

Когда аргумент IdentifierType SQL_BEST_ROWID, SQLSpecialColumns возвращает столбец или столбцы, которые уникально идентифицируют каждую строку в таблице. Эти столбцы всегда могут использоваться в клаузе select-list или WHERE . SQLColumns, используемый для возврата разнообразной информации по столбцам таблицы, не обязательно возвращает столбцы, уникально идентифицирующие каждую строку, или столбцы, которые автоматически обновляются при обновлении любого значения в строке транзакцией. Например, SQLColumns может не возвращать псевдостолбец Oracle ROWID. Вот почему для возврата этих столбцов используется SQLSpecialColumns . Дополнительные сведения см. в разделе "Использование данных каталога".

Замечание

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

Если нет столбцов, уникально идентифицирующих каждую строку в таблице, SQLSpecialColumns возвращает набор строк без строк; последующий вызов SQLFetch или SQLFetchScroll на операторе возвращает SQL_NO_DATA.

Если аргументы IdentifierType, Scope или Nullable указывают характеристики, не поддерживаемые источником данных, SQLSpecialColumns возвращает пустой набор результатов.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, аргументы CatalogName, SchemaName и TableName рассматриваются как идентификаторы, поэтому их нельзя установить в null указатели в определённых ситуациях. (Для получения дополнительной информации см. Аргументы в каталожных функциях.)

SQLSpecialColumns возвращает результаты как стандартный набор результатов, упорядоченный по SCOPE.

Следующие столбцы были переименованы для ODBC 3.x. Изменения названий столбцов не влияют на обратную совместимость, поскольку приложения связываются по номеру столбцов.

Столбец ODBC 2.0 Столбец ODBC 3.x
PRECISION РАЗМЕР_СТОЛБЦА
ДЛИНА длина буфера
ШКАЛА десятичные цифры

Чтобы определить фактическую длину столбца COLUMN_NAME, приложение может вызвать SQLGetInfo с помощью опции SQL_MAX_COLUMN_NAME_LEN.

В следующей таблице перечислены столбцы в результирующем наборе. Дополнительные столбцы за столбцем 8 (PSEUDO_COLUMN) могут быть определены драйвером. Приложение должно получать доступ к специфическим для драйвера столбцам, обратный отсчёт от конца набора результатов, а не указывая явное порядковое положение. Дополнительные сведения см. в разделе "Данные, возвращаемые функциями каталога".

Название столбца Номер столбца Тип данных Comments
SCOPE (ODBC 1.0) 1 Smallint Фактический обхват rowid. Содержит одно из следующих значений:

SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION

NULL возвращается, когда IdentifierType SQL_ROWVER. Описание каждого значения см. описание Scope в разделе «Синтаксис» ранее в этом разделе.
COLUMN_NAME (ODBC 1.0) 2 Варчар, а не NULL Имя столбца. Драйвер возвращает пустую строку для столбца, который не имеет имени.
DATA_TYPE (ODBC 1.0) 3 Smallint, не NULL Тип данных SQL. Это может быть тип данных ODBC SQL или тип данных SQL для конкретного драйвера. Для списка допустимых типов данных ODBC SQL см. раздел SQL Data Types. Сведения о типах данных SQL для конкретного драйвера см. в документации по драйверу.
TYPE_NAME (ODBC 1.0) 4 Варчар, а не NULL Имя типа данных, зависящей от источника данных; например, CHAR, VARCHAR, MONEY, LONG VARBINARY или CHAR () FOR BIT DATA.
COLUMN_SIZE (ODBC 1.0) 5 Integer Размер столбца на источнике данных. Для получения дополнительной информации о размере столбца см. разделы «Размер столбца», «Десятичные цифры», «Длина октета переноса» и «Размер отражания».
BUFFER_LENGTH (ODBC 1.0) 6 Integer Длина в байтах данных, передаваемых в SQLGetData или операции SQLFetch при указании SQL_C_DEFAULT. Для числовых данных этот размер может отличаться от размера данных, хранящихся в источнике данных. Это значение может отличаться от COLUMN_SIZE столбца для данных символов. Для получения дополнительной информации см. разделы «Размер столбца», «Десятичные цифры», «Длина октета передачи» и «Размер дисплея».
DECIMAL_DIGITS (ODBC 1.0) 7 Smallint Десятичные цифры столбца на источнике данных. NULL возвращается для типов данных, где десятичные цифры не применимы. Для получения дополнительной информации о десятичных цифрах см. разделы «Размер столбца», «Десятичные цифры», «Длина октета переноса» и «Размер отображения».
PSEUDO_COLUMN (ODBC 2.0) 8 Smallint Указывает, является ли столбец псевдостолбцем, например, Oracle ROWID:

SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Примечание: Для максимальной совместимости псевдостолбцы не должны цитироваться с символом цитаты идентификатора, возвращаемым SQLGetInfo.

После того как приложение получает значения для SQL_BEST_ROWID, оно может использовать эти значения для повторного выбора этой строки в определённой области. Оператор SELECT гарантирует либо отсутствие строк, либо одну строку.

Если приложение перевыбирает строку на основе столбца или столбцов rowid, и строка не найдена, оно может предположить, что строка была удалена или столбцы rowid были изменены. Обратное не верно: даже если rowid не изменился, другие столбцы в строке могли измениться.

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

Столбец или столбцы строки могут оставаться действительными даже если курсор не расположен на строке; приложение может определить это, проверив столбец SCOPE в наборе результатов.

Столбцы, возвращаемые для SQL_ROWVER типа столбца, полезны для приложений, которым нужно проверять, были ли какие-либо столбцы в данной строке обновлены во время повторного выбора строки с помощью rowid. Например, после повторного выбора строки с помощью rowid приложение может сравнить предыдущие значения в SQL_ROWVER столбцах с только что полученными. Если значение в столбце SQL_ROWVER отличается от предыдущего, приложение может уведомить пользователя о изменении данных на дисплее.

Пример кода

Для примера кода аналогичной функции см. SQLColumns.

Сведения о Смотри
Привязка буфера к столбцу в результирующем наборе Функция SQLBindCol
Отмена обработки инструкций Функция SQLCancel
Возврат столбцов в таблице или таблицах Функция SQLColumns
Получение одной строки или блока данных в направлении только вперёд Функция SQLFetch
Получение блока данных или прокрутка результирующий набор Функция SQLFetchScroll
Возврат столбцов первичного ключа Функция SQLPrimaryKeys

Связанные материалы

  • Last updated on