16.10.10 SQLTables, SQLTablesW

Organization of this subsection

(1) Function
(2) Format
(3) Arguments
(4) Return value
(5) SQLSTATE
(6) Notes

(1) Function

This ODBC function returns a list of the table names, schema names, and table types stored at the HADB server.

The driver returns the information as a result set for the specified SQL statement.

(2) Format

For SQLTables

SQLRETURN SQLTables
(
  SQLHSTMT         StatementHandle,        /* In */
  SQLCHAR        * CatalogName,            /* In */
  SQLSMALLINT      NameLength1,            /* In */
  SQLCHAR        * SchemaName,             /* In */
  SQLSMALLINT      NameLength2,            /* In */
  SQLCHAR        * TableName,              /* In */
  SQLSMALLINT      NameLength3,            /* In */
  SQLCHAR        * TableType,              /* In */
  SQLSMALLINT      NameLength4             /* In */
)

For SQLTablesW

SQLRETURN SQLTablesW
(
  SQLHSTMT         StatementHandle,        /* In */
  SQLWCHAR       * CatalogName,            /* In */
  SQLSMALLINT      NameLength1,            /* In */
  SQLWCHAR       * SchemaName,             /* In */
  SQLSMALLINT      NameLength2,            /* In */
  SQLWCHAR       * TableName,              /* In */
  SQLSMALLINT      NameLength3,            /* In */
  SQLWCHAR       * TableType,              /* In */
  SQLSMALLINT      NameLength4             /* In */
)

To Page Top

(3) Arguments

StatementHandle

Specifies a statement handle.

CatalogName

Specifies that the specified information is to be used as a catalog name.

The specified information is ignored, but the specification itself is required. Therefore, when you use this function, specify a null character string ("") or NULL.

NameLength1

Specifies the length of *CatalogName^#1 or SQL_NTS. The specified information is ignored, but the specification itself is required.

Therefore, when you use this function, specify 0.

SchemaName

Specifies an authorization identifier or a pattern character string^#2 for authorization identifiers. If a null pointer or a null character string ("") is specified, the driver assumes that '%' is specified as the pattern character string.

NameLength2

Specifies the length of *SchemaName^#1 or SQL_NTS.

If 0 is specified, the processing is the same as when '%' is specified as the pattern character string in SchemaName.

TableName

Specifies a table identifier or a pattern character string^#2 for table identifiers. If a null pointer or a null character string ("") is specified, the driver assumes that '%' is specified as the pattern character string.

NameLength3

Specifies the length of *TableName^#1 or SQL_NTS.

If 0 is specified, the processing is the same as when '%' is specified as the pattern character string in TableName.

TableType

Specifies a pointer to the character string that indicates the matching table type. The HADB ODBC driver recognizes the following character strings as table types:

SYSTEM TABLE
TABLE
VIEW

When you specify this argument, optionally enclose each character string in single quotation marks ('). To acquire the results of multiple table types, delimit the values with the comma (,).

Examples:

To acquire dictionary tables and system tables

Specify SYSTEM TABLE or 'SYSTEM TABLE'.
To acquire base and viewed tables

Specify TABLE,VIEW or 'TABLE','VIEW'.

If a null pointer, a null character string (""), or SQL_ALL_TABLE_TYPES is specified in this argument, 'SYSTEM TABLE','TABLE','VIEW' is assumed as the table types.

If the specified value contains a character string that is not recognized as a table type by the HADB ODBC driver, only any character strings recognized by the HADB ODBC driver take effect, and any others are ignored. If the specified value contains only invalid character strings, the HADB ODBC driver assumes that 'SYSTEM TABLE','TABLE','VIEW' is specified, in the same manner as when a null pointer or a null character string ("") is specified.

NameLength4

Specifies the length of *TableType^#1 or SQL_NTS.

If 0 is specified, 'SYSTEM TABLE','TABLE','VIEW' is assumed for TableType.

#1

The length must be in bytes for SQLTables and in characters for SQLTablesW.

#2

For details about the special characters that can be specified in pattern character strings, see Table 16‒10: Special characters that can be specified in pattern character strings.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

The following table describes the format of the result set that is returned.

Table 16‒17: Format of result set that is returned
Column No.	Type	Column name	Description
1	`Varchar`	`TABLE_CAT`	The function always returns a null value.
2	`Varchar`	`TABLE_SCHEM`	Schema name
3	`Varchar`	`TABLE_NAME`	Table name
4	`Varchar`	`TABLE_TYPE`	Table type: `TABLE`: Base table `VIEW`: Viewed table `SYSTEM` `TABLE`: Dictionary table or system table
5	`Varchar`	`REMARKS`	The function always returns a null value.

To Page Top

(5) SQLSTATE

This ODBC function returns one of the following SQLSTATE values:

SQLSTATE	Description	Remarks	Returned
`01000`	General warning	--	N
`08S01`	Communication link failure		N
`24000`	Invalid cursor status		N
`40001`	Serialization failure		N
`40003`	Statement completion unknown		N
`5C002`	Character encoding conversion error	A character code that cannot be converted was detected.	Y
`5C041`	Unsupported data type error	The driver does not support the specified data type.	N
`HY000`	General error	--	N
`HY001`	Memory allocation error	The memory required to execute or complete the function has not been allocated for the HADB ODBC driver.	Y
`HY008`	Operation cancelled	--	N
`HY009`	Invalid use of null pointer		N
`HY010`	Function sequence error		Y
`HY013`	Memory management error		N
`HY090`	Invalid string or buffer length	One of the arguments that stores a name length exceeded the maximum length for the corresponding name.	Y
`HYC00`	Optional feature not implemented	--	N
`HYT00`	Timeout expired		N
`HYT01`	Connection timeout expired		N
`IM001`	Driver does not support this function		N

Legend:

Y: This SQLSTATE might be returned by the HADB ODBC driver.

N: This SQLSTATE is not returned by the HADB ODBC driver.

--: None

To Page Top

(6) Notes

The table information that can be acquired depends on the privileges of the HADB user who executes this function. For details about the privileges and the table information that can be acquired, see the topic Scope of information in dictionary tables and system tables that can be referenced by HADB users in the HADB Setup and Operation Guide.

To Page Top