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);
参数
StatementHandle
[输入]语句句柄。
CatalogName
[输入]过程目录名称。 如果驱动程序支持某些过程的目录，但不支持其他过程，例如当驱动程序从不同的 DBMS 检索数据时，空字符串 （“”） 表示没有目录的过程。
CatalogName 不能包含字符串搜索模式。
如果将 SQL_ATTR_METADATA_ID 语句属性设置为SQL_TRUE，CatalogName 被视为标识符，并且其大小写不重要。 如果SQL_FALSE，CatalogName 是一个普通参数;它按字面处理，其大小写非常重要。 有关详细信息，请参阅目录函数中的
NameLength1
[输入]*CatalogName的长度（以字符为单位）。
SchemaName
[输入]过程架构名称的字符串搜索模式。 如果驱动程序支持某些过程的架构，但不支持其他过程，例如当驱动程序从不同的 DBMS 检索数据时，空字符串 （“”） 表示没有架构的过程。
如果 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时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，其 HandleType 为 SQL_HANDLE_STMT，HandleStatementHandle。 下表列出了 SQLProcedureColumns 通常返回的 SQLSTATE 值，并在此函数的上下文中解释每个值：表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 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。 *MessageText 缓冲区中 SQLError 返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 为 StatementHandle启用了异步处理。 调用了该函数，并在完成执行之前，SQLCancel 或 SQLCancelHandle 在 StatementHandle上调用。 然后在 StatementHandle上再次调用该函数。 调用了该函数，并在完成执行之前，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 参数为 null 指针。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle关联的连接句柄调用异步执行函数。 调用 SQLProcedureColumns 函数时，此异步函数仍在执行。 （DM） SQLExecute、SQLExecDirect或 SQLMoreResults 被调用 StatementHandle 并返回SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 为 StatementHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） SQLExecute、SQLExecDirect、SQLBulkOperations或 SQLSetPos 为 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 |
| HY090 | 字符串或缓冲区长度无效 | （DM） 名称长度参数之一的值小于 0，但不等于SQL_NTS。 名称长度参数之一的值超过了相应目录、架构、过程或列名的最大长度值。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| 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 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 StatementHandle 关联的驱动程序不支持该函数。 |
| IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时，轮询将被禁用。 |
| IM018 | SQLCompleteAsync 尚未调用以完成此句柄上的上一个异步操作。 | 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用通知模式 ，则必须在句柄上调用 SQLCompleteAsync 才能执行后期处理并完成操作。 |
评论
在语句执行之前，通常使用此函数来检索有关过程参数的信息以及构成过程返回的结果集或集的列（如果有）。 有关详细信息，请参阅 过程。
注意
SQLProcedureColumns 可能不会返回过程使用的所有列。 例如，驱动程序可能仅返回有关过程使用的参数的信息，而不能返回它生成的结果集中的列。
SchemaName、ProcName和 ColumnName 参数接受搜索模式。 有关有效搜索模式的详细信息，请参阅 模式值参数。
注意
有关 ODBC 目录函数的常规用途、参数和返回数据的详细信息，请参阅 目录函数。
SQLProcedureColumns 将结果作为标准结果集返回，按PROCEDURE_CAT、PROCEDURE_SCHEM、PROCEDURE_NAME和COLUMN_TYPE排序。 按以下顺序为每个过程返回列名：返回值的名称、过程调用中的每个参数的名称（按调用顺序），然后返回过程返回的结果集中每个列的名称（按列顺序）。
应用程序应将特定于驱动程序的列绑定到结果集末尾。 有关详细信息，请参阅目录函数返回
若要确定PROCEDURE_CAT、PROCEDURE_SCHEM、PROCEDURE_NAME和COLUMN_NAME列的实际长度，应用程序可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_PROCEDURE_NAME_LEN和SQL_MAX_COLUMN_NAME_LEN选项调用 SQLGetInfo。
已为 ODBC 3 重命名以下列。x。 列名更改不会影响向后兼容性，因为应用程序按列号绑定。
| ODBC 2.0 列 | ODBC 3.x 列 |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| 过程_OWNER | PROCEDURE_SCHEM |
| 精度 | COLUMN_SIZE |
| 长度 | BUFFER_LENGTH |
| 规模 | DECIMAL_DIGITS |
| 基数 | 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。 如果驱动程序支持某些过程的目录，但不支持其他过程，例如当驱动程序从不同的 DBMS 检索数据时，它将为没有目录的过程返回空字符串 （“”）。 |
| PROCEDURE_SCHEM （ODBC 2.0） | 2 | Varchar | 过程架构名称;如果不适用于数据源，则为 NULL。 如果驱动程序支持某些过程的架构，但不支持其他过程，例如当驱动程序从不同的 DBMS 检索数据时，它将为没有架构的过程返回一个空字符串（“”）。 |
| PROCEDURE_NAME （ODBC 2.0） | 3 | Varchar 非 NULL | 过程名称。 对于没有名称的过程，将返回一个空字符串。 |
| COLUMN_NAME （ODBC 2.0） | 4 | Varchar 非 NULL | 过程列名称。 驱动程序为没有名称的过程列返回一个空字符串。 |
| COLUMN_TYPE （ODBC 2.0） | 5 | Smallint not 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 not NULL | SQL 数据类型。 这可以是 ODBC SQL 数据类型，也可以是特定于驱动程序的 SQL 数据类型。 对于日期/时间和间隔数据类型，此列返回简洁的数据类型（例如，SQL_TYPE_TIME或SQL_INTERVAL_YEAR_TO_MONTH）。 有关有效 ODBC SQL 数据类型的列表，请参阅附录 D：数据类型 |
| 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 | 整数 | 如果指定了SQL_C_DEFAULT，则 SQLGetData 或 SQLFetch 操作上传输的数据的长度（以字节为单位）。 对于数值数据，此大小可能与存储在数据源上的数据的大小不同。 有关详细信息，请参阅附录 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） 列将返回 10 的NUM_PREC_RADIX，COLUMN_SIZE为 12，DECIMAL_DIGITS为 5;FLOAT 列可以返回 10 的NUM_PREC_RADIX、15 COLUMN_SIZE和 NULL 的DECIMAL_DIGITS。 如果为 2，则COLUMN_SIZE和DECIMAL_DIGITS中的值提供列中允许的位数。 例如，FLOAT 列可以返回 2 的NUM_PREC_RADIX、53 的COLUMN_SIZE和 NULL 的DECIMAL_DIGITS。 对于不适用NUM_PREC_RADIX的数据类型，返回 NULL。 |
| NULLABLE （ODBC 2.0） | 12 | Smallint not 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 not NULL | 在描述符的SQL_DESC_TYPE字段中显示 SQL 数据类型的值。 此列与DATA_TYPE列相同，日期/时间和间隔数据类型除外。 对于日期/时间和间隔数据类型，结果集中的SQL_DATA_TYPE字段将返回SQL_INTERVAL或SQL_DATETIME，SQL_DATETIME_SUB字段将返回特定间隔或日期/时间数据类型的子代码。 （请参阅 附录 D：数据类型。） |
| SQL_DATETIME_SUB （ODBC 3.0） | 16 | Smallint | 日期/时间数据类型和间隔数据类型的子类型代码。 对于其他数据类型，此列返回 NULL。 |
| CHAR_OCTET_LENGTH （ODBC 3.0） | 17 | 整数 | 字符或二进制数据类型列的最大长度（以字节为单位）。 对于所有其他数据类型，此列返回 NULL。 |
| ORDINAL_POSITION （ODBC 3.0） | 18 | 整数不为 NULL | 对于输入和输出参数，参数在过程定义中的序号位置（以递增参数顺序，从 1 开始）。 对于返回值（如果有），返回 0。 对于结果集列，列在结果集中的序号位置，结果集中的第一列为数字 1。 如果有多个结果集，则以特定于驱动程序的方式返回列序号位置。 |
| IS_NULLABLE （ODBC 3.0） | 19 | Varchar | 如果列不包含 NULL，则为“否”。 如果列可以包含 NULL，则为“是”。 如果可为 null 性未知，此列将返回零长度字符串。 遵循 ISO 规则来确定可为 null 性。 符合 ISO SQL 的 DBMS 无法返回空字符串。 为此列返回的值不同于为 NULLABLE 列返回的值。 （请参阅 NULLABLE 列的说明。 |
代码示例
请参阅 过程调用。
相关函数
| 有关 | 看 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 提取单行或仅向前方向的数据块 | SQLFetch 函数 |
| 提取数据块或滚动结果集 | SQLFetchScroll 函数 |
| 返回数据源中的过程列表 | SQLProcedures 函数 |