dce_svc_printf(3dce)
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(3) 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:
svcsvc_c_action_abort
svcsvc_c_action_exit_bad
svcsvc_c_action_exit_ok
svcsvc_c_action_brief
svcsvc_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.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
This routine has no return value.
Related Information
Functions: dce_svc_register(3dce)