一致性
推出版本：ODBC 1.0 标准合规：ODBC
总结
SQLTablePrivileges 返回表列表及与每个表关联的权限。 驱动程序将信息作为指定语句的结果集返回。
Syntax
SQLRETURN SQLTablePrivileges(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3);
Arguments
StatementHandle
[输入]语句句柄。
CatalogName
[输入]餐桌目录。 如果驱动程序支持某些表的目录，但不支持其他表，例如当驱动程序从不同的数据库管理系统检索数据时，空字符串（“”）表示那些没有目录的表。
目录名称 不能包含字符串搜索模式。
如果SQL_ATTR_METADATA_ID语句属性设置为SQL_TRUE，目录 名 被视为标识符，其大小写不重要。 如果是SQL_FALSE，目录 名称 是一个普通的论证;它被字面处理，且其案例意义重大。 有关详细信息，请参阅目录函数中的参数。
NameLength1
[输入]*目录名称字符长度。
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字符长度。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
Diagnostics
当 SQLTablePrivileges 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值，Handle 为 SQL_HANDLE_STMT，Handle 为 StatementHandle。 下表列出 了SQLTablePrivileges 通常返回的SQLSTATE值，并在此函数的上下文中解释每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 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。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 为 StatementHandle 启用了异步处理。 调用了SQLTablePrivileges函数，在执行完成前，StatementHandle上调用了SQLCancel或SQLCancelHandle。 然后再次调用 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，SchemaName 或 TableName 参数是空指针。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 当调用 SQLTablePrivileges 函数时，该异步函数仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 为 StatementHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了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 才能执行后期处理并完成操作。 |
注释
SchemaName 和 TableName 参数接受搜索模式。 有关有效搜索模式的更多信息，请参见 模式值参数。
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_SCHEM |
下表列出了结果集中的列。 第7列（IS_GRANTABLE）之外的额外列可由驱动程序定义。 应用程序应通过从结果集末尾倒计时来访问驱动程序特定的列，而不是指定明确的序数位置。 有关详细信息，请参阅 目录函数返回的数据。
| 列名称 | 列号 | 数据类型 | 注释 |
|---|---|---|---|
| TABLE_CAT（ODBC 1.0） | 1 | Varchar | 目录名称;如果不适用于数据源，则使用NULL。 如果驱动程序支持某些表的目录，但不支持其他表，例如当驱动程序从不同数据库管理系统检索数据时，对于没有目录的表，驱动程序会返回一个空字符串（“”）。 |
| TABLE_SCHEM（ODBC 1.0） | 2 | Varchar | 模式名称;如果不适用于数据源，则使用NULL。 如果驱动程序支持某些表的模式，而不支持其他表，例如当驱动程序从不同数据库管理系统检索数据时，对于没有模式的表，驱动程序会返回一个空字符串（“”）。 |
| TABLE_NAME（ODBC 1.0） | 3 | Varchar 非 NULL | 表名。 |
| GRANTOR（ODBC 1.0） | 4 | Varchar | 授予该权限的用户姓名;如果不适用于数据源，则使用NULL。 对于所有 GRANTEE 列中值为对象所有者的行，GRANTOR 列将为“_SYSTEM”。 |
| 受赠人（ODBC 1.0） | 5 | Varchar 非 NULL | 授予该特权的用户姓名。 |
| 特权（ODBC 1.0） | 6 | Varchar 非 NULL | 餐桌特权。 可能是以下之一，也可能是特定数据源的特权。 SELECT：受赠方可以检索表中一个或多个列的数据。 INSERT：受赠方被允许在表格中插入包含一个或多个列数据的新行。 UPDATE：受赠方可以更新表中一个或多个列的数据。 DELETE：受赠方可以从表中删除数据行。 引用：受赠方允许在约束内引用表中的一个或多个列（例如，唯一的、引用性或表检查约束）。 受赠者通过特定表权限允许的行动范围取决于数据源。 例如，该 UPDATE 权限可能允许受赠者更新表中同一数据源上的所有列，仅更新授予者在另一个数据源上拥有 UPDATE 权限的列。 |
| IS_GRANTABLE（ODBC 1.0） | 7 | Varchar | 表示受让人是否被允许将该特权授予其他用户;如果数据源未知或不适用，则为“是”、“否”或“NULL”。 特权要么可授予，要么不可授予，但不能两者兼有。 SQLColumnPrivileges 返回的结果集绝不会包含除 IS_GRANTABLE 列外所有列值相同的两行。 |
代码示例
类似函数的代码示例请参见 SQLColumns。
相关函数
| 有关信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 某一栏或多个列的返回权限 | SQLColumnPrivileges 函数 |
| 返回表格中的列 | SQLColumns 函数 |
| 仅向前取一行或数据块 | SQLFetch 函数 |
| 提取数据块或滚动结果集 | SQLFetchScroll 函数 |
| 返回表格统计和索引 | SQLStatistics 函数 |
| 返回数据源中的表列表 | SQLTables 函数 |