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.
For the length of the name storage area of the a_rdb_SQLNameInfo_t structure, specify a value that is greater by the byte length of one null character than the actual length. The null character here refers to 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 when the retrieval result column is not of the array type 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	BIGINT	8	0
2	INTEGER^#3	4	0
3	SMALLINT^#4	2	0
4	DECIMAL(`m`,`n`)^#1	`m`	`n`
5	NUMERIC(`m`,`n`)^#1	`m`	`n`
6	REAL	4	0
7	DOUBLE PRECISION	8	0
8	FLOAT	8	0
9	CHAR(`n`)	`n`	0
10	VARCHAR(`n`)	`n`	0
11	STRING	32,000,000	0
12	DATE	4	0
13	TIME(`p`)^#2	3 + ↑`p` ÷ 2↑	`p`
14	TIMESTAMP(`p`)^#2	7 + ↑`p` ÷ 2↑	`p`
15	BINARY(`n`)	`n`	0
16	VARBINARY(`n`)	`n`	0
17	BOOLEAN	1	0
18	UUID	16	0
19	ROW	`Row length`	0

Legend:

m, n, p: Positive integer

#1

If the data type is DECIMAL or NUMERIC, the column length acquires the precision.

Similarly, the column length attribute acquires scaling.

#2

If the data type is TIME or TIMESTAMP, the column length acquires the data length. Similarly, the column length attribute acquires the number of digits in the fractional seconds.

#3

If the integer data type format is in legacy format, the column length will be 8 and the column length attribute will be 0.

#4

If the integer data type format is in legacy format, the column length will be 4 and the column length attribute will be 0.

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

To Page Top