From InterBase

Go Up to Statement and Function Reference (Language Reference Guide)

Declares a database handle for database access. Available in gpre.

SET {DATABASE | SCHEMA} dbhandle = 
[USER 'name' PASSWORD 'string']
{'dbname' | :<var}>
[USER {'name' | :<var}> PASSWORD {'string' |:<var}>]];
Argument Description


An alias for a specified database

  • Must be unique within the program.
  • Used in subsequent SQL statements that support database handles.


[Default] Makes this database declaration available to all modules.


Limits scope of this database declaration to the current module.


References a database declaration in another module, rather than actually declaring a new handle.


Identifies the database used to look up column references during preprocessing.

  • If only one database is specified in SET ­DATABASE, it is used both at run time and compile time.


Location and path name of the database associated with <­dbhandle>; platform-specific.


Specifies a database to use at run time if different than the one specified for use during preprocessing.


Host-language variable containing a database specification, user name, or password.

USER ‘<name>’

A valid user name on the server where the database resides

  • Used with PASSWORD to gain database access on the server.
  • Required for PC client attachments, optional for all others.


A valid password on the server where the database resides

  • Used with USER to gain database access on the server.
  • Required for PC client attachments, optional for all others.

Description: SET DATABASE declares a database handle for a specified database and associates the handle with that database. It enables optional specification of different compile-time and run-time databases. Applications that access multiple databases simultaneously must use SET DATABASE statements to establish separate database handles for each database.

dbhandle is an application-defined name for the database handle. Usually handle names are abbreviations of the actual database name. Once declared, database handles can be used in subsequent CONNECT, COMMIT, and ROLLBACK statements. They can also be used within transactions to differentiate table names when two or more attached databases contain tables with the same names.

dbname is a platform-specific file specification for the database to associate with dbhandle. It should follow the file syntax conventions for the server where the database resides.

GLOBAL, STATIC, and EXTERN are optional parameters that determine the scope of a database declaration. The default scope, GLOBAL, means that a database handle is available to all code modules in an application. STATIC limits database handle availability to the code module where the handle is declared. EXTERN references a global database handle in another module.

The optional COMPILETIME and RUNTIME parameters enable a single database handle to refer to one database when an application is preprocessed, and to another database when an application is run by a user. If omitted, or if only a COMPILETIME database is specified, InterBase uses the same database during preprocessing and at run time.

The USER and PASSWORD parameters are required for all PC client applications, but are optional for all other remote attachments. The user name and password are verified by the server in the security database before permitting remote attachments to succeed.

Examples: The following embedded SQL statement declares a handle for a database:

SET DATABASE DB1 = 'employee.ib';

The next embedded SQL statement declares different databases at compile time and run time. It uses a host-language variable to specify the run-time database.

SET DATABASE EMDBP = 'employee.ib' RUNTIME :db_name;

See Also

Advance To: