OSF DCE Application Development Guide--Core Components

OSF DCE Application Development Guide—Core Components
Because we executed the simplest form of the sams command (that is, without
specifying any output flags), the full repertory of sams output files was created, even
though the following files were not needed for our application:
• dcehel.msg and dcehel.cat
The file dcehel.msg is input to gencat when it is invoked by sams to create
dcehel.cat, the message catalog. (Although our example application used in-memory
tables, the serviceability routines always attempt to use the message catalog first.)
• dcehelmsg.man and dcehelmsg.sgm
These are automatically generated documentation files (their nature and purpose
were previously described) that have nothing to do with the operation of the interface
itself.
The many additional features of serviceability will be described in the following
sections. A definitive description of sams and the contents of sams files can be found on
the sams(1dce) reference page.
4.2 Integrating Serviceability into a Server
The purpose of the preceding tutorial was simply to give a brief taste of what it feels like
to use the interface. The main task involved in using serviceability does not, however,
lie in mastering the mechanics of the interface, but rather in understanding the purpose of
handling server messages in this way, and then applying this understanding in order to
develop an effective and serviceable messaging strategy for one’s own application.
4.2.1 Serviceability Strategy
The serviceability mechanism is designed to be used mainly for server informational and
error messaging—that is, for messages that are of interest to those who are concerned
with server maintenance and administration (in the broadest sense of these terms). The
essential idea of the mechanism is that all server events that are significant for
maintaining or restoring normal operation should be reported in messages that are made
to be self-documenting so that (provided all significant events have been correctly
identified and reported) users and administrators will by definition always be able to
learn what action they should take whenever anything out of the ordinary occurs. User-
prompted, interactive, client-generated messaging should be handled through the DCE
messaging interface, which is described in Chapter 3.
It follows that serviceability is not just an interface; it is partly a state of mind. The first
thing that a developer who wishes to use serviceability should do is examine his or her
server code with a view to identifying all the event points that should be covered by
serviceability calls. Once these have been determined, the sams file (containing the
message definitions) should be written; the last step will be to insert the messaging calls
into the code.
4− 14 Tandem Computers Incorporated 124245