fb_shutdown(), fb_shutdown_callback() - new API call in Firebird
2.5.
Implements smart shutdown of engine. Primarily used when
working with embedded Firebird.
Author:
Alex Peshkoff <peshkoff@mail.ru>
Syntax is:
typedef int (*FB_SHUTDOWN_CALLBACK)(const int reason, const int
mask, void* arg);
int fb_shutdown(unsigned int timeout,
const int reason);
ISC_STATUS fb_shutdown_callback(ISC_STATUS* status_vector,
FB_SHUTDOWN_CALLBACK
callback_function,
const int mask,
void* arg);
DESCRIPTION
fb_shutdown() performs smart shutdown of various Firebird
subsystems (yValve, engine, redirector).
It DOES NOT perform shutdown of remote servers, to which you are
currently attached — just terminates any Firebird activity in
the current process. fb_shutdown() was primarily designed to be used
by engine itself, but also can be used in user applications - for
example, if you want to close all opened handles at once,
fb_shutdown() may be used for it. Normally it should not be used,
because Firebird libraries (both kinds - embedded or pure client) do
call it automatically at exit(). To make fb_shutdown() be called at
exit, you should attach at least one database (or service).
Parameters and return values
fb_shutdown() accepts 2 parameters - timeout in milliseconds and
reason of shutdown. Engine uses negative reason codes (they are
listed in ibase.h, see constants starting with fb_shutrsn), if you
need to call fb_shutdown() from your program, you must use positive
value for reason. This value is passed to callback_function, passed
as an argument to fb_shutdown_callback(), and you can take
appropriate actions when writing callback function.
Zero return value of fb_shutdown() means shutdown is successfull,
non-zero means some errors took place during shutdown. You should
consult firebird.log for more information.
fb_shutdown_callback() setups callback function, which will be
called during shutdown. It has 4 parameters - status vector, pointer
to callback function, call mask and argumnet to be passed to callback
function. Call mask can have the following values:
fb_shut_preproviders - callback function will be called
before shutting down engine
fb_shut_postproviders - callback function will be called
after shutting down engine or ORed combination of them (to make same
function be called in both cases).
Callback function has 3 parameters - reason of shutdown, actual
value of mask with which it was called and argument passed by user to
fb_shutdown_callback(). There are 2 specially interesting shutdown
reasons:
Second parameter (actual value of mask) helps to distinguish if
callback was invoked before or after engine shutdown. First and
second parameters help you decide what action to be taken in your
callback. Third can be used for any purporse you like and may be
NULL.
Zero return value of callback function means it performed it's job
OK, non-zero is interpreted depending upon call mask. For
fb_shut_postproviders calls it means some errors took place, and
non-zero value will be returned from fb_shutdown(). It's callback
function responsibility to notify world about exact reasons of error
return. For fb_shut_preproviders non-zero means that shutdown will
not be performed. It's bad idea to return non-zero if shutdown is due
to exit() called.
fb_shutdown_callback() almost always returns successfully, though
in some cases (out of memory for example) it can return error.
Sample (it will make your program do not terminate on ctrl-C
pressed after attaching databases):
#include <ibase.h>
// callback function for shutdown
static int ignoreCtrlC(const int reason, const int, void*)
{
return reason == fb_shutrsn_signal ? 1 : 0;
}
int main(int argc, char *argv[])
{
ISC_STATUS_ARRAY status;
if (fb_shutdown_callback(status, ignoreCtrlC,
fb_shut_preproviders, 0))
{
isc_print_status(status);
return 1;
}
// your code continues ...
}
| 
