NAME

dce_db_open - Opens an existing backing store or creates a new one

SYNOPSIS

#include <dce/dce.h>
#include <dce/dbif.h>

void dce_db_open(
    const char *name,
    const char *backend_type,
    unsigned32 flags,
    dce_db_convert_func_t convert,
    dce_db_handle_t *handle,
    error_status_t *status);

PARAMETERS

Input

name

The filename of the backing store to be opened or created.

backend_type

Either of the strings, bsd4.4-hash or bsd4.4-btree, or a null pointer, which defaults to hash. This parameter specifies the backing store backend type for licensees adding multiple backends.

flags

The manner of opening, as specified by any of the following bits:

db_c_index_by_name: The backing store is to be indexed by name. Either this or db_c_index_by_uuid, but not both, must be selected.
db_c_index_by_uuid: The backing store is to be indexed by UUID. Either this or db_c_index_by_name, but not both, must be selected.
db_c_std_header: The first field of each item (which is defined as a union in dce_db_header_t) is the standard backing store header, with the case dce_db_header_std selected. The selection for header cannot have both db_c_std_header and db_c_acl_uuid_header. If neither header flag is specified, no header is used.
db_c_acl_uuid_header: The first field of each item (the union) is an ACL UUID, with the case dce_db_header_acl_uuid selected. The selection for header cannot have both db_c_std_header and db_c_acl_uuid_header. If neither header flag is specified, no header is used.
db_c_readonly: An existing backing store is to be opened in read-only mode. Read/write is the default.
db_c_create: Creates an empty backing store if one of the given name does not already exist. It is an error to try to create an existing backing store.

convert

The function, generated by the IDL compiler, that is called to perform serialization.

Output

handle: A pointer to a handle that identifies the backing store being used.
status: A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.

DESCRIPTION

The dce_db_open() routine opens the specified backing store. The flags parameter must specify whether the backing store is to be indexed by name or by UUID. If all of a server's objects have entries in the CDS namespace, then it is probably best to use a UUID index. If the server provides a junction or another name-based lookup operation, then it is probably best to use a name index.

The IDL code in /usr/include/dce/database.idl defines the backing store header (selected by the flags parameter) that is placed on each item, the possible header types, and the form of the function for serializing headers.

NOTES

Backing stores are also called databases. For instance, the associated IDL header is dce/database.idl, and the name of the backing store routines begin with dce_db_. Nevertheless, backing stores are not databases in the conventional sense, and have no support for SQL or for any other query system.

EXAMPLES

Standardized use of the backing store library is encouraged. The following is the skeleton IDL interface for a server's backing store:

interface XXX_db
{
    import "dce/database.idl";

    typedef XXX_data_s_t {
        dce_db_header_t header;
        /* server-specific data */
    } XXX_data_t;

    void XXX_data_convert(
        [in] handle_t h,
        [in, out] XXX_data_t *data,
        [out] error_status_t *st
    );
}

This interface should be compiled with the following ACF:

interface XXX_db
{
    [encode, decode] XXX_data_convert();
}

A typical call to dce_db_open(), using the preceding IDL example, follows: would be:

dce_db_open("XXX_db", NULL,
    db_c_std_header | db_c_index_by_uuid,
    (dce_db_convert_func_t)XXX_data_convert,
    &handle, &st);

ERRORS

db_s_bad_index_type: The index type in flags is specified neither by name nor by UUID; or else it is specified as both.
db_s_bad_header_type: The header type in flags is specified as both standard header and ACL header.
db_s_index_type_mismatch: An existing backing store was opened with the wrong index type.
db_s_open_already_exists: The backing store file specified for creation already exists.
db_s_no_name_specified: No filename is specified.
db_s_open_failed_eacces: The server does not have permission to open the backing store file.
db_s_open_failed_enoent: The specified directory or backing store file was not found.
db_s_open_failed: The underlying database-open procedure failed. The global variable errno may provide more specific information.
error_status_ok: The call was successful.

RELATED INFORMATION

Functions: dce_db_close(3dce).