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