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