OSF DCE Application Development Guide--Core Components

OSF DCE Application Development Guide—Core Components
specify message routing, and those that specify some action (usually some form of
program exit) that should be taken immediately after the message is written. The effect
of the presence of a severity attribute is to cause the message text to contain a severity-
identifying string when displayed or written. The effect of the presence of a routing
attribute is to cause the message to be routed by default to one of a couple of standard
destinations (more flexible routing is available dynamically). The effect of the presence
of an action attribute is to cause the program to terminate execution in one of three ways
as soon as the message has been written or displayed, or to cause a special short form of
the message to be generated.
The serviceability API can also be used by DCE applications. The advantage in using it
consists mainly in the following:
• It allows all application messaging to be routed uniformly, on the basis of the
severity of the message and the functional part of the program originating the
message.
• It allows application messages to be made self-documenting.
Serviceability also contains facilities for debug messaging, which can be compiled in or
out of executables and which can be activated and routed by component at nine different
levels.
4.1.1 HowPrograms Use Serviceability
The DCE serviceability mechanism uses XPG4 message catalogs to hold message text.
Additional files contain the messages’ associated documentation and other extra
information used by the mechanism. All of these files, including the message catalog,
are generated in a single step by running the DCE sams utility. The input to sams is a
single sams file that is written by the developer, and which contains all the necessary
information (text, documentation, additional information) for each message. The
message catalogs and associated information generated by sams are then accessed
whenever dce_svc_printf() or one of the other serviceability routines is called to print or
log a message.
Thus, the result of converting a program to use serviceability will essentially be that all
printf(), fprintf( ), and other such routines will be replaced by calls to dce_svc_printf()
or one of the related serviceability routines. For example, a line of code such as the first
one that follows would be replaced by the second:
fprintf(stderr, "File %s not found\n", filename);
dce_svc_printf(DCE_SVC(cmp _svc_handle, ""), cmp _s_server, \
svc_c_sev_error, cmp_s_file_not_found, filename);
where the constants cmp _s_server and cmp_s_file_not_found were generated by sams,
and identify the server ‘‘subcomponent’’ of the application and the message to be
written, respectively. The cmp_svc_handle constant is the application’s handle to its
serviceability message tables and other necessary data; cmp_s_server is actually an
index to a subtable within this dynamically generated area, and cmp_s_file_not_found is
4− 2 Tandem Computers Incorporated 124245