16.10.2 SQLColumns, SQLColumnsW

Organization of this subsection

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

(1) Function

This ODBC function returns a listing of column information as a result set.

(2) Format

For SQLColumns

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

For SQLColumnsW

SQLRETURN SQLColumnsW
(
  SQLHSTMT          StatementHandle,   /* In */
  SQLWCHAR        * CatalogName,       /* In */
  SQLSMALLINT       NameLength1,       /* In */
  SQLWCHAR        * SchemaName,        /* In */
  SQLSMALLINT       NameLength2,       /* In */
  SQLWCHAR         * TableName,        /* In */
  SQLSMALLINT       NameLength3,       /* In */
  SQLWCHAR        * ColumnName,        /* 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 a pattern character string^#2 for schema names. If NULL is specified, the driver processing is the same as when '%' is specified as the pattern character string.

NameLength2

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

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

TableName

Specifies a pattern character string^#2 for table names. If NULL is specified, the driver processing is the same as when '%' is specified as the pattern character string.

NameLength3

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

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

ColumnName

Specifies a pattern character string^#2 for column names. If NULL is specified, the driver processing is the same as when '%' is specified as the pattern character string.

NameLength4

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

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

#1

The length must be in bytes for SQLColumns and in characters for SQLColumnsW.

#2

The following table lists the special characters that can be specified in pattern character strings.

Table 16‒10: Special characters that can be specified in pattern character strings
Special character	Meaning
`_` (underscore)	Any single character.
`%`	A character string of any length, including zero characters.
`\`	An escape character. A special character that immediately follows an escape character in a pattern character string is handled as a normal character. The character `\` is represented by the Shift-JIS character code 0x5c (or 0x5c00 in UTF-16LE). In UTF-8, specify the character displayed as a backslash (`\`).

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 shows the format of the result set that is returned after execution.

Table 16‒11: Format of the 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`	`COLUMN_NAME`	Column name
5	`smallint`	`DATA_TYPE`	ODBC SQL data type identifier
6	`Varchar`	`TYPE_NAME`	Type name
7	`Integer`	`COLUMN_SIZE`	Column size
8	`Integer`	`BUFFER_LENGTH`	Column data definition length
9	`Smallint`	`DECIMAL_DIGITS`	Number of decimal places
10	`Smallint`	`NUM_PREC_RADIX`	Cardinal number Exact numeric value: `10` Nonnumeric value: Null value
11	`Smallint`	`NULLABLE`	Returns a value indicating whether a null value can be used for this type. `SQL_NO_NULLS`: Null values might not be permitted. `SQL_NULLABLE`: Null values are permitted.
12	`Varchar`	`REMARKS`	The function always returns a null value.
13	`Varchar`	`COLUMN_DEF`	The function returns the default value of a column. When the returned value is enclosed by single quotation marks ('), it means the default value of the column is a character string. If `NULL` is specified as the default value of the column, the character string `NULL` is returned without single quotation marks (`'`). If no default value is specified for the column, the function returns a null value. For details about other return values, see the description of the `DEFAULT_VALUE` column under Content of SQL_COLUMNS in the HADB Setup and Operation Guide. If no default value has been specified, the function returns `NULL`.
14	`Smallint`	`SQL_DATA_TYPE`	ODBC SQL data type identifier
15	`Smallint`	`SQL_DATETIME_SUB`	Subcode of ODBC SQL data type identifier
16	`Integer`	`CHAR_OCTET_LENGTH`	Maximum length (in bytes) of a column whose data type is character string data
17	`Integer`	`ORDINAL_POSITION`	Column number Begins with 1.
18	`Varchar`	`IS_NULLABLE`	Returns a value indicating whether a null value can be used for this type: `YES`: Null values might be permitted. `NO`: Null values are not permitted.

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		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
`HY117`	Connection suspended	--	N
`HYC00`	Optional feature not implemented		N
`HYT00`	Timeout expired		N
`HYT01`	Connection timeout expired		N
`IM001`	Driver does not support this function		N
`IM017`	Invalid asynchronous polling		N
`IM018`	Incomplete asynchronous execution		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 column information that can be acquired depends on the privileges of the HADB user who executes this function. For details about the privileges and the column 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