Column Information Block

In this section: ColInfo ColAvailable ColRetrieved Result Set Block

The Column Information Block contains the following items:

Item Name	Data Type	Description
Colinfo	long	Information about the column.
Col Available	long	Bytes remaining to be retrieved.
Col Retrieved	long	Number of bytes retrieved.
Data	pointer	Reserved for future use.

ColInfo

The ColInfo array describes each column of a retrieved row, and it provides information about the column: whether or not it is null, whether it can be retrieved, and whether or not the length is known.

The data is treated as an array of blocks, each element describing a column. The first element (0) is reserved for future use.

To access the information for a column, an index of the column number may be used. When allocating memory for a ColInfo array, a sufficient size should be specified to accommodate the number of columns plus one, multiplied by the ColInfo size.

Reference: ColInfo Value References

Value Reference	Value	Description
EDA_COLINFO_AVAIL	0	Data available, length known.
EDA_COLINFO_NULL	1 (EDA_IS_NULL)	Column value is NULL.
EDA_COLINFO_BLOB	2	Data available, length unknown.
EDA_COLINFO_ERR	3	Unable to compute ColAvailable.
EDA_COLINFO_OFLO	8 (EDA_FIELD_OVERFLOW)	Value overflow.

ColAvailable

ColAvailable provides the number of bytes remaining to be retrieved from the column value by EDAFIELD. This value is reset in response to each EDANEXT or EDAFETCH call.

Reference: ColAvailable Values

Value	Description
0	All data has been retrieved.
N	Number of bytes remaining.

ColRetrieved

Following the execution of EDAFIELD, the value of ColRetrieved is updated to reflect the number of bytes delivered to application storage. This number should be equal to the number of bytes requested, unless the block is the last one retrieved from the column value.

This enables the application to:

• Determine whether or not an additional EDAFIELD call is required.
• Identify when retrieval is complete.
• Identify the number of bytes retrieved.

Reference: ColRetrieved Values

Value	Description
0	No data has been retrieved.
N	Number of bytes retrieved.

Result Set Block

Example: Defining a Result Set Block to Receive a Tuple Dynamically Allocating the Result Set Block in C

The API uses the result set block to return a single tuple from the result set. It passes as a parameter to the EDAFETCH method call. Upon completion of that method, the result set block will contain the first unprocessed tuple.

The result set block is a data structure defined within the application program. Unlike the SCB and the information block, the result set block has no set definition. Its definition depends on the application and the SQL statements that are executed using EDASQL, EDAEXECUTE, EDARPC, and EDABROWSE calls.

Depending on the type of application, the result set block may be a static structure within the application program, or a dynamically allocated data block built from the information block data or SCB.

A static result set is sufficient for:

Applications that contain embedded SQL statements and that pass these statements in an EDASQL or EDAPREPARE method call.

Applications that contain EDARPC method calls that produce a result set with the same description every time.

Example: Defining a Result Set Block to Receive a Tuple

In this example, a Cobol program containing the following in working storage:

77  TABLE-LIST-QUERY          PIC X(80) VALUE
        "SELECT NAME,CREATOR FROM SYSTABLE ORDER BY NAME;".
77  TABLE-LIST-LENGTH         PIC S9(8) COMP-5 VALUE 80.

would need the following result set block definition to receive a single tuple:

01  TABLE-LIST-TUPLE.
    02  TABLE-NAME            PIC X(18).
    02  TABLE-CREATOR         PIC X(8).

Note: The result set block must be dynamically allocated after each EDASQL or EDAPREPARE statement, based on the information provided by an EDAINFO call, for applications that can dynamically create SQL or take received SQL statements from a user or other source.

Example: Dynamically Allocating the Result Set Block in C

The following sample code illustrates how a C program supports dynamic SQL and fetches an alphanumeric tuple:

.
.
.
tuple = malloc((int) SCB.a_size);
.
.
.