SQLSpecialColumns, функция

Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: open Group

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

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

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

Синтаксис

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

Аргументы

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

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

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

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

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

Если для атрибута инструкции SQL_ATTR_METADATA_ID задано значение SQL_TRUE, Имя каталога рассматривается как идентификатор, и его регистр не имеет значения. Если это 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.

Область применения
[Входные данные] Минимальный обязательный область строкового идентификатора. Возвращаемый строковой идентификатор может быть больше область. Должна быть одной из следующих:

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

SQL_SCOPE_TRANSACTION. Идентификатор строки гарантированно действителен в течение текущей транзакции.

SQL_SCOPE_SESSION. Идентификатор строки гарантированно действителен в течение сеанса (через границы транзакций).

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

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

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

Возвраты

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

Диагностика

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

SQLSTATE	Ошибка	Описание
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) Задано недопустимое значение области .
HY099	Тип, допускающий значение NULL, вне диапазона	(DM) Указано недопустимое значение NULL .
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	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSet Подключение Attr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, связанный с StatementHandle , не поддерживает функцию.
IM017	Опрос отключен в асинхронном режиме уведомлений	При использовании модели уведомлений опрос отключается.
IM018	SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором.	Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции.

Комментарии

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

Примечание.

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

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

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

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

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

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

Столбец ODBC 2.0	Столбец ODBC 3.x
PRECISION	COLUMN_SIZE
LENGTH	BUFFER_LENGTH
МАСШТАБ	DECIMAL_DIGITS

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

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

Имя столбца	Номер столбца	Тип данных	Комментарии
ОБЛАСТЬ (ODBC 1.0)	1	Smallint	Фактический область строкового идентификатора. Содержит одно из следующих значений: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION Значение NULL возвращается при SQL_ROWVER идентификатора . Описание каждого значения см. в описании области в разделе "Синтаксис", приведенном ранее в этом разделе.
COLUMN_NAME (ODBC 1.0)	2	Varchar не NULL	Имя столбца. Драйвер возвращает пустую строку для столбца, который не имеет имени.
DATA_TYPE (ODBC 1.0)	3	Smallint, не NULL	Тип данных SQL. Это может быть тип данных ODBC SQL или тип данных SQL для конкретного драйвера. Список допустимых типов данных ODBC SQL см. в разделе "Типы данных SQL". Сведения о типах данных SQL для конкретного драйвера см. в документации по драйверу.
TYPE_NAME (ODBC 1.0)	4	Varchar не NULL	Имя типа данных, зависящей от источника данных; например, CHAR, VARCHAR, MONEY, LONG VARBINARY или CHAR () FOR BIT DATA.
COLUMN_SIZE (ODBC 1.0)	5	Целое	Размер столбца в источнике данных. Дополнительные сведения о размере столбца см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения".
BUFFER_LENGTH (ODBC 1.0)	6	Целое	Длина в байтах данных, передаваемых в операции 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. Противоположность неправда: даже если идентификатор строки не изменился, другие столбцы в строке могут измениться.

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

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

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

Пример кода

Пример кода аналогичной функции см . в разделе SQLColumns.

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

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

См. также

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