NAME
DCE_INTRO - Introduction to the DCE routines
DESCRIPTION
The DCE routines provide several facilities that are applicable across
more than one DCE component. They can be divided into the following
major areas:
DCE attribute interface routines
These routines allow applications to define and access
attribute types (schema entries) in a schema of your
choice. They are based on the Extended Registry Attribute
(ERA) interface, which defines and accesses attribute
types in the register database schema.
For more information about the individual attribute
interface routines, see the dce_attr_intro reference
page.
DCE configuration routines
These routines return information based on the contents
of the local DCE configuration file, which is created
during the DCE cell-configuration or machine-configuration
process.
For more information about the individual configuration
routines, see the dce_cf_intro reference page.
DCE backing store routines
These routines allow you to maintain typed data between
program invocations. The backing store routines can be
used in servers, in clients or in standalone programs
that do not involve remote procedure calls (RPC).
For more information about the individual backing store
routines, see the dce_db_intro reference page.
DCE messaging interface routines
These routines give you access to message catalogs, to
specific message texts and message IDs, and to in-memory
message tables.
For more information about the individual messaging
interface routines, see the dce_msg_intro reference
page.
DCE server routines
These routines are used by servers to register themselves
with DCE. This includes RPC runtime, the local endpoint
mapper, and the namespace. Routines are also available
to set up DCE security so that servers can receive and
invoke authenticated RPCs.
For more information about the individual server routines,
see the dce_server_intro reference page.
DCE serviceability routines
These routines are intended for use by servers that
export the serviceability interface defined in service.idl.
There are also a set of DCE serviceability macros can be
used for diagnostic purposes, and to create a
serviceability handle.
For more information about the individual serviceability
routines, see the dce_svc_intro reference page.
For more information about the individual DCE serviceability
macros, see the DCE_SVC_INTRO_2 reference page.
DCE Host daemon application programming interface
These routines give management applications remote
access to various data, servers, and services on DCE hosts.
For more information about the individual host daemon
application programming interface routines, see the
dced_intro reference page.
1 – dce_attr_intro
NAME
dce_attr_intro - Introduction to the DCE Attribute Interface routines
DESCRIPTION
The DCE Attribute Interface API allows applications to define and
access attributes types (schema entries) in a schema of your choice.
It is based on the Extended Registry Attribute (ERA) interface, which
defines and accesses attribute types in the registry database schema.
Except for the binding methods, the two APIs are similar.
Note however, that the Extended Registry Attribute API provides
routines to create attribute types in the registry schema, to create
and manipulate attribute instances, and to attach those instances to
objects. The DCE Attribute Interface in its current state provides
calls only to create attribute types.
For general usage guidelines for the DCE Attribute Interface refer to
the chapter in this manual titled "The Extended Attribute Application
Program Interface." The DCE Attribute Interface routine reference
pages are supplied in this section.
The DCE Attribute Interface Routines
The DCE Attribute Interface consists of the following routines:
dce_attr_sch_bind
Returns an opaque handle of type dce_attr_sch_handle_t to a
schema object specified by name and sets authentication and
authorization parameters for the handle.
dce_attr_sch_bind_free
Releases an opaque handle of type dce_attr_sch_handle_t.
dce_attr_sch_create_entry
Creates a schema entry in a schema bound to with
dce_attr_sch_bind.
dce_attr_sch_update_entry
Updates a schema entry in a schema bound to with
dce_attr_sch_bind.
dce_attr_sch_delete_entry
Deletes a schema entry in a schema bound to with
dce_attr_sch_bind.
dce_attr_sch_scan
Reads a specified number of schema entries.
dce_attr_sch_cursor_init
Allocates resources to and initializes a cursor used with
dce_attr_sch_scan. The dce_attr_sch_cursor_init routine makes
a remote call that also returns the current number of schema
entries in the schema.
dce_attr_sch_cursor_alloc
Allocates resources to a cursor used with dce_attr_sch_scan.
The dce_attr_sch_cursor_alloc routine is a local operation.
dce_attr_sch_cursor_release
Releases states associated with a cursor created by
dce_attr_sch_cursor_alloc or dce_attr_sch_cursor_init.
dce_attr_sch_cursor_reset
Reinitializes a cursor used with dce_attr_sch_scan. The reset
cursor can then be reused without releasing and re-allocating.
dce_attr_sch_lookup_by_id
Reads a schema entry identified by attribute type UUID.
dce_attr_sch_lookup_by_name
Reads a schema entry identified by attribute name.
dce_attr_sch_get_acl_mgrs
Retrieves the manager types of the ACLs protecting objects
dominated by a named schema.
dce_attr_sch_aclmgr_strings
Returns printable ACL strings associated with an ACL manager
protecting a schema object.
Data Types and Structures
dce_attr_sch_handle_t
An opaque handle to a schema object. Use dce_attr_sch_bind to
acquire the handle.
dce_attr_component_name_t
A pointer to a character string used to further specify a schema
object.
dce_bind_auth_info_t
A enumeration that defines whether or not the binding is
authenticated. This data type is defined exactly as the
sec_attr_bind_auth_info_t data type in the ERA interface.
See the sec_intro reference page for more information
on sec_attr_bind_auth_info_t.
dce_attr_schema_entry_t
A structure that defines a complete attribute entry for the schema
catalog. This data type is defined exactly as the
sec_attr_schema_entry_t data type in the ERA interface. See the
sec_intro reference page for more information on
sec_attr_schema_entry_t.
dce_attr_cursor_t
A structure that provides a pointer into a database and is used for
multiple database operations. This cursor must minimally represent
the object indicated by dce_attr_sch_handle_t. The cursor may
additionally represent an entry within that schema.
dce_attr_schema_entry_parts_t
A 32-bit bitset containing flags that specify the schema entry
fields that can be modified on a schema entry update operation.
This data type is defined exactly as the
sec_attr_schema_entry_parts_t data type in the ERA interface.
See the sec_intro reference page for more information on
sec_attr_schema_entry_parts_t.
1.1 – dce_attr_sch_bind
NAME
dce_attr_sch_bind - Return an opaque handle to a schema object
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_bind( dce_attr_component_name_t schema_name,
dce_bind_auth_info_t *auth_info,
dce_attr_sch_handle_t *h,
error_status_t *status );
PARAMETERS
Input
schema_name
A pointer to a value of type dce_attr_component_name_t that
specifies the name of the schema object to bind to.
auth_info
A value of type dce_bind_auth_info_t that defines the
authentication and authorization parameters to use with the
binding handle. If set to NULL, the default authentication
and authorization parameters are used.
Output
h An opaque handle of type dce_attr_sch_handle_t to the named
schema object for use with dce_attr_sch operations.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_bind() routine returns an opaque handle of type
dce_attr_sch_handle_t to a named schema object. The returned handle
can then be used for subsequent dce_attr_sch operations performed
on the object.
Permissions Required
The dce_attr_sch_update_entry() routine requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_name
sec_login_s_no_current_context
rpc_s_entry_not_found
rpc_s_no_more_bindings
dce_attr_s_unknown_auth_info_type
dce_attr_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_bind_free
1.2 – dce_attr_sch_bind_free
NAME
dce_attr_sch_bind_free - Releases an opaque handle of type
dce_attr_sch_handle_t to a schema object
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_bind_free( dce_attr_sch_handle_t *h,
error_status_t *status );
PARAMETERS
Input
h An opaque handle of type dce_attr_sch_handle_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_bind_free() routine releases an opaque handle
of type dce_attr_sch_handle_t. The handle was returned with the
dce_attr_sch_bind() routine and used to perform dce_attr_sch
operations.
Permissions Required
The dce_attr_sch_bind_free() routine requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_SCH.IDL
The idl file from which dce/dce_attr_sch.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_bind
1.3 – dce_attr_sch_create_entry
NAME
dce_attr_sch_create_entry - Create a schema entry in a schema bound
to by a previous dce_attr_sch_bind()
routine
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_create_entry( dce_attr_sch_handle_t h,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
schema_entry
A pointer to a dce_attr_schema_entry_t that contains the
schema entry values for the schema in which the entry is
to be created.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_create_entry() routine creates schema entries that
define attribute types in the schema object bound to by h.
Permissions Required
The dce_attr_sch_create_entry() routine requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_binding
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_delete_entry
dce_attr_sch_update
1.4 – dce_attr_sch_update_entry
NAME
dce_attr_sch_update_entry - Update a schema entry
SYNOPSIS
#include <dce/dce_attr_sch.h>
void dce_attr_sch_update_entry(
dce_attr_sch_handle_t h,
dce_attr_schema_entry_parts_t modify_parts,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
modify_parts
A value of type dce_attr_schema_entry_parts_t that identifies
the fields in the schema bound to by h that can be modified.
schema_entry
A pointer to a dce_attr_schema_entry_t that contains the
schema entry values for the schema entry to be updated.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_update_entry() routine modifies schema entries.
Only those schema entry fields set to be modified in the
dce_attr_schema_entry_parts_t data type can be modified.
Some schema entry components can never be modified. Instead to make
any changes to these components, the schema entry must be deleted
(which deletes all attribute instances of that type) and recreated.
These components are listed below:
+ Attribute name
+ Reserved flag
+ Apply defaults flag
+ Intercell action flag
+ Trigger binding
+ Comment
Fields that are arrays of structures (such as acl_mgr_set and
trig_binding) are completely replaced by the new input array.
This operation cannot be used to add a new element to the existing
array.
Permissions Required
The dce_attr_sch_update_entry() routine requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_binding
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_delete_entry
dce_attr_sch_create_entry
1.5 – dce_attr_sch_delete_entry
NAME
dce_attr_sch_delete_entry - Delete a schema entry
SYNOPSIS
#include <dce/dce_attr_sch.h>
void dce_attr_sch_delete_entry( dce_attr_sch_handle_t h,
uuid_t *attr_id,
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
attr_id
A pointer to a uuid_t that identifies the schema entry to be
deleted in the schema bound to by h.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_delete_entry() routine deletes a schema entry.
Because this is a radical operation that invalidates any existing
attributes of this type on objects dominated by the schema, access
to this operation should be severely limited.
Permissions Required
The dce_attr_sch_delete_entry() routine requires requires
appropriate permissions on the schema object. These permissions
are managed by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_binding
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_create_entry
dce_attr_sch_update_entry
1.6 – dce_attr_sch_scan
NAME
dce_attr_sch_scan - Read a specified number of schema entries
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_scan( dce_attr_sch_handle_t h,
dce_attr_cursor_t *cursor,
unsigned32 num_to_read,
unsigned32 *num_read,
dce_attr_schema_entry_t schema_entries[],
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
num_to_read
An unsigned 32-bit integer specifying the size of the
schema_entries[] array and the maximum number of entries to
be returned.
Input/Output
cursor
A pointer to a dce_attr_cursor_t. As input cursor must
be allocated and can be initialized. If cursor is not
initialized, dce_attr_sch_scan will initialize it. As
output, cursor is positioned at the first schema entry
after the returned entries.
Output
num_read
A pointer to an unsigned 32-bit integer specifying the number
of entries returned in schema_entries[].
schema_entries[]
A dce_attr_schema_entry_t that contains an array of the
returned schema entries.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_scan() routine reads schema entries. The read
begins at the entry at which the input cursor is positioned and
ends after the number of entries specified in num_to_read.
The input cursor must have been allocated by either the
dce_attr_sch_cursor_init() or the dce_attr_sch_cursor_alloc() call.
If the input cursor is not initialized, dce_attr_sch_scan()
initializes it; if cursor is initialized, dce_attr_sch_scan() simply
advances it.
To read all entries in a schema, make successive dce_attr_sch_scan()
calls. When all entries have been read, the call returns the message
no_more_entries.
This routine is useful as a browser.
Permissions Required
The dce_attr_sch_scan() routine requires requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_binding
dce_attr_s_bad_cursor
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_cursor_init
dce_attr_sch_cursor_alloc
dce_attr_sch_cursor_release
1.7 – dce_attr_sch_cursor_init
NAME
dce_attr_sch_cursor_init - Initialize and allocate a cursor used
with the dce_attr_sch_scan call
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_rgy_attr_cursor_init( dce_attr_sch_handle_t h,
unsigned32 *cur_num_entries,
dce_attr_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
Output
cur_num_entries
A pointer to an unsigned 32-bit integer that specifies the
total number of entries contained in the schema at the time
of this call.
cursor
A pointer to a dce_attr_cursor_t that is initialized to the
first entry in the the schema.
status
A pointer to the completion status. On successful completion,
the call returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_cursor_init() call initializes and allocates a
cursor used with the dce_attr_sch_scan call. This call makes
remote calls to initialize the cursor. To limit the number of
remote calls, use the dce_attr_sch_cursor_alloc() call to allocate
cursor, but not initialize it. If the cursor input to
dce_attr_sch_scan has not been initialized, dce_attr_sch_scan call
will initialize it; if it has been initialized, dce_attr_sch_scan
advances it.
Unlike the dce_attr_sch_cursor_alloc() call, the
dce_attr_sch_cursor_init() call supplies the total number
of entries found in the schema as an output parameter.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_binding
dce_attr_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_cursor_release
dce_attr_sch_scan
dce_attr_sch_cursor_allocate
1.8 – dce_attr_sch_cursor_alloc
NAME
dce_attr_sch_cursor_alloc - Allocates resources to a cursor used
with the dce_attr_sch_scan call
SYNOPSIS
#include <dce/dce_attr_sch.h>
void dce_rgy_attr_cursor_alloc( dce_attr_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Output
cursor A pointer to a dce_attr_cursor_t.
status A pointer to the completion status. On successful
completion, the call returns error_status_ok. Otherwise,
it returns an error.
DESCRIPTION
The dce_attr_sch_cursor_alloc() call allocates resources to a
cursor used with the dce_attr_sch_scan call. This routine,
which is a local operation, does not initialize cursor.
The dce_attr_sch_cursor_init() routine, which makes a remote
call, allocates and initializes the cursor. In addition,
dce_attr_sch_cursor_init() returns the total number of entries
found in the schema as an output parameter;
dce_attr_sch_cursor_alloc() does not.
Permissions Required
The dce_attr_sch_cursor_alloc() call requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_cursor_init
dce_attr_sch_cursor_release
dce_attr_sch_scan
1.9 – dce_attr_sch_cursor_release
NAME
dce_attr_sch_cursor_release - Release states associated with a cursor
that has been allocated with either
dce_attr_sch_cursor_init() or
dce_attr_sch_cursor_alloc().
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_cursor_init( dce_attr_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input/Output
cursor
A pointer to a dce_attr_cursor_t. As an input parameter,
cursor must have been initialized to the first entry in a
schema. As an output parameter, cursor is uninitialized
with all resources released.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_cursor_init() routine releases the resources
allocated to a cursor that has been allocated by either a
dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). This
call is a local operation and makes no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_cursor_init
dce_attr_sch_cursor_alloc
dce_attr_sch_cursor_reset
dce_attr_sch_scan
1.10 – dce_attr_sch_cursor_reset
NAME
dce_attr_sch_cursor_reset - Resets a cursor that has been allocated
with either dce_attr_sch_cursor_init()
or dce_attr_sch_cursor_alloc().
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_cursor_reset( dce_attr_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input/Output
cursor
A pointer to a dce_attr_cursor_t. As an input parameter, an
initialized cursor. As an output parameter, cursor is reset
to the first attribute in the schema.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_cursor_reset() routine resets a dce_attr_cursor_t
that has been allocated by either a dce_attr_sch_cursor_init() or
dce_attr_sch_cursor_alloc(). The reset cursor can then be used to
process a new dce_attr_sch_scan query by reusing the cursor instead
of releasing and re-allocating it. This is a local operation and
makes no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_SCH.IDL
The idl file from which dce/dce_attr_sch.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_cursor_init
dce_attr_sch_cursor_alloc
dce_attr_sch_scan
1.11 – dce_attr_sch_lookup_by_id
NAME
dce_attr_sch_lookup_by_id - Read a schema entry identified by UUID
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_lookup_by_id( dce_attr_sch_handle_t h,
uuid_t *attr_id,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
attr_id
A pointer to a uuid_t that identifies a schema entry.
Output
schema_entry
A dce_attr_schema_entry_t that contains an entry identified
by attr_id.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_lookup_by_id() routine reads a schema entry
identified by attr_id. This routine is useful for programmatic
access.
Permissions Required
The dce_attr_sch_lookup_by_id() routine requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_binding
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_lookup_by_name
dce_attr_sch_scan
1.12 – dce_attr_sch_lookup_by_name
NAME
dce_attr_sch_lookup_by_name - Read a schema entry identified by name
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_lookup_by_name(
dce_attr_sch_handle_t h,
char *attr_name,
dce_attr_schema_entry_t *schema_entry,
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
attr_name
A pointer to a character string that identifies the schema
entry.
Output
schema_entry
A dce_attr_schema_entry_t that contains the schema entry
identified by attr_name.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_lookup_by_name() routine reads a schema entry
identified by name. This routine is useful for use with an
interactive editor.
Permissions Required
The dce_attr_sch_lookup_by_name() routine requires appropriate
permissions on the schema object. These permissions are managed
by the target server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_bad_binding
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_lookup_by_id
dce_attr_sch_scan
1.13 – dce_attr_sch_get_acl_mgrs
NAME
dce_attr_sch_get_acl_mgrs - Retrieve the manager types of the
ACLs protecting the objects dominated
by a named schema
SYNOPSIS
#include <dce/dce_attr_base.h>
void dce_attr_sch_get_acl_mgrs( dce_attr_sch_handle_t h,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_acl_mgr_types,
uuid_t acl_mgr_types[],
error_status_t *status );
PARAMETERS
Input
h An opaque handle bound to a schema object. Use
dce_attr_sch_bind() to acquire the handle.
size_avail
An unsigned 32-bit integer containing the allocated length
of the acl_manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the acl_mgr_types[] array.
num_acl_mgr_types
An unsigned 32-bit integer containing the number of types
returned in the acl_mgr_types[] array. This may be greater
than size_used if there was not enough space allocated by
size_avail for all the manager types in the
acl_manager_types[] array.
acl_mgr_types[]
An array of the length specified in size_avail to contain
UUIDs (of type uuid_t) identifying the types of ACL managers
protecting the target object.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The dce_attr_sch_get_acl_mgrs() routine returns a list of the
manager types protecting the schema object identified by h.
ACL editors and browsers can use this operation to determine the ACL
manager types protecting a selected schema object. Then, using the
dce_attr_sch_aclmgr_strings() routine, they can determine how to
format for display the permissions supported by that ACL manager type.
Permissions Required
The dce_attr_sch_get_acl_mgrs() routine requires appropriate
permissions on the schema object for which the ACL manager types
are to be returned. These permissions are managed by the target
server.
FILES
SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL
The idl file from which dce/dce_attr_base.h was derived.
ERRORS
dce_attr_s_not_implemented
error_status_ok
RELATED INFORMATION
Functions: dce_attr_intro
dce_attr_sch_aclmgr_strings
2 – dce_cf_intro
NAME
dce_cf_intro - Introduction to the DCE configuration routines
DESCRIPTION
The DCE configuration routines return information based on the
contents of the local DCE configuration file, which is created
during the DCE cell-configuration or machine-configuration process.
A configuration file is located on each DCE machine; it contains the
host's name, the primary name of the cell in which the host is
located, and any aliases for that cell name.
The configuration routines can also be used to get some additional
information corollary to the hostname, namely:
+ The host's principal name.
+ Binding information to the host.
The configuration file on machines that belong to internationalized
DCE cells also contains the pathname to the code set registry object
file on the host.
The Security Service component on each DCE machine must be able to
find out, by strictly local means, its machine's hostname, the host
machine's principal name, and its cell's name. The DCE configuration
routines exist primarily to enable Security components to do these
things. But because this information can be useful to DCE
applications as well, these routines are made available as part of
the general application programming interface.
Note that "hostname" as used throughout this section refers to the
DCE hostname (that is, the machine's
/.../cellname/host_directory/hostname entry in the CDS namespace),
and not, for example, its DNS (Domain Name Service) hostname, which
could be quite different from the DCE name.
The DCE configuration routines are:
dce_cf_binding_entry_from_host()
Returns the host binding entry name.
dce_cf_dced_entry_from_host()
Returns the dced entry name on a host.
dce_cf_find_name_by_key()
Returns a string tagged by key (this is a lower-level
utility routine that is used by the others).
dce_cf_free_cell_aliases()
Frees a list of cell aliases for a cell.
dce_cf_get_cell_aliases()
Returns a list of cell aliases for a cell.
dce_cf_get_cell_name()
Returns the primary cell name for the local cell.
dce_cf_get_csrgy_filename()
Returns the pathname of the local code set registry
object file.
dce_cf_get_host_name()
Returns the hostname relative to a local cell.
dce_cf_prin_name_from_host()
Returns the host's principal name.
dce_cf_profile_entry_from_host
Returns the host's profile entry.
dce_cf_same_cell_name()
Indicates whether or not two cell names refer to the same
cell.
CAUTIONS
The DCE 1.0 implementations of the DCE configuration routines will
accept only lines (in the configuration file) whose length is less
than 1024 characters. If a tag occurs more than once in the input,
the routines will recognize only the first occurrence.
FILES
DCE$LOCAL:[000000]dce_cf.db
The machine's local DCE configuration file (where DCE$LOCAL is
usually something like DIA0:[SYS0.DCELOCAL.]).
The format of the configuration file is as follows.
Each of the entries is tagged with its own identifier, which must be
the first nonblank token on a line that does not begin with a #
(number sign) comment character. The second token on a line is
assumed to be the name associated with the tag that was detected in
front of it.
For example, cellname and hostname are tags, identifying the cellname
and hostname, respectively, for the machine on which the
configuration file is located. A sample configuration file could have
the following contents:
cellname /.../osf.org
hostname hosts/brazil
which would identify the host brazil in the osf.org cell.
Text characterized by the following is ignored:
+ Garbage lines; that is, lines that do not conform to the
previously described format.
+ Leading and trailing spaces in lines.
+ Additional tokens appearing on a line after the second token.
The configuration file should be writable only by privileged users,
and readable by all.
OUTPUT
The DCE configuration routines return names without global or cell-
relative prefixes, such as:
host_directory/hostname
or:
principalname
where:
host_directory is usually hosts.
However, the DCE NSI (Name Service Interface) routines require names
passed to them to be expressed either in a cell-relative form, such
as:
/.:/host_directory/hostname
or as global names, with the global root prefix /.../ and the cell
name, such as:
/.../cellname/host_directory/hostname
Therefore, an application must add either the cell-relative (/.:/) or
correct global (/.../cellname) prefix to any name it receives from a
DCE configuration routine before it passes the name to an NSI
routine. (NSI routines all have names beginning with rpc_ns_.) For
example, the name host_directory/hostname would become, if expressed
in cell-relative form:
/.:/hosts/hostname
The cell-relative form of the name principalname would be:
/.:/sec/principals/principalname
where:
hostname and principalname are the host's name and principal name,
respectively.
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide-Core Components
OSF DCE Command Reference.
FUNCTIONS:
2.1 – dce_cf_binding_entry_from_host
NAME
dce_cf_binding_entry_from_host - Returns the host binding entry
name
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_binding_entry_from_host( char *hostname,
char **entry_name,
error_status_t *status);
PARAMETERS
INPUT
hostname - Specifies the name of the host. Note that host names
are case sensitive. If NULL, the configuration file
is searched for the hostname, and that name, if found,
is used.
OUTPUT
entry_name - The binding entry name associated with the specified
host.
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation completed successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No hostname entry in the DCE
configuration file.
DESCRIPTION
The dce_cf_binding_entry_from_host() routine returns the binding entry
name string associated with the hostname passed to it. If hostname is
NULL, the binding entry name associated with the name returned by
dce_cf_get_host_name() is returned.
FILES
DCE$LOCAL:[000000]dce_cf.db
The machine's local DCE configuration file (where dcelocal is
usually something like DIA0:[SYS0.DCELOCAL.]).
RETURN VALUES
No value is returned.
RELATED INFORMATION
BOOKS: OSF DCE Administration Guide.
FUNCTIONS: dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
2.2 – dce_cf_dced_entry_from_host
NAME
dce_cf_dced_entry_from_host - Returns the dced entry name on a host
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_dced_entry_from_host( char *hostname,
char **entry_name,
error_status_t *status);
PARAMETERS
INPUT
hostname - Specifies the name of the host. Note that host names
are case-sensitive. If this value is NULL, the value
returned by dce_cf_get_host_name is used.
OUTPUT
entry_name - The dced entry name associated with the specified
host. Storage for this name is dynamically allocated;
release it with free() when you no longer need it.
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation completed successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No hostname entry in the DCE
configuration file.
DESCRIPTION
The dce_cf_dced_entry_from_host() routine returns the name entered into
the DCE namespace for a DCE host daemon (dced) on the host specified by
the hostname parameter. If the hostname parameter is NULL, the dced
name associated with the name returned by dce_cf_get_host_name() is
returned. The string name is of the form /.:/hosts/hostname/config,
and specifies the entry point into the dced namespace on the host.
This is the location in the DCE namespace at which dced stores the
objects associated with the host services it provides (the hostdata,
srvrconf, srvrexec, secval, and keytab services, as well as ACL
editing). It is also an actual name in the DCE namespace that you can
import if you want to create your own RPC binding to dced.
You can use the dced entry name returned by this routine as input to
the dced_binding_create() routine, input to sec_acl_* routines, or to
rpc_ns_binding_import_* routines to establish a binding to a dced host
service.
If using dced_binding_create(), you append a service name to the entry
returned by this routine. If using sec_acl_* routines, you append the
service and the object name. If using rpc_ns_binding_import_*, you use
only the entry returned by the routine.
You can also use the returned string to name objects that dced
maintains, for example, when editing these objects' ACLs with dcecp.
For example, the string name /.:/hosts/vineyard/config/srvrconf/dtsd
names the server configuration data for the DTS server on the host
vineyard.
FILES
DCE$LOCAL:[000000]dce_cf.db
The machine's local DCE configuration file (where dcelocal is
usually something like DIA0:[SYS0.DCELOCAL.]).
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
dced_binding_create
BOOKS: OSF DCE Application Development Guide-Core Components
OSF DCE Com mand Reference.
2.3 – dce_cf_find_name_by_key
NAME
dce_cf_find_name_by_key - Returns a string tagged by a character
string key
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_find_name_by_key( FILE *fp,
char *key,
char **name,
error_status_t *status);
PARAMETERS
INPUT
fp - A file pointer to a correctly formatted text file opened for
reading.
key - A character string key that will be used to find name.
INPUT/OUTPUT
name - A pointer to a string (char **) in which a string containing
the name found will be placed. The name string will be
allocated by malloc().
OUTPUT
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation completed succesfully.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for key in the file.
DESCRIPTION
The dce_cf_find_name_by_key() routine searches a text file for the
first occurrence of a string tag identical to the string passed in
key. The tag string, in order to be found, must be the first non-white
space string on an uncommented line. If the tag string is found,
dce_cf_find_name_by_key() allocates (by a call to malloc()) a buffer
for the next string found on the same line as the tag string, copies
this second string into the buffer, and returns its address in the name
input parameter.
The name of the DCE configuration file is in the constant
dce_cf_c_db_name; in turn, this constant is defined in the include file
<dce_cf.h>.
CAUTIONS
The memory for a returned name string is allocated by malloc(), and
must be freed by the original caller of the configuration routine that
called dce_cf_find_name_by_key().
The DCE 1.0 version of this routine is limited to processing lines of
text whose length is less than 1024 characters.
FILES
DCE$LOCAL/dce_cf.db
The machine's local DCE configuration file (where dcelocal
is usually something like DIA0:[SYS0.DCELOCAL.]).
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_binding_entry_from_host
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
BOOKS: OSF DCE Administration Guide.
2.4 – dce_cf_free_cell_aliases
NAME
dce_cf_free_cell_aliases - Frees a list of cell name aliases for
the local cell
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_free_cell_aliases( char **cell_alias_list,
error_status_t *status);
PARAMETERS
INPUT
cell_alias_list - The address of a cell alias list, which is a
null-terminated array of pointers to the cell
alias names for the local cell.
OUTPUT
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as
follows:
dce_cf_st_ok Operation completed succesfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for key in the file.
DESCRIPTION
The dce_cf_free_cell_aliases() routine frees the list of aliases for
the local cell that the dce_cf_free_cell_aliases() routine allocated.
The routine frees the memory allocated to hold the array of pointers
to cell alias string buffers, and also frees the string buffers.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_get_cell_aliases
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
dce_cf_same_cell_name
BOOKS: OSF DCE Application Development Guide-Core Components
OSF DCE Command Reference.
2.5 – dce_cf_get_cell_aliases
NAME
dce_cf_get_cell_aliases - Returns a list of aliases for the local
cell
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_get_cell_aliases( char ***cell_alias_list,
error_status_t *status);
PARAMETERS
INPUT
None.
OUTPUT
cell_alias_list - The address of a string pointer array. This
routine sets this address to point to the
address of an allocated null-terminated array
of pointers to the cell alias names for the
local cell. If no aliases exist, the routine
returns NULL in this parameter.
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation completed succesfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for key in the file.
DESCRIPTION
The dce_cf_get_cell_aliases() routine retrieves the local cell's cell
name aliases. If cell aliases are found, the routine returns the
address of an allocated list of cell alias names in the cell_alias_list
parameter. If no aliases exist for the cell, the routine returns NULL.
Use the dce_cf_free_cell_aliases() routine to free the memory allocated
by the dce_cf_get_cell_aliases() routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_free_cell_aliases
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_same_cell_name
BOOKS: OSF DCE Application Development Guide-Core Components,
OSF DCE Command Reference.
2.6 – dce_cf_get_cell_name
NAME
dce_cf_get_cell_name - Returns the primary name for the local
cell
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_get_cell_name( char **cellname,
error_status_t *status);
PARAMETERS
INPUT
None.
OUTPUT
cellname - The address of a string pointer. This pointer will be
set by the function to point to an allocated buffer
that contains the cellname.
OUTPUT
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation completed succesfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No match for key in the file.
DESCRIPTION
The dce_cf_get_cell_name() routine retrieves the primary name for the
local cell. If the name is found, dce_cf_get_cell_name() returns an
allocated (by a call to malloc()) copy of it in the cellname input
parameter. Use free() to free the allocated copy when you no longer
need it.
The DCE 1.0 version of this routine is limited to processing lines of
text whose length is less than 1024 characters.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_free_cell_aliases
dce_cf_get_cell_aliases
dce_cf_get_host_name
dce_cf_prin_name_from_host
BOOKS: OSF DCE Administration Guide.
2.7 – dce_cf_get_csrgy_filename
NAME
dce_cf_get_csrgy_filename - Returns the pathname of the code set
registry file on a host
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_get_csrgy_filename( char **csrgy_filename,
error_status_t *status);
PARAMETERS
INPUT
None.
INPUT/OUTPUT
csrgy_filename - The address of a string pointer. This pointer
will be set by the function to point to a buffer
that contains the pathname to the code set
registry file.
OUTPUT
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation successfully completed.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
DESCRIPTION
The dce_cf_get_csrgy_filename() routine is a DCE function that returns
the pathname of a code set registry file that has been created on a
given host with the csrc utility. DCE RPC routines for code set inter-
operability use this routine when they need to locate a host's code set
registry file in order to map between unique code set identifiers and
their operating system-specific local code set names, or to obtain
supported code sets for a client or server. User-written code set
interoperability routines can also use the routine.
The dce_cf_get_csrgy_filename() routine searches the DCE configuration
file for the name of the local host's code set registry file, allocates
a buffer for it (by a call to malloc()), copies the name into the
buffer, and returns its address in the csrgy_filename input parameter.
CAUTIONS
The memory for a returned name string is allocated by malloc(), and
must be freed by the caller of dce_cf_get_csrgy_filename().
The DCE 1.0 verion of this routine is limited to processing lines of
text whose length is less than 1024 characters.
FILES
DCE$LOCAL:[000000]dce_cf.db
The machine's local DCE configuration file (where dcelocal
is usually something like DIA0:[SYS0.DCELOCAL.]).
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_get_cell_name
dce_cf_find_name_by_key
dce_cf_get_host_name
dce_cf_prin_name_from_host
dce_loc_to_rgy
dce_rgy_to_loc
rpc_rgy_get_codesets
COMMANDS: csrc.
BOOKS: OSF DCE Administration Guide.
2.8 – dce_cf_get_host_name
NAME
dce_cf_get_host_name - Returns the hostname relative to the local
cell root
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_get_host_name( char **hostname,
error_status_t *status);
PARAMETERS
INPUT
None.
INPUT/OUTPUT
hostname - The address of a string pointer. This pointer will be
set by the function to point to a buffer that contains
the hostname.
OUTPUT
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation successfully completed.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No hostname entry in the DCE
configuration file.
DESCRIPTION
The dce_cf_get_host_name() routine searches the DCE configuration file
for the local host's name relative to the local cell's root. If the
name is found, dce_cf_get_host_name() allocates (by a call to malloc())
a buffer for it, copies the name into the buffer, and returns its
address in the hostname input parameter.
CAUTIONS
The memory for a returned name string is allocated by malloc(), and
must be freed by the caller of dce_cf_get_host_name().
The DCE 1.0 version of this routine is limited to processing lines of
text whose length is less than 1024 characters.
FILES
DCE$LOCAL:[000000]dce_cf.db
The machine's local DCE configuration file (where dcelocal
is usually something like DIA0:[SYS0.DCELOCAL.]).
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_prin_name_from_host
BOOKS: OSF DCE Administration Guide.
2.9 – dce_cf_prin_name_from_host
NAME
dce_cf_prin_name_from_host - Returns the host's principal name
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_prin_name_from_host( char *hostname,
char **prin_name,
error_status_t *status);
PARAMETERS
INPUT
hostname - The name of the host. Note that host names are case
sensitive. If NULL, the configuration file is searched
for the hostname, and that name, if found, is used.
OUTPUT
prin_name - The principal name associated with the specified host.
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation completed successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No hostname entry in the DCE
configuration file.
DESCRIPTION
The dce_cf_prin_name_from_host() routine returns the principal name
associated with the hostname passed to it. If hostname is NULL,
dce_cf_prin_name_from_host() returns the principal name associated
with the name returned by dce_cf_get_host_name().
FILES
DCE$LOCAL:[000000]dce_cf.db
The machine's local DCE configuration file (where dcelocal is
usually something like DIA0:[SYS0.DCELOCAL.]).
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_binding_entry_from_host
dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
BOOKS: OSF DCE Administration Guide.
2.10 – dce_cf_profile_entry_from_host
NAME
dce_cf_profile_entry_from_host - Returns the host profile entry
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_profile_entry_from_host( char *hostname,
char **prof_name,
error_status_t *status);
PARAMETERS
INPUT
hostname - Specifies the name of the host. Note that host names
are case sensitive. If NULL, the configuration file is
searched for the hostname, and that name, if found, is
used.
OUTPUT
prof_name - The profile entry associated with the specified host.
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes and their meanings are as follows:
dce_cf_st_ok Operation completed successfully.
dce_cf_e_file_open File open error.
dce_cf_e_no_mem No memory available.
dce_cf_e_no_match No hostname entry in the DCE
configuration file.
DESCRIPTION
The dce_cf_profile_entry_from_host() routine returns the profile entry
string associated with the hostname passed to it. If hostname is NULL,
the profile entry associated with the name returned by
dce_cf_get_host_name() is returned.
FILES
DCE$LOCAL:[000000]dce_cf.db
The machine's local DCE configuration file (where dcelocal is
usually something like DIA0:[SYS0.DCELOCAL.]).
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_find_name_by_key
dce_cf_get_cell_name
dce_cf_get_host_name
dce_cf_prin_name_from_host
dce_cf_binding_entry_from_host
BOOKS: OSF DCE Administration Guide.
2.11 – dce_cf_same_cell_name
NAME
dce_cf_same_cell_name - Indicates whether or not two cell names
refer to the same cell
SYNOPSIS
#include <dce/dce_cf.h>
void dce_cf_same_cell_name( char *cell_name1,
char *cell_name2,
boolean result,
error_status_t *status);
PARAMETERS
INPUT
cell_name1 - A character string that specifies the name of a
cell.
cell_name2 - A character string that specifies the name of a
cell to compare with cell_name1. If this value is
NULL, the routine determines whether or not the cell
name specified in cell_name1 is the name of the local
cell.
OUTPUT
result - A boolean value that indicates whether or not the
specified cell names match, when two cell names are
given, and indicates whether or not the specified cell
name is the name of the local cell, when only one cell
name is given. A value of TRUE indicates that the cell
names refer to the same cell.
status - Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
Possible status codes are as follows:
dce_cf_st_ok Operation completed successfully.
dce_cf_e_no_match No hostname entry in the DCE
configuration file.
DESCRIPTION
The dce_cf_same_cell_name () routine, when given the names of two cells
as input parameters, compares the cell names to determine whether or
not they refer to the same call. The result parameter is set to TRUE if
they do, and to FALSE if they do not.
If only one cell name is specified as an input parameter, the
dce_cf_same_cell_name() routine determines whether or not the specified
cell name is the same as the local cell's primary name (which it
retrieves by calling dce_cf_get_cell_name()). You can use the routine
in this way to determine whether a given cell name is the primary name
of your local cell.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: dce_cf_free_cell_aliases
dce_cf_get_cell_aliases
dce_cf_get_cell_name
BOOKS: OSF DCE Application Development Guide-Core Components
OSF DCE Command Reference
3 – dce_db_intro
NAME
dce_db_intro - Introduction to the DCE backing store interface
DESCRIPTION
The DCE backing store interface allows you to maintain typed data
between program invocations. For example, you might store application-
specific configuration data in a backing store, and then retrieve it
from the backing store when the application restarts. The backing
store routines can be used in servers, in clients or in standalone
programs that do not involve remote procedure calls (RPC). A program
can have more than one backing store open at the same time.
Sometimes the backing store is called a database. For instance, the
associated IDL file is dce/database.idl, and the name of the backing
store routines begin with dce_db_. The backing store is, however,
not a full-fledged database in the conventional sense, and it has no
support for SQL or for any other query system.
BACKING STORE DATA
The backing store interface provides for the tagged storage and
retrieval of typed data. The tag (or retrieval key) can be either
a UUID or a standard C string. For a specific backing store, the
data type must be specified at compile time, and is established
through the IDL Encoding Services. Each backing store can contain
only a single data type.
Each data item (also called a data object or data record) consists
of the data stored by a single call to a storage routine
(dce_db_store(), dce_db_store_by_name(), or dce_db_store_by_uuid()).
Optionally, data items can have headers. If a backing store has been
created to use headers, then every data item must have a header. For
a description of the data item header, see "Data Structures," below.
ENCODING AND DECODING IN THE BACKING STORE
When a Remote Procedure Call (RPC) sends data between a client and a
server, it serializes the user's data structures by using the IDL
Encoding Services (ES), described in the OSF DCE Application
Development Guide.
The backing store uses this same serialization scheme for encoding
and decoding, informally called "pickling," when storing data
structures to disk. The IDL compiler, idl, writes the routine that
encodes and decodes the data. This routine is passed to dce_db_open(),
remembered in the handle, and used by the store and fetch routines:
+ dce_db_fetch()
+ dce_db_fetch_by_name()
+ dce_db_fetch_by_uuid()
+ dce_db_header_fetch()
+ dce_db_store()
+ dce_db_store_by_name()
+ dce_db_store_by_uuid()
MEMORY ALLOCATION
When fetching data, the Encoding Services (ES) allocate memory for
the data structures that are returned. These services accept a
structure, and use rpc_sm_allocate() to provide additional memory
needed to hold the data.
The backing store library does not know what memory has been allocated,
and therefore cannot free it. For fetch calls that are made from a
server stub, this is not a problem, because the memory is freed
automatically when the server call terminates. For fetch calls that
are made from a non-server, the programmer is responsible for freeing
the memory.
Programs that call the fetch or store routines, such as dce_db_fetch(),
outside of a server operation (for instance, if a server does some
backing store initialization, or in a standalone program) must call
rpc_sm_enable_allocate() first.
THE BACKING STORE ROUTINES
Many of the backing store routines appear in three versions: plain,
by name, and by UUID. The plain version will work with backing
stores that were created to be indexed either by name, or by UUID,
while the restricted versions accept only the matching type. It is
advantageous to use the restricted versions when they are appropriate,
because they provide type checking by the compiler, as well as visual
clarity of purpose.
The backing store routines are as follows, listed in alphabetical order:
dce_db_close() Frees the handle returned by dce_db_open().
It closes any open files and releases all other
resources associated with the backing store.
dce_db_delete() Deletes an item from a backing store that is
indexed by name or by UUID. The key's type must
match the flag that was used in dce_db_open().
dce_db_delete_by_name()
Deletes an item only from a backing store that
is indexed by name.
dce_db_delete_by_uuid()
Deletes an item only from a backing store that
is indexed by UUID.
dce_db_fetch() Retrieves data from a backing store that is
indexed by name or by UUID. The key's type
must match the flag that was used in dce_db_open().
dce_db_fetch_by_name()
Retrieves data only from a backing store that is
indexed by name.
dce_db_fetch_by_uuid()
Retrieves data only from a backing store that is
indexed by UUID.
dce_db_free() Releases the data supplied from a backing store.
dce_db_header_fetch()
Retrieves a header from a backing store.
dce_db_inq_count() Returns the number of items in a backing store.
dce_db_iter_done() Terminates and iteration operation initiated by
dce_db_iter_start(). It should be called when
iteration is done.
dce_db_iter_next() Returns the key for the next item from a backing
store that is indexed by name or by UUID. The
db_s_no_more return value indicates that there
are no more items.
dce_db_iter_next_by_name()
Returns the key for the next item only from a
backing store that is indexed by name. The
db_s_no_more return value indicates that there
are no more items.
dce_db_iter_next_by_uuid()
Returns the key for the next item only from a
backing store that is indexed by UUID. The
db_s_no_more return value indicates that there
are no more items.
dce_db_iter_start() Prepares for the start of iteration.
dce_db_lock() Locks a backing store. A lock is associated with
an open backing store's handle. The storage
routines, dce_db_store(), dce_db_store_by_name(),
and dce_db_store_by_uuid(), all acquire the lock
before updating.
dce_db_open() Creates a new backing store or opens an existing
one. The backing store is identified by a
filename. Flags allow you to:
+ Create a new backing store, or open an
existing one.
+ Create a new backing store indexed by name,
or indexed by UUID.
+ Open an existing backing store read/write,
or read-only.
+ Use the standard data item header, or not.
The routine returns a handle by which subsequent routines can
reference the opened backing store.
dce_db_std_header_init()
Initializes a standard backing store header
retrieved by dce_db_header_fetch(). It only
places the values into the header, and does
not write into the backing store.
dce_db_store() Stores a data item into a backing store that
is indexed by name or by UUID. The key's type
must match the flag that was used in
dce_db_open().
dce_db_store_by_name()
Stores a data item only into a backing store
that is indexed by name.
dce_db_store_by_uuid()
Stores a data item only into a backing store
that is indexed by UUID.
dce_db_unlock() Unlocks a backing store.
DATA TYPES AND STRUCTURES
dce_db_handle_t An opaque handle to a backing store. Use
dce_db_open() to acquire the handle.
dce_db_header_t The data structure that defines a standard
backing store header for data items. Use
dce_db_header_fetch() to retrieve it from a
backing store and dce_db_std_header_init() to
initialize it.
dce_db_convert_func_t
An opaque pointer to the data conversion
function to be used when storing or retrieving
data. This function is specified as an
argument to dce_db_open() at open time. It
converts between native format and on-disk
(serialized) format. It is generated from the
IDL file by the IDL compiler.
CAUTIONS
You can not use conformant arrays in objects stored to a backing
store. This is because the idl-generated code that encodes (pickles)
the structure has no way to predict or detect the size of the array.
When the object is fetched, there will likely be insufficient space
provided for the structure, and the array's data will destroy
whatever is in memory after the structure.
FILES
database.idl, database.h, db.h, and dbif.h
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide
3.1 – dce_db_close
NAME
dce_db_close - Closes an open backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_close( dce_db_handle_t *handle,
error_status_t *status );
PARAMETERS
Input
handle A handle identifying the backing store to be closed.
Output
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_close() routine closes a backing store that was opened
by dce_db_open(). It also frees the storage used by the handle,
and sets the handle's value to NULL.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_open
3.2 – dce_db_delete
NAME
dce_db_delete - Deletes an item from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_delete( dce_db_handle_t handle,
void *key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A pointer to a string or UUID that is the key to the
item in the backing store. The datatype of key must
match the key method that was selected in the flags
parameter to dce_db_open() when the backing store was
created.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error code.
DESCRIPTION
The dce_db_delete() routine deletes an item from the backing store
that is identified by the handle parameter, which was obtained from
dce_db_open(). It is a general deletion routine, interpreting the
key parameter according to the type of index with which the backing
store was created.
ERRORS
db_s_del_failed
The deletion did not occur. The global variable errno
may indicate further information about the error.
db_s_bad_index_type
The key's type is wrong, or the backing store is not by
name or by UUID.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Deletion is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete_by_name
dce_db_delete_by_uuid
dce_db_open
3.3 – dce_db_delete_by_name
NAME
dce_db_delete_by_name - Deletes an item from a string-indexed
backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_delete_by_name( dce_db_handle_t handle,
char *key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A NULL-terminated string that is the key to the item
in the backing store.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error code.
DESCRIPTION
The dce_db_delete_by_name() routine deletes an item from the
backing store that is identified by the handle parameter, which
was obtained from dce_db_open(). It is a specialized deletion
routine for backing stores that are indexed by name, as selected
by the db_c_index_by_name bit in the flags parameter to
dce_db_open() when the backing store was created.
ERRORS
db_s_del_failed
The deletion did not occur. The global variable errno
may indicate further information about the error.
db_s_bad_index_type
The backing store is not indexed by name.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Deletion is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete
dce_db_delete_by_uuid
dce_db_open
3.4 – dce_db_delete_by_uuid
NAME
dce_db_delete_by_uuid - Deletes an item from a UUID-indexed
backing-store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_delete_by_uuid( dce_db_handle_t handle,
uuid_t *key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing-store being used.
key A pointer to a UUID that is the key to the item in the
backing store.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error code.
DESCRIPTION
The dce_db_delete_by_uuid() routine deletes an item from the
backing-store that is identified by the handle parameter, which
was obtained from dce_db_open(). It is a specialized deletion
routine for backing stores that are indexed by UUID, as selected
by the db_c_index_by_uuid bit in the flags parameter to
dce_db_open() when the backing store was created.
ERRORS
db_s_del_failed
The deletion did not occur. The global variable errno
may indicate further information about the error.
db_s_bad_index_type
The backing-store is not indexed by UUID.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Deletion is
not allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete
dce_db_delete_by_name
dce_db_open
3.5 – dce_db_fetch
NAME
dce_db_fetch - Retrieves data from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_fetch( dce_db_handle_t handle,
void *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A string or UUID that is the key to the item in the
backing store. The datatype of key must match the key
method that was selected in the flags parameter to
dce_db_open() when the backing store was created.
Output
data A pointer to the returned data.
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_fetch() routine retrieves data from the backing store
that is identified by the handle parameter, which was obtained
from dce_db_open(). It is a general retrieval routine,
interpreting the key parameter according to the type of index
with which the backing store was created.
The data parameter is shown as a pointer to an arbitrary data
type. In actual use it will be the address of the backing-store-
specific data type.
NOTES
After calling dce_db_fetch(), it may be necessary to free some
memory, if the call was made outside of an RPC, on the server
side. This is done by calling rpc_sm_client_free(). (Inside
an RPC the memory is allocated through rpc_sm_allocate(), and
is automatically freed.)
Programs that call dce_db_fetch() outside of a server operation
(for instance, if a server does some backing store initialization,
or in a standalone program) must call rpc_sm_enable_allocate()
first. Indeed, every thread that calls dce_db_fetch() must do
rpc_sm_allocate(), but in the server side of an RPC, this is
already done.
ERRORS
db_s_key_not_found
The specified key was not found in the backing store.
(This circumstance is not necessarily an error.)
db_s_bad_index_type
The key's type is wrong, or else the backing store is
not by name or by UUID.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch_by_name
dce_db_fetch_by_uuid
dce_db_free
dce_db_open
3.6 – dce_db_fetch_by_name
NAME
dce_db_fetch_by_name - Retrieves data from a string-indexed
backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_fetch_by_name( dce_db_handle_t handle,
char *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A null-terminated string that is the key to the item
in the backing store.
Output
data A pointer to the returned data.
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_fetch_by_name() routine retrieves data from the
string-indexed backing store that is identified by the handle
parameter, which was obtained from dce_db_open(). It is a
specialized retrieval routine for backing stores that are indexed
by string, as selected by the db_c_index_by_name bit in the flags
parameter to dce_db_open() when the backing store was created.
The data parameter is shown as a pointer to an arbitrary data type.
In actual use it will be the address of the backing-store-specific
data type.
NOTES
After calling dce_db_fetch_by_name(), it may be necessary to free
some memory, if the call was made outside of an RPC, on the server
side. This is done by calling rpc_sm_client_free(). (Inside an
RPC the memory is allocated through rpc_sm_allocate(), and is
automatically freed.)
Programs that call dce_db_fetch_by_name() outside of a server
operation (for instance, if a server does some backing store
initialization, or in a standalone program) must call
rpc_sm_enable_allocate() first. Indeed, every thread that calls
dce_db_fetch_by_name() must do rpc_sm_allocate(), but in the
server side of an RPC, this is already done.
EXAMPLES
This example shows the use of the user-defined data type as the
data parameter.
extern dce_db_handle_t db_h;
uuid_t key_uuid;
my_data_type_t my_data;
error_status_t status;
/* set key_uuid = xxx; */
dce_db_fetch_by_name(db_h, &key_uuid, &my_data, &status);
ERRORS
db_s_key_not_found
The specified key was not found in the backing store.
(This circumstance is not necessarily an error.)
db_s_bad_index_type
The backing store is not indexed by name.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_uuid
dce_db_free
dce_db_open
3.7 – dce_db_fetch_by_uuid
NAME
dce_db_fetch_by_uuid - Retrieves data from a UUID-indexed backing
store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_fetch_by_uuid( dce_db_handle_t handle,
uuid_t *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A UUID that is the key to the item in the backing store.
Output
data A pointer to the returned data.
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_fetch_by_uuid() routine retrieves data from the
UUID-indexed backing store that is identified by the handle
parameter, which was obtained from dce_db_open(). It is a
specialized retrieval routine for backing stores that are
indexed by UUID, as selected by the db_c_index_by_uuid bit in
the flags parameter to dce_db_open() when the backing store was
created.
The data parameter is shown as a pointer to an arbitrary data type.
In actual use it will be the address of the backing-store-specific
data type.
NOTES
After calling dce_db_fetch_by_uuid(), it may be necessary to free
some memory, if the call was made outside of an RPC, on the server
side. This is done by calling rpc_sm_client_free(). (Inside an
RPC the memory is allocated through rpc_sm_allocate(), and is
automatically freed.)
Programs that call dce_db_fetch_by_uuid() outside of a server
operation (for instance, if a server does some backing store
initialization, or in a standalone program) must call
rpc_sm_enable_allocate() first. Indeed, every thread that calls
dce_db_fetch_by_uuid() must do rpc_sm_allocate(), but in the
server side of an RPC, this is already done.
EXAMPLES
This example shows the use of the user-defined data type as the
data parameter.
extern dce_db_handle_t db_h;
uuid_t key_uuid;
my_data_type_t my_data;
error_status_t status;
/* set key_uuid = xxx; */
dce_db_fetch_by_uuid(db_h, &key_uuid, &my_data, &status);
ERRORS
db_s_key_not_found
The specified key was not found in the backing store.
(This circumstance is not necessarily an error.)
db_s_bad_index_type
The backing store is not indexed by UUID.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_name
dce_db_free
dce_db_open
3.8 – dce_db_free
NAME
dce_db_free - Releases the data supplied from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_free( dce_db_handle_t handle,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
data The data area to be released.
Output
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_free() routine is designed to free the data
area previously returned via a call to dce_db_fetch(),
dce_db_fetch_by_name(), or dce_db_fetch_by_uuid().
NOTES
In the current implementation, the dce_db_free() routine does not
perform any action. For servers that execute properly this is of
little consequence, because their allocated memory is automatically
cleaned up when a remote procedure call finishes. For completeness,
and for compatibility with future releases, the use of dce_db_free()
is recommended.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_name
dce_db_fetch_by_uuid
3.9 – dce_db_header_fetch
NAME
dce_db_header_fetch - Retrieves the header from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_header_fetch( dce_db_handle_t handle,
void *key,
dce_db_header_t *hdr,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A string or UUID that is the backing store key.
Output
hdr A pointer to a caller-supplied header structure to be
filled in by the library.
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_header_fetch() routine returns a pointer to a copy of the
header of the object in the backing store that is identified by the
handle parameter, which was obtained from dce_db_open(). The caller
must free the copy's storage. It was allocated (as with other fetch
routines) through rpc_ss_alloc(). The key parameter is interpreted
according to the type of index with which the backing store was
created.
The hdr parameter is shown as a pointer to an arbitrary data type.
In actual use it will be the address of the backing-store-specific
data type.
ERRORS
db_s_key_not_found
The key was not found in the backing store.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_std_header_init
3.10 – dce_db_inq_count
NAME
dce_db_inq_count - Returns the number of items in a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_inq_count( dce_db_handle_t handle,
unsigned32 *count,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
count A pointer to the number of items in the backing store.
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_inq_count() routine returns the number of items in the
backing store that is identified by the handle parameter, which was
obtained from dce_db_open(). It performs identically on backing
stores that are indexed by UUID and those that are indexed by string.
The count of items can be helpful when iterating through a backing
store.
ERRORS
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Determining the
count is not allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_next
3.11 – dce_db_iter_done
NAME
dce_db_iter_done - Frees the state associated with iteration
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_done( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
DESCRIPTION
The dce_db_iter_done() routine frees the state that permits
iteration. It should be called after an iteration through a
backing store is finished.
The iteration state is established by dce_db_iter_start().
The routines for performing iteration over the items are
dce_db_iter_next(), dce_db_iter_next_by_name(), and
dce_db_iter_next_by_uuid().
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_iter_start
3.12 – dce_db_iter_next
NAME
dce_db_iter_next - During iteration, returns the next key from
a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_next( dce_db_handle_t handle,
void **key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
key A pointer to the string or UUID that is the key to the
item in the backing store.
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_iter_next() routine retrieves the next key from the
backing store that is identified by the handle parameter. An
iterator established by the dce_db_iter_start() routine maintains
the identity of the current key. Use one of the dce_db_fetch()
routines to retrieve the actual data.
The iteration functions scan sequentially through a backing store,
in no particular order. The dce_db_iter_start() routine initialized
the process, a dce_db_iter_next() routine retrieves successive keys,
for which the data can be retrieved with dce_db_fetch(), and the
dce_db_iter_done() routine finishes the process. The iteration can
also use the dce_db_iter_next_by_name() and dce_db_iter_next_by_uuid()
routines; the fetching can use the dce_db_fetch_by_name() and
dce_db_fetch_by_uuid() routines.
The iteration routine returns a pointer to a private space
associated with the handle. Each call to the iteration routine
reuses the space, instead of using allocated space.
ERRORS
db_s_no_more
All the keys in the backing store have been accessed;
there are no more iterations remaining to be done.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_name
dce_db_fetch_by_uuid
dce_db_iter_done
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_iter_start
3.13 – dce_db_iter_next_by_name
NAME
dce_db_iter_next_by_name - During iteration, returns the next key
from a backing store indexed by string
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_next_by_name( dce_db_handle_t handle,
char **key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
key The string that is the key to the item in the backing store.
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_iter_next_by_name() routine retrieves the next key
from the backing store that is identified by the handle parameter.
An iterator established by the dce_db_iter_start() routine maintains
the identity of the current key. Use the dce_db_fetch_by_name()
routine to retrieve the actual data.
This iteration routine is the same as dce_db_iter_next(), except
that it only works with backing stores indexed by name, and returns
an error if the backing store index is the wrong type.
The iteration routine returns a pointer to a private space
associated with the handle. Each call to the iteration routine
reuses the space, instead of using allocated space.
ERRORS
db_s_no_more
All the keys in the backing store have been accessed;
there are no more iterations remaining to be done.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch_by_uuid
dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_uuid
dce_db_iter_start
3.14 – dce_db_iter_next_by_uuid
NAME
dce_db_iter_next_by_uuid - During iteration, returns the next key
from a backing store indexed by UUID
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_next_by_uuid( dce_db_handle_t handle,
uuid_t **key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
key The UUID that is the key to the item in the backing store.
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_iter_next_by_uuid() routine retrieves the next key
from the backing store that is identified by the handle parameter.
An iterator established by the dce_db_iter_start() routine maintains
the identity of the current key. Use the dce_db_fetch_by_uuid()
routine to retrieve the actual data.
This iteration routine is the same as dce_db_iter_next(), except
that it only works with backing stores indexed by UUID, and returns
an error if the backing store index is the wrong type.
The iteration routine returns a pointer to a private space
associated with the handle. Each call to the iteration routine
reuses the space, instead of using allocated space.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_start
3.15 – dce_db_iter_start
NAME
dce_db_iter_start - Prepares a backing store for iteration
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_start( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
DESCRIPTION
The dce_db_iter_start() routine prepares the backing store that is
identified by the handle parameter for iterative retrieval of all
its keys in succession.
A given handle can support only a single instance of iteration at
one time.
To avoid the possibility that another thread will write to the
backing store during an iteration, always use the dce_db_lock()
routine before calling dce_db_iter_start().
ERRORS
db_s_iter_not_allowed
The function was called while an iteration was already
in progress. The concept of nested iterations is not
supported.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_lock
dce_db_unlock
dce_db_open
3.16 – dce_db_lock
NAME
dce_db_lock - Applies an advisory lock on a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_lock( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
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_lock() routine acquires the lock associated with the
handle.
There is an advisory lock associated with each handle. The routines
for storing and deleting backing stores apply the lock before
updating a backing store. This routine provides a means to apply
the lock for other purposes, such as iteration.
Advisory locks allow cooperating threads to perform consistent
operations on backing stores, but do not guarantee consistency;
that is, threads may still access backing stores without using
advisory locks, possibly resulting in inconsistencies.
ERRORS
db_s_already_locked
An attempt was made to lock a backing store, but it
was already locked.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete
dce_db_delete_by_name
dce_db_delete_by_uuid
dce_db_store
dce_db_store_by_name
dce_db_store_by_uuid
dce_db_unlock
3.17 – dce_db_open
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
3.18 – dce_db_std_header_init
NAME
dce_db_std_header_init - Initializes a standard backing store header
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_std_header_init( dce_db_handle_t handle,
dce_db_header_t *hdr,
uuid_t *uuid,
uuid_t *acl_uuid,
uuid_t *def_object_acl,
uuid_t *def_container_acl,
unsigned32 ref_count,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
hdr Pointer to the object header part of the users' structure.
uuid The UUID to be placed into the header. Can be NULL.
acl_uuid The UUID of the ACL protecting this object, to be placed
into the header. Can be NULL.
def_object_acl
The UUID of the default object ACL, to be placed into
the header. Can be NULL.
def_container_acl
The UUID of the default container ACL, to be placed into
the header. Can be NULL.
ref_count The reference count to be placed into the header.
Output
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_std_header_init() routine initializes the fields of the
standard header for a data object whose backing store is identified
by the handle parameter. The fields are only set in memory and
should be stored to the backing store by one of the store routines.
The handle was obtained from dce_db_open(), which must have been
called with the db_c_std_header flag.
ERRORS
db_s_bad_header_type
The header type is not dce_db_header_std.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_header_fetch
3.19 – dce_db_store
NAME
dce_db_store - Stores data into a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_store( dce_db_handle_t handle,
void *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A string or UUID that is the backing store key. The
datatype of key must match the key method that was
selected in the flags parameter to dce_db_open() when
the backing store was created.
data A pointer to the data structure to be stored.
Output
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_store() routine stores the data structure pointed to by
data into the backing store. The conversion function that was
specified in the call to dce_db_open() serializes the structure so
that it can be written to disk.
If the key value is the same as a key already stored, the new data
replaces the previously stored data associated with that key.
NOTES
Because the dce_db_store() routine uses the encoding services,
and they in turn use rpc_sm_allocate(), all programs that call
dce_db_store() outside of a server operation (for instance, if a
server does some backing store initialization, or in a standalone
program) must call rpc_sm_enable_allocate() first. Indeed, every
thread that calls dce_db_store() must do rpc_sm_enable_allocate(),
but in the server side of an RPC, this is already done.
ERRORS
db_s_bad_index_type
The key's type is wrong, or else the backing store is not
by name or by UUID.
db_s_readonly
The backing store was opened with the db_c_readonly flag,
and cannot be written to.
db_s_store_failed
The data could not be stored into the backing store for
some reason. The global variable errno may contain more
information about the error.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Storing is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_open
dce_db_store_by_name
dce_db_store_by_uuid
3.20 – dce_db_store_by_name
NAME
dce_db_store_by_name - Stores data into a string-indexed backing
store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_store_by_name( dce_db_handle_t handle,
char *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A null-terminated string that is the backing store key.
data A pointer to the data structure to be stored.
Output
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_store_by_name() routine stores the data structure pointed
to by data into the backing store. The conversion function that was
specified in the call to dce_db_open() serializes the structure so
that it can be written to disk.
This routine is specialized for storage into backing stores that
are indexed by string, as selected by the db_c_index_by_name bit
in the flags parameter to dce_db_open() when the backing store was
created.
If the key value is the same as a key already stored, the new data
replaces the previously stored data associated with that key.
NOTES
Because the dce_db_store_by_name() routine uses the encoding
services, and they in turn use rpc_sm_allocate(), all programs
that call dce_db_store_by_name() outside of a server operation
(for instance, if a server does some backing store initialization,
or in a standalone program) must call rpc_sm_enable_allocate()
first. Indeed, every thread that calls dce_db_store_by_name() must
do rpc_sm_enable_allocate(), but in the server side of an RPC, this
is already done.
ERRORS
db_s_bad_index_type
The backing store is not indexed by name.
db_s_readonly
The backing store was opened with the db_c_readonly flag,
and cannot be written to.
db_s_store_failed
The data could not be stored into the backing store for
some reason. The global variable errno may contain more
information about the error.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Storing is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_open
dce_db_store
dce_db_store_by_uuid
3.21 – dce_db_store_by_uuid
NAME
dce_db_store_by_uuid - Stores data into a UUID-indexed backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_store_by_uuid( dce_db_handle_t handle,
uuid_t *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A UUID that is the backing store key.
data A pointer to the data structure to be stored.
Output
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_store_by_uuid() routine stores the data structure pointed
to by data into the backing store. The conversion function that was
specified in the call to dce_db_open() serializes the structure so
that it can be written to disk.
This routine is specialized for storage into backing stores that are
indexed by UUID, as selected by the db_c_index_by_uuid bit in the
flags parameter to dce_db_open() when the backing store was created.
If the key value is the same as a key already stored, the new data
replaces the previously stored data associated with that key.
NOTES
Because the dce_db_store_by_uuid() routine uses the encoding services,
and they in turn use rpc_sm_allocate(), all programs that call
dce_db_store_by_uuid() outside of a server operation (for instance,
if a server does some backing store initialization, or in a standalone
program) must call rpc_sm_enable_allocate() first. Indeed, every
thread that calls dce_db_store_by_uuid() must do
rpc_sm_enable_allocate(), but in the server side of an RPC, this is
already done.
ERRORS
db_s_bad_index_type
The backing store is not indexed by UUID.
db_s_readonly
The backing store was opened with the db_c_readonly flag,
and cannot be written to.
db_s_store_failed
The data could not be stored into the backing store for
some reason. The global variable errno may contain more
information about the error.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Storing is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_open
dce_db_store
dce_db_store_by_name
3.22 – dce_db_unlock
NAME
dce_db_unlock - Releases the backing store lock
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_unlock( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
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_unlock() routine releases the lock associated with the
handle.
ERRORS
db_s_not_locked
An attempt was made to unlock a backing store, but it
was not locked.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_lock
4 – dce_msg_intro
NAME
dce_msg_intro - Introduction to the DCE messaging interface
DESCRIPTION
All DCE message texts are assigned a unique message ID. This is a
32-bit number, with the special value of all-bits-zero reserved to
indicate success. All other numbers are divided into a
technology/component that identifies the message catalog, and an
index into the catalog.
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component is built.
(The messages may also be compiled into the application code,
rendering the successful retrieval of message text independent of
whether or not the message catalogs were correctly installed.)
In typical use, a message is first retrieved from a message catalog,
allowing localization to occur. If this fails, the default message
is retrieved from an in-memory table. If this fails, a fallback text
identifying the message number is generated. The two most useful
routines, dce_error_inq_text() and dce_msg_get(), and the DCE printf
routines follow these rules. The rest of this API gives direct access
for special needs.
The dce_msg_cat_xxx() routines provide a DCE abstraction to standard
message catalog routines, mapping DCE message IDs to message catalog
names. They offer a convenient way of opening and accessing a message
catalog simply by supplying the ID of a message contained in it,
rather than the name of the catalog itself. Once opened, the catalog
is accessed by means of an opaque handle (the dce_msg_cat_handle_t
typedef).
THE DCE MESSAGING ROUTINES
The messaging routines are as follows, listed in alphabetical order:
dce_error_inq_text()
Retrieves from the installed DCE component
message catalogs the message text associated
with an error status code returned by a DCE
library routine.
dce_fprintf() Functions much like dce_printf(), except that
it prints the message and its arguments on the
specified stream.
dce_msg_cat_close() Closes the message catalog (which was opened with
dce_msg_cat_open()).
dce_msg_cat_get_msg()
Retrieves the text for a specified message.
dce_msg_cat_open() Opens the message catalog that contains the
specified message, and returns a handle that
can be used in subsequent calls to
dce_msg_cat_get_msg().
dce_msg_define_msg_table()
Registers an in-memory table containing the
messages.
dce_msg_get() Retrieves the text for a specified message.
A "convenience" form of the
dce_msg_get_msg() routine.
dce_msg_get_cat_msg()
A "convenience" form of the
dce_msg_cat_get_msg() routine. Unlike
dce_msg_cat_get_msg(), dce_msg_get_cat_msg()
does not require the message catalog to be
explicitly opened.
dce_msg_get_default_msg()
Retrieves a message from the application's in-
memory tables.
dce_msg_get_msg() Retrieves the text for a specified message.
dce_msg_translate_table()
The dce_msg_translate_table() routine overwrites
the specified in-memory message table with the
values from the equivalent message catalogs.
dce_pgm_fprintf() Equivalent to dce_fprintf(), except that it
prepends the program name and appends a newline.
dce_pgm_printf() Equivalent to dce_printf(), except that it
prepends the program name and appends a newline.
dce_pgm_sprintf() Equivalent to dce_sprintf(), except that it
prepends the program name and appends a newline.
dce_printf() Retrieves the message text associated with the
specified message ID, and prints the message and
its arguments on the standard output.
dce_sprintf() Retrieves the message text associated with the
specified message ID, and prints the message and
its arguments into an allocated string that is
returned.
DATA TYPES AND STRUCTURES
dce_error_string_t An array of characters big enough to hold any
error text returned by dce_error_inq_text().
dce_msg_cat_handle_t
An opaque handle to a DCE message catalog.
(Use dce_msg_cat_open() to get a handle.)
FILES
dce/dce_msg.h
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide
4.1 – dce_error_inq_text
NAME
dce_error_inq_text - Retrieves message text associated with a DCE
error code
SYNOPSIS
#include <dce/dce_error.h>
void dce_error_inq_text( error_status_t status_to_convert,
dce_error_string_t error_text,
int *status );
PARAMETERS
Input
status_to_convert
DCE status code for which text message is to be retrieved.
Output
error_text
The message text associated with the status_to_convert.
status
Returns the status code from this operation. The status code
is set to 0 on success, and to -1 on failure.
DESCRIPTION
The dce_error_inq_text() routine retrieves from the installed DCE
component message catalogs the message text associated with an error
status code returned by a DCE library routine.
All DCE message texts are assigned a unique 32-bit message ID. The
special value of all-bits-zero is reserved to indicate success.
The dce_error_inq_text() routine uses the message ID as a series of
indices into the correct DCE component's message catalog; the text
found by this indexing is the message that explains the status code
that was returned by the DCE or DCE application routine.
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component is built.
(The messages may also be compiled into the component code,
rendering the successful retrieval of message text independent of
whether or not the message catalogs were correctly installed.)
If the user sets their LANG variable and has the correct message
catalog files installed, the user can receive translated messages.
That is, the text string returned by dce_error_inq_text() is
dependant on the current locale.
EXAMPLES
The following code fragment shows how dce_error_inq_text() can be
used to retrieve the message text describing the status code returned
by a DCE RPC library routine:
dce_error_string_t error_string;
error_status_t status;
int print_status;
rpc_server_register_if( application_v1_0_s_ifspec,
&type_uuid,
(rpc_mgr_epv_t)&manager_epv, &status );
if (status != rpc_s_ok) {
dce_error_inq_text( status,
error_string,
&print_status );
fprintf( stderr,
" Server: %s: %s\n",
caller,
error_string );
}
4.2 – dce_msg_cat_close
NAME
dce_msg_cat_close - DCE message catalog close routine
SYNOPSIS
#include <dce/dce_msg.h>
void dce_msg_cat_close( dce_msg_cat_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle
The handle (returned by dce_msg_cat_open()) to the catalog
that is to be closed.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_cat_close() routine closes the message catalog (which
was opened with dce_msg_cat_open()). On error, it fills in status
with an error code.
ERROR CODES
See dce_msg_get
RELATED INFORMATION
Functions: dce_msg_cat_get_msg
dce_msg_cat_open
dce_msg_get_cat_msg
dce_msg_get
dce_msg_get_msg
4.3 – dce_msg_cat_get_msg
NAME
dce_msg_cat_get_msg - DCE message text retrieval routine
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_cat_get_msg( dce_msg_cat_handle_t handle,
unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
The ID of the message to be retrieved.
handle
A handle (returned by dce_msg_cat_open()) to an opened message
catalog.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
Once the catalog has been opened with the dce_msg_cat_open() routine,
the dce_msg_cat_get_msg() routine can be used to retrieve the text
for a specified message (which is a 32-bit DCE message ID as described
in dce_error_inq_text). If the specified message cannot be found
in the catalog, the routine returns a NULL and fills in status with
the appropriate error code.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_cat_close
dce_msg_cat_open
dce_msg_get_cat_msg
dce_msg_get
dce_msg_get_msg
4.4 – dce_msg_cat_open
NAME
dce_msg_cat_open - DCE message catalog open routine
SYNOPSIS
#include <dce/dce_msg.h>
dce_msg_cat_handle_t dce_msg_cat_open( unsigned32 message_ID,
error_status_t *status );
PARAMETERS
Input
message_ID
The ID of the message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_cat_open() routine opens the message catalog that
contains the specified message_ID. It returns a handle that can
be used in subsequent calls to dce_msg_cat_get_msg(). On error,
it returns NULL and fills in status with an appropriate error code.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_cat_close
dce_msg_cat_get_msg
dce_msg_get_cat_msg
dce_msg_get
dce_msg_get_msg
4.5 – dce_msg_define_msg_table
NAME
dce_msg_define_msg_table - Adds a message table to in-memory table
SYNOPSIS
#include <dce/dce_msg.h>
void dce_msg_define_msg_table( dce_msg_table_t *table,
unsigned32 count,
error_status_t *status );
PARAMETERS
Input
table A message table structure (defined in a header file generated
by sams during compilation (see the EXAMPLES section).
count The number of elements contained in the table.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component
(application) is built.
However, the messages may also be compiled directly into the
component code, thus rendering the successful retrieval of message
text independent of whether or not the message catalogs were
correctly installed. Generation of in-memory message tables is
specified by the incatalog flag in the sams file in which the
message text is defined (see SAMS for more information on sams
files). If the messages have been generated at compile time with
this option specified, the dce_msg_define_msg_table() routine can be
called by the application to register an in-memory table containing
the messages.
The table parameter to the call should identify a message table
structure defined in a header file generated by sams during
compilation (see the EXAMPLES section). The count parameter
specifies the number of elements contained in the table. If an
error is detected during the call, the routine will return an
appropriate error code in the status parameter.
EXAMPLES
The following code fragment shows how an application (whose
serviceability component name is app) would set up an in-memory
message table:
#include <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#include "dceappmsg.h" /* defines app_msg_table */
error_status_t status;
The following call adds the message table to the in-memory table.
Note that you must include <dce/dce_msg.h>. You also have to link
in dceappmsg.obj and dceappsvc.obj (object files produced by
compiling sams-generated .c files), which contain the code for the
messages and the table, respectively.
dce_msg_define_msg_table( app_msg_table,
sizeof(app_msg_table) /
sizeof(app_msg_table[0]),
&status );
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_get
dce_msg_get_msg
dce_msg_get_default_msg
4.6 – dce_msg_get
NAME
dce_msg_get - Retrieves text of specified DCE message
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get( unsigned32 message );
PARAMETERS
Input
message
ID of message to be retrieved.
DESCRIPTION
The dce_msg_get() routine is a convenience'' form of the
dce_msg_get_msg() routine. Like dce_msg_get_msg(), dce_msg_get()
retrieves the text for a specified message (which is a 32-bit DCE
message ID as described in dce_msg_intro). However, dce_msg_get()
does not return a status code; it either returns the specified
message successfully or fails (aborts the program) with an
assertion error if the message could not be found or memory could
not be allocated.
The routine implicitly determines the correct message catalog in
which to access the specified message, and opens it; the caller
only has to call this routine.
The routine first searches the appropriate message catalog for the
message, and then (if it cannot find the catalog) searches the in-
memory message table, if it exists.
The message, if found, is returned in allocated space to which the
routine returns a pointer. The pointed-to space must be freed by the
caller using free.
ERROR CODES
msg_s_bad_id
Invalid message ID
A message ID with an invalid technology or component was
specified.
msg_s_no_cat_open
Could not open the message catalog for the specified
message ID.
msg_s_no_cat_perm
Local file permissions prevented the program from opening
the message catalog for the specified message ID.
msg_s_no_catalog
The message catalog for the specified message ID does not
exist.
msg_s_no_default
Could not find the default message for the specified status
code in the internal tables.
msg_s_no_memory
Could not allocate memory for message table, string copy,
or other internal requirement.
msg_s_not_found
Could not find the text for the specified status code in
either the in-core message tables or the message catalogs.
msg_s_ok_text
The operation was performed successfully.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
dce_msg_get_msg
dce_msg_get_default_msg
4.7 – dce_msg_get_cat_msg
NAME
dce_msg_get_cat_msg - Opens message catalog and retrieves message
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get_cat_msg( unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
ID of message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_get_cat_msg() routine is a "convenience" form of the
dce_msg_cat_get_msg() routine. The difference between it and the
latter routine is that dce_msg_get_cat_msg() does not require the
message catalog to be explicitly opened; it determines the correct
catalog from the message parameter (which is a 32-bit DCE message
ID as described in dce_error_inq_text), opens it, retrieves the
message, and returns a pointer to malloc()'d space containing the
message. If the message catalog is inaccessible, the routine returns
an error. (See the routine dce_msg_get() for a description of the
return value.)
The routine will fail if the message catalog is not correctly
installed.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_cat_close
dce_msg_cat_get_msg
dce_msg_cat_open
dce_msg_get
dce_msg_get_msg
4.8 – dce_msg_get_default_msg
NAME
dce_msg_get_default_msg - Retrieves DCE message from in-memory tables
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get_default_msg( unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
ID of message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_get_default_msg() routine retrieves a message from the
application's in-memory tables. It returns a pointer to static space
that should not be freed. If the specified message (which is a 32-bit
DCE message ID as described in dce_error_inq_text) cannot be found in
the in-memory tables, the routine returns NULL and fills in status
with the appropriate error code.
This routine should be used only for message strings that will never
have to be translated (see dce_msg_translate_table).
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component is built.
Messages may also be compiled directly into the component code, thus
rendering the successful retrieval of message text independent of
whether or not the message catalogs were correctly installed.
Generation of in-memory message tables is specified by the incatalog
flag in the sams file in which the message text is defined. (See sams
for more information on sams files.) If the messages have been
generated at compile time with this option specified, the
dce_msg_define_msg_table() routine can be called by the application to
set up an in-memory table containing the messages.
EXAMPLES
The following code fragment shows how dce_msg_get_default_msg() might
be called to retrieve the in-memory copy of a message defined by a DCE
application (whose serviceability component name is app):
#include <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#include "dceappmsg.h" /* "test_msg" is defined in this file */
unsigned char *my_msg;
error_status_t status;
<. . .>
my_msg = dce_msg_get_default_msg(test_msg, &status);
printf("Message is: %s\n", my_msg);
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
dce_msg_get
dce_msg_get_msg
4.9 – dce_msg_get_msg
NAME
dce_msg_get_msg - Retrieve a DCE message from its ID
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get_msg( unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
ID of message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_get_msg() routine retrieves the text for a specified
message (which is a 32-bit DCE message ID as described in
dce_error_inq_text). The routine implicitly determines the correct
message catalog in which to access the message, and opens it; the
caller only has to call the routine.
The routine first searches the appropriate message catalog for the
message, and then (if it cannot find the catalog) searches the in-
memory message table. If the message cannot be found in either of
these places, the routine returns a default string and fills in
status with an error code. This routine thus always returns a string,
even if there is an error (except for msg_s_no_memory).
The message, if found, is returned in allocated space to which the
routine returns a pointer. The pointed-to space must be freed by the
caller using free. If memory cannot be allocated, the routine returns
NULL and fills in status with the msg_s_no_memory error code.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
dce_msg_get
dce_msg_get_default_msg
4.10 – dce_msg_translate_table
NAME
dce_msg_translate_table - Translates all in-memory messages in
a table
SYNOPSIS
#include <dce/dce_msg.h>
void dce_msg_translate_table( dce_msg_table_t *table,
unsigned32 count,
error_status_t *status );
PARAMETERS
Input
table A message table structure (defined in a header file generated
by sams during compilation (see "EXAMPLES" below), the
contents of which are to be translated.
count The number of elements contained in the table.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_translate_table() routine overwrites the specified
in-memory message table (that is, updates the in-memory table with
the contents of a message table, which has changed for some reason;
for example, because of a change in locale).
If any in-memory message is not found in the message catalog, all
in-memory messages are left unchanged.
EXAMPLES
The following code fragment shows how dce_msg_translate_table()
might be called (in an application whose serviceability component
name is app) to translate a DCE application's in-memory message
table, set up by an earlier call to dce_msg_define_msg_table():
#include <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#include "dceappmsg.h"
char *loc_return;
error_status_t status;
<. . .>
dce_msg_translate_table (app_msg_table,
sizeof(app_msg_table) /
sizeof(app_msg_table[0]),
&status );
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
4.11 – dce_pgm_printf
NAME
dce_pgm_printf
dce_pgm_fprintf
dce_pgm_sprintf - Formatted DCE message output routines
SYNOPSIS
#include <dce/dce.h>
int dce_pgm_printf( unsigned32 messageid, . . . );
int dce_pgm_fprintf( FILE *stream, unsigned32 messageid, . . . );
unsigned char *dce_pgm_sprintf( unsigned32 messageid, . . . );
PARAMETERS
Input
messageid
The message ID, defined in the message's code field in
the sams file.
stream An open file pointer.
. . . Any format arguments for the message string.
DESCRIPTION
The dce_pgm_printf() routine is equivalent to dce_printf(), except
that it prefixes the program name to the message (in the standard
style of DCE error messages), and appends a newline to the end of the
message. The routine dce_printf() does neither. This allows clients
(which do not usually use the serviceability interface) to produce
error (or other) messages which automatically include the originating
application's name. Note that the application should call
dce_svc_set_progname() first to set the desired application name.
Otherwise, the default program name will be PID#nnnn, where nnnn is
the process ID of the application making the call.
The dce_pgm_sprintf() routine is similarly equivalent to
dce_sprintf(), and the dce_pgm_fprintf() routine is similarly
equivalent to dce_fprintf().
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_fprintf
dce_msg_get_msg
dce_printf
dce_sprintf
dce_svc_set_progname
4.12 – dce_printf
NAME
dce_printf
dce_fprintf
dce_sprintf - Formatted DCE message output routines
SYNOPSIS
#include <dce/dce.h>
int dce_printf( unsigned32 messageid, . . . );
int dce_fprintf( FILE *stream, unsigned32 messageid, . . . );
unsigned char *dce_sprintf( unsigned32 messageid, . . . );
PARAMETERS
Input
messageid
The message ID, defined in the message's code field in
the sams file.
stream An open file pointer.
. . . Any format arguments for the message string.
DESCRIPTION
The dce_printf() routine retrieves the message text associated with
the specified messageid, and prints the message and its arguments on
the standard output. The routine determines the correct message
catalog and, if necessary, opens it. If the message catalog is
inaccessible, and the message exists in an in-memory table, then this
message is printed. If neither the catalog nor the default message is
available, a default message is printed.
The dce_fprintf() routine functions much like dce_printf(), except
that it prints the message and its arguments on the specified stream.
The dce_sprintf() routine retrieves the message text associated with
the specified messageid, and prints the message and its arguments into
an allocated string that is returned. The routine determines the
correct message catalog and, if necessary, opens it. If the message
catalog is inaccessible, and the message exists in an in-memory table,
then this message is printed. If neither the catalog nor the default
message is available, a default message is printed. The
dce_pgm_printf() routine is equivalent to dce_printf(), except that it
prefixes the program name to the message (in the standard style of DCE
error messages), and appends a newline to the end of the message. For
more information, see the dce_pgm_printf reference page.
EXAMPLES
Assume that the following message is defined in an application's sams
file:
start
code arg_msg
text "This message has exactly %d, not %d argument(s)"
action "None required"
explanation "Test message with format arguments"
end
The following code fragment shows how dce_sprintf() might be called
to write the message (with some argument values) into a string:
unsigned char *my_msg;
my_msg = dce_sprintf(arg_msg, 2, 8);
puts(my_msg);
free(my_msg);
Of course, dce_printf() could also be called to print the message and
arguments:
dce_printf(arg_msg, 2, 8);
ERROR CODES
See dce_msg_get.
NOTES
The final formatted string generated by dce_sprintf() must not
exceed 1024 bytes.
RELATED INFORMATION
Functions: dce_msg_get_msg
dce_svc_set_progname
5 – dce_server_intro
NAME
dce_server_intro - Introduction to the DCE server routines
DESCRIPTION
The routines described on this reference page are used by servers to
register themselves with DCE. This includes registering with the RPC
runtime, the local endpoint mapper, and the namespace. Routines are
also available to set up DCE security so that servers can receive and
invoke authenticated RPCs.
THE DCE SERVER ROUTINES
The server routines are as follows, listed in alphabetical order:
dce_server_disable_service()
Unregisters an individual interface of a DCE
server from the RPC runtime, and marks the
server's endpoints as disabled in the dced's
endpoint mapper service.
dce_server_enable_service()
Registers an individual interface (application
service) of a DCE server with the RPC runtime,
and marks the server's endpoints as enabled in
the dced's endpoint mapper service.
dce_server_inq_attr()
Obtains application-specific attribute data
from the dced server configuration data.
dce_server_inq_server()
Obtains the server configuration data dced
used to start the server.
dce_server_inq_uuids()
Obtains the UUIDs that dced used in its srvrconf
and srvrexec facilities to identify the server's
configuration and execution data.
dce_server_register()
Registers a DCE server by establishing a server's
binding information, registering its services
(represented by interface IDs) with the RPC
runtime, and entering its endpoints in the dced's
endpoint mapper service.
dce_server_sec_begin()
Prepares a server to receive and generate
authenticated RPCs.
dce_server_sec_done()
Releases the resources previously set up by a
call to dce_server_sec_begin().
dce_server_unregister()
Unregisters a DCE server by unregistering a
servers services (interfaces) from the RPC
runtime, and removing the server's endpoints
from the dced's endpoint mapper service.
dce_server_use_protseq()
Registers a protocol sequence to use for the
server.
DATA TYPES AND STRUCTURES
dce_server_handle_t An opaque data structure containing information
the runtime uses to establish the server with DCE.
dce_server_register_data_t
A structure that contains an interface handle
(generated by IDL), a default EPV, and a count
and array of dce_server_type_ts for services that
use RPC object types.
dce_server_type_t A structure containing a manager type UUID and an
RPC entry-point vector (EPV) that specified which
routines implement the IDL interface for the
specific type.
server_t See dced_intro for a complete description of
server_t.
FILES
dce/dced.h
dce/dced_base.idl
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide
5.1 – dce_server_disable_service
NAME
dce_server_disable_service - Disables an individual service of a
server
SYNOPSIS
#include <dce/dced.h>
void dce_server_disable_service( dce_server_handle_t server_handle,
rpc_if_handle_t interface,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle returned by dce_server_register().
interface
Specifies an opaque variable containing information the runtime
uses to access interface specification data.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_disable_service() routine disables an individual
service that a server provides by unregistering the service's
interface from the RPC runtime and marking the server's endpoints
as disabled in the local dced's endpoint mapper service.
For dced to recognize all of a server's services, a server should
register all its application services using the dce_server_register()
routine. If it later becomes necessary for the server to disable an
interface, it can use the dce_server_disable_service() routine rather
than unregistering the entire server.
RELATED INFORMATION
Routines: rpc_intro
dce_server_enable_service
dce_server_register
Books: OSF DCE Application Development Guide
5.2 – dce_server_enable_service
NAME
dce_server_enable_service - Enables an individual service for a
server
SYNOPSIS
#include <dce/dced.h>
void dce_server_enable_service( dce_server_handle_t server_handle,
rpc_if_handle_t interface,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle returned by dce_server_register().
interface
Specifies an opaque variable containing information the runtime
uses to access interface specification data.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The
only status code is error_status_ok.
DESCRIPTION
The dce_server_enable_service() routine enables an individual
service that a server provides by registering the service's
interface with the RPC runtime, and registering the endpoints in
the endpoint map. If the dce_server_c_no_endpoints flag was set
with the dce_server_register() call prior to callibng this routine,
the endpoints are not registered in the endpoint map.
A server commonly registers all its services with DCE at once by
using the dce_server_register() routine. If necessary, a server
can use the dce_server_disable_service() routine to disable
individual services and then reenable them by using
dce_server_enable_service(). However, suppose a server needs its
services registered in a certain order, or it require application-
specific activities between the registration of services. If a
server requires this kind of control as services are registered,
you can set the server->services.list[i].flags field of the
server_t structure to service_c_disabled for individual services
prior to calling dce_server_register(). Then, the server can call
dce_server_enable_service() for each service when needed.
RELATED INFORMATION
Routines: dce_server_disable_service
dce_server_register
Books: OSF DCE Application Development Guide
5.3 – dce_server_inq_attr
NAME
dce_server_inq_attr - Obtains from dced the value of an attribute
known to the server
SYNOPSIS
#include <dce/dced.h>
void dce_server_inq_attr( uuid_t *attribute_uuid,
sec_attr_t *value,
error_status_t *status );
PARAMETERS
Input
attribute_uuid
The UUID dced uses to identify an attribute.
Output
value
Returns the attribute.
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_server_attr_not_found
dced_s_not_started_by_dced
DESCRIPTION
The dce_server_inq_attr() routine obtains an attribute from the
environment created by dced when it started the server. Each
server maintains among other things, a list of attributes that
are used to describe application-specific behavior.
RELATED INFORMATION
Routines: sec_intro
dced_intro
dce_server_inq_uuids
dce_server_inq_server
Books: OSF DCE Application Development Guide
5.4 – dce_server_inq_server
NAME
dce_server_inq_server - Obtains the server configuration data dced
used to start the server
SYNOPSIS
#include <dce/dced.h>
void dce_server_inq_server( server_t **server,
error_status_t *status );
PARAMETERS
Output
server
Returns the structure that describes the server's configuration.
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_not_started_by_dced
dced_s_data_unavailable
DESCRIPTION
The dce_server_inq_server() routine obtains the server configuration
data (srvrconf) maintained by dced and used by dced to start the
server. This routine is commonly called prior to registering the
server to obtain the server data used as input to
dce_server_register().
RELATED INFORMATION
Routines: dced_intro
dce_server_register
Books: OSF DCE Application Development Guide
5.5 – dce_server_inq_uuids
NAME
dce_server_inq_uuids - Obtains the UUIDs that dced associates with
the server's configuration and execution data
SYNOPSIS
#include <dce/dced.h>
void dce_server_inq_uuids( uuid_t *conf_uuid,
uuid_t *exec_uuid,
error_status_t *status );
PARAMETERS
Output
conf_uuid
Returns the UUID that dced uses to identify the server's
configuration data. If a NULL value is input, no value is
returned.
exec_uuid
Returns the UUID that dced uses to identify the executing server.
If a NULL value is input, no value is returned.
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_not_started_by_dced
DESCRIPTION
The dce_server_inq_uuids() routine obtains the UUIDs that dced uses
in its srvrconf and srvrexec services to identify the server's
configuration and execution data. The server can then use dced API
routines to access the data and perform other server management
functions.
RELATED INFORMATION
Routines: dced_intro
dce_server_inq_server
dced_API
Books: OSF DCE Application Development Guide
5.6 – dce_server_register
NAME
dce_server_register - Registers a server with DCE
SYNOPSIS
#include <dce/dced.h>
void dce_server_register( unsigned32 flags,
server_t *server,
dce_server_register_data_t *data,
dce_server_handle_t *server_handle,
error_status_t *status );
PARAMETERS
Input
flags
Specifies options for server registration. Combinations of the
following values may be used:
dce_server_c_no_protseqs
dce_server_c_no_endpoints
dce_server_c_ns_export
server
Specifies the server data, commonly obtained from dced by calling
dce_server_inq_server(). The server_t structure is described in
sec_intro.
data
Specifies the array of data structures that contain the
additional information required for the server to service
requests for specific remote procedures. Each structure of
the array includes:
+ An interface handle (ifhandle) of type rpc_if_handle_t
+ An entry point vector (epv) of type rpc_mgr_epv_t
+ A number (num_types) of type unsigned32 representing the
number in the following array
+ An array of server types (types) of type dce_server_type_t
The dce_server_type_t structure contains a UUID (type) of type uuid_t
representing the object type, and a manager entry point vector (epv)
of type rpc_mgr_epv_t representing the set of procedures implemented
for the object type.
Output
server_handle
Returns a server handle, which is a pointer to an opaque data
structure containing information about the server.
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
rpc_s_no_memory
DESCRIPTION
By default, the dce_server_register() routine registers a DCE server
by establishing a server's binding information for all valid protocol
sequences, registering all the servers services with the RPC runtime,
and entering the server's endpoints in dced's endpoint mapper service.
Prior to calling the dce_server_register() routine, the server
obtains the server configuration data from dced by calling
dce_server_inq_server(). The server must also set up an array of
registration data, where the size of the array represents all the
server's services that are currently registered in the server
configuration data of dced. (server->services.count). If the
memory for the array is dynamically allocated, it must not be freed
until after the corresponding dce_server_unregister() routine is
called.
You can modify the behavior of dce_server_register() Depending on
the values of the flags parameter. If the flag has the value
dce_server_c_ns_export, the the binding information is also exported
to the namespace. The namespace entry is determined for each service
by the server->services.list[i].entryname parameter. If this parameter
has no value, the default value for the entire server is used
(server->entryname). If the flag has the value
dce_server_c_no_endpoints, the binding information is not registered
with the endpoint map. Your application can use rpc_ep_register() to
register specific binding information. If the flag has the value
dce_server_c_no_protseqs, specific protocol sequences are used rather
than all valid protocol sequences. Use of this flag requires that
the server first call dce_server_use_protseq() at least once for a
valid protocol sequence.
RELATED INFORMATION
Routines: dced_intro
dce_server_inq_server
dce_server_unregister
rpc_server_listen
dce_server_sec_begin
Books: OSF DCE Application Development Guide
5.7 – dce_server_sec_begin
NAME
dce_server_sec_begin - Establishes a server to receive fully
authenticated remote procedure calls (RPCs)
and to also act as a client to do authenti-
cated RPCs
SYNOPSIS
#include <dce/dced.h>
void dce_server_sec_begin( unsigned32 flags,
error_status_t *status );
PARAMETERS
Input
flags
Flags are set to manage keys and setup a login context.
Valid values include the following:
dce_server_c_manage_key
dce_server_c_login
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
dced_s_need_one_server_prin
dced_s_not_started_by_dced
dced_s_no_server_keyfile
dced_s_cannot_create_key_mgmt_thr
dced_s_cannot_detach_key_mgmt_thr
DESCRIPTION
The dce_server_sec_begin() routine prepares a server to receive
authenticated RPCs. It also sets up all that is required for the
application, when behaving as a client to other servers, to do
authenticated RPCs as a client. When authentication is required,
this call must preceed all other RPC and DCE server initialization
calls, including dce_server_register(). When your application is
finished listening for RPCs, it should call the dce_server_sec_done()
routine.
RELATED INFORMATION
Routines: dce_server_register
rpc_server_listen
dce_server_sec_done
Books: OSF DCE Application Development Guide
5.8 – dce_server_sec_done
NAME
dce_server_sec_done - Releases resources established for a server
to receive (and when acting as a client, to
send) fully authenticated remote procedure
calls (RPCs)
SYNOPSIS
#include <dce/dced.h>
void dce_server_sec_done( error_status_t *status );
PARAMETERS
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_sec_done() routine releases the resources
previously set up by a call to dce_server_sec_begin(). The
dce_server_sec_begin() routine sets all that is needed for a
server to receive authenticated RPCs and it also sets up all that
is required for the application to do authenticated RPCs as a
client. If this routine is used, it must follow all other server
DCE and RPC initialization and cleanup calls.
RELATED INFORMATION
Routines: dce_server_sec_begin
rpc_server_listen
Books: OSF DCE Application Development Guide
5.9 – dce_server_unregister
NAME
dce_server_unregister - Unregisters a DCE server
SYNOPSIS
#include <dce/dced.h>
void dce_server_unregister( dce_server_handle_t *server_handle,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle returned by dce_server_register().
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_unregister() routine unregisters a DCE server by
unregistering a servers services (interfaces) from the RPC runtime.
When a server has stopped listening for remote procedure calls, it
should call this routine.
The flags set with the corresponding dce_server_register() routine
are part of the server handle's information used to determine what
action to take or not take. These actions include removing the
server's endpoints from the dced's endpoint mapper service and
unexporting binding information from the namespace.
Use the dce_server_disable_service() routine to disable specific
application services rather than unregistering the whole server.
RELATED INFORMATION
Routines: dce_server_register
rpc_server_listen
dce_server_disable_service
Books: OSF DCE Application Development Guide
5.10 – dce_server_use_protseq
NAME
dce_server_use_protseq - Tells DCE to use the specified protocol
sequence for receiving remote procedure
calls
Used by server applications.
SYNOPSIS
#include <dce/dced.h>
void dce_server_use_protseq( dce_server_handle_t server_handle,
unsigned char *protseq,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle. Use the value of NULL.
protseq
Specifies a string identifier for the protocol sequence to
register with the RPC runtime. (For a list of string
identifiers, see the table of valid protocol sequences in the
rpc_intro reference page.)
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_use_protseq() routine registers an individual
protocol sequence with DCE. Typical servers use all valid protocol
sequences, the default behavior for the dce_server_register() call,
and so most servers do not need to call this dce_server_use_protseq()
routine. However, this routine may be called prior to
dce_server_register(), to restrict the protocol sequences used. A
server must register at least one protocol sequence with the RPC
runtime to receive remote procedure call requests. A server can
call this routine multiple times to register additional protocol
sequences.
RELATED INFORMATION
Routines: rpc_intro
dce_server_register
rpc_server_use_protseq
Books: OSF DCE Application Development Guide
6 – dce_svc_intro
NAME
dce_svc_intro - Introduction to the DCE serviceability interface
DESCRIPTION
The routines listed below are intended to be used by servers that
export the serviceability interface defined in service.idl. The
complete list of these remote serviceability implementation calls
is as follows (the remote operation name is given in the left column,
and the corresponding implementation routine is given in the right
column).
dce_svc_set_route dce_svc_routing
dce_svc_set_dbg_route dce_svc_debug_routing
dce_svc_set_dbg_levels dce_svc_debug_set_levels
dce_svc_inq_components dce_svc_components
dce_svc_inq_table dce_svc_table
dce_svc_filter_control dce_svc_filter
dce_svc_inq_stats dce_svc_inq_stats
These routines perform all the necessary processing (except for
checking clients' authorization) that must be done by the application
manager to implement the remote serviceability operations.
Note that most of these routines have little meaning except as
implementations of remote operations. However, the dce_svc_routing(),
dce_svc_filter(), dce_svc_debug_routing() and
dce_svc_debug_set_levels() routines can conceivably be used by
servers as purely local operations (for example, in order to allow
routing and debug levels to be set via command line flags when the
server is invoked).
The dce_svc_log_ routines provide read access to BINFILE format logs
which are created and written by the DCE serviceability routines;
see svcroute for further information. The dce_svc_log_handle_t
typedef is an opaque pointer to a handle for an opened logfile.
Applications that use the serviceability interface can install a
routine that will be effectively "hooked" into the operation of the
interface. If a filter is installed, it will be called whenever one
of the serviceability output routines (dce_svc_printf()) is about to
output a message; whenever this happens, the filter will receive a
group of parameters that describe the message that is about to be
output and the circumstances that provoked the action. The filter can
then allow the message output to proceed, or suppress the message.
Along with the filter routine itself, the application also installs
a filter control routine, whose purpose is to permit the behavior of
the filter to be altered dynamically while the application is running.
The dce_svc_filter() routine is the interface's call-in to such an
installed filter control.
THE DCE SERVICEABILITY ROUTINES
The serviceability routines are as follows, listed in alphabetical
order:
dce_assert() Adds runtime "can't happen" assertions to
programs (such as, programming errors).
dce_svc_components()
Returns an array containing the names of all
components in the program that have been
registered with the dce_svc_register() routine.
dce_svc_debug_routing()
Specifies both the level of an applications's
serviceability debug messaging, and where the
messages are routed.
dce_svc_debug_set_levels()
Sets serviceability debugging message level(s)
for a component.
dce_svc_define_filter()
Lets applications define serviceability filtering
routines.
dce_svc_filter() Controls the behavior of the serviceability
message filtering routine, if one exists.
dce_svc_log_close() Closes an open binary format serviceability log
and releases all internal state associated with
the handle.
dce_svc_log_get() Reads the next entry from a binary format
serviceability log.
dce_svc_log_open() Opens the specified file for reading.
dce_svc_log_rewind()
Rewinds the current reading position of the
specified (by handle) logfile to the first
record.
dce_svc_printf() Provides the normal call for writing or
displaying serviceability messages.
dce_svc_register() Registers a serviceability handle and sub-
component table.
dce_svc_routing() Specifies how normal (non-debug)
serviceability messages are routed.
dce_svc_set_progname()
If not called, the application's generated
serviceability messages will be identified
by its process ID.
dce_svc_table() Returns the serviceability subcomponent table
registered with the specified component.
dce_svc_unregister()
Destroys a serviceability handle, releasing all
allocated resources associated with the handle.
DATA TYPES AND STRUCTURES
dce_svc_filter_proc_t
The prototype of a serviceability filtering
routine.
dce_svc_filterctl_proc_t
The prototype of a serviceability filter-control
routine.
dce_svc_handle_t An opaque handle to generate serviceability
messages. (Use dce_svc_register() or
DCE_DEFINE_SVC_HANDLE to obtain one.)
dce_svc_log_handle_t
An opaque handle to an open serviceability
binary format log file. (Use dce_svc_log_open()
to obtain one.)
dce_svc_log_prolog_t
A structure containing data about a serviceability
binary format log entry.
dce_svc_prolog_t A structure containing the initial message
parameters passed to the filtering routine.
FILES
dce/service.idl
dce/dce_svc.h
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide
6.1 – dce_assert
NAME
dce_assert - Inserts program diagnostics
SYNOPSIS
#define DCE_ASSERT
#include <dce/assert.h>
void dce_assert( dce_svc_handle_t handle,
int expression );
PARAMETERS
Input
handle A registered serviceability handle.
expression
An expression the truth of which is to be tested.
DESCRIPTION
The dce_assert macro is used to add runtime "can't happen"
assertions to programs (that is, programming errors). On
execution, when expression evaluates to 0 (that is, to "false"),
then dce_svc_printf() is called with parameters to generate a
message identifying the expression, source file and line number.
The message is generated with a severity level of svc_c_sev_fatal,
with the svc_c_action_abort flag specified (which will cause the
program to abort when the assertion fails and the message is
generated). See the dce_svc_register reference page for more
information.
The handle parameter should be a registered serviceability handle; it
can also be NULL, in which case an internal serviceability handle will
be used.
Assertion-checking can be enabled or disabled at compile time.
The header file dce/assert.h can be included multiple times.
If DCE_ASSERT is defined before the header is included, assertion
checking is performed. If it is not so defined, then the
assertion-checking code is not compiled in. The system default is
set in dce/dce.h.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_register
6.2 – dce_svc_components
NAME
dce_svc_components - DCE serviceability routine that returns
registered component names
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
void dce_svc_components( dce_svc_stringarray_t *table,
error_status_t *status );
PARAMETERS
Output
table An array containing the names of all components that have been
registered with the dce_svc_register() routine.
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_svc_components routine returns an array containing the names
of all components in the program that have been registered with the
dce_svc_register() routine.
EXAMPLES
The following code fragment shows how the dce_svc_components()
routine should be used in a DCE application's implementation of the
serviceability remote interface. The function defined below is the
implementation of the app_svc_inq_components operation defined in the
application's serviceability .epv file. Clients call this function
remotely, and the function, when called, first checks the caller's
authorization and then (if the client is authorized to perform the
operation) calls the dce_svc_components() routine to perform the
actual operation.
/*****
*
* app_svc_inq_components -- remote request for list of all
* components registered by
* dce_svc_register().
*
*****/
static void
app_svc_inq_components( handle_t h,
dce_svc_stringarray_t *table,
error_status_t *st )
{
int ret;
/* Check the client's permissions here; if they are insufficient, */
/* deny the request. Otherwise, proceed with the operation... */
dce_svc_components(table, st);
}
ERROR CODES
See dce_svc_register.
FILES
dce/service.idl
6.3 – dce_svc_debug_routing
NAME
dce_svc_debug_routing - Specifies how debugging messages are routed
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
void dce_svc_debug_routing( unsigned char *where,
error_status_t *status );
PARAMETERS
Input
where A four-field routing string, the format of which is described
in svcroute.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_svc_debug_routing() routine specifies both the level of an
applications's serviceability debug messaging, and where the messages
are routed. The where parameter is a four-field routing string, as
described in svcroute. All four fields are required.
The routine is used to specify the disposition of serviceability
debug messages. If called before the component is registered (with
dce_svc_register()), the disposition is stored until it is needed.
In case of error, the status parameter is filled in with an error
code.
To set only the debugging level for a component, use the
dce_svc_debug_set_levels() routine.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_debug_set_levels.
Files: svcroute
6.4 – dce_svc_debug_set_levels
NAME
dce_svc_debug_set_levels - Sets the debugging level for a component
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
void dce_svc_debug_set_levels( unsigned char *where,
error_status_t *status );
PARAMETERS
Input
where A multi-field string consisting of the component name separated
by a colon from a comma-separated list of subcomponent/level
pairs, as described in svcroute.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_svc_debug_set_levels() routine sets serviceability debugging
message level(s) for a component. The where parameter is a multi-field
string consisting of the component name separated by a colon from a
comma-separated list of subcomponent/level pairs, as described in
svcroute. The subcomponents are specified by codes defined in the
component's sams file; the levels are specified by single digits (1
through 9).
If the routine is called before the component is registered (with
dce_svc_register()), the disposition is stored until it is needed.
In case of error, the status parameter is filled in with an error
code.
To set both the debug level and routing for a component, use the
dce_svc_debug_routing() routine.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_debug_routing
Files: svcroute
6.5 – dce_svc_define_filter
NAME
dce_svc_define_filter - DCE serviceability filtering routines
SYNOPSIS
#include <stdarg.h>
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svcfilter.h>
void dce_svc_define_filter(
dce_svc_handle_t handle,
dce_svc_filter_proc_t filter_function,
dce_svc_filterctl_proc_t filter_ctl_function,
error_status_t *status );
DESCRIPTION
The serviceability interface provides a hook'' into the message-output
mechanism that allows applications to decide at the time of messaging
whether the given message should be output or not. The application
defines its own routine to perform whatever checking is desired, and
installs the routine (the filter_function parameter) with a call to
dce_svc_define_filter().
The filter routine to be installed must have the signature defined
by the dce_svc_filter_proc_t typedef. Once installed, the routine
will be automatically invoked every time a serviceability routine is
called to output a message. The filter receives a prolog argument
which contains all the pertinent information about the message. If
the filter returns TRUE, the message is output per the original
serviceability call. If the filter returns FALSE, the message is
not output. The information in the prolog allows such decisions to
be made on the basis of severity level, subcomponent, message index,
and so on. For details, see the header file dce/svcfilter.h.
In addition, an application that installs a message-filtering
routine must also define a routine that can be called remotely
to alter the operation of the filter routine. This procedure must
have the signature defined by the dce_svc_filterctl_proc_t typedef.
The routine will be invoked with an opaque byte array parameter
(and its length), which it is free to interpret in an appropriate
manner. The remote-control routine is installed by the same call to
dce_svc_define_filter() (as the filter_ctl_function parameter) in
which the filter itself is installed. See dce_svc_filter.
EXAMPLES
The following code fragment consists of example versions of an
application's routines to: filter serviceability messages; alter the
behavior of the filter routine; install the two routines.
/*****
* Filter routine-- this is the routine that's hooked into the
* serviceability mechanism when you install it by
* calling dce_svc_define_filter().
*****/
boolean app_filter(prolog, args)
dce_svc_prolog_t prolog;
va_list args;
{
if (filter_setting) {
printf("The value of filter_setting is TRUE\n");
printf("The progname is %s\n", prolog->progname);
if (prolog->attributes & svc_c_sev_notice)
printf("This is a Notice-type message\n");
switch (prolog->table_index) {
case app_s_server:
printf("Server sub-component\n");
break;
case app_s_refmon:
printf("Refmon sub-component\n");
break;
case app_s_manager:
printf("Manager sub-component\n");
break;
}
}
return 1;
}
/*****
* Filter Control routine-- this is the entry point for the remote-
* control call to modify the filter
* routine's behavior.
*****/
void app_filter_control(arg_size, arg, status)
idl_long_int arg_size;
idl_byte *arg;
error_status_t *status;
{
if (strncmp(arg, "Toggle", arg_size) != 0)
return;
else {
filter_setting = (filter_setting == FALSE) ? TRUE : FALSE;
if (filter_setting)
printf(" FILTER IS TURNED ON\n");
else
printf(" FILTER IS TURNED OFF\n");
}
return;
}
/*****
* install_filters-- calls dce_svc_define_filter() to install the
* above 2 routines.
*****/
void install_filters()
{
unsigned32 status;
filter_setting = TRUE;
dce_svc_define_filter(app_svc_handle, app_filter,
dce_svc_filterctl_proc_t)app_filter_control, &status);
}
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_register
DCE_SVC_DEFINE_HANDLE
6.6 – dce_svc_filter
NAME
dce_svc_filter - Controls behavior of serviceability filter
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
void dce_svc_filter( dce_svc_string_t component,
idl_long_int arg_size,
idl_byte *argument,
error_status_t *status );
PARAMETERS
Input
component
The name of the serviceability-registered component, defined
in the component field of the sams file.
arg_size
The number of characters contained in argument.
argument
A string value to be interpreted by the target component's
filter control routine.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_svc_filter() routine controls the behavior of the
serviceability message filtering routine, if one exists.
Along with the filter routine itself, the application also installs
a filter control routine, whose purpose is to permit the behavior of
the filter to be altered dynamically while the application is running.
The dce_svc_filter() routine is the interface's call-in to such an
installed filter control.
If an application has installed a serviceability filtering routine,
and if filter remote control is desired, the application's filter
routine (installed by the call to dce_svc_define_filter()) should be
coded so that its operation can be switched to the various desired
alternatives by the values of static variables to which it has
access. These variables should also be accessible to the filter
control routine. The filter control routine thus receives from
dce_svc_filter() an argument string (which it uses to set the
variables), the meaning of whose contents are entirely application-
defined.
ERROR CODES
See dce_svc_register.
FILES
dce/service.idl
6.7 – dce_svc_log_close
NAME
dce_svc_log_close - Closes an open logfile
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
void dce_svc_log_close( dce_svc_log_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle The handle (returned by dce_svc_log_open()) of the logfile
to be closed.
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
DESCRIPTION
The dce_svc_log_close() routine closes an open binary format
serviceability log and releases all internal state associated
with the handle.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_log_get
dce_svc_log_open
dce_svc_log_rewind
6.8 – dce_svc_log_get
NAME
dce_svc_log_get - Reads the next record from a binary logfile
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
void dce_svc_log_get( dce_svc_log_handle_t handle,
dce_svc_log_prolog_t *prolog,
error_status_t *status );
PARAMETERS
Input
handle The handle (returned by dce_svc_log_open()) of the logfile
to be read.
Output
prolog A pointer to a structure containing information read from
the logfile record.
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
DESCRIPTION
The dce_svc_log_get() routine reads the next entry from a binary
format serviceability log, and fills in prolog with a pointer to a
private data area containing the data read. The contents of the
prolog structure are defined in dce/svclog.h.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_log_close
dce_svc_log_open
dce_svc_log_rewind
6.9 – dce_svc_log_open
NAME
dce_svc_log_open - Opens binary log file
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
void dce_svc_log_open( const char *name,
dce_svc_log_handle_t *handle,
error_status_t *status );
PARAMETERS
Input
name The pathname of the logfile to be opened.
Output
handle A filled-in handle to the opened logfile specified by name.
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
DESCRIPTION
The dce_svc_log_open() routine opens the binary log file specified
by name for reading. If the call is successful, handle is filled in
with a handle to be used with the other dce_svc_log_ calls. On
error, status will contain an error code.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_log_close
dce_svc_log_get
dce_svc_log_rewind
6.10 – dce_svc_log_rewind
NAME
dce_svc_log_rewind - Rewinds binary logfile to first record
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
void dce_svc_log_rewind( dce_svc_log_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle The handle (returned by dce_svc_log_open()) of the
logfile to be rewound.
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
DESCRIPTION
The dce_svc_log_rewind() routine rewinds the current reading
position of the specified (by handle) binary logfile to the
first record.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_log_close
dce_svc_log_get
dce_svc_log_open
6.11 – dce_svc_printf
NAME
dce_svc_printf - Generates a serviceability message
SYNOPSIS
#include <dce/dce.h>
void dce_svc_printf(
DCE_SVC(dce_svc_handle_t handle, char * argtypes),
const unsigned32 table_index,
const unsigned32 attributes,
const unsigned32 messageID,
. . . );
PARAMETERS
Input
handle The caller's serviceability handle.
argtypes
Format string for the message.
table_index
The message's sub-component name (defined in the sams file).
attributes
Any routing, severity, action, or debug attributes that are
to associated with the generated message, OR'd together.
messageID
The message ID, defined in the message's code field in the
sams file.
. . . Any format arguments for the message string.
DESCRIPTION
The dce_svc_printf() routine is the normal call for writing or
displaying serviceability messages. It cannot be called with a
literal text argument. Instead, the message text is retrieved
from a message catalog or an in-core message table. These are
generated by the sams utility, which in turn outputs sets of tables
from which the messages are extracted for output.
There are two main ways in which to call the routine. If a message
has been defined in the sams file with both sub-component and
attributes specified, then the sams output will include a
"convenience macro" for the message that can be passed as the single
argument to dce_svc_printf(), for example:
dce_svc_printf(SIGN_ON_MSG);
The convenience macro's name will be generated from the uppercase
version of the message's code value (as specified in the sams file),
with the string _MSG appended.
If a convenience macro is not generated, or if you want to override
some of the message's attributes at the time of output, then you must
call the routine in its long form. An example of this form of the call
looks as follows:
dce_svc_printf(DCE_SVC(app_svc_handle, ""), app_subcomponent,
svc_c_sev_error | svc_c_route_stderr, messageID);
DCE_SVC() is a macro that must be passed as the first argument to
dce_svc_printf() if a convenience macro is not being used. It takes
two arguments:
+ The caller's serviceability handle
+ A format string for the message that is to be output
The format string is for use with messages that have been coded with
argument specifiers. It is a character string consisting of the
argument types as they would be passed to a printf call. If the
message is to be routed to a binary file, the format is extended to
include a %b specifier; using %b in a different routing will give
unpredictable results. The %b specifier takes two arguments: an
integer size, and a buffer pointer.
The remaining arguments passed to dce_svc_printf() are as follows:
+ subcomponent table index
This symbol is declared in the sub-component list coded in
Part II of the sams file; its value is used to index into the
subtable of messages in which the desired message is located.
+ message attribute(s)
This argument consists of one or more attributes to be applied
to the message that is to be printed. Note that you must
specify at least one severity here. Multiple attributes are
OR'd together, as shown in the following example.
There are four categories of message attributes:
Routing The available routing attribute constants are:
- svc_c_route_stderr
- svc_c_route_nolog
However, most routing is done either by passing
specially-formatted strings to dce_svc_routing() or
by environment variable values. Note that using
svc_c_route_nolog without using svc_c_route_stderr
will result in no message being generated.
Severity The available severity attribute constants are:
- svc_c_sev_fatal
- svc_c_sev_error
- svc_c_sev_warning
- svc_c_sev_notice
- svc_c_sev_notice_verbose
Action The available message action attribute constants are:
- svc_c_action_abort
- svc_c_action_exit_bad
- svc_c_action_exit_ok
- svc_c_action_brief
- svc_c_action_none
Note that svc_c_action_brief is used to suppress
the standard prolog.
Debug Level
Nine different debug levels can be specified
(svc_c_debug1...svc_c_debug9 or svc_c_debug_off).
+ message ID
This argument consists of the message's code, as declared in
the sams file.
ERROR CODES
This routine has no return value.
RELATED INFORMATION
Functions: dce_svc_register
DCE_SVC_DEFINE_HANDLE
6.12 – dce_svc_register
NAME
dce_svc_register - Registers a serviceability message table
SYNOPSIS
#include <dce/dce.h>
dce_svc_handle_t dce_svc_register( dce_svc_subcomp_t *table,
const idl_char *component_name,
error_status_t *status );
PARAMETERS
Input
table A message table structure (defined in a header file generated
by sams during compilation).
component_name
The serviceability name of the component, defined in the
component field of the sams file.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_svc_register() routine registers a serviceability message
table. An application must call either it (or the
DCE_SVC_DEFINE_HANDLE() macro) in order to set up its table(s) and
obtain the serviceability handle it must have in order to use the
serviceability interface.
Two parameters are required for the call: table is a pointer to
the application's serviceability table, defined in a file called
dceappsvc.h generated by the sams utility. component_name is a
string whose value is app, which is defined in the component field
of the sams file in which the serviceability messages are defined.
On error, this routine returns NULL and fills in status with an
error code.
ERROR CODES
The following serviceability status codes are defined:
svc_s_assertion_failed
A programmer-developed compile-time assertion failed.
svc_s_at_end
No more data is available.
svc_s_bad_routespec
See svcroute for information on routing specification
format.
svc_s_cantopen
Permission denied or file does not exist; consult errno.
svc_s_no_filter
Attempted to send data to the filter-control handle for
a component that does not have a filter registered.
svc_s_no_memory
Could not allocate memory for message table, string copy
or other internal requirement.
svc_s_no_stats
The definition of the return value has not been specified.
svc_s_ok Operation performed.
svc_s_unknown_component
Could not find the service handle for a component.
RELATED INFORMATION
Functions: dce_svc_debug_routing
dce_svc_debug_set_levels
dce_svc_define_filter
dce_svc_routing
dce_svc_unregister
6.13 – dce_svc_routing
NAME
dce_svc_routing - Specifies routing of serviceability messages
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
void dce_svc_routing( unsigned char *where,
error_status_t *status );
PARAMETERS
Input
where A three-field routing string, as described in svcroute.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_svc_routing() routine specifies how normal (non-debug)
serviceability messages are routed. The where parameter is a three-
field routing string, as described in svcroute. For convenience,
the first field of the routing specifier (which indicates the message
severity type to which the routing is to be applied) may be an *
(asterisk) to indicate that all messages, whatever their severity,
should be routed as specified.
If the routine is called before the component is registered (with
the dce_svc_register() routine), the routing is stored until it is
needed. In case of error, the status parameter is filled in with an
error code.
ERROR CODES
See dce_svc_register.
FILES
dce/service.idl
6.14 – dce_svc_set_progname
NAME
dce_svc_set_progname - Sets an application's program name
SYNOPSIS
#include <dce/dce.h>
void dce_svc_set_progname( char *program_name,
error_status_t *status );
PARAMETERS
Input
program_name
A string containing the name that is to be included in the
text of all serviceability messages that the application
generates during the session.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
This function sets the application's program name, which is included
in serviceability messages. This allows serviceability messages
from more than one application to be written to the same file and
still be distinguishable as to their separate origins.
If dce_svc_set_progname() is not called, the application's generated
serviceability messages will be identified by its process ID.
EXAMPLES
Suppose an application sets its program name to be "demo_program",
as shown:
dce_svc_set_progname("demo_program", &status);
Serviceability messages generated by the program will as a result
look like the following:
1994-04-05-20:13:34.500+00:00I----- demo_program NOTICE app
main.c 123 0xa444e208
message text
If the application does not set its program name, its generated
serviceability messages will have the following form:
1994-04-05-20:13:34.500+00:00I----- PID#9467 NOTICE app main.c
123 0xa444e208
message text
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_printf
dce_svc_printf
DCE_SVC_DEBUG
6.15 – dce_svc_table
NAME
dce_svc_table - Returns a registered component's subcomponent table
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
void dce_svc_table( dce_svc_string_t component,
dce_svc_subcomparray_t *table,
error_status_t *status );
PARAMETERS
Input
component
The name of the serviceability-registered component, defined
in the component field of the application's sams file.
Output
table An array of elements, each of which describes one of the
component's serviceability sub-components (as defined in its
sams file).
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_svc_table routine returns the serviceability subcomponent
table registered with the specified component. The returned table
consists of an array of elements, each of which describes one sub-
component. Each element consists of four fields, which contain the
sub-component name, its description, its message catalog ID, and the
current value of its debug message level. The first three of these
values are specified in the sams file which is processed during the
application's compilation, and from which the application's message
catalogs and other serviceability and message files are generated.
EXAMPLES
The following code fragment shows how the remote operation might be
called from an application's client side, and how the results might
be printed out:
#include <dce/rpc.h>
#include <dce/service.h>
handle_t svc_bind_handle;
dce_svc_string_t component;
dce_svc_subcomparray_t subcomponents_table;
error_status_t remote_status;
int i;
dce_svc_inq_table( svc_bind_handle,
component,
&subcomponents_table,
&remote_status );
fprintf(stdout, "Subcomponent table size received is: %d...\n",
subcomponents_table.tab_size);
fprintf(stdout, "Subcomponent table contents are:\n");
for (i = 0; i < subcomponents_table.tab_size; i++)
{
fprintf(stdout, "Name: %s\n",
subcomponents_table.table[i].sc_name);
fprintf(stdout, "Desc: %s\n",
subcomponents_table.table[i].sc_descr);
fprintf(stdout, "Msg Cat ID: 0x%8.8lx\n",
(long) subcomponents_table.table[i].sc_descr_msgid);
fprintf(stdout, "Active debug level: %d\n\n",
subcomponents_table.table[i].sc_level);
}
ERROR CODES
See dce_svc_register.
FILES
dce/service.idl
6.16 – dce_svc_unregister
NAME
dce_svc_unregister - Destroys a serviceability handle
SYNOPSIS
#include <dce/dce.h>
void dce_svc_unregister( dce_svc_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle The application's serviceability handle, originally
returned by a call to dce_svc_register(), or filled in
by the DCE_SVC_DEFINE_HANDLE() macro
Output
status Returns the status code from this operation. The status
code is a value that indicates whether the routine
completed successfully and if not, why not.
DESCRIPTION
The dce_svc_unregister() routine destroys a serviceability handle.
Calling it closes any open serviceability message routes and frees
all allocated resources associated with the handle.
The handle parameter is the serviceability handle that was originally
returned by the call to dce_svc_register(), or filled in by the
DCE_SVC_DEFINE_HANDLE() macro. On error, the routine fills in status
with an error code.
Note that it is not usually necessary to call this routine, since
the normal process exit will perform the required cleanup.
ERROR CODES
See dce_svc_register.
RELATED INFORMATION
Functions: dce_svc_register
7 – dce_svc_macros
NAME
DCE_SVC_INTRO - Introduction to the DCE serviceability macros
DESCRIPTION
The DCE_SVC_DEFINE_HANDLE macro is used to create a serviceability
handle. This can be useful in a library that has no explicit
initialization routine in which a call to dce_svc_register() could
be added. The remaining macros can be "compiled out" of production
code, or left in to aid diagnostics, depending on whether or not
DCE_DEBUG (normally found in dce/dce.h) is defined.
The DCE Serviceability Macros
The serviceability macros are as follows, listed in alphabetical order:
DCE_SVC_DEBUG() Used to generate debugging output.
DCE_SVC_DEBUG_ATLEAST()
Can be used to test the debug level of a
subcomponent for a specified handle. Tests
whether the debug level is at least at the
specified level.
DCE_SVC_DEBUG_IS() Can be used to test the debug level of a
subcomponent for a specified handle. Tests
for an exact match with the specified level.
DCE_SVC_DEFINE_HANDLE()
Registers a serviceability message table.
DCE_SVC_LOG() Generates debugging output based on a message
defined in an application's sams file.
FILES
dce/service.idl
dce/dce_svc.h
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide
7.1 – DCE_SVC_DEBUG
NAME
DCE_SVC_DEBUG - Macro to output a serviceability debug message
SYNOPSIS
#include <dce/dce.h>
DCE_SVC_DEBUG( ( dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level,
char * format,
..) );
PARAMETERS
Input
handle The caller's serviceability handle.
table_index
The message's sub-component name (defined in the sams file).
debug_level
Serviceability debug level for the message.
format The message string.
. . . Format arguments, if any.
DESCRIPTION
The DCE_SVC_DEBUG macro is used to generate debugging output.
Because it is a macro that takes a variable number of arguments,
the entire parameter list must be enclosed in two sets of
parentheses. The handle and table_index parameters are as
described for dce_svc_printf().
In contrast to the normal operation of the serviceability interface,
DCE_SVC_DEBUG requires the caller to specify the message as a string
literal in the call, rather than by defining it in the application's
sams file specifying the message by a message ID.
The debug_level argument indicates the level of detail associated with
this message and must be in the range svc_c_debug1 to svc_c_debug9.
Thus the value of debug_level associates the message with one of
nine "levels", and whether or not the message is actually generated
at run time will depend on what debugging level has been set for the
application. The level can be set by the application itself (by a
call to dce_svc_debug_set_levels() or dce_svc_debug_routing()) or by
the value of an environment variable or a serviceability routing file;
see svcroute for further information.
The significance of the various levels is application-defined, but
in general the higher levels (numbers) imply more detail in debugging
output.
The format and . . . parameters are passed directly to fprintf()
or its equivalent.
RELATED INFORMATION
Functions: dce_svc_debug_routing
dce_svc_debug_set_levels
dce_svc_printf
dce_svc_routing
Files: svcroute
7.2 – DCE_SVC_DEBUG_ATLEAST
NAME
DCE_SVC_DEBUG_ATLEAST - Macro to test a component's serviceability
debug level
SYNOPSIS
#include <dce/dce.h>
DCE_SVC_DEBUG_ATLEAST( dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level );
PARAMETERS
Input
handle The caller's serviceability handle.
table_index
The sub-component name (defined in the sams file) whose
debug level is being tested.
debug_level
Debug level being tested.
DESCRIPTION
If serviceability debug code was enabled (by defining DCE_DEBUG)
during compilation, the DCE_SVC_DEBUG_ATLEAST and DCE_SVC_DEBUG_IS
macros can be used to test the debug level of a subcomponent
(specified by table_index) for the specified handle.
DCE_SVC_DEBUG_ATLEAST tests whether the debug level is at least at
the specified level. DCE_SVC_DEBUG_IS tests for an exact match with
the specified level. In either case, the specified level should be
a number between 1 and 9.
RELATED INFORMATION
Functions: DCE_SVC_DEBUG
DCE_SVC_DEBUG_IS
DCE_SVC_LOG
7.3 – DCE_SVC_DEBUG_IS
NAME
DCE_SVC_DEBUG_IS - Macro to test a component's serviceability debug
level
SYNOPSIS
#include <dce/dce.h>
DCE_SVC_DEBUG_IS( dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level );
PARAMETERS
Input
handle The caller's serviceability handle.
table_index
The name of the sub-component name (defined in the sams
file) whose debug level is to be tested.
debug_level
The serviceability debug level being tested.
DESCRIPTION
If serviceability debug code was enabled (by defining DCE_DEBUG)
during compilation, the DCE_SVC_DEBUG_ATLEAST and DCE_SVC_DEBUG_IS
macros can be used to test the debug level of a subcomponent
(specified by table_index) for the specified handle.
DCE_SVC_DEBUG_ATLEAST tests whether the debug level is at least at
the specified level. DCE_SVC_DEBUG_IS tests for an exact match with
the specified level. In either case, the specified level should be
a number between 1 and 9.
RELATED INFORMATION
Functions: DCE_SVC_DEBUG
DCE_SVC_DEBUG_ATLEAST
DCE_SVC_LOG
7.4 – DCE_SVC_DEFINE_HANDLE
NAME
DCE_SVC_DEFINE_HANDLE - Macro to create a serviceability handle
SYNOPSIS
#include <dce/dce.h>
DCE_SVC_DEFINE_HANDLE( dce_svc_handle_t handle,
dce_svc_subcomp_t *table,
const idl_char *component_name );
PARAMETERS
Input
table A message table structure (defined in a header file
generated by sams during compilation).
component_name
The serviceability name of the component, defined in
the component field of the sams file.
Output
handle A serviceability handle structure which will be filled
in by the macro.
DESCRIPTION
There are two ways to register a serviceability table preparatory to
using the serviceability interface in an application. The first is to
create a global variable using the DCE_SVC_DEFINE_HANDLE macro. The
first parameter is the serviceability handle, the second is a pointer
to the component's message table, and the third is the name of the
serviceability component (application). The macro creates a skeleton
variable that will be completed the first time the handle is used.
This can be useful when writing library code that has no explicit
initialization routine.
The second method is to call the dce_svc_register() routine.
RELATED INFORMATION
Functions: dce_svc_register
7.5 – DCE_SVC_LOG
NAME
DCE_SVC_LOG - Macro to output a binary form of a serviceability
debug message
SYNOPSIS
#include <dce/dce.h>
DCE_SVC_LOG( ( dce_svc_handle_t handle,
const unsigned32 table_index,
unsigned32 debug_level,
const unsigned32 messageid,
char * format,
. . .) );
PARAMETERS
Input
handle The caller's serviceability handle.
table_index
The message's sub-component name (defined in the sams file).
debug_level
Serviceability debug level for the message.
messageid
A message ID, defined in the message's code field in
the sams file.
format A message format specifier string (used if messageid
cannot be found).
. . . Any format arguments for the message string.
DESCRIPTION
The DCE_SVC_LOG macro is used to generate debugging output based on
a message defined in an application's sams file (in this respect it
is unlike DCE_SVC_DEBUG, in which the message is specified as a
literal string parameter). Because it is a macro that takes a
variable number of arguments, the entire parameter list must be
enclosed in two sets of parentheses. The handle and table_index
parameters are as described for dce_svc_printf().
The message can be specified in either one of two ways: by messageid,
identifying a message defined in the normal way in the application's
sams file; or as a string literal paramater (format). The format
string is used only if the specified messageid cannot be found.
DCE_SVC_LOG generates a record in the serviceability binary format,
not a conventional serviceability message as such. The complete
message text is not normally written; instead, only the message ID
(the messageid specified in the macro parameter), and its format
arguments (if any) are written. When the binary log is read (see
svcdumplog), the text of the message is reconstructed from the
application's installed message catalog. However, if the original
message was generated from the format argument, then the entire
message text is written to the binary record.
The debug_level argument indicates the level of detail associated
with the message and must be in the range svc_c_debug1 to
svc_c_debug9.
Thus the value of debug_level associates the message with one of nine
"levels", and whether or not the message is actually generated at run
time will depend on what debugging level has been set for the
application. The level can be set by the application itself (by a
call to dce_svc_debug_set_levels() or dce_svc_debug_routing()) or by
the value of an environment variable or a serviceability routing file;
see svcroute for further information.
The significance of the various levels is application-defined, but
in general the higher levels (numbers) imply more detail in debugging
output.
RELATED INFORMATION
Functions: DCE_SVC_DEBUG
DCE_SVC_DEBUG_ATLEAST
DCE_SVC_DEBUG_IS
8 – dced_intro
NAME
dced_intro - Introduction to the DCE Host daemon routines
DESCRIPTION
This introduces the DCE Host Daemon application programming interface:
the dced API. This API gives management applications remote access to
various data, servers, and services on DCE hosts. Servers manage their
own configuration in the local dced by using the routines starting with
dce_server, introduced in the dce_server_intro reference page.
THE DCED API NAMING CONVENTIONS
All of the dced API routine names begin with the dced_ prefix. This
API contains some specialized routines that operate on services
represented by the following keywords in the routine names:
hostdata The host data management service stores host-specific data
such as the host name, the host's cell name, and other data,
and it provides access to these data items.
server The server control service configures, starts, and stops
servers, among other things. Applications must distinguish
two general states of server control: server configuration
(srvrconf) and server execution (srvrexec).
secval The security validation service maintains a host's principal
identity and ensures applications that the DCE Security
daemon is genuine.
keytab The key table management service remotely manages key tables.
The dced also provides the endpoint mapper service which has
its own API, described with the RPC API. These routines
begin with rpc_ep and rpc_mgmt_ep.
Since some of the dced daemon's services require the same operations
(but on different data types), the dced API also contains generic
routines that may operate on more than one of the above services.
For example, you use the routine dced_object_read() to read a data
item (object) from the hostdata, srvrconf, srvrexec, or keytab services.
FILES
dce/dced_base.h
dce/dced.h
dce/dced_data.h
dce/rpctypes.idl
dce/passwd.idl
dce/sec_attr_base.idl
RELATED INFORMATION
ROUTINES: dced_* API.
BOOKS: OSF DCE Application Development Guide
8.1 – Dced Binding Routines
A binding must be established to a dced service on a particular host
before you can use any other dced routines. The resources of the
dced binding should also be released when an application is finished
with the service.
dced_binding_create Establishes a dced binding to a host service
dced_binding_from_rpc_binding
Establishes a dced binding to a dced service on
the host specified in an already-established RPC
binding handle to any server
dced_binding_set_auth_info
Sets authentication, authorization, and
protection level information for a dced binding
handle
dced_binding_free Releases the resources of a dced binding handle
8.1.1 – dced_binding_create
NAME
dced_binding_create - Establishes a dced binding to one of the
host services of a remote (or the local) dced.
SYNOPSIS
#include <dce/dced.h>
void dced_binding_create( dced_string_t service,
unsigned32 binding_flags,
dced_binding_handle_t *dced_bh,
error_status_t *status );
PARAMETERS
Input
service
A character string that specifies a host daemon service name
and an optional remote host. A service name is specified with
one of the following: hostdata, srvrconf, srvrexec, secval, or
keytab. The format of a complete service and host specification
is one of the following:
service_name
A service at the local host. Pre-existing defined
values include:
dced_c_service_hostdata
dced_c_service_srvrconf
dced_c_service_srvrexec
dced_c_service_secval
dced_c_service_keytab
service_name@hosts/host_name
A service at a host anywhere in the local namespace.
/.:/hosts/host_name/config/service_name
A complete specification for service_name@host, where
the host is anywhere in the local namespace.
/.../cell/hosts/host_name/config/service_name
A service at a host anywhere in the global namespace.
binding_flags
Currently, the only valid flag value is
dced_c_binding_syntax_default.
Output
dced_bh
Returns a dced binding handle which is a pointer to an opaque
data structure containing information about an RPC binding, the
host, the host service, and a local cache.
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
dce_cf_e_no_mem
dced_s_invalid_arg
dced_s_no_memory
dced_s_unknown_service
rpc_s_entry_not_found
rpc_s_incomplete_name
rpc_s_invalid_object
rpc_s_name_service_unavailable
rpc_s_no_memory
rpc_s_no_more_bindings
rpc_s_no_ns_permission
DESCRIPTION
The dced on each DCE host maintains the host services and provides
a remote interface to them. The host services include the
following:
+ Endpoint Mapper
+ Host Data Management (hostdata)
+ Server Management: Including Server Configuration (srvrconf)
and Server Execution (srvrexec)
+ Security Validation (secval)
+ Key Table Management (keytab)
The dced_binding_create() routine establishes a dced binding to a
dced service and it (or dced_binding_from_rpc_binding()) must be the
first dced API routine called before an application can access one
of the host services with other dced API routines. When an
application is finished with the service, it should call the
dced_binding_free() routine to free resources. To establish a dced
binding to your local host's dced, you can use the service name by
itself, and do not need to specify a host.
To access the endpoint map directly, use rpc_mgmt_ep_elt_inq_begin()
and associated routines.
EXAMPLES
This example establishes a dced binding to the server configuration
service on the host patrick.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create("srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status);
.
. /* Other routines including dced API routines. */
.
dced_binding_free(dced_bh, &status);
RELATED INFORMATION
Routines: dced_binding_free
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.1.2 – dced_binding_from_rpc_binding
NAME
dced_binding_from_rpc_binding - Establishes a dced binding to one
of the host services on the host
specified in an existing RPC binding
handle.
SYNOPSIS
#include <dce/dced.h>
void dced_binding_from_rpc_binding( dced_service_type_t service,
handle_t rpc_bh,
dced_binding_handle_t *dced_bh,
error_status_t *status );
PARAMETERS
Input
service
A variable that specifies one of the host services. A valid
variable name includes one of the following:
dced_e_service_type_hostdata
dced_e_service_type_srvrconf
dced_e_service_type_srvrexec
dced_e_service_type_secval
dced_e_service_type_keytab
rpc_bh
An RPC binding handle to some server.
Output
dced_bh
Returns a dced binding handle which is a pointer to an opaque
data structure containing information about an RPC binding, the
host, the host service, and a local cache.
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_memory
dced_s_unknown_service
ept_s_cant_perform_op
ept_s_database_invalid
ept_s_invalid_context
ept_s_invalid_entry
rpc_s_comm_failure
rpc_s_fault_context_mismatch
rpc_s_invalid_arg
rpc_s_invalid_binding
rpc_s_no_more_elements
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced on each DCE host maintains the host services and provides
a remote interface to the services. The
dced_binding_from_rpc_binding() routine establishes a dced binding
to a dced service, and it (or dced_binding_create()) must be the
first dced API routine called before an application can access one
of the host services with other dced routines. When an application
is finished with the service, it should call the dced_binding_free()
routine to free resources.
Prior to using the RPC binding in this routine, make a copy of the
binding by using the rpc_binding_copy() routine. This is necessary
if the application needs to continue using the RPC binding because
otherwise the dced binding takes over the RPC binding.
The RPC binding may be obtained from a call to specific RPC
runtime routines such as rpc_binding_from_string_binding,
rpc_ns_binding_import_next, or rpc_ns_binding_lookup_next.
EXAMPLES
This example obtains an RPC binding from a string binding,
and it later makes a copy of the RPC binding for use in the
dced_binding_from_rpc_binding() call.
handle_t rpc_bh, binding_handle;
dced_binding_handle_t dced_bh;
dced_service_type_t service_type;
error_status_t status;
unsigned_char_t string_binding[STRINGLEN];
.
.
.
rpc_binding_from_string_binding( string_binding,
&binding_handle,
&status );
.
.
.
rpc_binding_copy( binding_handle, &rpc_bh, &status );
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
.
. /* Other routines including dced API routines. */
.
dced_binding_free(dced_bh, &status);
RELATED INFORMATION
Routines: dced_binding_free
dced_binding_create
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_binding_from_string_binding
rpc_binding_copy
Books: OSF DCE Application Development Guide.
8.1.3 – dced_binding_set_auth_info
NAME
dced_binding_set_auth_info - Sets authentication and authorization
information for a dced binding handle
SYNOPSIS
#include <dce/dced.h>
void dced_binding_set_auth_info(
dced_binding_handle_t dced_bh,
unsigned32 protect_level,
unsigned32 authn_service,
rpc_auth_identity_handle_t authn_identity,
unsigned32 authz_service,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for which to set the
authentication and authorization information.
protect_level
Specifies the protection level for dced API calls that will
use the dced binding handle dced_bh.
authn_service
Specifies the authentication service to use for dced API calls
that will use the dced binding handle dced_bh.
authn_identity
Specifies a handle for the data structure that contains the
calling application's authentication and authorization
credentials appropriate for the selected authn_service and
authz_service services. Specify NULL to use the default
security login context for the current address space.
authz_service
Specifies the authorization service to be implemented by dced
for the host service accessed.
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
dced_s_bad_binding
dced_s_no_support
ept_s_not_registered
rpc_s_authn_authz_mismatch
rpc_s_binding_incomplete
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_mgmt_op_disallowed
rpc_s_rpcd_comm_failure
rpc_s_unknown_authn_service
rpc_s_unsupported_protect_level
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced_binding_set_auth_info() routine sets up the dced binding
handle so it can be used for authenticated calls that include
authorization information. The rpc_binding_set_auth_info routine
performs in the same way as this one. See it for details of the
parameters and values. 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
This example establishes a dced binding to a host's key table
service, and then it calls dced_binding_set_auth_info() so that
the application is authorized to access remote key tables by using
additional calls to the key table service.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create( (dced_string_t)"keytab@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_binding_set_auth_info( dced_bh,
rpc_c_protect_level_default,
rpc_c_authn_pkt_privacy,
NULL,
rpc_c_authz_dce,
&status );
.
. /* Other routines including dced API routines. */
.
RELATED INFORMATION
Routines rpc_binding_set_auth_info
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.1.4 – dced_binding_free
NAME
dced_binding_free - Releases the resources associated with a dced
binding handle
SYNOPSIS
#include <dce/dced.h>
void dced_binding_free( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies a dced binding handle to free for a dced service on a
specific host.
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
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced_binding_free() routine frees resources used by a dced
binding handle and referenced information. Use this routine when
your application is finished with a host service to break the
communication between your application and the dced. The dced
binding handle and referenced information is created with the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.2 – Generic Entry Routines
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
8.2.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.
8.2.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.
8.2.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.
8.2.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.
8.2.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.
8.2.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.
8.2.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.2.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.
8.2.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.
8.3 – Generic Routines To Read Data Objects
These routines obtain the actual data for items to which entries
refer (objects).
dced_object_read Reads one data item of a dced service, based on
the entry UUID
dced_object_read_all
Reads all the data of a dced service's entry list
dced_objects_release
Releases the resources allocated for data obtained
8.3.1 – dced_object_read
NAME
dced_object_read - Reads a data item of a dced service on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_object_read( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
void **data,
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 dced service's data entry associated
with the data item.
Output
data
Returns the data read. The data returned is one of the
following structures, depending on the service:
Service Data Type Returned
_____________________________
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
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_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
uuid_s_bad_version
DESCRIPTION
The dced_object_read() routine reads the data for a specified entry
of a dced service. When the application is done with the data, it
should call the dced_objects_release() routine with a value of 1
for the count parameter.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab. These host services each have a
list of data entries maintained by dced. The entries do not contain
the actual data but contain the data's identity and an indicator of
the location of the data item. The hostdata service also has the
dced_hostdata_read() routine to read data, and the keytab service
has a series of routines that traverse over the keys in a key table.
(See the dced_keytab_initialize_cursor() routine.) The secval and
endpoint services do not have data items to read with this routine.
Applications can also read the data for all entries of a service
using one call to dced_objects_read_all().
Prior to reading the actual data, an application commonly obtains
the entries to read using the series of cursor routines that begin
with dced_entry_initialize_cursor().
Prior to calling the dced_object_read() 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 creates a dced binding to a dced service based
on a service type and host in an rpc binding handle. The example
then obtains the service's entry list and reads the data associated
with each entry.
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++) {
dced_object_read( dced_bh,
&entries.list[i].id,
&data,
&status );
.
.
.
dced_objects_release( dced_bh, 1, data, &status );
}
.
.
.
RELATED INFORMATION
Routines: dced_objects_release
dced_objects_read_all
dced_hostdata_read
dced_keytab_initialize_cursor
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.3.2 – dced_object_read_all
NAME
dced_object_read_all - Reads all the data for a service of the
DCE Host daemon (dced) on specific host
SYNOPSIS
#include <dce/dced.h>
void dced_object_read_all( dced_binding_handle_t dced_bh,
unsigned32 *count,
void **data_list,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Output
count
Returns the count of the number of data items read.
data_list
Returns the list of data items read. The data returned is an
array of one of the following types, depending on the service:
Service Data Type of Array Returned
______________________________________
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
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_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
sec_s_no_memory
uuid_s_bad_version
DESCRIPTION
The dced_object_read_all() routine reads all the data for a
specified host service on a specific host. When the application
is done with the data, it should call the dced_objects_release()
routine. Applications can also read individual data objects for a
service using the dced_object_read() routine.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab.
Prior to calling the dced_object_read_all() 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 reads and displays all the data for a
particular dced service.
dced_binding_handle_t dced_bh;
dced_string_t host_service;
void *data_list;
unsigned32 count;
error_status_t status;
dced_binding_create( host_service,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_object_read_all( dced_bh, &count, &data_list, &status );
display( host_service, count, &data_list ); /* app. specific */
dced_objects_release( dced_bh, count, data_list, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_objects_release
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.3.3 – dced_objects_release
NAME
dced_objects_release - Releases the resources allocated for data
read from a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_objects_release( dced_binding_handle_t dced_bh,
unsigned32 count,
void *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
count
Specifies the number of data items previously read and now to
be released.
Input/Output
data
Specifies the data 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 possible status codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_support
DESCRIPTION
The dced_objects_release() routine releases the resources allocated
when data for dced is read. Applications should call
dced_objects_release() when finished with data allocated by the
following dced API routines:
+ dced_object_read_all()
+ dced_object_read()
+ dced_hostdata_read()
If the data being released was read by using dced_object_read_all(),
the count returned from this routine is used as input to the
dced_objects_release() routine. If the data being released was read
by using dced_object_read() or dced_hostdata_read(), the count value
required as input for the dced_objects_release() routine is 1.
EXAMPLES
In the following example, a binding is created to a dced service
on some host for a service that stores data, and the service's
entry list is obtained. For each entry, the data is read,
displayed, and released.
dced_binding_handle_t dced_bh;
dced_entry_list_t entries;
unsigned32 i;
void *data;
error_status_t status;
dced_binding_create( host_service,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_list_get( dced_bh, &entries, &status );
for(i=0; i<entries.count; i++) {
dced_object_read( dced_bh,
&(entries.list[i].id),
&data,
&status );
display( host_service, 1, &data ); /* app. specific */
dced_objects_release( dced_bh, 1, data, &status );
.
.
.
RELATED INFORMATION
Routines: dced_object_read
dced_object_read_all
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.4 – Host Data Management Routines
dced_hostdata_create
Creates a hostdata item and the associated entry
dced_hostdata_read Reads a hostdata item
dced_hostdata_write Replaces an existing hostdata item
dced_hostdata_delete
Deletes a hostdata item from a specific host and
removes the associated entry
8.4.1 – dced_hostdata_create
NAME
dced_hostdata_create - Creates a hostdata item and the associated
entry in dced on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_create( dced_binding_handle_t dced_bh,
dced_entry_t *entry,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the host data service
on a specific host.
Input/Output
entry
Specifies the hostdata entry to create. You supply a name
(entry->name), description (entry->description), and file
name (entry->storage_tag), in the form of dced strings. You
can supply a UUID (entry->id) for dced to use or you can use
a NULL value and dced will generate a new UUID for the entry.
Input
data
Specifies the data created and written to a file on the host.
The dced_attr_list_t consists of a count of the number of
attributes, and an array of attributes of type sec_attr_t.
The reference OSF implementation has one attribute for a
hostdata item (file contents). However some vendors may
provide multiple attributes.
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_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_import_already_exists
dced_s_unknown_attr_type
sec_acl_invalid_permission
DESCRIPTION
The dced_hostdata_create() routine creates a new host data item in
a file on the host to which the dced binding handle refers, and it
generates the associated hostdata entry in the host's dced.
If data that you want to add to the host data service already exists
on the host (in a file), you can add it to the service by calling
dced_entry_add(), which only creates the new data entry for dced.
Prior to calling the dced_hostdata_create() routine, the
application must have established a valid dced binding handle
to the hostdata service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example creates a binding to the host data service
on the local host, creates the entry data, and fills in the data
structure for one attribute to a hypothetical printer configuration.
The attribute represents a plain-text file containing one string of
data.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_entry_t entry;
dced_attr_list_t data;
int num_strings, str_size;
sec_attr_enc_str_array_t *attr_array;
dced_binding_create( dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh,
&status );
/*Create an Entry. */
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");
/* create the attributes */
data.count = 1;
num_strings = 1;
data.list = (sec_attr_t *)
malloc( data.count * sizeof(sec_attr_t) );
data.list->attr_id = dced_g_uuid_fileattr;
data.list->attr_value.attr_encoding =
sec_attr_enc_printstring_array;
str_size = sizeof(sec_attr_enc_str_array_t) + num_strings
* sizeof(sec_attr_enc_printstring_p_t);
attr_array = (sec_attr_enc_str_array_t *)malloc(str_size);
data.list->attr_value.tagged_union.string_array = attr_array;
attr_array->num_strings = num_strings;
attr_array->strings[0] = (dced_string_t)
("New printer configuration data");
dced_hostdata_create( dced_bh, &entry, &data, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_entry_add
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.4.2 – dced_hostdata_read
NAME
dced_hostdata_read - Reads a hostdata item maintained by dced
on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_read( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
uuid_t *attr_uuid,
sec_attr_t **data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the hostdata service
on a specific host.
entry_uuid
Specifies the hostdata entry UUID associated with the data
to read.
attr_uuid
Specifies the UUID associated with an attribute of the data.
The attribute is either plain text (dced_g_uuid_fileattr) or
binary (dced_g_uuid_binfileattr). Some vendors may allow other
attributes.
Output
data
Returns the data for the item. See the sec_intro reference
page for details on the sec_attr_t data type.
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_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_invalid_attr_type
dced_s_no_memory
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_hostdata_read() routine returns a hostdata item maintained
by dced on a specific host. The standard data items include the
cell name, a list of cell aliases, the host name, a list of UUID-
program pairs (post_processors), and the DCE configuration database,
among other items. For programming convenience, the following
global variables are defined for the entry_uuid of some standard
data items:
dced_g_uuid_cell_name
dced_g_uuid_cell_aliases
dced_g_uuid_host_name
dced_g_uuid_hostdata_post_proc
dced_g_uuid_dce_cf_db
dced_g_uuid_pe_site
dced_g_uuid_svc_routing
Other host-specific data items may also be maintained by the
hostdata service. The UUIDs for these are established when the
data item is created (See dced_hostdata_create()). After the
applications reads host data and when it is done with the data,
it should call the dced_objects_release() routine to release the
resources allocated.
Each hostdata item for a specific host is stored in a local file.
The name of an item's storage file is indicated in the storage tag
field of each dced hostdata entry.
You can also use the dced_object_read() routine to read the text
of a hostdata item. You might use this routine if your application
needs to read data for other host services (srvrconf, srvrexec, or
keytab) in addition to data for the hostdata service.
Prior to calling the dced_hostdata_read() routine, the
application must have established a valid dced binding handle
to the hostdata service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_objects_release
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.4.3 – dced_hostdata_write
NAME
dced_hostdata_write - Replaces an existing hostdata item
maintained by dced on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_write( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the Host Data service
on a specific host.
entry_uuid
Specifies the hostdata entry UUID to associate with the data
to be written.
data
Specifies the data to write. The dced_attr_list_t consists
of a count of the number of attributes, and an array of
attributes of type sec_attr_t. The reference OSF
implementation has one attribute for a hostdata item (file
contents). However some vendors may require multiple
attributes.
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_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_no_postprocessors
dced_s_postprocessor_file_fail
dced_s_postprocessor_spawn_fail
dced_s_unknown_attr_type
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_hostdata_write() routine replaces existing data for a
hostdata item maintained by dced on a specific host. If the
entry_uuid is not one maintained be dced, an error is returned
and a new entry is not created. Use dced_hostdata_create() to
create a new entry.
Prior to calling the dced_hostdata_write() routine, the
application must have established a valid dced binding
handle to the hostdata service by calling either the
dced_binding_create() or dced_binding_from_rpc_binding()
routine.
RELATED INFORMATION
Routines: dced_hostdata_read
dced_hostdata_create
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.4.4 – dced_hostdata_delete
NAME
dced_hostdata_delete - Deletes a hostdata item from a specific
host and removes the associated entry
from dced
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_delete( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the hostdata service
on a specific host.
entry_uuid
Specifies the UUID of the hostdata entry (and associated data)
to delete.
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_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_remove_storage_file
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_hostdata_delete() routine deletes a hostdata item (a file)
from a specific host, and removes the associated entry from the host
data service of that host's dced.
If you want to only make the data inaccessible remotely but not
delete it, use the dced_entry_remove() routine which only removes
the data's hostdata entry.
Prior to calling the dced_hostdata_delete() routine, the
application must have established a valid dced binding handle
for the hostdata service by calling either the
dced_binding_create() or dced_binding_from_rpc_binding()
routine.
WARNINGS
Do not delete the standard hostdata items such as cell_name,
cell_aliases, host_name, post_processors, or dce_cf.db. This
will cause operational problems for the host.
RELATED INFORMATION
Routines: dced_entry_remove
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.5 – Server Configuration Control Routines
dced_server_create Creates a DCE server's configuration data
dced_server_modify_attributes
Modifies a DCE server's configuration data
dced_server_delete Deletes a DCE server's configuration data
dced_server_start Starts a DCE-configured server
8.5.1 – dced_server_create
NAME
dced_server_create - Creates a DCE server's configuration data
for the host's dced
SYNOPSIS
#include <dce/dced.h>
void dced_server_create( dced_binding_handle_t dced_bh,
server_t *conf_data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service on a
specific host.
Input/Output
conf_data
Specifies the configuration data for the server. The dced_intro
reference page describes the server_t structure.
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_bad_header_type
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_name_missing
sec_acl_invalid_permission
DESCRIPTION
The dced_server_create() routine creates a server's configuration
data. This routine is used by management installation applications
to remotely (or locally) establish the data used to control how a
DCE server starts. However, it does not create the program or
start it. Since this activity is typically part of a server's
installation, you can also use dcecp's server create operation.
Management applications use the dced_object_read() routine to read
the configuration data.
Prior to calling dced_server_create(), the application must have
established a valid dced binding handle to the srvrconf service
by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
EXAMPLES
The following example shows how to fill in some of the fields of
a server_t structure and then create the configuration in dced.
dced_binding_handle_t dced_bh;
server_t conf;
error_status_t status;
dced_binding_create( "srvrconf@hosts/katharine",
dced_c_binding_syntax_default,
&dced_bh,
&status );
/* setup a server_t structure */
uuid_create(&conf.id, &status);
conf.name = (dced_string_t)"application";
conf.entryname = (dced_string_t)"/.:/development/new_app";
conf.services.count = 1;
/* service_t structure(s) */
conf.services.list = malloc( conf.services.count *
sizeof(service_t) );
rpc_if_inq_id( application_v1_0_c_ifspec,
&(conf.services.list[0].ifspec),
&status );
conf.services.list[0].ifname =
(dced_string_t)"application";
conf.services.list[0].annotation =
(dced_string_t)"A new application";
conf.services.list[0].flags = 0;
/* server_fixedattr_t structure */
conf.fixed.startupflags = server_c_startup_explicit |
server_c_startup_on_failure;
conf.fixed.flags = 0;
conf.fixed.program = (dced_string_t)"/usr/users/bin/new_app";
dced_server_create( dced_bh, &conf, &status );
.
.
.
RELATED INFORMATION
Routines: dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
dcecp objects: server
Books: OSF DCE Application Development Guide.
8.5.2 – dced_server_modify_attributes
NAME
dced_server_modify_attributes - Modifies attributes for a DCE
server's configuration data
SYNOPSIS
#include <dce/dced.h>
void dced_server_modify_attributes(
dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service
on a specific host.
conf_uuid
Specifies the UUID that dced uses to identify a server's
configuration data to be modified.
data
Specifies the attributes to be modified.
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_bad_index_type
db_s_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_modify_attributes() routine replaces a server's
attributes of its configuration data maintained by dced on a
specific host. This routine is typically called after a
configuration is created with the dced_server_create() routine.
A server's configuration is manipulated in a server_t data
structure, and the dced_server_modify_attributes() routine
affects only the attributes member of this structure. To change
other server configuration data, you must first delete the
configuration by using dced_server_delete() and then create the
configuration again by using dced_server_create().
Prior to calling dced_server_modify_attributes(), the application
must have established a valid dced binding handle to the srvrconf
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
RELATED INFORMATION
Routines: dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide
8.5.3 – dced_server_delete
NAME
dced_server_delete - Deletes a DCE server's configuration data
from dced
SYNOPSIS
#include <dce/dced.h>
void dced_server_delete( dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service
on a specific host.
conf_uuid
Specifies the UUID that dced uses to identify the server's
configuration data to be deleted.
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_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_delete() routine deletes a server's configuration
data from the server's dced. This routine removes a server from
DCE control by making it incapable of starting via dced. It does
not delete the program from disk nor does it affect the server
if it is currently running.
Prior to using dced_server_delete(), the server configuration
data must be created by an administrator using the dcecp server
create operation or by an application that using
dced_server_create().
Prior to calling dced_server_delete(), the application must
have established a valid dced binding handle to the srvrconf
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
EXAMPLES
In the following example, a dced binding is created to the
server configuration service on a host, and then an inquiry
is made as to the UUID associated with a particular server.
The dced_server_delete() routine is then used to delete the
configuration.
dced_binding_handle_t dced_bh;
dced_string_t server_name;
uuid_t srvrconf_id;
error_status_t status;
name_server( &server_name ); /* application specific */
dced_binding_create( "srvrconf@hosts/katharine",
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_inq_id( dced_bh, server_name, &srvrconf_id, &status );
dced_server_delete( dced_bh, &srvrconf_id, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_server_create
dced_server_modify_attributes
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
8.5.4 – dced_server_start
NAME
dced_server_start - Starts a DCE-configured server on a
specified host
SYNOPSIS
#include <dce/dced.h>
void dced_server_start( dced_binding_handle_t dced_bh,
uuid_t *conf_uuid,
dced_attr_list_t *attributes,
uuid_t *exec_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrconf service on a
specific host.
conf_uuid
Specifies the UUID that dced uses to identify the server to
start. If the value input is that of a server that is
already running, dced starts a new instance.
attributes
Specifies the configuration attributes to use to start the
server. If the value is NULL, the default configuration
defined in dced is used.
Input/Output
exec_uuid
Specifies a new UUID for dced to use to identify the running
server. If a NIL UUID is input, a new UUID is created and
returned. If the value input is that of a server that is
already running, dced starts a new instance and returns a
new value.
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_bad_header_type
db_s_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
dced_s_sc_cant_fork
dced_s_sc_invalid_attr_type
dced_s_sc_open_file_failed
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_server_start() routine starts DCE-configured servers on
a specific remote host (or the local host). The configuration
data is stored in an object in the srvrconf service of dced.
When the server starts, dced uses the server configuration object
and creates a server execution object in the srvrexec service.
A server execution object consists of data that describes the
executing server.
Management applications create the configuration data by using
the dced_server_create() use the dced_object_read() routine to
read the configuration or execution data.
Prior to calling dced_server_start(), the application must have
established a valid dced binding handle to the srvrconf service
by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
EXAMPLES
The following example starts a configured server using a nil UUID
as input for the executing server.
dced_binding_handle_t conf_bh;
dced_string_t server_name;
uuid_t srvrconf_id, srvrexec_id;
error_status_t status;
dced_binding_create( "srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&conf_bh,
&status );
dced_inq_id( conf_bh, server_name, &srvrconf_id, &status );
uuid_create_nil( &srvrexec_id, &status );
dced_server_start( conf_bh,
&srvrconf_id,
NULL,
&srvrexec_id,
&status );
.
.
.
RELATED INFORMATION
Routines: dced_server_create
dced_server_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands: server
Books: OSF DCE Application Development Guide.
8.6 – Server Execution Control Routines
dced_server_disable_if
Disables a service provided by a server
dced_server_enable_if
Re-enables a service provided by a server
dced_server_stop Stops a DCE-configured server
8.6.1 – dced_server_disable_if
NAME
dced_server_disable_if - Disables a service (rpc interface)
provided by a specific server on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_server_disable_if( dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
rpc_if_id_t *interface,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrexec service
on a specific host.
exec_uuid
Specifies the UUID that dced uses to identify the running
server.
interface
Specifies the RPC interface identifier that represents the
service to be disabled. The interface identifier is generated
when idl compiles an interface definition file. The interface
identifier is an rpc_if_id_t structure that contains the
interface UUID (uuid) of type uuid_t, and numbers of type
unsigned16 representing the major (vers_major) and minor
(vers_minor) version numbers for the interface.
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_bad_index_type
db_s_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_disable_if() routine disables a service provided
by a server on a specific host. A service is represented by an
RPC interface identifier. Management applications use this
routine to remotely disable an interface so it is inaccessible by
clients, without completely stopping the entire server.
When a server starts and initializes itself, it must call the
dce_server_register() routine to enable all of its services.
The server can then disable its own individual services by using
dce_server_disable_service(). This routine unregisters the
service's interface from the RPC runtime and marks the interface
as disabled in the endpoint map. As an alternative, a management
application can use dced_server_disable_if() to disable individual
services. However, this routine only affects the endpoint map in
dced by marking the interface as disabled and does not affect the
server's runtime.
A management application can re-enable a service again by calling
the dced_server_enable_if() routine. (Servers re-enable their
own services using the dce_server_enable_if() routine.)
Prior to calling dced_server_disable_if(), the application must
have established a valid dced binding handle to the srvrexec
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
RELATED INFORMATION
Routines: dce_server_register
dce_server_disable_if
dce_server_enable_if
dced_server_enable_if
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
8.6.2 – dced_server_enable_if
NAME
dced_server_enable_if - Enables a service (rpc interface) of
a specific server on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_server_enable_if( dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
rpc_if_id_t *interface,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrexec service
on a specific host.
exec_uuid
Specifies the UUID that dced uses to identify the running
server.
interface
Specifies the RPC interface identifier that represents the
service to be enabled. The interface identifier is generated
when idl compiles an interface definition file. The interface
identifier is a structure that contains the interface UUID
(interface->uuid), and the major (interface->vers_major) and
minor (interface->vers_minor) version numbers for the interface.
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_bad_index_type
db_s_iter_not_allowed
db_s_readonly
db_s_store_failed
dced_s_bad_binding
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_server_enable_if() routine enables a service (or re-enables
a previously disabled service) that a specific server provides.
Management applications use this routine. A service is represented
by an RPC interface identifier.
When a server starts and initializes itself, it typically calls
the dce_server_register() routine to enable all of its services.
The services can then be disabled and re-enabled, as needed. A
server enables and disables its own services by using
dce_server_enable_service() and dce_server_disable_service() and
a management application enables and disables a remote server's
service using dced_server_enable_if() and dced_server_disable_if().
The dce_server* routines affect both the RPC runtime and the local
endpoint map by registering (or unregistering) with the runtime
and setting a flag for the interface in the the endpoint map as
enabled (or disabled). The dced_server_enable_if() and
dced_server_disable_if() routines affect only the remote endpoint
map by setting the flag.
Prior to calling dced_server_enable_if(), the application must
have established a valid dced binding handle to the srvrexec
service by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
RELATED INFORMATION
Routines: dce_server_register
dce_server_enable_if
dce_server_disable_if
dced_server_disable_if
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
8.6.3 – dced_server_stop
NAME
dced_server_stop - Stops a DCE-configured server running on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_server_stop( dced_binding_handle_t dced_bh,
uuid_t *exec_uuid,
srvrexec_stop_method_t method,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the srvrexec service
on a specific host.
exec_uuid
Specifies a UUID that dced uses to identify the running server.
If the value input is dced_g_uuid_all_servers, then dced
attempts to stop all the DCE servers running on that host.
method
Specifies the method dced uses to stop a server. A method is
represented by one of the following values:
srvrexec_stop_rpc
Uses the rpc_mgmt_stop_server_listening routine.
This is the cleanest way to stop a server
because it waits for outstanding remote procedure
calls to finish before making the server's
rpc_server_listen() routine return.
srvrexec_stop_soft
Uses a "soft" local host mechanism (such as the
TERM signal in UNIX)
srvrexec_stop_hard
Uses a "hard" local host mechanism (such as the
KILL signal in UNIX)
srvrexec_stop_error
Uses a mechanism that saves the program state
(such as the ABORT signal in UNIX)
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
dced_s_bad_binding
dced_s_no_support
dced_s_not_found
rpc_s_binding_incomplete
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_mgmt_op_disallowed
rpc_s_unknown_if
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_server_stop() routine stops DCE-configured servers on
specific hosts. When the server is completely stopped and no
longer a running process, dced deletes the associated execution
data it maintained.
Administrators use the dcecp operations server create and server
start to configure and start a server, and management applications
use the associated dced_server_create() and dced_server_start()
routines.
Prior to calling dced_server_stop(), the application must have
established a valid dced binding handle to the srvrexec service
by calling either dced_binding_create() or
dced_binding_from_rpc_binding().
CAUTIONS
Using the value dced_g_uuid_all_servers for the exec_uuid parameter
causes dced to shutdown all servers including itself.
EXAMPLES
The following example obtains dced binding handles to the server
configuration and execution services of dced on the host patrick.
The example then checks to see if the server is running by seeing
if dced has a UUID and entry for the executing server. However,
the server may be in the process of starting up or stopping, so the
example also checks to be sure the instance UUID of the running
server matches the UUID of the configuration for that server. If
there is a match, the server is running. Finally, the example
stops the server by calling dced_server_stop() with the
srvrexec_stop_rpc parameter.
dced_binding_handle_t conf_bh, exec_bh;
dced_string_t server_name;
void *data;
server_t *exec_ptr;
uuid_t srvrconf_id, srvrexec_id;
error_status_t status;
.
.
.
dced_binding_create( "srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&conf_bh,
&status );
dced_binding_create( "srvrexec@hosts/patrick",
dced_c_binding_syntax_default,
&exec_bh,
&status) ;
/* is server running? */
dced_inq_id( exec_bh, server_name, &srvrexec_id, &status );
/* also check to be sure server is not coming up or going down */
dced_object_read( exec_bh, &srvrexec_id, &data, &status );
exec_ptr = (server_t*)data;
dced_inq_id( conf_bh, server_name, &srvrconf_id, &status );
if (uuid_equal( &srvrconf_id,
&exec_ptr->exec_data.tagged_union.running_data.instance,
&status) ) {
dced_server_stop( exec_bh,
&srvrexec_id,
srvrexec_stop_rpc,
&status );
}
dced_objects_release( exec_bh, 1, data, &status );
dced_binding_free( conf_bh, &status );
dced_binding_free( exec_bh, &status );
RELATED INFORMATION
Routines: dced_server_create
dced_server_start
rpc_mgmt_stop_server_listening
dced_binding_create
dced_binding_from_rpc_binding
dcecp Objects: server
Books: OSF DCE Application Development Guide.
8.7 – Security Validation Routines
dced_secval_start Starts a host's security validation service
dced_secval_validate
Validates that the DCE Security daemon (secd)
used by a specific host is legitimate
dced_secval_status Returns a status parameter of TRUE if the
security validation service is activated and
FALSE if not
dced_secval_stop Stops a host's security validation service
8.7.1 – dced_secval_start
NAME
dced_secval_start - Starts the security validation service of
a specific host's dced
SYNOPSIS
#include <dce/dced.h>
void dced_secval_start( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
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
dced_s_bad_binding
dced_s_sv_already_enabled
sec_acl_invalid_permission
DESCRIPTION
The dced_secval_start() routine starts the Security Validation
service of a specific host's dced. This routine is typically
used by management applications.
The Security Validation service (secval) has two major functions:
1. Maintain a login context for the host's self identity.
2. Validate and certify to applications (usually login programs)
that the DCE Security daemon (secd) is legitimate.
The secval is commonly started by default when dced starts.
See the dced_secval_stop() routine for a discussion of when to
use the combination of dced_secval_stop() and dced_secval_start().
Prior to calling this routine, the application must have
established a valid dced binding handle to the secval service
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_secval_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
The secval object of dcecp
Books: OSF DCE Application Development Guide.
8.7.2 – dced_secval_validate
NAME
dced_secval_validate - Validates that the secd used by a
specific host is legitimate
SYNOPSIS
#include <dce/dced.h>
void dced_secval_validate( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
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
dced_s_bad_binding
ept_s_not_registered
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_rpcd_comm_failure
rpc_s_wrong_kind_of_binding
sec_login_s_no_current_context
DESCRIPTION
The dced_secval_validate() routine validates and certifies for
a specific host that the DCE Security daemon (secd) is legitimate.
Typically, a login program uses the security validation service
when it uses the Security Service's Login API (routines that begin
with sec_login). However, if a management application trusts some
remote host, it can use dced_secval_validate() to validate secd,
without logging in to the host.
RELATED INFORMATION
Routines: sec_login* API
dced_secval_start
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
The secval object of dcecp
Books: OSF DCE Application Development Guide.
8.7.3 – dced_secval_status
NAME
dced_secval_status - Indicates whether or not a specific host's
security validation service of dced is
running
SYNOPSIS
#include <dce/dced.h>
void dced_secval_status( dced_binding_handle_t dced_bh,
boolean32 *secval_active,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
Output
secval_active
Returns a value of TRUE if the security validation service
is running and FALSE if it is not running.
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
DESCRIPTION
The dced_secval_status() routine sets a parameter to TRUE or
FALSE depending on whether the security validation service has
been activated or deactivated.
Prior to calling this routine, the application must have
established a valid dced binding handle to the secval service
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_secval_start
dced_secval_stop
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
the secval object of dcecp
Books: OSF DCE Application Development Guide.
8.7.4 – dced_secval_stop
NAME
dced_secval_stop - Stops the security validation service of
a specific host's dced
SYNOPSIS
#include <dce/dced.h>
void dced_secval_stop( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the secval service on
a specific host.
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
dced_s_bad_binding
dced_s_sv_not_enabled
sec_acl_invalid_permission
DESCRIPTION
The dced_secval_stop() routine stops the security validation service
(secval) of a specific host's dced. This routine is typically used
by managment applications.
The secval service is commonly started by default when dced starts.
The main use of dced_secval_stop() and dced_secval_start() is to
force a refresh of the host principal credentials. This is the only
way to force certain registry changes made by the host principal
(such as groupset membership) to be seen by processes running on the
host.
You can easily stop and then start the secval service with the
following operations:
dcecp -c secval deactivate
dcecp -c secval activate
It is not a good idea to remove the machine principal self
credentials for an extended period of time because processes
running as self will fail in their attempts to perform
authenticated operations.
RELATED INFORMATION
Routines: dced_secval_start
dced_binding_create
dced_binding_from_rpc_binding
Commands: dced
The secval object of dcecp
Books: OSF DCE Application Development Guide.
8.8 – Key Table Management Routines
dced_keytab_create Creates a key table with a list of keys in a new
file
dced_keytab_delete Deletes a key table file and removes the
associated entry
dced_keytab_initialize_cursor
Obtains a list of keys from a key table and sets
a cursor at the beginning of the list
dced_keytab_get_next_key
Returns a key from a cached list, and advances
the cursor
dced_keytab_release_cursor
Releases the resources associated with a cursor
that traverses a key table
dced_keytab_add_key Adds a key to a key table
dced_keytab_change_key
Changes a key in both a key table and in the
security registry
dced_keytab_remove_key
Removes a key from a key table
8.8.1 – dced_keytab_create
NAME
dced_keytab_create - Creates a key table with a list of keys
(server passwords) in a new file on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_create( dced_binding_handle_t dced_bh,
dced_entry_t *keytab_entry,
dced_key_list_t *keys,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service on
a specific host.
Input/Output
keytab_entry
Specifies the keytab entry to create for dced.
keys
Specifies the list of keys to be written to the key table file.
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_bad_header_type
db_s_bad_index_type
db_s_bad_index_type
db_s_iter_not_allowed
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_import_already_exists
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_unauthorized
uuid_s_bad_version
DESCRIPTION
The dced_keytab_create() routine creates a new key table file on
a specific host, and it generates the associated keytab service
entry in dced. This routine is used by management applications
to remotely create a key table. Servers typically create their
own key table locally using the sec_key_mgmt_set_key routine.
However, if several servers on different hosts share the same
principal, each host requires a local copy of the key table.
If a key table that you want to add to the keytab service already
exists on the host, you can add it to the service by calling
dced_entry_add(). This routine creates a new keytab service
entry by associating the existing key table file with a new UUID
in dced.
Prior to calling the dced_keytab_create() routine, the
application must have established a valid dced binding handle
to the keytab service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: sec_key_mgmt_set_key
dced_entry_add
dced_binding_from_rpc_binding
dced_binding_create
Books: OSF DCE Application Development Guide.
8.8.2 – dced_keytab_delete
NAME
dced_keytab_delete - Deletes a key table file from a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_delete( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service on
a specific host.
keytab_uuid
Specifies the UUID of the keytab entry and associated key
table to be deleted.
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_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_remove_storage_file
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
DESCRIPTION
The dced_keytab_delete() routine deletes a key table (file) from
a specific host and removes the associated entry from the keytab
service of that host's dced. A key table is a file containing a
list of server keys (passwords). This routine is used by
management applications to remotely delete a key table.
To remove individual keys from a remote key table, use the
dced_keytab_remove_key() routine. If you want to only make
the key table inaccessible remotely (via dced) but not delete
it, use the dced_entry_remove() routine. This routine only
removes the key table's keytab entry from dced.
Prior to calling the dced_keytab_delete() routine, the
application must have established a valid dced binding handle
to the keytab service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_keytab_remove_key
dced_entry_remove
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.8.3 – dced_keytab_initialize_cursor
NAME
dced_keytab_initialize_cursor - Obtains a list of keys from a key
table and sets a cursor at the
beginning of the list
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_initialize_cursor(
dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_keytab_cursor_t *cursor,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service on
a specific host.
keytab_uuid
Specifies the keytab entry dced associates with a key table.
Output
cursor
Returns the cursor that is used to traverse the list of keys.
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_need_privacy
dced_s_no_memory
dced_s_no_support
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_unauthorized
DESCRIPTION
The dced_keytab_initialize_cursor() routine obtains the complete
list of keys from a remote key table and sets a cursor at the
beginning of the cached list keys. In order to minimize the
security risks of keys exposed to the network, the entire set of
keys are encrypted and transferred in one remote procedure call
rather than individually or in chunks. The cursor is then used in
subsequent calls to dced_keytab_get_next_key() to obtain individual
keys. When the application is finished traversing the key list, it
should call dced_keytab_release_cursor() to release the resources
previously allocated.
Management applications use dced_keytab_initialize_cursor() and
its associated routines to remotely access server keys. Servers
use sec_key_mgmt_initialize_cursor and its associated routines
to manage their own keys locally.
Prior to calling the dced_keytab_initialize_cursor() routine, the
application must have established a valid dced binding handle to
the keytab service by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_keytab_get_next_key
dced_keytab_release_cursor
sec_key_mgmt_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.8.4 – dced_keytab_get_next_key
NAME
dced_keytab_get_next_key - Returns a key from a cached list,
and advances the cursor in the list
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_get_next_key( dced_keytab_cursor_t cursor,
dced_key_t **key,
error_status_t *status );
PARAMETERS
Input/Output
cursor
Specifies the cursor that points to a key, and returns
the cursor advanced to the next key in the list.
Output
key Returns the current key to which the cursor points.
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_keytab_get_next_key() routine obtains the current key to
which the key-list cursor points. This routine is commonly used
in a loop to traverse a key table's keys. The keys are returned
in an undetermined order. Prior to using this routine in the loop,
the application must call dced_keytab_initialize_cursor() to obtain
the key list and established the beginning of the cursor. When the
application is finished traversing the key list, it should call
dced_keytab_release_cursor() to release the resources allocated.
Management applications use dced_keytab_get_next_key() to
remotely access a server's individual keys. Servers use
sec_key_mgmt_get_next_key to access their own local keys
individually.
You can also use the dced_object_read() routine to read an entire
key table. You might use dced_object_read() if your application
needs to bind to and read data for other host services (srvrconf,
srvrexec, or hostdata) in addition to data for the keytab service.
RELATED INFORMATION
Routines: dced_keytab_initialize_cursor
dced_keytab_release_cursor
sec_key_mgmt_get_next_key
dced_object_read
Books: OSF DCE Application Development Guide.
8.8.5 – dced_keytab_release_cursor
NAME
dced_keytab_release_cursor - Releases the resources of a cursor
that traverses a key table's list
of keys (server passwords)
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_release_cursor( dced_keytab_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 possible status codes are:
error_status_ok
dced_s_bad_binding
dced_s_no_support
DESCRIPTION
The dced_keytab_release_cursor() routine releases the cursor and
resources initially set by the dced_keytab_initialize_cursor()
routine and used by the dced_keytab_get_next_key() routine.
Prior to calling this routine, the application must have first
established a valid dced binding handle by calling either
dced_binding_create() or dced_binding_from_rpc_binding(), and
then the application must have called the
dced_keytab_initialize_cursor() routine.
RELATED INFORMATION
Routines: dced_keytab_initialize_cursor
dced_keytab_get_next_key
Books: OSF DCE Application Development Guide.
8.8.6 – dced_keytab_add_key
NAME
dced_keytab_add_key - Adds a key (server password) to a specified
key table on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_add_key( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service
on a specific host.
keytab_uuid
Specifies the UUID that dced uses to identify the key table
to which the key is to be added.
Input/Output
key Specifies the key to be added. Some fields are completed
by dced. See dced_intro.
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_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_key_v0_not_allowe
dced_s_key_version_mismatch
dced_s_need_privacy
dced_s_random_key_not_allowed
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_unauthorized
DESCRIPTION
The dced_keytab_add_key() routine adds a key to a server's key
table (file) on a specific host, without changing the key in the
security registry. (Servers use sec_key_mgmt_set_key to do this
for their own local key table.)
Most management applications use the dced_keytab_change_key()
routine to remotely change a key because it also changes the key
in the Security Registry.
Managing the same key in multiple key tables is a more complex
process. The Security Registry needs a copy of a server's key so
that during the authentication process, it can encrypt tickets
that only a server with that key can later decrypt. Part of
updating a key in the Security Registry also includes automatic
version number updating. When servers share the same principle
identity they use the same key. If these servers are on different
hosts, then the key must be in more than one key table. (Even if
the servers are on the same host, it is possible for their keys to
be in different key tables, although this is not a recommended key
management practice.) When the same keys in different tables need
changing, one (perhaps the master server or busiest one) is changed
using dced_keytab_change_key() which also causes an automatic
version update. However, all other copies of the key must be
changed using the dced_keytab_add_key() routine so that the version
number does not change again.
Prior to calling dced_keytab_add_key() the application must have
established a valid dced binding handle to the keytab service by
calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_keytab_change_key
sec_key_mgmt_set_key
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.8.7 – dced_keytab_change_key
NAME
dced_keytab_change_key - Changes a key (server password) in both
a key table and in the security registry
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_change_key( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service
on a specific host.
keytab_uuid
Specifies the UUID dced uses to identify the key table in
which the key is to be changed.
Input/Output
key Specifies the new key. Some fields are modified by dced.
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_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_key_version_mismatch
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_authn_unavailable
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_key_unsupported
sec_key_mgmt_e_key_version_exists
sec_key_mgmt_e_not_implemented
sec_key_mgmt_e_unauthorized
sec_rgy_object_not_found
sec_rgy_server_unavailable
DESCRIPTION
The dced_keytab_change_key() routine updates a key in both the key
table on a specific host and in the Security Registry. Management
applications change keys remotely with this routine. (Servers can
change their own keys locally with the sec_key_mgmt_change_key
routine.)
The Security Registry needs a copy of a server's current key so
that during the authentication process, it can encrypt tickets that
only a server with that key can later decrypt. When a management
application calls dced_keytab_change_key(), dced first tries to make
the modification in the Security Registry, and, if successful it
then modifies the key in the key table. The old key is not really
replaced but a new version and key is established for all new
authenticated communication. The old version is maintained in the
key table (and Registry too) for a time so that existing clients
with valid tickets can still communicate with the server. The old
key is removed depending on the local cell's change policy and if
the server calls sec_key_mgmt_garbage_collect() to purge its old
keys explicitly, or sec_key_mgmt_manage_key() to purge them
implicitly.
When more than one server shares the same principal identity, they
use the same key. If you need to change the same key in more than
one key table, use decd_keytab_change_key() for one change and then
use the dced_keytab_add_key() routine for all others.
RELATED INFORMATION
Routines: dced_keytab_add_key
sec_key_mgmt_change_key
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.8.8 – dced_keytab_remove_key
NAME
dced_keytab_remove_key - Removes a key (server password) from a
specified key table on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_keytab_remove_key( dced_binding_handle_t dced_bh,
uuid_t *keytab_uuid,
dced_key_t *key,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the keytab service
on a specific host.
keytab_uuid
Specifies the UUID dced maintains to identify the key table
from which the key is to be removed.
key Specifies the key to be removed from the key table.
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_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_need_privacy
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
DESCRIPTION
The dced_keytab_remove_key() routine removes a key from a key
table (file) on a specific host. The key table is specified
with a keytab entry UUID from the host's dced. Management
applications use dced_keytab_remove_key() to remotely remove
server keys from key tables. Typically, servers delete their
own keys from their local key tables implicitly by calling
sec_key_mgmt_manage_key, or explicitly by calling
sec_key_mgmt_delete_key. Applications can delete an entire
key table file using the dced_keytab_delete() routine.
Prior to calling this routine, the application must have
established a valid dced binding handle to the keytab service
by calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: sec_key_mgmt_delete_key
dced_keytab_delete
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
8.9 – Data Types And Structures
The following data types used with the dced API are defined in
dce/dced_base.idl and are shown here in alphabetical order.
dced_attr_list_t
This data structure specifies the configuration attributes to
use when you start a server via dced. The structure consists
of the following:
count An unsigned32 number representing the number of
attributes in the list.
list An array of configuration attributes where each
element is of type sec_attr_t. This data type is
described in the sec_intro reference page.
For dced, the list[i].attr_id field can have values
of either dced_g_uuid_fileattr specifying plain text
or dced_g_uuid_binfileattr specifying binary data.
dced_binding_handle_t
A dced binding handle is an opaque pointer that refers to
information that includes a dced service (hostdata, srvrconf,
srvrexec, secval, or keytab) and RPC binding information for
a specific DCE Host daemon.
dced_cursor_t
The entry list cursor is an opaque pointer used to keep track
of a location in an entry list between calls that traverse the
list.
dced_entry_t
An entry is the structure that contains information about a
data item (or object) maintained by a dced service. The
actual data is maintained elsewhere. Each entry consists of
the following structure members:
id A unique identifer of type uuid_t that dced maintains
for every data item it maintains
name The name for the data item. The data type is
dced_string_t .
description
A brief description the data item (of type
dced_string_t) for the convenience of human users.
storage_tag
A string of type dced_string_t describing the
location of the actual data. This is implementation-
specific and may be a file (with a pathname) on the
host system or a storage identifier for the dced
process.
dced_entry_list_t
An entry list is a uniform way to list the data items a dced
service maintains. The entry list structure contains a list
of all the entries for a given service. For example, the
complete list of all entries of hostdata, server configuration
data, server execution data, and keytab data are each
maintained in separate entry lists. The structure consists of
the following:
count An unsigned32 number representing the number of
entries in the list.
list An array of entries where each element is of type
dced_entry_t.
dced_key_t
A key consists of the following structure members:
principal A dced_string_t type string representing the principal
for the key.
version An unsigned32 number representing the version number
of the key.
authn_service
An unsigned32 number representing the authentication
service used.
passwd A pointer to a password. This is of type
sec_passwd_rec_t .
See also the Security introduction reference page, sec_intro.
dced_key_list_t
A key list contains all the keys for a given key table and
consists of the following structure elements:
count An unsigned32 number representing the number of keys
in the list.
list An array of keys where each element is of type
dced_key_t.
dced_keytab_cursor_t
The keytab cursor is an opaque pointer used to keep track of
a location in a key list between calls that traverse the list.
dced_opnum_list_t
A list of operation numbers is used in the service_t structure.
This structure consists of the following fields:
count An unsigned32 number representing the number of
operations in the list.
list An array of UUIDs where each element is of type
uuid_t.
dced_service_type_t
The dced service type distinguishes the services provided by
dced. It is an enumerated type used mainly in a parameter of
the dced_binding_from_rpc_binding() routine. It can have one
of the following values:
dced_e_service_type_hostdata
The host data management service
dced_e_service_type_srvrconf
The server configuration management service
dced_e_service_type_srvrexec
The server execution management service
dced_e_service_type_secval
The security validation service
dced_e_service_type_keytab
The key table management service
dced_e_service_type_null
A NULL service type used internally
dced_string_t
This data type is a character string from the Portable
Character Set (PCS).
dced_string_list_t
A list of strings with the following format:
count An unsigned32 number representing the number of
strings in the list.
list An array of strings where each element is of type
dced_string_t.
dced_tower_list_t
A list of protocol towers used in the service_t structure.
This structure consists of the following fields:
count An unsigned32 number representing the number of
protocol towers in the list.
list An array of pointers where each element is a
pointer to a protocol tower of the type
sec_attr_twr_set_p_t. This data type is
described in the sec_intro reference page.
server_fixedattr_t
This structure is a field in the server_t structure. It
contains the following fields:
startupflags
This field is of type unsigned32 and can be any
combination of the following bits:
server_c_startup_at_boot
This means that dced should start
the server when dced is started.
server_c_startup_auto
This means that the server can be
started automatically if dced
determines there is a need.
server_c_startup_explicit
This means dced can start the server
if it receives an explicit command to
do so via dced_server_start() or the
dcecp operation server start.
server_c_startup_on_failure
This means that the server should
be restarted by dced if it exits
with an unsuccesful exit status.
Several bits are also reserved for vendor-specific startup and
include server_c_startup_vendor1, server_c_startup_vendor2,
server_c_startup_vendor3, and server_c_startup_vendor4.
flags This represents the execution state of the server and
is the unsigned32 type. This field is maintained only
by dced and should not be modified. Valid values to
check for are self-explanatory and include the
following:
server_c_exec_notrunning
server_c_exec_running
Several bits are also reserved for vendor-specific
execution states and include:
server_c_exec_vendor1
server_c_exec_vendor2
server_c_exec_vendor3
server_c_exec_vendor4
program This is the full path name of the server and is of
type dced_string_t.
arguments This is a list of arguments for the server and is of
type dced_string_list_t.
prerequisites
This is an advisory field that means this server is
a client of other prerequisite servers whose IDs are
in a list of type uuid_list_t. The UUIDs should be
the id fields from the server_t structures of the
relevent servers.
keytables This is a list of keytab entry UUIDs representing
the key tables for this server and is of type
uuid_list_t.
posix_uid This is a POSIX execution attribute for the user ID.
It is of type unsigned32.
posix_gid This is a POSIX execution attribute for the group ID.
It is of type unsigned32.
posix_dir This is a POSIX execution attribute for the directory
in which the server started when it is invoked. It
is of type dced_string_t.
server_t
The DCE Host daemon describes a server as follows:
id Each server has a unique ID of type uuid_t.
name Each server's name is of type dced_string_t.
entryname The server's entry name is a hint as to where the
server appears in the namespace. This is of type
dced_string_t.
services Each server offers a list of services specified in
a list of type service_list_t. This structure has
the following members:
count An unsigned32 number representing the
number of services in the list.
list A pointer to an array of services where
each element is of type service_t.
fixed This is a set of attributes common to all DCE
implementations. The data type is
server_fixedattr_t.
attributes
This field is of type dced_attr_list_t and contains
a list of attributes representing the behavior
specific to a particular server or host.
prin_names
This field is a list of principal names for the
server and is of type dced_string_list_t.
exec_data Data about an executing server is maintained in
a tagged union (named tagged_union) with a
discriminator of type unsigned32 named execstate
representing the server's execution state. The
union has the following two execution states:
server_c_exec_notrunning
For the case where the server is not running,
the union member has no value. For example:
if(server->exec_data.execstate == server_c_exec_no)
server->exec_data.tagged_union = NULL;
server_c_exec_running
For the case where the server is running,
and the value of the union member is a
srvrexec_data_t data type named running_data.
A srvrexec_data_t structure contains the
following members:
instance Each instance of a server on a host
is identified with a UUID
(type uuid_t).
posix_pid Each server has a POSIX process ID
of type unsigned32.
service_t
This structure describes each service offered by a server.
The server_t structure, described earlier, contains an array
of these structures. The service_t structure contains the
following fields:
ifspec An interface specification of type rpc_if_id_t,
generated by an idl compilation of the interface
definition representing the service. This data
type is described in the rpc_intro reference
page.
ifname An interface name of type dced_string_t.
annotation
An annotation about the purpose of the interface
(type dced_string_t). This field is for user
display purposes only.
flags The flag field is of type unsigned32 and currently
has only one bit field defined, service_c_disabled.
If this flag is set, it indicates that the service
is not currently available for the server. Also, the
dced Endpoint Mapper will not map an endpoint to a
disabled service. Several values are also reserved
for vendor-specific use and include
service_c_vendor1, service_c_vendor2,
service_c_vendor3, and service_c_vendor4.
entryname The entry name (type dced_string_t) is a hint as to
where this service appears in the namespace. If the
value is NULL, the value in the entryname field of
the server_t structure is used.
objects This is a list of objects supported by the service.
The list is of type uuid_list_t.
operations
This is a list of operation numbers of type
dced_opnum_list_t. This field is not currently used.
towers This is a list of protocol towers of type
dced_tower_list_t, specifying the endpoints
where this server can be reached.
srvrexec_stop_method_t
The server execution stop method is an enumerated type with
one of the following values:
srvrexec_stop_rpc Stops the running server gracefully by
letting the server complete all out-
standing remote procedure calls. This
causes dced to invoke the
rpc_mgmt_server_stop_listening()
routine in that server.
srvrexec_stop_soft This uses a system-specific mechanism
such as the SIGTERM signal. It stops
the running server with a mechanism that
the server can ignore or intercept in
order to do application-specific cleanup.
srvrexec_stop_hard This uses a system-specific mechanism
such as the SIGKILL signal. It stops
the running server immediately with a
mechanism that the server cannot inter-
cept.
srvrexec_stop_error This uses a system-specific mechanism
such as the SIGABRT signal. The local
operating system captures the server's
state before stopping it, and the server
can also intercept it.
uuid_list_t
A list of UUIDs in the following format:
count An unsigned32 number representing the number of
UUIDs in the list.
list A pointer to an array of UUIDs where each element
is of type uuid_t.