DB2 10.5 for Linux, UNIX, and Windows

Allocating an SQLDA structure for a dynamically executed SQL program

Allocate an SQLDA structure for your application so that you can use it to pass data to and from your application.

About this task

To create an SQLDA structure with C, either embed the INCLUDE SQLDA statement in the host language or include the SQLDA include file to get the structure definition. Then, because the size of an SQLDA is not fixed, the application must declare a pointer to an SQLDA structure and allocate storage for it. The actual size of the SQLDA structure depends on the number of distinct data items being passed using the SQLDA.

In the C and C++ programming language, a macro is provided to facilitate SQLDA allocation. This macro has the following format: 
     #define SQLDASIZE(n) (offsetof(struct sqlda, sqlvar) \
             + (n) × sizeof(struct sqlvar))

The effect of this macro is to calculate the required storage for an SQLDA with n SQLVAR elements.

To create an SQLDA structure with COBOL, you can either embed an INCLUDE SQLDA statement or use the COPY statement. Use the COPY statement when you want to control the maximum number of SQLVAR entries and hence the amount of storage that the SQLDA uses. For example, to change the default number of SQLVAR entries from 1489 to 1, use the following COPY statement: 
     COPY "sqlda.cbl" 
       replacing --1489-- 
       by --1--.

The FORTRAN language does not directly support self-defining data structures or dynamic allocation. No SQLDA include file is provided for FORTRAN, because it is not possible to support the SQLDA as a data structure in FORTRAN. The precompiler will ignore the INCLUDE SQLDA statement in a FORTRAN program.

However, you can create something similar to a static SQLDA structure in a FORTRAN program, and use this structure wherever an SQLDA can be used. The file sqldact.f contains constants that help in declaring an SQLDA structure in FORTRAN.

Execute calls to SQLGADDR to assign pointer values to the SQLDA elements that require them.

The following table shows the declaration and use of an SQLDA structure with one SQLVAR element.

Language Example Source Code
C and C++ 
 #include 
 struct sqlda *outda = (struct sqlda *)malloc(SQLDASIZE(1)); 

 /* DECLARE LOCAL VARIABLES FOR HOLDING ACTUAL DATA */ 
 double sal = 0; 
 short salind = 0;

 /* INITIALIZE ONE ELEMENT OF SQLDA */ 
 memcpy( outda->sqldaid,"SQLDA   ",sizeof(outda->sqldaid)); 
 outda->sqln = outda->sqld = 1; 
 outda->sqlvar[0].sqltype = SQL_TYP_NFLOAT; 
 outda->sqlvar[0].sqllen  = sizeof( double );. 
 outda->sqlvar[0].sqldata = (unsigned char *)&sal; 
 outda->sqlvar[0].sqlind  = (short *)&salind;
COBOL 
       WORKING-STORAGE SECTION. 
       77 SALARY          PIC S99999V99 COMP-3. 
       77 SAL-IND         PIC S9(4)     COMP-5. 
  
          EXEC SQL INCLUDE SQLDA END-EXEC 
  
      * Or code a useful way to save unused SQLVAR entries. 
      * COPY "sqlda.cbl" REPLACING --1489-- BY --1--. 
  
            01 decimal-sqllen pic s9(4) comp-5. 
            01 decimal-parts redefines decimal-sqllen. 
               05 precision pic x. 
               05 scale pic x. 
  
      * Initialize one element of output SQLDA 
            MOVE 1 TO SQLN 
            MOVE 1 TO SQLD 
            MOVE SQL-TYP-NDECIMAL TO SQLTYPE(1) 
  
      * Length = 7 digits precision and 2 digits scale 

            MOVE x"07" TO PRECISION. 
            MOVE x"02" TO SCALE. 
            MOVE DECIMAL-SQLLEN TO O-SQLLEN(1). 
            SET SQLDATA(1) TO ADDRESS OF SALARY 
            SET SQLIND(1)  TO ADDRESS OF SAL-IND
FORTRAN 
      include 'sqldact.f' 
  
      integer*2  sqlvar1 
      parameter ( sqlvar1 = sqlda_header_sz + 0*sqlvar_struct_sz ) 
  
C     Declare an Output SQLDA -- 1 Variable 
      character    out_sqlda(sqlda_header_sz + 1*sqlvar_struct_sz) 
  
      character*8  out_sqldaid     ! Header 
      integer*4    out_sqldabc 
      integer*2    out_sqln 
      integer*2    out_sqld 
  
      integer*2    out_sqltype1    ! First Variable 
      integer*2    out_sqllen1 
      integer*4    out_sqldata1 
      integer*4    out_sqlind1 
      integer*2    out_sqlnamel1 
      character*30 out_sqlnamec1 
  
      equivalence( out_sqlda(sqlda_sqldaid_ofs), out_sqldaid ) 
      equivalence( out_sqlda(sqlda_sqldabc_ofs), out_sqldabc ) 
      equivalence( out_sqlda(sqlda_sqln_ofs), out_sqln       ) 
      equivalence( out_sqlda(sqlda_sqld_ofs), out_sqld       ) 
      equivalence( out_sqlda(sqlvar1+sqlvar_type_ofs), out_sqltype1 ) 
      equivalence( out_sqlda(sqlvar1+sqlvar_len_ofs), out_sqllen1   ) 
      equivalence( out_sqlda(sqlvar1+sqlvar_data_ofs), out_sqldata1 ) 
      equivalence( out_sqlda(sqlvar1+sqlvar_ind_ofs), out_sqlind1   ) 
      equivalence( out_sqlda(sqlvar1+sqlvar_name_length_ofs), 
     +             out_sqlnamel1                                   ) 
      equivalence( out_sqlda(sqlvar1+sqlvar_name_data_ofs), 
     +             out_sqlnamec1                                   ) 
  
C     Declare Local Variables for Holding Returned Data. 
      real*8       salary 
      integer*2    sal_ind 
  
C     Initialize the Output SQLDA (Header) 
      out_sqldaid  = 'OUT_SQLDA' 
      out_sqldabc  = sqlda_header_sz + 1*sqlvar_struct_sz 
      out_sqln     = 1 
      out_sqld     = 1 
C     Initialize VAR1 
      out_sqltype1 = SQL_TYP_NFLOAT 
      out_sqllen1  = 8 
      rc = sqlgaddr( %ref(salary), %ref(out_sqldata1) ) 
      rc = sqlgaddr( %ref(sal_ind), %ref(out_sqlind1) )
Note: This example was written for 32-bit FORTRAN.

In languages not supporting dynamic memory allocation, an SQLDA with the required number of SQLVAR elements must be explicitly declared in the host language. Be sure to declare enough SQLVAR elements as determined by the needs of the application.