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,
   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