Функция SQLProcedureColumns
Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: ODBC
Сводка
SQLProcedureColumns возвращает список входных и выходных параметров, а также столбцы, составляющие результирующий набор для указанных процедур. Драйвер возвращает сведения в виде результирующих наборов для указанной инструкции.
Синтаксис
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
Имя каталога
[Входные данные] Имя каталога процедур. Если драйвер поддерживает каталоги для некоторых процедур, но не для других, например, когда драйвер извлекает данные из разных СУБД, пустая строка ("") обозначает те процедуры, которые не имеют каталогов. CatalogName не может содержать шаблон поиска строк.
Если для атрибута инструкции SQL_ATTR_METADATA_ID задано значение SQL_TRUE, Имя каталога рассматривается как идентификатор, и его регистр не имеет значения. Если это SQL_FALSE, CatalogName является обычным аргументом; он обрабатывается буквально, и его дело является значительным. Дополнительные сведения см. в разделе "Аргументы" в функциях каталога.
NameLength1
[Входные данные] Длина символов *CatalogName.
Schemaname
[Входные данные] Шаблон поиска строк для имен схем процедуры. Если драйвер поддерживает схемы для некоторых процедур, но не для других, например, когда драйвер извлекает данные из разных СУБД, пустая строка ("") обозначает эти процедуры, которые не имеют схем.
Если для атрибута инструкции SQL_ATTR_METADATA_ID задано значение SQL_TRUE, schemaName обрабатывается как идентификатор, и его регистр не имеет значения. Если это SQL_FALSE, SchemaName является аргументом значения шаблона; он обрабатывается буквально, и его случай является значительным.
NameLength2
[Входные данные] Длина символов *SchemaName.
ProcName
[Входные данные] Шаблон поиска строк для имен процедур.
Если для атрибута оператора SQL_ATTR_METADATA_ID задано значение SQL_TRUE, ProcName обрабатывается как идентификатор, и его регистр не имеет значения. Если это SQL_FALSE, ProcName является аргументом значения шаблона; он обрабатывается буквально, и его дело является значительным.
NameLength3
[Входные данные] Длина символов *ProcName.
ColumnName
[Входные данные] Шаблон поиска строк для имен столбцов.
Если для атрибута оператора SQL_ATTR_METADATA_ID задано значение SQL_TRUE, ColumnName обрабатывается как идентификатор, и его регистр не имеет значения. Если это SQL_FALSE, ColumnName является аргументом значения шаблона; он обрабатывается буквально, и его случай является значительным.
NameLength4
[Входные данные] Длина символов *ColumnName.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLProcedureColumns возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLProcedureColumns и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением 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 для конкретной реализации. Сообщение об ошибке, возвращаемое SQLError в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция снова была вызвана на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении. |
| HY009 | Недопустимое использование указателя NULL | Для атрибута инструкции SQL_ATTR_METADATA_ID задано значение SQL_TRUE, аргумент CatalogName был пустым указателем, а SQL_CATALOG_NAME InfoType возвращает поддерживаемые имена каталогов. (DM) Атрибут инструкции SQL_ATTR_METADATA_ID был задан как SQL_TRUE, а аргумент SchemaName, ProcName или ColumnName был пустым указателем. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLProcedureColumns. (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY090 | Недопустимая длина строки или буфера | (DM) Значение одного из аргументов длины имени было меньше 0, но не равно SQL_NTS. Значение одного из аргументов длины имени превысило максимальное значение длины для соответствующего каталога, схемы, процедуры или имени столбца. |
| 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 должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
Эта функция обычно используется перед выполнением инструкции для получения сведений о параметрах процедуры и столбцах, составляющих результирующий набор или наборы, возвращаемые процедурой, если таковые есть. Дополнительные сведения см. в разделе Procedures in Visual Basic (Процедуры в Visual Basic).
Заметка
SQLProcedureColumns может не возвращать все столбцы, используемые процедурой. Например, драйвер может возвращать только сведения о параметрах, используемых процедурой, а не столбцами в результирующем наборе.
Аргументы SchemaName, ProcName и ColumnNameпринимают шаблоны поиска. Дополнительные сведения о допустимых шаблонах поиска см. в разделе "Аргументы значения шаблона".
Заметка
Дополнительные сведения об общем использовании, аргументах и возвращаемых данных функций каталога ODBC см. в разделе "Функции каталога".
SQLProcedureColumns возвращает результаты в виде стандартного результирующий набор, упорядоченный по PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME и COLUMN_TYPE. Имена столбцов возвращаются для каждой процедуры в следующем порядке: имя возвращаемого значения, имена каждого параметра в вызове процедуры (в порядке вызова), а затем имена каждого столбца в результирующем наборе, возвращаемом процедурой (в порядке столбца).
Приложения должны привязывать столбцы, относящиеся к драйверу, относительно конца результирующего набора. Дополнительные сведения см. в разделе "Данные, возвращаемые функциями каталога".
Чтобы определить фактическую длину столбцов PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME и COLUMN_NAME, приложение может вызывать SQLGetInfo с параметрами SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN и SQL_MAX_COLUMN_NAME_LEN.
Следующие столбцы были переименованы для ODBC 3.x. Изменения имени столбца не влияют на обратную совместимость, так как приложения привязываются по номеру столбца.
| Столбец ODBC 2.0 | ODBC 3.Столбец x |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| ПРОЦЕДУРА _OWNER | PROCEDURE_SCHEM |
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| МАСШТАБ | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
Следующие столбцы были добавлены в набор результатов, возвращенный SQLProcedureColumns для ODBC 3.x:
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
В следующей таблице перечислены столбцы в результирующем наборе. Дополнительные столбцы за пределами столбца 19 (IS_NULLABLE) можно определить драйвером. Приложение должно получить доступ к столбцам для конкретного драйвера, отсчитывая от конца результирующего набора, а не указывая явное порядковое положение. Дополнительные сведения см. в разделе "Данные, возвращаемые функциями каталога".
| Столбец | Номер столбца | Тип данных | Комментарии |
|---|---|---|---|
| PROCEDURE_CAT (ODBC 2.0) | 1 | Varchar | Имя каталога процедур; ЗНАЧЕНИЕ NULL, если применимо к источнику данных. Если драйвер поддерживает каталоги для некоторых процедур, но не для других, например, когда драйвер извлекает данные из разных СУБД, он возвращает пустую строку ("") для тех процедур, которые не имеют каталогов. |
| PROCEDURE_SCHEM (ODBC 2.0) | 2 | Varchar | Имя схемы процедуры; ЗНАЧЕНИЕ NULL, если применимо к источнику данных. Если драйвер поддерживает схемы для некоторых процедур, но не для других, например, когда драйвер извлекает данные из разных СУБД, он возвращает пустую строку ("") для тех процедур, которые не имеют схем. |
| PROCEDURE_NAME (ODBC 2.0) | 3 | Varchar не NULL | Имя процедуры. Пустая строка возвращается для процедуры, которая не имеет имени. |
| COLUMN_NAME (ODBC 2.0) | 4 | Varchar не NULL | Имя столбца процедуры. Драйвер возвращает пустую строку для столбца процедуры, который не имеет имени. |
| COLUMN_TYPE (ODBC 2.0) | 5 | Smallint, не NULL | Определяет столбец процедуры как параметр или столбец результирующих наборов: SQL_PARAM_TYPE_UNKNOWN. Столбец процедуры является параметром, тип которого неизвестен. (ODBC 1.0) SQL_PARAM_INPUT. Столбец процедуры является входным параметром. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT. Столбец процедуры является параметром ввода и вывода. (ODBC 1.0) SQL_PARAM_OUTPUT. Столбец процедуры является выходным параметром. (ODBC 2.0) SQL_RETURN_VALUE. Столбец процедуры является возвращаемым значением процедуры. (ODBC 2.0) SQL_RESULT_COL. Столбец процедуры является столбцом результирующих наборов. (ODBC 1.0) |
| DATA_TYPE (ODBC 2.0) | 6 | Smallint, не NULL | Тип данных SQL. Это может быть тип данных ODBC SQL или тип данных SQL для конкретного драйвера. Для типов данных datetime и интервала этот столбец возвращает краткие типы данных (например, SQL_TYPE_TIME или SQL_INTERVAL_YEAR_TO_MONTH). Список допустимых типов данных ODBC SQL см . в разделе "Типы данных SQL" в приложении D: Типы данных. Сведения о типах данных SQL для конкретного драйвера см. в документации по драйверу. |
| TYPE_NAME (ODBC 2.0) | 7 | Varchar не NULL | Имя типа данных, зависящей от источника данных; например, CHAR, VARCHAR, MONEY, LONG VARBINARY или CHAR () FOR BIT DATA. |
| COLUMN_SIZE (ODBC 2.0) | 8 | Целое | Размер столбца процедуры в источнике данных. Значение NULL возвращается для типов данных, в которых размер столбца неприменимо. Дополнительные сведения о точности см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения" в приложении D: Типы данных. |
| BUFFER_LENGTH (ODBC 2.0) | 9 | Целое | Длина в байтах данных, передаваемых в операции SQLGetData или SQLFetch , если указана SQL_C_DEFAULT. Для числовых данных этот размер может отличаться от размера данных, хранящихся в источнике данных. Дополнительные сведения см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения" в приложении D: Типы данных. |
| DECIMAL_DIGITS (ODBC 2.0) | 10 | Smallint | Десятичные цифры столбца процедуры в источнике данных. Значение NULL возвращается для типов данных, в которых десятичные цифры неприменимо. Дополнительные сведения о десятичных цифрах см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения" в приложении D: Типы данных. |
| NUM_PREC_RADIX (ODBC 2.0) | 11 | Smallint | Для числовых типов данных — 10 или 2. Если значение 10, значения в COLUMN_SIZE и DECIMAL_DIGITS укажите число десятичных цифр, разрешенных для столбца. Например, столбец DECIMAL(12,5) возвращает NUM_PREC_RADIX 10, COLUMN_SIZE 12 и DECIMAL_DIGITS из 5; Столбец FLOAT может возвращать NUM_PREC_RADIX 10, COLUMN_SIZE 15 и DECIMAL_DIGITS NULL. Если 2, значения в COLUMN_SIZE и DECIMAL_DIGITS дать количество битов, разрешенных в столбце. Например, столбец FLOAT может возвращать NUM_PREC_RADIX 2, COLUMN_SIZE 53 и DECIMAL_DIGITS NULL. Значение NULL возвращается для типов данных, в которых NUM_PREC_RADIX неприменимо. |
| NULLABLE (ODBC 2.0) | 12 | Smallint, не NULL | Принимает ли столбец процедуры значение NULL: SQL_NO_NULLS. Столбец процедуры не принимает значения NULL. SQL_NULLABLE. Столбец процедуры принимает значения NULL. SQL_NULLABLE_UNKNOWN: неизвестно, принимает ли столбец процедуры значения NULL. |
| ПРИМЕЧАНИЯ (ODBC 2.0) | 13 | Varchar | Описание столбца процедуры. |
| COLUMN_DEF (ODBC 3.0) | 14 | Varchar | Значение по умолчанию для столбца. Если значение NULL было указано в качестве значения по умолчанию, этот столбец является словом NULL, а не заключено в кавычки. Если значение по умолчанию не может быть представлено без усечения, этот столбец содержит TRUNCATED без заключительных одинарных кавычки. Если значение по умолчанию не указано, этот столбец имеет значение NULL. Значение COLUMN_DEF можно использовать при создании нового определения столбца, за исключением случаев, когда он содержит значение TRUNCATED. |
| SQL_DATA_TYPE (ODBC 3.0) | 15 | Smallint, не NULL | Значение типа данных SQL, как оно отображается в поле SQL_DESC_TYPE дескриптора. Этот столбец совпадает с столбцом DATA_TYPE, за исключением типов данных datetime и интервала. Для типов данных datetime и интервала поле SQL_DATA_TYPE в результирующем наборе вернет SQL_INTERVAL или SQL_DATETIME, а поле SQL_DATETIME_SUB вернет подкод для определенного интервала или типа данных datetime. (См. раздел Приложение D. Типы данных.) |
| SQL_DATETIME_SUB (ODBC 3.0) | 16 | Smallint | Код подтипа для типов данных datetime и интервала. Для других типов данных этот столбец возвращает значение NULL. |
| CHAR_OCTET_LENGTH (ODBC 3.0) | 17 | Целое | Максимальная длина в байтах столбца типа данных символа или двоичного типа данных. Для всех других типов данных этот столбец возвращает значение NULL. |
| ORDINAL_POSITION (ODBC 3.0) | 18 | Integer, не NULL | Для входных и выходных параметров порядковый номер параметра в определении процедуры (при увеличении порядка параметров, начиная с 1). Для возвращаемого значения (если таковые имеются), возвращается значение 0. Для столбцов результирующего набора порядковый номер столбца в результирующем наборе, а первый столбец в результирующем наборе — число 1. Если имеется несколько результирующих наборов, порядковые позиции столбцов возвращаются в конкретном драйвере. |
| IS_NULLABLE (ODBC 3.0) | 19 | Varchar | Значение NO, если столбец не содержит NULLs. Значение "ДА", если столбец может включать NULLs. Если допустимость значения NULL неизвестна, то этот столбец возвращает строку нулевой длины. Допустимость значений NULL определяется в соответствии с правилами ISO. СУБД, совместимая с ISO SQL, не может вернуть пустую строку. Значение, возвращаемое в данном столбце, отличается от значения, возвращаемого в столбце NULLABLE. (См. описание столбца NULLABLE.) |
Пример кода
См . вызовы процедур.
Связанные функции
| Сведения | Раздел |
|---|---|
| Привязка буфера к столбцу в результирующем наборе | Функция SQLBindCol |
| Отмена обработки инструкций | Функция SQLCancel |
| Получение одной строки или блока данных в направлении только для пересылки | Функция SQLFetch |
| Получение блока данных или прокрутка результирующий набор | Функция SQLFetchScroll |
| Возврат списка процедур в источнике данных | Функция SQLProcedures |