SQLTablePrivileges Function(SQLTablePrivileges 函数)

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

摘要
SQLTablePrivileges 返回表的列表以及与每个表关联的特权。 驱动程序将信息作为指定语句的结果集返回。

语法

  
SQLRETURN SQLTablePrivileges(  
     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 检索数据时,空字符串 (“”) 表示那些没有架构的表。

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

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

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。

诊断

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

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

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

调用 了 SQLTablePrivileges 函数,在它完成执行之前, SQLCancelSQLCancelHandle 是从多线程应用程序中的不同线程在 StatementHandle 上调用的。
HY009 null 指针的使用无效 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, CatalogName 参数为空指针,SQL_CATALOG_NAME InfoType 返回支持的目录名称。

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

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

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

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos 已为 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行时参数或列发送数据之前调用了此函数。
HY013 内存管理错误 无法处理函数调用,因为无法访问基础内存对象,可能是因为内存不足。
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 SQL_ATTR_CONNECTION_TIMEOUT设置。
IM001 驱动程序不支持此函数 (DM) 与 StatementHandle 关联的驱动程序不支持 函数。
IM017 在异步通知模式下禁用轮询 每当使用通知模型时,将禁用轮询。
IM018 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 如果对句柄的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式,则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。

注释

SchemaNameTableName 参数接受搜索模式。 有关有效搜索模式的详细信息,请参阅 模式值参数

SQLTablePrivileges 以标准结果集的形式返回结果,按TABLE_CAT、TABLE_SCHEM、TABLE_NAME、PRIVILEGE 和 GRANTEE 排序。

若要确定TABLE_CAT、TABLE_SCHEM和TABLE_NAME列的实际长度,应用程序可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN和SQL_MAX_TABLE_NAME_LEN选项调用 SQLGetInfo

注意

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

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

ODBC 2.0 列 ODBC 3.x
TABLE_QUALIFIER TABLE_CAT
TABLE_OWNER TABLE_SCHEM

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

列名称 列号 数据类型 注释
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 表名。
GRANTOR (ODBC 1.0) 4 Varchar 授予权限的用户的名称;如果不适用于数据源,则为 NULL。

对于 GRANTEE 列中的值是对象所有者的所有行,GRANTOR 列将为“_SYSTEM”。
GRANTEE (ODBC 1.0) 5 Varchar 非 NULL 向其授予权限的用户的名称。
PRIVILEGE (ODBC 1.0) 6 Varchar 非 NULL 表特权。 可以是以下权限之一,也可以是特定于数据源的特权。

SELECT:允许被授权者检索表的一列或多列的数据。

INSERT:允许被授权者在表中插入包含一列或多列数据的新行。

更新:允许被授权者更新表的一列或多列中的数据。

DELETE:允许被授权者从表中删除数据行。

引用:允许被授权者在约束 (引用表的一列或多列,例如,唯一、引用或表检查约束) 。

给定表特权允许被授权者的操作范围取决于数据源。 例如,UPDATE 特权可能允许被授权者更新表中一个数据源的所有列,并且仅允许授权者对另一个数据源具有 UPDATE 权限的列。
IS_GRANTABLE (ODBC 1.0) 7 Varchar 指示是否允许被授权者向其他用户授予权限;“YES”、“NO”或 NULL(如果未知或不适用于数据源)。

特权要么是可授予的,要么是不可授予的,但不能同时授予两者。 SQLColumnPrivileges 返回的结果集永远不会包含除 IS_GRANTABLE 列以外的所有列都包含相同值的两行。

代码示例

有关类似函数的代码示例,请参阅 SQLColumns

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

另请参阅

ODBC API 参考
ODBC 头文件