The new connection option isc_dpb_utf8_filename has been introduced, to enable Firebird to be specifically informed that the file name or other character item being passed is in the UTF8 (UTF-8) character set. If the option is not used, the character set defaults to the codepage of the operating system.

On Windows the code page used for conversions is Windows ANSI. On all other platforms, UTF-8 is used.

The operating system codepage and UTF-8 may not be the best choice for file names. For example, if you had a script or other text file for processing in isql or some other script-running tool that used another connection character set, it would not be possible to edit the file correctly using multiple character sets (code pages).

There is a solution: the Unicode code point. If used correctly, it enables correct interpretation of a character even if the client is older than V.2.5.

The cycle of fb_cancel_disable and fb_cancel_enable requests may be repeated as often as necessary. If the engine is already in the requested state there is no exception: it is simply a no-op.

Usually fb_cancel_raise is called when you need to stop a long-running request. It is called from a separate thread, not from the signal handler, because it is not async signal safe.

Another aspect of asynchronous execution is that, at the end of API call, the attachment's activity might be cancelled or it might not. The latter is always a possibility. The asynchronicity also means that returned status vector will almost always return FB_SUCCESS. Exceptions, though, are possible: a network packet error, for example.

Example

Thread A:
fb_cancel_operation(isc_status, &DB, fb_cancel_enable);
isc_dsql_execute_immediate(isc_status, &DB, &TR, 0, "long running statement", 3, NULL);
// waits for API call to finish...

		Thread B:
		fb_cancel_operation(local_status, &DB, fb_cancel_raise);

Thread A:
if (isc_status[1])
	isc_print_status(isc_status); // will print "operation was cancelled"
          

This release exposes two fb_shutdown* functions that may be useful for embedded server applications: fb_shutdown() and fb_shutdown_callback.

Prototypes

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

#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_confirmation, 0))
	{
		isc_print_status(status);
		return 1;
	}
	// your code continues ...
}
            

The new database shutdown modes can now be set using calls to the Services API. A number of new isc_spb_prp_* constants are available as arguments.

Usage Examples

Following are a few examples of using the new parameters with the fbsvcmgr utility. For simplicity, it is assumed that login has already been established. Each example, though broken to fit the page-width, is a single line command.

Starts a user trace session

Parameter(s)

  isc_spb_trc_name : trace session name, string, optional
  isc_spb_trc_cfg  : trace session configuration, string, mandatory
          

The mandatory parameter is a string encompassing the text for the desired configuration. A template file named fbtrace.conf is provided in Firebird's root directory as a guide to the contents of this string.

Output

Stops a designated trace session

Parameter(s)

  isc_spb_trc_id : trace session ID, integer, mandatory
          

Output

A text message providing the result (status) of the request:

Suspends a designated trace session

Parameter(s)

  isc_spb_trc_id : trace session ID, integer, mandatory
          

Output

A text message providing the result (status) of the request:

Resumes a designated trace session that has been suspended

Parameter(s)

  isc_spb_trc_id : trace session ID, integer, mandatory
          

Output

A text message providing the result (status) of the request:

Lists existing trace sessions

No parameters

Output

A text message listing the trace sessions and their states:

To back up a remote database using fbsvcmgr, enter a command with the following pattern:

fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \
  action_backup -dbname some.fdb -bkp_file stdout >some.fbk
          

To restore a database from a remotely located backup file using fbsvcmgr, enter a command with the following pattern:

fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \
  action_restore -dbname some.fdb -bkp_file stdin <some.fbk
          

If you want to perform a remote backup or restore from your own program, use the Services API.

Other ODS checks, such as Header\PIP\TIP\Generators pages, are not performed.

While a table (and\or its index) is undergoing validation, user attachments are allowed to read this table. Any attempt to change data (INSERT\UPDATE\DELETE) will wait until validation finishes or, depending on the lock timeout of the user transaction, will return a lock timeout error.

Any kind of garbage collection on the table or its indexes is disabled whilst it is undergoing validation:

When online validation starts to check a table, it acquires a couple of locks to prevent concurrent modifications of its data:

Both locks are acquired using a user-specified lock timeout. An error is reported for any lock request that fails and that table is skipped.

Online validation is implemented as a Firebird service and is accessed through the Services API. Thus, it cannot be run from the gfix utility.

The call involves the following elements:

Action:
	isc_action_svc_validate

Parameters:
	isc_spb_dbname :
		database file name, string, mandatory

	isc_spb_val_tab_incl, isc_spb_val_tab_excl,
	isc_spb_val_idx_incl, isc_spb_val_idx_excl :
		patterns for tables\indices names, string, optional

	isc_spb_val_lock_timeout :
		lock timeout, integer, optional

Output:
	text messages with progress of online validation process
           

The fbsvcmgr utility has full support for the new service. The syntax is:

fbsvcmgr [host:]service_mgr [user <...>] [password <...>]
	action_validate dbname <filename>
	[val_tab_incl <pattern>]
	[val_tab_excl <pattern>]
	[val_idx_incl <pattern>]
	[val_idx_excl <pattern>]
	[val_lock_timeout <number>]
           

where

Examples

Two tag items have been added to the services parameter block (SPB) to to enable or disable the RDB$ADMIN role for a privileged operating system user when requesting access to the security database.

The new parameter isc_spb_sec_admin, is the SPB implementation of the new DDL syntax introduced to enable SYSDBA or another sufficiently privileged user to grant or revoke the RDB$ADMIN role in the security database (security2.fdb) to or from an ordinary Firebird user. An ordinary user needs this role to acquire the same privileges as SYSDBA to create, alter or drop users in the security database.

isc_spb_sec_admin is of type spb_long with a value of either 0 (meaning REVOKE ADMIN ROLE) or a non-zero number (meaning GRANT ADMIN ROLE).

For more information, refer to the topic CREATE/ALTER/DROP USER in the chapter Data Definition Language.

This new SPB tag reflects the Services API side of the -nodbtriggers switch introduced in the gbak utility at V.2.1 to prevent database-level and transaction-level triggers from firing during backup and restore. It is intended for use as a member of the isc_spb_options set of optional directives that includes items like isc_spb_bkp_ignore_limbo, etc.

Tracker reference: CORE-3462.

If you pass the isc_spb_bkp_metadata_only tag to the restore service option in the SPB, it will perform a metadata-only restore. Many tools, including Firebird's fbsvcmgr do not provide for specifying a backup option in a restore request.

(v.2.5.1) To avoid confusion, the tag isc_spb_res_metadata_only, simply reimplementing isc_spb_bkp_metadata_only was added as a constant to the public header and fbsvcmgr.

Three additions were made to support nBackup actions in the Services API.

Tracker reference CORE-2439

The FIX_FSS_DATA and FIX_FSS_METADATA functions that were implemented as gbak -restore switches in Firebird 2.1 have been implemented in the core engine and exposed as corresponding tag constants for the isc_action_svc_restore structure in the Services API. Thus, developers now have a path for writing applications to automate the migration of older Firebird databases to the new on-disk structure.

The new SPB tags are isc_spb_res_fix_fss_data and isc_spb_res_fix_fss_metadata.