FirebirdSQL logo
  • Anglaiskeyboard_arrow_down
 Firebird EventsExamples 

Using the Services API

The ODBC/JDBC driver wraps a great many of the Services API functions.The management console built into the Windows DSN interface provides examples of most of them.One thing you cannot do via the console is create databases.Fear not! the driver has it wrapped!

In the Connection chapter is a table of the keywords available to signify the values for attachments via Firebird’s “regular” API.The table below provides the keywords for the KEYWORD=value parameters for connecting to the server and launching a service request.These are additional to the relevant connection parameters.For some cases, the default settings from the DSN, if used, will be correct for Service requests.

Table 1. Keywords for Service Request Attributes
Keyword Description More Information

BACKUPFILE

Backup file

This is a filesystem path and file name.Unlike a database, a backup path can be a network storage address.

LOGFILE

Path and name of the log file for the service

Optional;valid for any service that provides a log file option.The same filesystem rules apply as for backup files.

CREATE_DB

Create database

See the examples below for usage

BACKUP_DB

Backup database

The path and name of the database backup file, for backups and restores.

RESTORE_DB

The network path and name of the database to which a backup is to be restored.This cannot be a network storage address.The file name part can be an alias, provided the alias exists.

 

REPAIR_DB

Repair database

Local path to the database to be repaired or validated.Remote access is invalid.

COMPACT_DB

Compact database

Not currently applicable to Firebird databases.

DROP_DB

Drop database

Not currently applicable to Firebird databases.

Examples of Services Use

The following samples show how to configure the various service requests.

Creating a Database
SQLConfigDataSource( NULL,
                     ODBC_ADD_DSN,
                     "Firebird/InterBase(r) driver",
                     "ODBC\0"
                     "CREATE_DB = D:\\TestService\\test.fdb\0"
                     "DESCRIPTION = My Firebird database\0"
                     "UID         = SYSDBA\0"
                     "PWD         = masterkey\0"
                     "CHARSET     = NONE\0"
                     "PAGESIZE    = 8192\0"
                     "DIALECT     = 3\0" );

More alternative examples for creating databases are at the end of this chapter.

Backing Up a Database
SQLConfigDataSource( NULL,
                     ODBC_ADD_DSN,
                     "Firebird/InterBase(r) driver",
                     "ODBC\0"
                     "BACKUP_DB = D:\\TestService\\test.fdb\0"
                     "BACKUPFILE = D:\\TestService\\test.fbk\0"
                     "UID         = SYSDBA\0"
                     "PWD         = masterkey\0" );
Restoring a Database
SQLConfigDataSource( NULL,
                     ODBC_ADD_DSN,
                     "Firebird/InterBase(r) driver",
                     "ODBC\0"
                     "RESTORE_DB = D:\\TestService\\testNew.fdb\0"
                     "BACKUPFILE = D:\\TestService\\test.fbk\0"
                     "LOGFILE = D:\\TestService\\test.log\0"
                     "UID         = SYSDBA\0"
                     "PWD         = masterkey\0" );
Repairing a Database
SQLConfigDataSource( NULL,
                     ODBC_ADD_DSN,
                     "Firebird/InterBase(r) driver",
                     "ODBC\0"
                     "REPAIR_DB = D:\\TestService\\test.fdb\0"
                     "UID         = SYSDBA\0"
                     "PWD         = masterkey\0" );

docnext count = 1

More Ways to Create a Database

Create a database using the ODBC API function SQLConfigDataSource.A convenient method for creating a database that is going to be managed by someone else.

SQLConfigDataSource( NULL,
                     ODBC_ADD_DSN,
                     "Firebird/InterBase(r) driver",
                     "ODBC\0"
                     "CREATE_DB = D:\\TestService\\test.fdb\0"
                     "DESCRIPTION = My Firebird database\0"
                     "UID         = SYSDBA\0"
                     "PWD         = masterkey\0"
                     "CHARSET     = NONE\0"
                     "PAGESIZE    = 8192\0"
                     "DIALECT     = 3\0" );

Create a database using the ODBC API function SQLDriverConnect.Convenient when the job is going to be performed from a user application.The driver will handle errors and continue attempting to create the database until it eventually succeeds in connecting to it.Access is passed to the client upon success.

UCHAR buffer[1024];
SWORD bufferLength;
SQLDriverConnect( connection, hWnd,
                  (UCHAR*)"DRIVER=Firebird/InterBase(r) driver;"
                  "UID=SYSDBA;"
                  "PWD=masterkey;"
                  "PAGESIZE=8192;"
                  "DBNAMEALWAYS=C:\\Temp\\NewDB.fdb", SQL_NTS,
                  buffer, sizeof (buffer), &bufferLength,
                  SQL_DRIVER_NOPROMPT );

Create a database using the ODBC API function SQLExecDirect.This scenario is interesting in that the database is created within the context of an existing client connection.It is not necessary therefore to include "DRIVER=Firebird/InterBase (r) driver;" in the call, since it will be taken from the current connection.

As with the first method that used SQLConfigDataSource, the current user does not get management rights on the database created.For that requirement, SQLDriverConnect should be used instead.

SQLExecDirect( hStmt,
               "CREATE DATABASE \'C:/TEMP/NEWDB00.FDB\'"
               "   PAGE_SIZE 8192"
               "   SET NAMES \'NONE\'"
               "   USER \'SYSDBA\'"
               "   PASSWORD \'masterkey\';",
               SQL_NTS );