SQLVAR_T Structure Components

Table 2–13 describes the components of the SQLVAR_T structure.

Table 2–13: SQLVAR_T Structure Components
Component
Description
DATA
Pointer to the storage in which the value that a dynamic FETCH returns is to be stored, or where the value to be supplied for a parameter marker might be located. The program must set it before the first FETCH or prior to executing a prepared statement. Align the storage for the data type of the values being retrieved according to the rules of your machine architecture. Otherwise, a memory violation might occur.
INDICATOR
Pointer to a host language variable of type long, to indicate whether a fetched value is NULL (or has been truncated) or to indicate that a value for a parameter marker is to assume the NULL value.
On a FETCH, the location to which INDICATOR refers is set to the value -1 if the column is NULL, and the total length of the column if the target value (as defined in the SQLDA) is too small for a character value. If INDICATOR returns -1, the value of DATA is undefined and should be ignored. Otherwise INDICATOR is set to 0.
INDICATOR is unused until a FETCH is executed. The host program must set the pointer. If it is not set, and the value of the column is NULL, the same error code is returned in SQLCODE as would be returned if an ordinary static FETCH did not provide an indicator.
On an EXECUTE, the ESQL-LIB interface examines the location to which INDICATOR refers in order to determine whether the value to be supplied for a parameter marker is NULL. If the location to which INDICATOR refers is set to the value of -1, then the NULL value is used as the value of the parameter marker.
If you are not using the INDICATOR field, ensure that INDICATOR is set to 0. Otherwise, unpredictable results may occur.
LENGTH
When fetching data, the declared length for an SQL CHARACTER column (a column in a table created through a CREATE TABLE statement). For Progress CHARACTER fields, which have no declared length, LENGTH is the field length the Progress display format indicates. For example, a format of "X(20)" would yield a LENGTH of 20; a format of "(999) 999-9999" would yield a LENGTH of 10 (filler display characters are not counted, because the value is returned to the host program unformatted). The LENGTH does not include the null terminator required for the target variable. LENGTH is undefined for other data types and for all expressions.
For parameter marker values, LENGTH is the length in bytes of an SQL CHARACTER value.
TYPE
Numeric code indicating the declared data type of the column:
SQLDACHAR (1) for CHARACTER
SQLDANUM (2) for NUMERIC
SQLDADE (3) for DECIMAL
SQLDAINT (4) for INTEGER
SQLDASML (5) for SMALLINT
SQLDAFLT (6) for FLOAT
SQLDAREAL (7) for REAL
SQLDADBL (8) for DOUBLE PRECISION
SQLDADATE (-1) for Progress DATE
SQLDALOG (-2) for Progress LOGICAL
SCALE
When fetching data, SCALE is set to 0 for INTEGER, SMALLINT, FLOAT, REAL, and DOUBLE PRECISION, and the declared scale for SQL DECIMAL or NUMERIC columns (for example, a declaration in a CREATE TABLE statement of DECIMAL(5,2) means a scale of 2). For Progress DECIMAL fields, SCALE is the value assigned to “Decimals” in the dictionary. SCALE is undefined for other data types and for derived columns (expressions). Any results that may be returned for SCALE for derived columns are unreliable and should not be used by the application.
When supplying values for parameter markers, SCALE is ignored. For DECIMAL and NUMERIC values, the SCALE factor is obtained by scanning the C character string for the decimal separator.
PRECISION
When fetching data, the declared precision for SQL DECIMAL, NUMERIC and FLOAT columns. (For example, for DECIMAL(5,2) the precision is 5.) For Progress DECIMAL fields, PRECISION is calculated from the Progress display format, disregarding display fill characters. For example, a format of “->>,>>>,>>9.99" yields a PRECISION of 10. PRECISION is undefined for other data types, and for derived columns. Any results that may be returned for PRECISION for derived columns are unreliable and should not be used by the application.
For decimal and numeric types, set PRECISION to 3 less than the length of the data, including the NULL character. For example, “-123.4" must set PRECISION to 4 with 7 bytes allocated.
NULLABLE
Is set to 1 if the column can have NULL values and 0 otherwise. It defaults to 0 for derived columns. This value is ignored when supplying values for parameter markers.
NAME
Holds the column name. This is undefined for derived columns. The first 33 bytes of NAME contain the column name (up to 32 bytes) and a NULL (\0) terminator. The NULL terminator is present at the end of the column name.
For array columns, 3 to 6 bytes can be used by the subscript, depending on the maximum value of the extent (2 bytes + number of digits in subscript value). Thus, the array column name can be from 26 to 29 bytes, depending on this maximum extent value. Any name that is too long for the extent value generates an error.
The last 3 bytes in NAME are reserved for internal ESQL use. This member is ignored when supplying values for parameter markers.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095