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