isc_attach_database()

From InterBase

Go Up to API Function Reference


Attaches to an existing database.

Syntax

 ISC_STATUS isc_attach_database(
 ISC_STATUS *status_vector,
 short db_name_length,
 char *db_name,
 isc_db_handle *db_handle,
 short parm_buffer_length,
 char *parm_buffer);
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_attach_database().

parm_buffer_length

short

Number of bytes in the database parameter buffer (DPB)

parm_buffer

char *

Address of the DPB

Description: The isc_attach_database() function connects to an existing 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 which to attach in db_name. For programs not written in C, the program must also pass the length, in bytes, of db_name in the db_name_length parameter. C programs should pass a 0 length in this parameter.

If successful, isc_attach_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().

Example: The following program fragment attaches to a database named employee.db. In the parameter buffer, it specifies a user name and password. These come from the contents of char * variables named user_name and user_password, respectively.

char dpb_buffer[256], *dpb, *p;
ISC_STATUS status_vector[20];
isc_db_handle handle = NULL;
short dpb_length;
/* Construct the database parameter buffer. */
dpb = dpb_buffer;
*dpb++ = isc_dpb_version1;
*dpb++ = isc_dpb_user_name;
*dpb++ = strlen(user_name);
for (p = user_name; *p;)
*dpb++ = *p++;
*dpb++ = isc_dpb_password;
*dpb++ = strlen(user_password);
for (p = user_password; *p;)
*dpb++ = *p++;
/* An alternate choice for the above construction is to call isc_expand_dpb(). */
dpb_length = dpb - dpb_buffer;
isc_attach_database( status_vector, 0, "employee.db",
 &handle, dpb_length, dpb_buffer);
if (status_vector[0] == 1 && status_vector[1]){
/* An error occurred. */
isc_print_status (status_vector);
return(1);
}

Return value

isc_attach_database() returns the second 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

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.


Advance To: