19.4.6 a_rdb_SQLDescribeCols() (acquire information about the retrieval result columns)

Organization of this subsection

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

(1) Function

This CLI function acquires information about the retrieval result columns. The information that is acquired includes the following:

Column names of the retrieval result columns
Data types of the retrieval result columns
Maximum numbers of elements in the retrieval result columns
Data lengths of the retrieval result columns

To Page Top

(2) Format

signed short a_rdb_SQLDescribeCols
(
  void                          *ConnectionHandle,   /* In  */
  void                          *StatementHandle,    /* In  */
  unsigned short                 ColumnCount,        /* In  */
  a_rdb_SQLColumnInfo_t         *ColumnInfo,         /* Out */
  void                          *Option              /* In  */
)

To Page Top

(3) Arguments

ConnectionHandle

Specifies a connection handle.

StatementHandle

Specifies a statement handle.

ColumnCount

Specifies the number of retrieval result columns for which information is to be acquired.

Specify the number of retrieval result columns that was acquired by a_rdb_SQLNumResultCols().

ColumnInfo

Specifies the start address of the column information area in which the addresses of the areas for acquiring retrieval result column information is to be set.

Provide an area in which as many a_rdb_SQLColumnInfo_t structures as is specified for ColumnCount can be placed consecutively.

For details about the a_rdb_SQLColumnInfo_t structure, see 19.7.1 a_rdb_SQLColumnInfo_t structure (column information).

Option

Specifies NULL.

To Page Top

(4) Return value

If a_rdb_SQLDescribeCols() terminates normally, a_rdb_RC_SQL_SUCCESS is returned.
If information about the retrieval result columns is acquired successfully, but the disk containing client message log files has become full, a_rdb_RC_SQL_WARNING is returned.
If an error occurs while messages cannot be output to the client message log file, the error cause code is returned. For details about the error cause code, see 19.8 Return values of the CLI functions.

To Page Top

(5) Notes

The names of the retrieval result columns are acquired in the name storage area of the a_rdb_SQLNameInfo_t structure. For details about the names of retrieval result columns, see Rules in Specification format and rules for the SELECT statement in the manual HADB SQL Reference.
Specify for the length of the name storage area of the a_rdb_SQLNameInfo_t structure a value that is greater by the byte length of one null character than the actual length (null character means 0x00).
If the length of the name storage area of the a_rdb_SQLNameInfo_t structure is equal to or greater than the length of the retrieval result column name (in bytes) plus the byte length of one null character, a character string to which one null character is appended is acquired as the retrieval result column name.
If the length of the name storage area of the a_rdb_SQLNameInfo_t structure is less than the length of the retrieval result column name (in bytes) plus the byte length of one null character, the trailing part of the retrieval result column name (the portion that does not fit in the name storage area) is truncated. As much of the leading part of the retrieval result column name as fits in the name storage area is stored with one null character appended.
The length of a retrieval result column name (in bytes) is acquired in the column name length storage area of the a_rdb_SQLNameInfo_t structure.
A code indicating the data type (data type code) of a retrieval result column is stored in the data type code storage area of the a_rdb_SQLDataType_t structure. For details about the data type code for each data type, see List of data types in the manual HADB SQL Reference.
The maximum number of elements in a retrieval result column is stored in the maximum elements count storage area of the a_rdb_SQLDataType_t structure. The maximum number of elements in a retrieval result column is always 1.

Information about the data length of a retrieval result column is stored in the column length storage area and column length attribute storage area of the a_rdb_SQLDataType_t structure. The value to be acquired in each area depends on the data type of the retrieval result column, as shown in the following table.

Table 19‒4: Column length and column length attribute
No.	Data type	Column length	Column length attribute
1	`INTEGER`	`8`	`0`
2	`SMALLINT`	`4`	`0`
3	`DECIMAL(m,n)`^#1	`m`	`n`
4	`DOUBLE` `PRECISION`	`8`	`0`
5	`CHAR(n)`	`n`	`0`
6	`VARCHAR(n)`	`n`	`0`
7	`DATE`	`4`	`0`
8	`TIME(p)`^#2	3 + ↑`p` ÷ 2↑	`p`
9	`TIMESTAMP(p)`^#2	7 + ↑`p` ÷ 2↑	`p`
10	`BINARY(n)`	`n`	`0`
11	`VARBINARY(n)`	`n`	`0`
12	`ROW`	`row-length`	`0`

Legend:: m, n, p: Positive integer
#1: If the data type is DECIMAL, the precision is set as the column length and the scaling is set as the column length attribute.
#2: If the data type is TIME or TIMESTAMP, the data length is set as the column length and the length of the fractional seconds is set as the column length attribute.

a_rdb_SQLDescribeCols() cannot be executed in the following cases:
- Connection has not been established.
- An invalid statement handle is specified.
- The value specified as the number of retrieval result columns is not the value acquired by a_rdb_SQLNumResultCols().

To Page Top