db_open()

Purpose

Opens a database

Old name

#define dbopen db_open

Syntax (CCOWN)

int db_open(const char *name, int generation, int flags,ADDITIONAL)

Syntax (DP4DBAPI)

DCONN * dp4_db_open(CONN * conn, const char *name,int generation,int flags, int reserved,dp4_swapper swapper,struct DP4_SWAP swap_table[])

Parameters

CONN * conn

Connection handle, as returned by an earlier call to dp4_srv_connect()

char* name

Null-terminated string specifying name of database to be opened

int generation

Generation in which the database is opened

int flags

Specifies the mode in which the database is opened

The value of the flags parameter determines the mode in which the database is opened. This is a combination of the following:

Value

Meaning

SHARED

Open the database in shared mode

READ_ONLY

Open in database in read only mode. Posting records to the database causes the program to be terminated

EXCLUSIVE

Open the database in exclusive mode. No other users are able to access the database. If the database is already in exclusive mode the program terminates

QUIT_ON_FAILURE

If a commit fails, a DP4 system error will be generated. Usually the program will terminate.

NO_LOGGING

Open the database with no logging (only effective with EXCLUSIVE)

NO_ROLLBACK

Open the database without rollback (only effective with EXCLUSIVE)

RETRIEVE_ENABLE

Allows the subsequent use of the map_retrieve function

FORCE_ENTRY

Opens the database even if it has been opened exclusively by another program. This value is reserved for internal use, and should not be used in applications.

PRIVATE_DB

Open the database using the private database facility. All updates (from calls to rec_post() or rec_kill() are effective immediately as far as the owning process is concerned. No other process can see the updates until the next call to db_update() or a similar function.

The database fetch functions with flags such as NEXT or PREV see the updated records even though the changes have not been committed.

A call to db_update(), db_commit() or db_checkpoint() is still required to make permanent updates to the database

BIG_TRANSACTIONS

Supplies a hint to the database manager that the program expects to perform very large transactions (in execess of several hundred updates without a commit). The database manager will allocate a larger than usual buffers for storing pending transactions for this program, to avoid performance degradation.

This flag should not be used unless absolutely necessary. If at all possible you should redesign your application to avoid the need for excessively large transactions.

MISSING_OK

db_open() normally generates DP4 system error 15 or 16 if one of the database files is mising. If thsi flag is specified and the database does not exist, db_open() returns -1

int reserved

Pass 0

This parameter is reserved for internal use.

dp4_swapper swapper

On big endian platforms this parameter must point to a function used for swapping data records between the native format and the DP4 internal format. On PC and other little endian platforms this pointer should be 0.

struct DP4_SWAP swap_table[]

On big endian platforms this parameter must point to the swap structure to be used for swapping the tables on this database. This is generated using the #swap directive in LIBMAKE. On PC and other little endian platforms this parameter should be 0.

Description

The db_open() function opens the database specified by the parameter name. All subsequent database processing is then for this database.

To override the database name in the program, use the command tail:
-DB <DBNAME>

LIBMAKE automatically generates a call to db_open() with the latest value for the generation parameter. The program DBCHECK also displays this value.

Certain LIBMAKE directives have the same effect as particular values of the flags parameter, as shown below:

For db_open() the command tail -db dbname can be used to override the database name passed to db_open(). (This normally only works for the first call to db_open())

You may have more than one database open at a time. To do this, save the value of the global variable db_nr after a call to db_open(), then reset the global variable db_nr back to the saved value after opening another database.

The SYSTEM database is initially open for users; the global variable db_nr has the value 0.

Return values

db_open() returns the value of the global variable db_nr if successful, otherwise -1 if the program does not terminate.

If dp4_db_open() succeeds it returns a handle of type DCONN * to be passed to other dp4_xxx() functions. Otherwise it returns 0. Error information can be found by calling dp4_error_status().

See also

db_close(), db_nr

Example