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

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

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

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

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

(DM) SQLExecute、SQLExecDirectSQLMoreResultsStatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。

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

(DM) SQLExecute、SQLExecDirectSQLBulkOperationsSQLSetPosStatementHandle 调用并返回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:被授权者允许在表中插入包含一个或多个列数据的新行。

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

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 头文件