n_gettsql() - Get resultant rows from a SQL statement

SYNOPSIS

#include "tstone.h"

int n_gettsql(ts,format,...)
TSQL   *ts;
char   *format;


DESCRIPTION
n_gettsql() retrieves resultant rows from execution of a SQL statement. It takes a format string containing scanf like conversion codes. There should not be any characters in the format string except format codes and optional space separators.

By default, only SELECT statements will generate result rows. To get result rows from INSERT and DELETE statements see n_resulttsql().

The following table summarizes the format codes and their respective data types. See the formatting codes man page for full descriptions.

Format Description C Type SQL Type
%b Raw binary data byte ** BYTE
%p%n Raw binary data byte ** BYTE
%s Character string char ** CHAR
%lf Double precision floating point double * DOUBLE
%lu Unix date stored as time_t long * DATE
%f Single precision floating point float * FLOAT
%d 32/64-bit signed integer int * INTEGER
%ld 32/64-bit signed integer long * LONG
%hd 16-bit signed integer short * SMALLINT
%w 16-bit unsigned integer word * UNSIGNED SMALLINT
%s Name of external file char ** INDIRECT
%> Name of external file char ** INDIRECT
%dw 32-bit unsigned integer dword * UNSIGNED INTEGER
%64d 64-bit signed integer EPI_INT64 * INT64
%64u 64-bit unsigned integer EPI_UINT64 * UINT64
%c Unique serial number ft_counter ** COUNTER
%ls A list of allocated strings char *** STRLST
%a All remaining fields as string char ** --
%o Metamorph subhit offsets MMOFFS ** --

After the format string are the variables to place the retrieved data into. You must provide the address of each variable, as in scanf, to set. Each variable will be pointed to an allocated region that must be released with free() when you are finished with it except for the fundamental types double, long, float, short, word, dword.

It is not necessary to get all result rows if you don't want them all. any subsequent n_settsql() will flush any ungotten rows.

n_gettsql() both returns 0 on "end of results" and non-0 otherwise.


EXAMPLE

/*
  This example accesses the same table described in the n_settsql()
  man page.  Given a Metamorph query, it will retrieve all rows
  that have a match in the text field.
*/
TSQL       *ts;
char       *query;
ft_counter *ctr;
char       *text;
byte       *thumbnail;
size_t      nthumbnail;
char       *imagefile;
MMOFFS     *mmo;

   ...
                                      /* setup the select statement */
   if(n_settsql(ts,
      "select ctr,text,thumb,image from docs where text like %s;"))
   {
            /* execute the select with the supplied Metamorph query */
      if(n_exectsql(ts,query))
      {
                                          /* get all resultant rows */
         while(n_gettsql(ts,"%c %s%o %p%n %s",
                         &ctr,&text,&mmo,&thumbnail,&nthumbnail,
                         &imagefile))
         {
               break;
            ...
            /* do something with the fields (like display them) */
            ...
            free(ctr);
            free(text);
            freemmoffs(mmo);
            free(thumbnail);
            free(imagefile);
         }
      }
   }
   ...


SEE ALSO

n_settsql() and n_resulttsql()


Copyright © Thunderstone Software     Last updated: Oct 5 2023
Copyright © 2024 Thunderstone Software LLC. All rights reserved.