The SQLDA Record

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

In order to use the SQLDA, you should issue the include sqlda statement at the proper scope of the source file, from where the SQLDA will be referenced. The include sqlda statement generates a BASIC include directive to a file that defines the SQLDA record type. The file does not declare an SQLDA record variable; your program must declare a variable of the specified type. You can also code this record declaration directly instead of using the include sqlda statement. When coding the declaration yourself, you can choose any name for the record type.

The definition of the SQLDA (as specified in the include file) is:

! IISQ_MAX_COLS - Maximum number of columns returned from Ingres
!
declare word constant IISQ_MAX_COLS = 300
!
! IISQLDA - SQLDA with maximum number of entries for
! variables.
!

record IISQLDA
         string sqldaid = 8
        long sqldabc
        word sqln
        word sqld
        group sqlvar(IISQ_MAX_COLS)
                word sqltype
                word sqllen
                long sqldata ! Address of any type
                long sqlind ! Address of 2-byte integer
                group sqlname
                    word     sqlnamel
                    string     sqlnamec = 34
                end group sqlname
        end group sqlvar
end record IISQLDA

!
! Type Codes
!
declare integer constant IISQ_DTE_TYPE = 3
! Date - Out
declare integer constant IISQ_MNY_TYPE = 5
! Money - Out
declare integer constant IISQ_DEC_TYPE =10
! Decimal - Out
declare integer constant IISQ_CHA_TYPE = 20
! Char - In/Out
declare integer constant IISQ_VCH_TYPE = 21
! Varchar - In/Out

declare integer constant IISQ_INT_TYPE = 30
! Integer - In/Out
declare integer constant IISQ_FLT_TYPE = 31
! Float - In/Out
declare integer constant IISQ_TBL_TYPE = 52
! Table field - Out
declare integer constant IISQ_DTE_LEN = 25
! Date length

!
! Dynamic allocation sizes - When allocating an
! SQLDA for N results use:
! IISQDA_HEAD_SIZE + (N * IISQDA_VAR_SIZE)
!
declare integer constant IISQDA_HEAD_SIZE = 16
declare integer constant IISQDA_VAR_SIZE = 48

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

• The sqlvar array is an array of IISQ_MAX_COLS (300) elements. If you declare a record variable of type IISQLDA, then the program will have a variable with IISQ_MAX_COLS sqlvar elements.

• Note that the sqlvar array begins at subscript 0 because of the BASIC default of arrays being zero-based. Because this array begins at subscript zero, it implies that relevant result variables are described by the elements 0 through sqld-1, rather than 1 through sqld.

• The sqldata and sqlind group members are declared as long integers. These must be set to the addresses of other result variables before using the SQLDA to retrieve or set Ingres data in the database or form. You can use the BASIC loc function to assign addresses.

• If you declare your own SQLDA record type and variable, you must confirm that the record layout is identical to that of the IISQLDA record type, although you can allocate a different number of sqlvar array elements.

• The nested group sqlname is a varying length character string consisting of a length and data area. The sqlnamec member 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 the sqlnamec field are blank padded. You can also set the sqlname group 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 represents the types that will be 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.