2. Embedded SQL for C : Dynamic Programming for C : SQLDA Structure Usage
 
Share this page                  
SQLDA Structure Usage
The SQL Descriptor Area (SQLDA) is used to pass 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, issue the include sqlda statement at the outermost scope of the source file. The include sqlda statement generates a C include directive to a file that defines the SQLDA type. The file does not declare an SQLDA variable; the program must declare a variable of the specified type. You can also code this structure directly instead of using the include sqlda statement. You can choose any name for the structure.
The definition of the SQLDA (as specified in the include file) is:
# define IISQ_MAX_COLS 1024 /*Maximum number of columns*/
typedef struct sqlvar
{
    /* Single SQLDA variable */
    short sqltype;
    short sqllen;
    char *sqldata;
    short *sqlind;
    struct {
                short sqlnamel;
                char sqlnamec[34];
            } sqlname;
 } IISQLVAR;
typedef struct sqda
{
    /* SQLDA structure */
    char sqldaid[8];
    long sqldabc;
    short sqln;
    short sqld;
    IISQLVAR sqlvar[IISQ_MAX_COLS];
 } IISQLDA;
/* Structure for Data handlers */
typdef struct sq_datahdlr_ {
  char *sqlarg; /*optional argument to pass*/
  int (*sqlhdlr)();/*user-defined datahandler function*/
} IISQLHDR
/* Type codes */
# define IISQ_DTE_TYPE 3 /* Date:Output */
# define IISQ_MNY_TYPE 5 /* Money:Output */
# define IISQ_DEC_TYPE 10 /* Decimal:Output*/
# define IISQ_CHA_TYPE 20 /* Char:Input,Output */
# define IISQ_VCH_TYPE 21 /* Varchar:Input,Output */
# define IISQ_LVCH_TYPE 22 /* LongVarchar:Input,Output*/
# define IISQ_BYTE_TYPE 23 /* Byte:Input,Output*/
# define IISQ_VBYTE_TYPE 24 /* Varbyte:Input,Output*/
# define IISQ_LBYTE_TYPE 25 /* Long Byte:Input,Output*/
# define IISQ_INT_TYPE 30 /* Integer:Input,Output */
# define IISQ_FLT_TYPE 31 /* Float:Input,Output */
# define IISQ_CHR_TYPE 32 /* C - not seen.*/
# define IISQ_TXT_TYPE 37 /* Text - not seen */
# define IISQ_OBJ_TYPE 45 /* 4GL Object: Output */
# define IISQ_HDLR_TYPE 46 /* IISQLHDLR: Datahandler */
# define IISQ_TBL_TYPE 52 /* Table field: Output */
# define IISQ_DTE_LEN 25 /* Date length */
/* Allocation sizes */
# define IISQDA_HEAD_SIZE 16
# define IISQDA_VAR_SIZE sizeof(IISQLVAR)
The actual definition in the included file is a C macro, which you can use to declare your own sized SQLDA. For more detail, see How to Declare an SQLDA Variable in this chapter.
Structure Definition and Usage Notes:
The 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 conflict.
The sqlvar array is a varying length array, which has a default dimension of IISQ_MAX_COLS (1024) elements. The real dimension is determined when the structure is dynamically allocated. Dynamic allocation is described later. If a variable of type IISQLDA is statically declared, then by default the program has a variable of IISQ_MAX_COLS or 1024 sqlvar elements.
The sqlvar array begins at subscript 0, not at 1.
If your program defines its own SQLDA type, you must confirm that the structure layout is identical to that of the IISQLDA type, although you can declare a different number of sqlvar elements.
The nested structure sqlname is a varying length character string consisting of a length and data area. The sqlnamec field contains the name of a result field or column after the describe (or prepare into) statement. The length of the name is specified by sqlnamel. Unlike regular C character data, the characters in the sqlnamec field are not null-terminated. You can also set the sqlname structure by a program using Dynamic FRS. (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 using an SQLDA. The type code IISQ_TBL_TYPE indicates a table field, and is set by the FRS when describing a form which contains a table field.
The allocation sizes are defined so that a program can allocate a sequential block of memory with one SQLDA head and any number of SQLDA variables. Dynamic allocation is described later.