Functions for Working with SQL Descriptor Areas

Table 2–11 lists a number of routines that are supplied in the ESQL-LIB interface that assist in defining and manipulating the SQLDA_T and SQLVAR_T structures.

Table 2–11: ESQL-LIB Routines  
Routine
Description
sqldynncols() 
Returns the number of columns in a cursor specification result set.
sqldynnparms()  
Returns the number of parameter markers in a prepared statement.
sqldsize()  
Returns the number of bytes required to allocate an SQLDA for a specified number of columns or parameter markers.
sqlald()  
Allocates an SQLDA for a specified number of columns or parameter markers (also supporting the ALLOCATE DESCRIPTOR statement).
sqldinit()  
Initializes an allocated SQLDA for a specified number of columns or parameter markers.
sqldyndesc()  
Describes an SQLDA with the attribute information for all the columns that a prepared cursor specification specifies (also supporting the DESCRIBE statement).
sqldyndescinp()  
Describes an SQLDA with the attribute information for all the parameter markers in a prepared statement (or cursor specification).
sqlalloc()  
Allocates memory for the DATA or INDICATOR member of an SQLVAR_T structure.
sqlfree() 
Deallocates memory for the DATA or INDICATOR member of an SQLVAR_T structure that sqlalloc() previously allocates.
sqldld()  
Deallocates the SQLDA that sqlald() allocates (also supporting the DEALLOCATE DESCRIPTOR statement).

NOTE: You can also use your own memory management routines other than sqlald(), sqlalloc(), sqlfree(), and sqldld() to allocate and deallocate SQLDAs.

After you prepare an SQL request, you can use the sqldynncols() and sqldynnparms() functions to return the number of result set columns specified for a cursor specification or the number of parameter markers specified for any request, respectively.

The sqldsize() ESQL-LIB function determines the amount of space that needs to be allocated to hold the SQLDA information for a given number of columns in a result set or parameter markers in a prepared statement. This function is especially useful if you are using your own memory management routines.

To allocate the SQLDA for a specified number of columns or parameter markers, you can use the sqlald() ESQL-LIB function. This example shows function sqlald() allocating space for an SQLDA that can handle 10 result columns or parameter marker values:

if ((psqlda = sqlald((int) 10)) == (struct SQLDA_T *) 0)
  {
     printf("Couldn’t alloc memory for SQLDA.\n");
     break;
  } 

The sqlald() function allocates memory for one instance of the SQLDA_T structure and a specified number of instances of the SQLVAR_T structure. (In the previous example, 10 instances of SQLVAR_T were allocated.) It also initializes the allocated SQLDA_T and SQLVAR_T structures.

Once an SQLDA has been allocated, you can use the sqldinit() ESQL-LIB function to initialize the members of the SQLVAR_T structure and their pointers in the SQLDA_T structure. This function is especially useful if you use your own memory management routines.

Both the sqlald() and sqldinit() routines set the SQLN member of the SQLDA_T structure to the number (of columns) passed to it. In the previous example, psqlda->SQLN equals 10 after sqlald() returns.

After an SQLDA has been allocated, you can use the sqldyndesc() and sqldyndescrinp() functions to fill in the attribute information for the columns specified for a prepared cursor specification or the parameter markers specified for any prepared request, respectively.

The sqlald() routine allocates memory only for the SQLDA_T and SQLVAR_T structures and not for the memory needed to hold the column or parameter marker data. After you allocate and describe the SQLDA_T structure, allocate memory for the column or parameter marker data to hold the values or set the DATA and INDICATOR members to reference the memory. You can also use the sqlalloc() routine to allocate memory for column data.

Call the deallocation routines sqldld() and sqlfree() in the reverse order from the allocation routines. If you use the sqlalloc() routine to allocate memory for the column data, call sqlfree() to deallocate this memory prior to freeing the SQLDA_T structure, and if you use the sqlald() routine to allocate the SQLDA_T structure, then you must call sqldld() to free the memory when you are done with a cursor or done executing prepared statements that contain parameter markers.

This example deallocates memory with the sqldld() routine:

sqldld(psqlda); 

Figure 2–3 shows a memory map of the SQLDA structure after you have allocated memory with sqlald() and sqlalloc().

Figure 2–3: SQLDA_T Memory Map After Allocation

If you use the sqlald() routine, Progress allocates the instances of SQLVAR_T contiguously, directly following the SQLDA_T structure. The sqldinit() routine presumes at SQLVAR_T directly follows the SQLDA_T structure. Both the sqlald() and sqldinit() routines initialize the array of SQLVAR_T pointers to point to the SQLVAR_T structures.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095