qdb_stmt_decltypes()

Get the declared column types for a prepared statement

Synopsis:

#include <qdb/qdb.h>

int qdb_stmt_decltypes( qdb_hdl_t *db, 
                        int stmtid, 
                        char **buf, 
                        ssize_t bufsize, 
                        ssize_t *required_size );

Arguments:

db
A pointer to the database handle.
stmtid
The prepared statement ID returned by qdb_stmt_init().
buf
A pointer to a buffer for storing the column types.
bufsize
The actual buffer size, in bytes.
required_size
The required buffer size, in bytes, for storing all declared column types. The function always fills in this field, even if you provide a sufficiently large buffer.

Library:

qdb

Description:

This function gets the declared column types for the prepared statement referred to by stmtid. The behavior of this function depends on the argument settings:
  • If buf is undefined (NULL) and bufsize is 0, the number of bytes needed for the buffer is written in required_size and the total number of columns in the statement is returned.
  • If buf is defined and bufsize is less than required_size, only partial data is written in the buffer and the number of valid declared column types is returned.
  • If buf is defined and bufsize is greater than or equal to required_size, the declared column types are written in the buffer and the total number of columns is returned.

When this function returns, the beginning of buf is an array of pointers to strings, which are also stored in the buffer. These buffer strings contain the declared column types. Note that if a column is the result of an expression or subquery, an empty string is written in the corresponding buffer position.

You must allocate (and manage) the memory in buf. To optimize the use of qdb_stmt_decltypes(), you can provide a buffer that you estimate is large enough before calling this function for the first time. On return, if bufsize is greater than or equal to required_size, then all of the data has been returned and you don't need to call the function again. This strategy lets you re-use a single buffer.

If bufsize is less than required_size, you must allocate the amount of memory specified by this latter argument, then call the function again to obtain all of the data. In the second call, you must pass in the previous required_size value for bufsize, and a pointer to the new, sufficiently large buffer.

If your program needs to conserve memory and you need to know the exact buffer size required in advance, call this function once with bufsize set to 0. The function still sets the required_size parameter, informing you of the buffer memory needed so you can allocate that exact amount of memory and call the function again to obtain the data. An example of this last strategy is given below.

Returns:

>=0
Success. The returned value is either the number of columns in the statement or the number of valid declared column types, depending on the arguments.
-1
An error occurred (errno is set).

Examples:

The following code sample demonstrates how to call qdb_stmt_decltypes() once to determine the required buffer size, then a second time to retrieve and print the declared column types:

char **pp;
ssize_t required_size, bufsize = 0;
int cols, i;

if ((cols = qdb_stmt_decltypes(db, stmtid, NULL, 0, 
                               &required_size)) > 0)
{
   pp = malloc(required_size);
   if (pp) {
      bufsize = required_size;
      cols = qdb_stmt_decltypes(db, stmtid, pp, bufsize, 
                                &required_size);
      for (i=0; i<cols; i++)
         printf("column %d: %s\n", i, pp[i]);
      free(pp);
   }
}

Classification:

QNX Neutrino

Safety:  
Interrupt handler No
Signal handler No
Thread Yes