PreviousNext

Overview - Using the DCE Serviceability Application Interface

DCE serviceability was originally developed simply as a way of standardizing server messages. The goal of its design was to make sure that all situations requiring human intervention that can be encountered by a server are documented and identified (both by the server when reporting them, and by the documentation when explaining them) in a standard coordinated way so that system administrators can easily determine the proper corrective action to take in response. Both the server message text and the relevant documentation are derived from the same source (that is, a .sams input file), which minimizes the possibility of any discrepancies appearing between the two.

The serviceability component is used by the DCE components (RPC, DTS, Security, and so on) for their server messaging, and it is made available as an API for use by DCE application programmers who wish to standardize their applications' server messaging. (The DCE components are required to use the serviceability routines, but applications are not.)

Serviceability uses XPG4 message catalogs to hold message text, but it adds an additional layer to the XPG4 functionality. The message catalogs and other required data (and documentation) files are generated by a utility called sams ("symbols and message strings"). Its input is a text file that establishes some organizational information about the program that is to use the messages, followed by a series of specifications of the messages themselves.

Each message specification contains, along with the message text itself, a detailed explanation of the situation in which the message will be displayed, together with a description of the action required, where applicable, to correct the situation. Part of the output of sams thus consists of "automatic" documentation of all the messages writeable via the serviceability API. This output was used as the basis of the contents of the OSF DCE Problem Determination Guide for the DCE component server messages.

Messages also have one or more attributes specified in the sams input file. The attributes fall into three broad categories: those that indicate message severity, those that 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.

More:

How Programs Use Serviceability

Simple Serviceability Interface Tutorial

Serviceability Input and Output Files