dce_db_open(3dce)

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

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

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)