The SQLDA Record

The SQLDA (SQL Descriptor Area) is used to pass type and size information about an SQL statement, an Ingres form, or a table field, between Ingres and your program.

To use the SQLDA, you should issue the include sqlda statement in front of each compilation unit containing references to the SQLDA. You cannot issue the include sqlda statement inside a compilation unit because the statement causes the preprocessor to generate Ada with and use clauses, which are not legal in that context.

The package specified by the include sqlda statement is called ESQLDA and contains the SQLDA record type definition. The package does not declare an SQLDA record variable; your program must declare a variable of the specified type. You can also code the SQLDA record variable directly instead of using the include sqlda statement. When coding the declaration yourself, you can choose any name for the record type.

-- Data Type Codes
IISQ_DTE_TYPE: constant := 3; -- Date - Output
IISQ_MNY_TYPE: constant := 5; -- Money - Output

IISQ_DEC_TYPE: constant := 10; -- Decimal - Output
IISQ_CHA_TYPE: constant := 20; -- Char-Input, Output
IISQ_VCH_TYPE: constant := 21; -- Varchar- Input, Output
IISQ_LVCH_TYPE:constant := 22; -- Long Varchar - Output
IISQ_INT_TYPE: constant := 30; -- Integer-Input, Output
IISQ_FLT_TYPE: constant := 31; -- Float-Input, Output
IISQ_OBJ_TYPE: constant := 45; -- 4GL Object: Output
IISQ_HDLR_TYPE:constant := 46; -- Datahandler -Inp/Output
IISQ_TBL_TYPE: constant := 52; -- Table field - Output
IISQ_DTE_LEN: constant := 25; -- Date length

-- Address constant to avoid SYSTEM requirement
IISQ_ADR_ZERO: constant ADDRESS := ADDRESS_ZERO;

type IISQL_NAME is -- Varying length name
record
sqlnamel: Short_Integer;
sqlnamec: String(1..34);
end record;

type IISQL_VAR is
               -- Single element of SQLDA column/variable
  record
             sqltype: Short_Integer;
             sqllen: Short_Integer;
             sqldata: Address; -- Address of any type
             sqlname: IISQL_NAME;
  end record;

type IISQL_VARS is -- Array of IISQL_VAR elements
  array(Short_Integer range <>) of IISQL_VAR;

-- IISQLDA - SQLDA with varying number of
-- result variables.
-- Default is maximum number (IISQ_MAX_COLS).
type IISQLDA (sqln: Short_Integer := IISQ_MAX_COLS) is
     record
             sqldaid: String(1..8);
             sqldabc: Integer;
             sqld:    Short_Integer;
             sqlvar: IISQL_VARS(1..sqln);
     end record;

-- Generic SQL-compatible record layout description.
-- for IISQLDA use
record
     sqldaid at 0 range 0..63;
                       -- Bytes 0..7 = String(1..8);
     sqldabc at 8 range 0..31;
                      -- Bytes 8..11 = Integer;
     sqln at 12 range 0..15;
                     -- Bytes 12..13 = Short_Integer;
     sqld at 14 range 0..15;
                     -- Bytes 14..15 = Short_Integer;
end record;

--
-- IISQHDLR - Structure type with function pointer and
-- function argument for the DATAHANDLER
--
type IISQHDLR is
    record
         sqlarg:    Address;
         sqlhdlr:   Address;
    end record;

• The record type definition of the SQLDA is called IISQLDA. This is done so that an SQLDA variable can be called "SQLDA" without causing an Ada compile-time conflict. You are not required to call your SQLDA record variable "SQLDA."

• The record type definition includes a discriminant, sqln. This discriminant indicates how many elements are allocated in the varying length array, sqlvar. The VAX/Ada default is to allocate space for the discriminant at the start of the record. In order to enforce a compatible SQLDA record layout with the Ingres runtime system and other embedded languages, an Ada representation clause is issued. This clause causes the discriminant, sqln, to be placed among the record components as defined in the SQL Reference Guide. This is described in more detail later.

• The varying length sqlvar array, whose length is determined by the discriminant sqln, has a default size of IISQ_MAX_COLS (1024) elements. If you declare an SQLDA record variable of type IISQLDA without a discriminant constraint, then the program will have declared a record with IISQ_MAX_COLS elements.

• Note that the sqlvar array begins at subscript 1. If you code your own SQLDA record you can specify any number for a lower bound.

• The sqldata and sqlind record components are declared as addresses. You must set these to point at variables using the Ada address attribute. You must set the addresses before using the SQLDA to retrieve or set Ingres data in the database or in a form. Because you can use null indicators, a constant (IISQ_ADR_ZERO) is provided so that you can set sqlind to the zero address without including the SYSTEM package.

• If your program defines its own SQLDA record type you must verify that the internal record layout is identical to that of the IISQLDA record type, although you can declare a different number of sqlvar elements. You need not declare the type with a discriminant, but if you do, you must issue an Ada representation clause to force the 2-byte discriminant to be placed between sqldabc and sqld. The internal layout of the IISQLDA record type is equivalent to the following pseudo Ada declaration:

type IISQLDA_RECORD_LAYOUT is
        record
            sqldaid: String(1..8);
            sqldabc: Integer;
            sqln:    Short_Integer; -- See FOR clause
            sqld:    Short_Integer;
            sqlvar: IISQL_VARS(1..sqln);
        end record;

Consequently, if you declare a record type without a discriminant (that is, with a fixed length array of sqlvar elements), you should position the sqln component as shown above.

• The sqlname component is a varying length character string consisting of a length and data area. The sqlnamec component contains the name of a result field or column after a describe or prepare into statement. The length of the name is specified by sqlnamel. The characters in sqlnamec are padded with blanks. You can also set the sqlname component by a program using Dynamic FRS. The program is not required to pad sqlnamec with blanks. For more information, see How to Set SQLNAME for Dynamic FRS in this chapter.

• The list of type codes represent the types that are returned by the describe statement, and the types used by the program when retrieving or setting data with an SQLDA. The type code IISQ_TBL_TYPE indicates a table field and is set by the FRS when describing a form that contains a table field.