Length/Indicator buffers

The length/indicator buffer is used to pass the byte length of the data in the data buffer or a special indicator such as SQL_NULL_DATA, which indicates the data is NULL. Depending on the function in which it is used, a length/indicator buffer is defined to be an SQLINTEGER_KIND or a SQLSMALLINT_KIND. Therefore, a single argument is needed to describe it. If the data buffer is a non-deferred input buffer, this argument contains the byte length of the data itself or an indicator value. It is often named StrLen_or_Ind or a similar name. If the data buffer is a deferred input buffer, a non-deferred output buffer, or an output buffer, the argument contains the address of the length/indicator buffer. It is often named StrLen_or_IndPtr or a similar name. Unless it is specifically prohibited, a length/indicator buffer argument can be 0 (if non-deferred input) or a null pointer (if output or deferred input). For input buffers, this causes the driver to ignore the byte length of the data. This returns an error when passing variable-length data but is common when passing non-null, fixed-length data. Neither a length nor an indicator value is needed in the last case. For output buffers, the driver will not return the byte length of the data or an indicator value. This is an error if the data returned by the driver is NULL, but is common when retrieving fixed-length, non-nullable data because neither a length nor an indicator value is needed.

As is the case when the address of a deferred data buffer is passed to the driver, the address of a deferred length/indicator buffer must remain valid until the buffer is unbound.

The following lengths are valid as length/indicator values:

• n, where n > 0.

• 0.

• SQL_NTS. A string sent to the driver in the corresponding data buffer is null-terminated. This is a convenient way for C programmers to pass strings without having to calculate their byte length. However, it is not very useful for Fortran programmers. This value is legal only when the application sends data to the driver. When the driver returns data to the application, it always returns the actual byte length of the data.

The following values are valid as length/indicator values (SQL_NULL_DATA is stored in the SQL_DESC_INDICATOR_PTR descriptor field. All other values are stored in the SQL_DESC_OCTET_LENGTH_PTR descriptor field):

• SQL_NULL_DATA. Indicates the data is a NULL value and the value in the corresponding data buffer is ignored. This value is legal only for SQL data sent to or retrieved from the driver.

• SQL_DATA_AT_EXEC. Indicates the data buffer does not contain any data. Instead, the data will be sent with f90SQLPutData when the statement is executed, or when f90SQLBulkOperations or f90SQLSetPos is called. This value is legal only for SQL data sent to the driver. For more information, see f90SQLBindParameter, f90SQLBulkOperations, and f90SQLSetPos.

• Result of the function f90SQLLenDataAtExec(length). This value is similar to SQL_DATA_AT_EXEC.

• SQL_NO_TOTAL. Indicates the driver cannot determine the number of bytes of long data still available to return in an output buffer. This value is legal only for SQL data retrieved from the driver.

• SQL_DEFAULT_PARAM. A procedure is to use the default value of an input parameter in a procedure instead of the value in the corresponding data buffer.

• SQL_COLUMN_IGNORE. Subroutines f90SQLBulkOperations and f90SQLSetPos will ignore the value in the data buffer. When updating a row of data by a call to f90SQLBulkOperations or f90SQLSetPos, the column value is not changed. When inserting a new row of data by a call to f90SQLBulkOperations, the column value is set to its default. If the column does not have a default it is set to NULL.

When you move through the next chapters and learn how to use many of these subroutines, the meaning and usefulness of these values will become clear.