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);
         }
      }
   }
   ...