19.4.3 a_rdb_SQLBindCols() (associate retrieval result columns)

(1) Function

This CLI function binds (associates) the retrieval result columns with an area for storing the values fetched from the retrieval result columns in the batch mode. Once a retrieval result column has been associated, the column's value is stored when the cursor is manipulated by execution of a_rdb_SQLFetch().

You can also execute a_rdb_SQLBindCols()for retrieval results that are not columns.

To Page Top

(2) Format

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

To Page Top

(3) Arguments

ConnectionHandle

Specifies a connection handle.

StatementHandle

Specifies a statement handle.

ColumnCount

Specifies the number of columns whose values are to be fetched.

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 value storage areas are 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

1. If a_rdb_SQLBindCols() terminates normally, a_rdb_RC_SQL_SUCCESS is returned.

2. If the retrieval result columns are associated successfully, but the disk containing client message log files has become full, a_rdb_RC_SQL_WARNING is returned.

3. 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

1. If the data type of obtained data is CHAR, the data storage area for the a_rdb_SQLColumnInfo_t structure stores the obtained data followed by a null character. The null character here refers to 0x00.

2. You must apply boundary alignment to the start addresses of the data storage areas of the a_rdb_SQLColumnInfo_t structure. For details about boundary alignment, see (2) Boundary alignment in 18.2.6 Notes about using the CLI functions.

3. The value for the area for storing either the data storage area length or the indicator value for the a_rdb_SQLColumnInfo_t structure is set according to the acquired data, as shown in the table below. In the table, BL means the length of the specified data storage area and DL means the size of the area required for storing the acquired data (in bytes).

   Table 19‒3: Value for the area for storing the data storage area length or the indicator value

   No.	Stored data	Data structure	Data type	Relationship between BL and DL	Data storage area length or indicator value
   1	Null value	Any	Any	Any	a_rdb_SQL_NULL_DATA
   2	Non-null value	Any	Any	BL = DL	a_rdb_SQL_NOT_NULL_DATA
   3				Other	-- (SQL error)#

   #

   This means that an SQL error occurred and the processing for setting a value in the indicator was not performed, resulting in an undefined value.

4. a_rdb_SQLBindCols() 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().

   • The data storage area length in the a_rdb_SQLColumnInfo_t structure is not the length required for storing the acquired data.

To Page Top