From what we have discussed I see the following groups of functions, wanted in
current API.


1. Functions, working with parameters blocks. I do not think we should limit
only with DPB, there are also very 'interesting' formats in SPB (specially
when you prepare it for service start), info blocks (here we also need a
parsing function(s) to analyze results of info calls).

All this functions return size of an item (when appicable), and -1 on error,
returning full error description is status vector. Taking into an account
that for some kinds of blocks (primary this is SPB for service start) only
size of spb is anyway not enough for consistense operation, therefore we will
anyway need to be able to track some other parameters internally, therefore -
why not track size internally too?

int fb_pb_allocate(ISC_STATUS* status, int kind, char** pb);
Creates parameters block of given kind, putting appropriate starting itmes
(like isc_dpb_version1) in it.

int fb_pb_set_option(ISC_STATUS* status, char** pb, unsigned char
option, ...);
Vararg is used here to let user enter any kind of variable according to option
value). The same trick is used is posix system call fcntl(). As a variant we
may use a set of such functions for bool, int, double and char* parameters,
i.e. fb_set_bool_option(), fb_set_int_option(), etc.

int fb_pb_free(ISC_STATUS* status, char** pb);
It should be specially noticed, that standard free() should not be used to
release parameters block, created by fb_pb_allocate().

More or less same set of functions should be used to extract information
returned by info calls.

int fb_allocate_info(ISC_STATUS* status, int kind, int size, char** ib);
Allocates buffer of desired kind and size, which can be later used in various
info calls. After it in a loop such calls are used:

int fb_ib_end(ISC_STATUS* status, char** ib);
Returns !=0 if end of info block is reached.

int fb_ib_tag(ISC_STATUS* status, char** ib);
Returns current tag of information block.

int fb_ib_get_option(ISC_STATUS* status, char** ib, void *value);
Places value of current option into address value, in native for current HW
format for int and double. (Or set of funtions like with fb_pb_set_option.)

int fb_ib_next(ISC_STATUS* status, char** ib);
Move to next oprion in info block.

TODO: As a base to make all this work engine's classes ClumpletReader and
ClumpletWriter can be used. They should be enhanced to work with info blocks
(support in classes is still missing) and a simple C-wrapper around C++ class
should be added.


2. Functions, simplifying XSQLDA-operation and all around it.

ISC_STATUS fb_sql_execute(ISC_STATUS* status, isc_db_handle* db_handle,
isc_tr_handle* trans_handle, char* sqlText, char* parameters,
fb_sql_handle* sqlHandle);

Accepts sqlText with parameters ':param', not '?' notation. Values for them
are given in unix environment format (name=value, '\0' separated, '\0\0'
ended) in parameters. Combines calls isc_dsql_allocate_statement(),
isc_dsql_describe(), isc_dsql_execute() and some other calls. Allocate
required XSQLDAs automatically, parses input parameters, and as the result
returns new type of handle (fb_sql_handle), which may be used in the
following calls (the first row if present is not prefetched):

unsigned short fb_sql_colno(fb_sql_handle* sqlHandle);

char *fb_sql_name(fb_sql_handle* sqlHandle, unsigned short colno)
short fb_sql_type(fb_sql_handle* sqlHandle, unsigned short colno)
short fb_sql_length(fb_sql_handle* sqlHandle, unsigned short colno)
....

void *fb_sql_bytes(fb_sql_handle* sqlHandle, unsigned short colno)
char *fb_sql_text(fb_sql_handle* sqlHandle, unsigned short colno)
long fb_sql_long(fb_sql_handle* sqlHandle, unsigned short colno)
....

bool fb_sql_fetch(fb_sql_handle* sqlHandle);
Returns true if next row is present.

ISC_STATUS fb_sql_release(ISC_STATUS* status, fb_sql_handle* sqlHandle);
Frees all resources used by sql statement.

TODO: write from scratch using existing API calls.