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