NAME

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:

• 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(3dce), DCE_SVC_DEFINE_HANDLE(3dce).