isc_create_database()

From InterBase
Jump to: navigation, search

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 since InterBase XE.

  1. V5.x & V6 compatible
  2. diagnostic
  3. 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 InterBase.

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.

  • 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

Advance To: