SQLPrimaryKeys 函数

一致性
引入的版本:ODBC 1.0 标准合规性:ODBC

摘要
SQLPrimaryKeys 返回构成表的主键的列名称。 驱动程序将信息作为结果集返回。 此函数不支持在单个调用中从多个表返回主键。

语法

  
SQLRETURN SQLPrimaryKeys(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3);  

参数

StatementHandle
[输入]语句句柄。

CatalogName
[输入]目录名称。 如果驱动程序支持某些表的目录,但不支持其他表的目录,例如当驱动程序从不同的 DBMS 检索数据时,空字符串 (“”) 表示那些没有目录的表。 CatalogName 不能包含字符串搜索模式。

如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, 则 CatalogName 被视为标识符,其大小写并不重要。 如果为SQL_FALSE, 则 CatalogName 是一个普通参数;它按字面处理,其大小写很重要。 有关详细信息,请参阅 目录函数中的参数

NameLength1
[输入]*CatalogName 的长度(以字符为单位)。

SchemaName
[输入]架构名称。 如果驱动程序支持某些表的架构,但不支持其他表的架构,例如当驱动程序从不同的 DBMS 检索数据时,空字符串 (“”) 表示那些没有架构的表。 SchemaName 不能包含字符串搜索模式。

如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, 则 SchemaName 被视为标识符,其大小写并不重要。 如果它是SQL_FALSE, 则 SchemaName 是一个普通参数;它按字面处理,其大小写并不重要。

NameLength2
[输入]*SchemaName 的长度(以字符为单位)。

TableName
[输入]表名称。 此参数不能为 null 指针。 TableName 不能包含字符串搜索模式。

如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, 则 TableName 被视为标识符,其大小写并不重要。 如果它是SQL_FALSE, 则 TableName 是一个普通参数;它按字面处理,其大小写并不重要。

NameLength3
[输入]*TableName 的长度(以字符为单位)。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

SQLPrimaryKeys 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,可以通过使用 handleType 为 SQL_HANDLE_STMT 和 Handle ofStatementHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLPrimaryKeys 通常返回的 SQLSTATE 值,并说明了此函数上下文中的每个值:表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR,除非另有说明。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
08S01 通信链接失败 在函数完成处理之前,驱动程序与所连接的数据源之间的通信链接失败。
24000 游标状态无效 (DM) StatementHandle 上打开了游标,并且调用了 SQLFetchSQLFetchScroll

在 StatementHandle 上打开了游标,但尚未调用 SQLFetchSQLFetchScroll
40001 序列化失败 由于与另一个事务发生资源死锁,事务已回滚。
40003 语句完成未知 在执行此函数期间,关联的连接失败,并且无法确定事务的状态。
HY000 常规错误 发生错误,其中没有特定的 SQLSTATE,也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec*MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY008 操作已取消 已为 StatementHandle 启用异步处理。 调用了函数,在它完成执行之前,在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle 然后,在 StatementHandle 上再次调用函数。

函数已调用,在它完成执行之前,在 StatementHandle 上从多线程应用程序中的不同线程调用 SQLCancel 或 SQLCancelHandle
HY009 null 指针的使用无效 (DM) TableName 参数为 null 指针。

SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, CatalogName 参数为 null 指针,具有SQL_CATALOG_NAME信息类型的 SQLGetInfo 返回支持目录名称。

(DM) SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, SchemaName 参数为 null 指针。
HY010 函数序列错误 (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLPrimaryKeys 函数时,此异步函数仍在执行。

(DM) SQLExecuteSQLExecDirectSQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流参数的数据之前调用的。

(DM) 为 StatementHandle 调用了异步执行的函数, (不是此函数) ,在调用此函数时仍在执行。

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos 已为 StatementHandle 调用,并返回SQL_NEED_DATA。 在针对所有数据执行参数或列发送数据之前调用了此函数。
HY013 内存管理错误 无法处理函数调用,因为无法访问基础内存对象,可能是由于内存不足。
HY090 无效的字符串或缓冲区长度 (DM) 其中一个名称长度参数的值小于 0 但不等于SQL_NTS,关联的 name 参数不是 null 指针。

其中一个名称长度参数的值超过了相应名称的最大长度值。
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 SQL_ATTR_CONNECTION_TIMEOUT设置。
IM001 驱动程序不支持此函数 (DM) 与 StatementHandle 关联的驱动程序不支持 函数。
IM017 在异步通知模式下禁用轮询 每当使用通知模型时,将禁用轮询。
IM018 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 如果对句柄的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式,则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。

注释

SQLPrimaryKeys 以标准结果集的形式返回结果,按TABLE_CAT、TABLE_SCHEM、TABLE_NAME和KEY_SEQ排序。 有关如何使用此信息的信息,请参阅 目录数据的使用

以下列已重命名为 ODBC 3。x. 列名更改不会影响向后兼容性,因为应用程序按列号绑定。

ODBC 2.0 列 ODBC 3。x
TABLE_QUALIFIER TABLE_CAT
TABLE_OWNER TABLE_SCHEM

若要确定TABLE_CAT、TABLE_SCHEM、TABLE_NAME和COLUMN_NAME列的实际长度,请使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_TABLE_NAME_LEN和SQL_MAX_COLUMN_NAME_LEN选项调用 SQLGetInfo

注意

有关 ODBC 目录函数的常规用法、参数和返回数据的详细信息,请参阅 目录函数

下表列出了结果集中的列。 第 6 列以外的其他列 (PK_NAME) 可由驱动程序定义。 应用程序应通过从结果集末尾倒数(而不是指定显式序号位置)来访问特定于驱动程序的列。 有关详细信息,请参阅 目录函数返回的数据

列名称 列号 数据类型 注释
TABLE_CAT (ODBC 1.0) 1 Varchar 主键表目录名称;如果不适用于数据源,则为 NULL。 如果驱动程序支持某些表的目录,但不支持其他表的目录,例如当驱动程序从不同的 DBMS 检索数据时,它将为没有目录的表返回空字符串 (“”) 。
TABLE_SCHEM (ODBC 1.0) 2 Varchar 主键表架构名称;如果不适用于数据源,则为 NULL。 如果驱动程序支持某些表的架构,但不支持其他表的架构,例如当驱动程序从不同的 DBMS 检索数据时,它会为没有架构的表返回空字符串 (“”) 。
TABLE_NAME (ODBC 1.0) 3 Varchar 非 NULL 主键表名称。
COLUMN_NAME (ODBC 1.0) 4 Varchar 非 NULL 主键列名称。 驱动程序返回没有名称的列的空字符串。
KEY_SEQ (ODBC 1.0) 5 Smallint(非 NULL) 键 (中的列序列号从 1) 开始。
PK_NAME (ODBC 2.0) 6 Varchar 主键名称。 如果不适用于数据源,则为 NULL。

代码示例

请参阅 SQLForeignKeys

有关以下方面的信息 请参阅
将缓冲区绑定到结果集中的列 SQLBindCol 函数
取消语句处理 SQLCancel 函数
提取数据块或滚动浏览结果集 SQLFetchScroll Function(SQLFetchScroll 函数)
以仅向前方向提取单行或数据块 SQLFetch 函数
返回外键的列 SQLForeignKeys 函数
返回表统计信息和索引 SQLStatistics 函数

另请参阅

ODBC API 参考
ODBC 头文件