isc_create_database()

Go Up to API Function Reference

Creates a new database and sets up an active connection. For more information about creating and populating a DPB, see Creating and Populating a DPB. For more information about attaching to a database, see Connecting to Databases.

Syntax

ISC_STATUS isc_create_database (
ISC_STATUS *status_vector,
short db_name_length,
char *db_name,
isc_db_handle *db_handle,
short parm_buffer_length,
char *parm_buffer, short db_type);

Parameter	Type	Description
Recommended DPB Parameters
isc_dpb_sql_dialect	Length of value	Number indicating the SQL dialect used by the client. Dialect 3 gives access to features introduced in InterBase XE. V5.x & V6 compatible diagnostic V6 only
isc_dpb_user_name	String containing user name	String user name, up to 255 characters.
isc_dpb_password	2 bytes length + string	Password to authenticate with user accounts in administration database.
Optional DPB Parameters
isc_dpb_admin_option	INTEGER	Length in bytes of value: EUA=1; global=0, 0 is default.
isc_dpb_force_write	INTEGER	Specifies whether database writes are synchronous or asynchronous. 0 = asynchronous; 1 = synchronous.
isc_dpb_lc_ctype	String containing character set name	String specifying the character set to be utilized.
isc_dpb_no_reserve	Length in bytes	Have all database pages compactly packed (1), or leave room for record back versions (0). Length in bytes of value: Default=0
isc_dpb_ods_version_major	Length in bytes	Value: Current major ODS version in XE7.
isc_dpb_page_size	INTEGER	This is for setting the page size of a newly-created DB. The allowed values include 1024, 2048, 4096, 8192, 16384. The default setting is 4096.
isc_dpb_preallocate	INTEGER	Specifies database preallocation. It is only recognized and processed by isc_create_database(). isc_attach_database() silently ignores isc_dpb_preallocate. Use the isc_info_db_preallocate database info parameter to request database preallocate information stored on the database header page.
isc_dpb_set_group_commit	Length in bytes	Value: No=0 Yes=1
isc_dpb_set_page_buffers	Length in bytes	Value: Number of database pages. 2048 is default.
isc_dpb_sweep_interval	Length in bytes	Value: Default is 20000.
isc_dpb_transaction	Length in bytes	Choose to start database from specified transaction number; XE7 feature. 1 byte represents the length of a data type of a vale. short/integer/int64 type represents the transaction ID value.
isc_dpb_working_directory		Current working directory; useful when mentioning secondary database. Files with relative path.

Note: The first three parameters are recommended. The last set of parameters are optional.

Description

The isc_create_database() function creates a new database to enable subsequent program access.

It also optionally specifies various operational characteristics such as a user name and password combination for access to a database on a remote server, or the number of database cache buffers to use. These optional characteristics are passed in a database parameter buffer (DPB) supplied and populated by the calling program, either through direct program construction, and by calling isc_expand_dpb() to build the DPB. A program passes the name of the database file to be created in db_name. The program must also pass the length, in bytes, of db_name in the db_name_length parameter.

If successful, isc_create_database() assigns a unique ID to db_handle. Subsequent API calls use this handle to identify the database against which they operate.

When finished accessing a database, disconnect from the database with isc_detach_database().

Parameter	Type	Description
status_vector	ISC_STATUS *	Pointer to the error status vector.
db_name_length	short	Number of bytes in db_name string; if 0, the string is assumed to be null-terminated.
db_name	char *	Database name.
db_handle	isc_db_handle *	Pointer to a database handle set by this function; it is recommended that you set db_handle to NULL before passing it to isc_create_database().
parm_buffer_length	short	Number of bytes in the database parameter buffer (DPB).
parm_buffer	char *	Address of the DPB.
db_type	short	Not used.

Example

This program creates a new database using the InterBase API isc_create_database(). The newly-created database is accessed after its creation, and a sample table is added.

The SQLCODE is extracted from the status vector and is used to check whether the database already exists.

Refer to <interbase>/examples/api0.c for the sample application for creating a new database using this API.

Return value

isc_create_database() returns the status in the first element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to an InterBase error code. To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

See Also

• isc_drop_database()
• isc_detach_database()
• isc_expand_dpb()