NAME

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(5) 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