SQLDA Data Structure

The SQLDA data structure definition (from SQLDA.H) looks like this:


// SQL Descriptor Area - SQLDA


struct sqlda


{





unsigned char sqldaid[8];


// Eye catcher = 'SQLDA  '



long sqldabc;


// SQLDA size in bytes = 16+44*SQLN



short sqln;


// Number of SQLVAR elements



short sqld;


// Num of used SQLVAR elements



struct sqlvar




{




   short sqltype;


// Variable datatype



   short sqllen;


// Variable data length



   unsigned char FAR




      *sqldata;


// Pointer to variable data value



   short FAR *sqlind;


// Pointer to null indicator



   struct sqlname


// Variable name



   {




      short length;


// Name length [1..30]



      unsigned char




         data[30];


// Variable or column name



   } sqlname;




} sqlvar[1];



};




SQLDA

Fields and datatypes for the SQLDA data structure are described in the following table.

Field and datatype

Contains

sqldaid

unsigned char*

The text string SQLDA. This field is not used for FETCH, OPEN, or EXECUTE statements.

sqldabc

long

The length of the SQLDA data structure (sqln* 44 + 16).

sqln

short

The total number of sqlvar entries that are allocated; equal to the number of input parameters or output columns.

sqld

short

The number of sqlvar entries that are used.

sqlvar

struct

The values that are listed in the sqlvar table; the values can occur several times, listed once per column in the results set or input parameter.

sqltype

short

The number that represents the datatype of columns or host variables, and that indicates whether null values are allowed. For valid values, see "Valid Values for sqltype," later in this chapter.

sqllen

short

The external length of a value from a column.

sqldata

unsigned char far*

The address of the host variable (which must be inserted by the application) for FETCH, OPEN, and EXECUTE statements. For DESCRIBE and PREPARE statements, sqldata is not used.

sqlind

short far*

The address of an indicator variable for FETCH, OPEN, and EXECUTE statements, if one exists.

If the column does not permit a null value, the field is undefined. If the column permits a null value, sqlind is set to –1 if the data value is null or to 0 if the data value is not null. For DESCRIBE and PREPARE statements, sqlind is not used.

sqlname

struct

The name and length of the column. (Is not used for FETCH, OPEN, and EXECUTE statements.)

length

short

The length of the name column.

name

unsigned char*

The name of the column. For a derived column, this field contains the ASCII numeric literal value that represents the derived column's original position within the select list.


Valid Values for sqltype

The following table lists the values for the sqltype field in SQLDA data structure and corresponding SQL Server datatypes for which they can serve as host variables in a FETCH statement or and EXECUTE statement. For each pair of sqltype codes, the odd number type signifies a host variable with a corresponding null indicator variable needed for setting or retrieving null values.


Sqltype code


Datatype description

Corresponding SQL Server datatype



Sample declaration

392/393

26-byte date & time char format corresponds to the formats supported by dbconvert for datetime to/from char (See "Programming DB-Library for C")

datetime, smalldatetime

char date1[27] =
"Mar 7 1988 7:12PM";

444/445

Binary

binary, varbinary, image, timestamp

Note: sqltype 444/445 is automatically used for these SQL Server column types on output.

char binary1[4097];

452/453

Char string <=254 bytes; not automatically null terminated

Note: Make sure you initialize the full array with nulls when using this type for output.

char, varchar, or text

char mychar[255];

456/457

Length-prefixed long character field; not automatically null terminated

char, varchar, or text

struct TEXTVAR

{

short len;

char data[4097];

} textvar;

462/463

Null-terminated string

Note: Declarations of known length (mychar1) will be padded with blanks and a terminating null. Declarations of char pointers (mychar2) will not be blank padded and the application program must ensure sufficient space is allocated.

char, varchar, or text.

char mychar1[41];

char * mychar2;

480/481

8-byte floating point

float, real, int, smallint, tinyint,
decimal, numeric, money, smallmoney

double mydouble1;

482/483

4-byte floating point

float, real, int, smallint, tinyint,
decimal, numeric, money, smallmoney

float myfloat1;

496/497

4-byte integer

int, smallint, tinyint, bit

long myint1;

500/501

2-byte integer

smallint, tinyint, bit

short myshort1;


When using SQLDAs in a DESCRIBE or PREPARE INTO, the following datatype codes are returned.




SQL Server column

sqltype returned by DESCRIBE or PREPARE INTO





Comments

char, varchar

452/453

452/453 is a Cobol char datatype, not null terminated. Easier to use 462/463 from C.

text

456/457

sqllen set to max of 32767 for text

binary, varbinary, image, timestamp

444/445

sqllen set to max of 32767 for image

smallint, tinyint, bit

500/501

int

496/497

float

480/481

real

482/483

datetime, smalldatetime

392/393

decimal, numeric, money, smallmoney

484/485

Cobol decimal format; not supported for FETCH or EXECUTE in ESQL/C (use 480 or 482 instead). sqllen encoded with scale and precision; use sqllen &= 0xFF to get just precision.


DESCRIBE and PREPARE INTO are only supported for output columns of SELECT statements. They are not supported for INSERT, UPDATE, or DELETE statements, or for any statement requiring an input host variable.