OSF DCE Application Development Guide--Core Components

OSF DCE Application Development Guide—Core Components

• dce_svc_printf( )

This is the normal call for writing or displaying serviceability messages. It cannot be

called with a literal text argument; instead, the message text and other necessary

information must be pre-speciﬁed in a ﬁle that is processed by the sams utility, which

in turn outputs sets of tables from which the messages are extracted for output. The

tutorial in Section 4.1.2 provides a brief example of how this is done.

There are two main ways in which to call the routine. If a message has been deﬁned

in the sams ﬁle with both sub-component and attributes speciﬁed, 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(HEL_S_HELLO_MSG);

The convenience macro’s name will be generated from the uppercase version of the

message’s code value (as speciﬁed in the sams ﬁle), 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. For the hel_s_hello message, such a form of the call might look as follows:

dce_svc_printf(DCE_SVC(hel_svc_handle, ""), hel_s_main,\

svc_c_sev_error | svc_c_route_stderr, hel_s_hello);

DCE_SVC() is a macro that must be passed as the ﬁrst 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

speciﬁers. The hel_s_hello message had no argument speciﬁers, so an empty string

is passed here to DCE_SVC. For an example of printing a message with arguments,

see the end of this subsection.

The remaining arguments passed to dce_svc_printf( ) are as follows:

— Subcomponent table index

This symbol was declared in the sub-component list coded in Part II of the sams

ﬁle; 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 a severity here (for a list of

message severity values, see Section 4.3.3). Multiple attributes are ORed

together, as shown in the example.

There are four categories of message attributes:

routing The available routing attribute constants are

— svc_c_route_stderr

4− 18 Tandem Computers Incorporated 124245