All data maintained by dced is managed as entries. Most of the
services of dced have lists of entries traversed with a cursor that
describe where the actual data is maintained.
dced_entry_add Adds a keytab or hostdata entry
dced_entry_remove Removes a hostdata or keytab data entry from dced
dced_initialize_cursor
Obtains a list of data entries from dced and sets
a cursor at the beginning of the list
dced_entry_get_next Obtains the next data entry from a list of entries
dced_release_cursor Releases the resources associated with a cursor
which traverses a service's list of entries
dced_list_get Returns the list of data entries maintained by
a DCE Host service
dced_list_release Releases the resources of a list of entries
dced_inq_id Obtains the UUID associated with an entry name
dced_inq_name Obtains the name associated with an entry UUID
1 – dced_entry_add
NAME
dced_entry_add - Adds a keytab or hostdata entry to a host's dced
for an existing file on that host
SYNOPSIS
#include <dce/dced.h>
void dced_entry_add( dced_binding_handle_t dced_bh,
dced_entry_t *entry,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Input/Output
entry
Specifies the data entry to add to the service.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes are:
error_status_ok
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_import_cant_access
dced_s_no_support
rpc_s_binding_has_no_auth
sec_acl_invalid_permission
uuid_s_no_address
DESCRIPTION
The dced_entry_add() routine adds a data entry to a dced service.
The data it refers to must already exist in a file on the dced's
host. You can only add hostdata or keytab entries.
A service's data entries do not contain the actual data. Instead,
they contain a UUID, a name for the entry, a brief description of
the item, and a storage tag that describes the location of the
actual data. In the cases of the hostdata and keytab services,
the data for each entry is stored in a file. The dced uses this
two-level scheme so that it can manipulate different kinds of data
in the same way and so names are independent of local file system
requirements.
The hostdata and keytab services each have their respective routines
to create new data and at the same time, add a new entry to the
appropriate service. These routines are dced_hostdata_create() and
dced_keytab_create().
Prior to calling the dced_entry_add() routine, the application must
have established a valid dced binding handle for the hostdata or
keytab service by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example shows how to add a printer configuration
file to the hostdata service. The example creates a dced binding
to the local hostdata service, an entry data structure is filled
in with the storage tag containing the full path of the existing
configuration file, and finally the dced_entry_add() routine is
called.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_entry_t entry;
dced_binding_create( dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh,
&status );
uuid_create( &(entry.id), &status );
entry.name = (dced_string_t)("NEWERprinter");
entry.description = (dced_string_t)
("Configuration for a new printer.");
entry.storage_tag = (dced_string_t)("/etc/NEWprinter");
dced_entry_add( dced_bh, &entry, &status );
.
.
.
RELATED INFORMATION
Routines: dced_entry_remove
dced_hostdata_create
dced_keytab_create
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2 – dced_entry_remove
NAME
dced_entry_remove - Removes a hostdata or keytab data entry from
a dced service's list of entries
SYNOPSIS
#include <dce/dced.h>
void dced_entry_remove( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
entry_uuid
Specifies the UUID of the entry to be removed from the service.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes are:
error_status_ok
db_s_del_failed
db_s_key_not_found
db_s_readonly
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_entry_remove() routine removes an entry from the hostdata
or keytab service entry list of dced. It does not remove the actual
data stored in the file, but makes it inaccessible from a remote
host by way of the dced's user interfaces which include the dced
API and the DCE control program, dcecp. Each host service that
maintains data also maintains a list of data entries. A data entry
contains a name, a UUID, a brief description, and a storage tag
indicating the location of the actual data.
To delete both the data and entry for the hostdata, keytab, or
srvrconf services use dced_hostdata_delete(), dced_keytab_delete(),
or dced_server_delete(), respectively. (The srvrexec service is
maintained only be dced and the secval service does not maintain
data, so you cannot remove data for these services.)
Applications commonly obtain an entry by traversing the entry list
using the dced_entry_get_next() routine with its associated cursor
routines.
Prior to calling the dced_entry_remove() routine, the application
must have established a valid dced binding handle to the hostdata
or keytab service by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_hostdata_delete
dced_keytab_delete
dced_server_delete
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3 – dced_initialize_cursor
NAME
dced_initialize_cursor - Sets a cursor to the start of a cached
list of data entries for a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_initialize_cursor( dced_binding_handle_t dced_bh,
dced_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Output
cursor
Returns the cursor used to traverse the list of data entries,
one at a time. The cursor is an opaque data structure that is
used to keep track of the entries between invocations of the
dced_entry_get_next() routine.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
DESCRIPTION
The dced_initialize_cursor() routine sets a cursor at the start of
a DCE host service's list of data entries. The cursor is then used
in subsequent calls to dced_entry_get_next() to obtain individual
data entries. When the application is finished traversing the
entry list, it should call dced_release_cursor() to free the
resources allocated for the cursor.
The valid services for this routine that have entry lists include
hostdata, srvrconf, srvrexec, and keytab.
If a service's entry list is small, it may be more efficient to
obtain the entire list using the dced_list_get() routine rather
than using cursor routines. This is because dced_list_get()
guarantees the list is obtained with one remote procedure call.
However, your application is scalable if you use the cursor
routines because if an entry list is very large, it may be more
efficient (or even necessary) to obtain the list in chunks with
more than one remote procedure call.
Prior to calling the dced_initialize_cursor() routine, the
application must have established a valid dced binding handle
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_entry_get_next
dced_release_cursor
dced_list_get
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4 – dced_entry_get_next
NAME
dced_entry_get_next - Obtains one data entry from a list of entries
of a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_entry_get_next( dced_cursor_t cursor,
dced_entry_t **entry,
error_status_t *status );
PARAMETERS
Input/Output
cursor
Specifies the entry list's cursor that points to an entry, and
returns the cursor advanced to the next entry in the list.
Output
entry
Returns a pointer to an entry.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes are:
error_status_ok
dced_s_no_more_entries
DESCRIPTION
The dced_entry_get_next() routine obtains a pointer to a data entry,
and advances the cursor to the next entry in the list. This routine
is commonly used in a loop to traverse a host service's entry list.
The data is obtained in an undetermined order. Prior to using this
routine, the application must call dced_initialize_cursor() to
obtain a list of entries and to establish the beginning of the
cursor. When the application is finished traversing the entry
list, it should call dced_release_cursor() to release resources.
A data entry does not contain the actual data, but it contains the
name, identity, description, and storage location of the data. In
the cases of hostdata and keytab services, the data for each entry
is stored in a file. In the cases of srvrconf and srvrexec
services, data is stored in memory. The dced uses this two-level
scheme so that it can manipulate different kinds of data in the same
way.
Prior to using the dced_entry_get_next() routine, the application
must have established a valid dced binding handle by calling either
the dced_binding_create() or dced_binding_from_rpc_binding()
routine.
EXAMPLES
In the following example, a dced binding is obtained from a service
type and an existing rpc binding handle. After establishing an
entry list cursor, the dced_entry_get_next() routine obtains an
entry, one at a time, and the name and description of each entry is
displayed until the entry list is exhausted.
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
dced_initialize_cursor( dced_bh, &cursor, &status );
for( ; ; ) { /* forever loop */
dced_entry_get_next( cursor, &entry, &status );
if (status != error_status_ok) break;
display(entry->name, entry->description); /* app. specific */
}
dced_release_cursor( &cursor, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_initialize_cursor
dced_release_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
5 – dced_release_cursor
NAME
dced_release_cursor - Releases the resources of a cursor which
traverses a dced service's list of entries
SYNOPSIS
#include <dce/dced.h>
void dced_release_cursor( dced_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input/Output
cursor
Specifies the cursor for which resources are released.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The only possible status code is:
error_status_ok
DESCRIPTION
The dced_release_cursor() routine releases the resources of a
cursor initially set by the dced_initilalize_cursor() routine
and used by the dced_entry_get_next() routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine,
and then the application must have called the
dced_initialize_cursor() routine.
RELATED INFORMATION
Routines: dced_initialize_cursor
dced_entry_get_next
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
6 – dced_list_get
NAME
dced_list_get - Returns the list of data entries maintained by a
dced service on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_list_get( dced_binding_handle_t dced_bh,
dced_entry_list_t *list,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Output
list
Returns a list of data entries for the service.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
DESCRIPTION
The dced_list_get() routine obtains all the data entries for a dced
service on a specific host. The list of data entries obtained is not
the actual data. Each entry contains a UUID, name, description, and
storage tag that describes where the data is located (for example, a
file name or memory location). Call the dced_list_release() routine
when your application is finished with the entry list to release
resources allocated with dced_list_get() routine.
If a service's entry list is small, it may be efficient to obtain
the entire list using the dced_list_get() routine because it
guarantees the list is obtained with one remote procedure call.
However, to make your application scalable, use the
dced_initialize_cursor(), dced_entry_get_next(), and
dced_release_cursor() set of routines because if an entry list is
very large, it may be more efficient (or even necessary) to obtain
the list in chunks with more than one remote procedure call.
Prior to calling this routine, the application must have
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
EXAMPLES
In the following example, a dced binding is obtained from a
service type and an existing rpc binding handle. The list of
entries for the service is obtained with the dced_list_get()
routine and each entry's name and description are displayed.
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
dced_list_get( dced_bh, &entries, &status );
for(i=0; i<entries.count; i++)
display(&entries); /* application specific */
dced_list_release( dced_bh, &entries, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_list_release
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
7 – dced_list_release
NAME
dced_list_release - Releases the resources for a list of entries
of a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_list_release( dced_binding_handle_t dced_bh,
dced_entry_list_t *list,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
InputOutput
list
Specifies a list of data entries for the service.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The only possible status code is:
error_status_ok
DESCRIPTION
The dced_list_release() routine releases the resources allocated for
a list of data entries previously retrieved by the dced_list_get()
routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine,
and then the application must have called the dced_list_get()
routine.
RELATED INFORMATION
Routines: dced_list_get
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8 – dced_inq_id
NAME
dced_inq_id - Obtains the entry UUID that dced associates with
a name
SYNOPSIS
#include <dce/dced.h>
void dced_inq_id( dced_binding_handle_t dced_bh,
dced_string_t name,
uuid_t *uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
name
Specifies the name for which to obtain the uuid.
Output
uuid
returns the UUID associated with the name input.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_inq_id() routine obtains the UUID associated with a name
in a service of a specific host's dced. Applications and
administrators use strings maintained by dced to identify data,
but dced and its API must associate each data entry with a UUID.
This routine is valid for the host-data, srvrconf, srvrexec, and
keytab services.
Prior to calling this routine, the application must have
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example establishes a dced binding to a host's
server configuration service. The example then obtains the
UUID of some known server in order to read the server's
configuration data.
dced_binding_handle_t dced_bh;
server_t conf;
dced_string_t server_name;
uuid_t srvrconf_id;
error_status_t status;
dced_binding_create( "srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_inq_id( dced_bh, server_name, &srvrconf_id, &status );
dced_object_read( dced_bh,
&srvrconf_id,
(void**)&(conf),
&status );
.
.
.
RELATED INFORMATION
Routines: dced_inq_name
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
9 – dced_inq_name
NAME
dced_inq_name - Obtains the entry name that dced associates with
a UUID
SYNOPSIS
#include <dce/dced.h>
void dced_inq_name( dced_binding_handle_t dced_bh,
uuid_t *uuid,
dced_string_t *name,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
uuid
Specifies the UUID for which to obtain the name.
Output
name
Returns the name associated with the uuid input.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes are:
error_status_ok
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
dced_s_not_found
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_inq_name() routine obtains the name associated with a
UUID in a service of a specific host's dced.
A name is a label for each data entry to help applications and
administrators identify all data maintained by dced. The dced
requires UUIDs to keep track of the data it maintains. But it
also maintains a mapping of UUIDs to names so that other
applications and administrators can more easily access the data
by using a recognizable name rather than a cumbersome UUID. A
name is a label for hostdata items, srvrconf and srvrexec servers,
and keytab tables.
Prior to calling this routine, the application must have
established a valid dced binding handle by calling either the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example establishes a dced binding handle to the
local host data service, reads an entry, and uses dced_inq_name()
to get the name associated with the attribute ID.
dced_binding_handle_t dced_bh;
uuid_t entry_uuid;
sec_attr_t *data_ptr;
error_status_t status;
.
.
.
dced_binding_create( dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_hostdata_read( dced_bh,
&entry_uuid,
&dced_g_uuid_fileattr,
&data_ptr,
&status );
dced_inq_name( dced_bh,
data_ptr->sec_attr.attr_id,
&name, &status );
.
.
.
RELATED INFORMATION
Routines: dced_inq_id
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.