In order to print any message through the serviceability interface, we must first define the message in a sams file and process the file with the sams utility. For the hello_svc program, we will define a sams file with the "bare minimum" contents necessary. Additional information on the use of sams can be found in the sams(1dce) reference page.
Each line in a sams file consists of a simple header and value combination. The header indicates the meaning of the value being specified, and value is the value itself. A sams file for serviceability use is made up of three parts. The first part consists of a minimum of one line that specifies the name of the component (that is, the application) that is to use the messages that will be generated from the file.
The component name that you specify at the top of a sams file must consist of a three-character (no more, no less) string. For the Hello World program, we will use the component name hel:
# Part I of simple sams file ...
component hel
The hel string will be used to identify all the files and data structures that sams will generate from the file.
The second part of the sams file contains some additional serviceability-specific information about the message data structures that will be generated. (This information is necessary if the sams file is intended for serviceability use because sams is also used to generate message files for general, nonserviceability use.)
This part of the file specifies the names of the serviceability table and the serviceability handle. It also contains a list of the component's subcomponents. A subcomponent consists of a distinct functional module of executing code. For example, most distributed applications would have a basic server subcomponent, a reference monitor subcomponent that would handle authorization decisions, and one or more subcomponents that would contain the application's particular functionality.
The serviceability interface finds a component's messages in one or more subtables, each one associated with a subcomponent. When the message is displayed or written, the associated subcomponent name is written in a field of the message. This allows messages to be distinguished during routing or other processing on the basis of the subcomponent with which they are associated.
Following is what the second part of our simplified sample sams file looks like. We call the serviceability table hel_svc_table, and we call the serviceability handle hel_svc_handle. Although we have used the three-letter component code hel in these names, we were under no obligation to do so; we could have named the table and the handle anything we wanted. (We will need to know both of these names when we make the call in the application to initialize the interface in preparation for displaying messages.)
A component must have at least one subcomponent specified in its sams file. Subcomponents are specified in this part simply by supplying their table index, their name, and their descriptive id in a series of separate lines, one per subcomponent and each one beginning with the sub-component keyword, between a set of start and end keywords:
# Part II
serviceability table hel_svc_table handle hel_svc_handle
start
subcomponent hel_s_main "main" hel_i_svc_main
end
In our example,
hel_s_main
is the table index name for the subcomponent. Serviceability routines need this name in order to locate and print any of the subcomponent's messages.
main
is the name of the subcomponent, specified in quotes.
hel_i_svc_main
is a name that will be used (later on in the file) to identify a message that describes the subcomponent.
(Note that sams assigns values to all of these indexes automatically.)
The third (and final) part of the sams file consists of a series of records that specify the messages themselves. Each record is delimited by the start and end keywords. Within each record, a series of keywords identifies the various information that each message consists of or has associated with it.
Our file will contain only one message, the text of which is to be "Hello World". The record that specifies it is as follows:
# Part III
start
code hel_s_hello
subcomponent hel_s_main
attributes "svc_c_sev_notice | svc_c_route_stderr"
text "Hello World"
explanation "A short informational greeting"
action "None required."
end
The keywords specified have the following meanings:
start
Marks the beginning of a message definition. This keyword can optionally be followed by various values.
· A number following the keyword specifies that the ID that is generated by sams for the message should be based on (number multiplied by 100). This allows the ID numbers of messages that belong to the same subcomponent of an application to be in the same numerical subseries (collection), even if additional messages for subcomponents have to be added later on. If each subcomponent's first message is started with a collection number that allows for enough extra ID space in the previous subcomponent to accommodate a reasonable number of future additional definitions, then each subcomponent's ID series will be able to maintain its unbroken series.
As mentioned, the default size of a collection number is 100. Thus, the following collection specification is interpreted as "200":
start 2
To change the default collection size, specify
collection size dddd
(where dddd is the collection size you desire) in a separate line in Part 1 of the sams file.
code
Identifies the message.
sub-component
Identifies the subcomponent that will use the message. (This must also have been defined in Part II of the sams file.)
attributes
Specifies various things about the message: what kind of message it is, how it is to be routed, and so on. Multiple attributes are specified by ORing their values
together. In the example shown, the message has the severity attribute svc_c_sev_notice, and the routing attribute svc_c_route_stderr; the latter forces the
message to be routed to stderr whenever it is written by a serviceability routine.
text
Specifies the text of the message itself.
explanation
Describes the meaning of the message. The text following this keyword is used to generate the documentation of the component's messages.
action
Describes any action(s) that should be taken in response to the message. The text following this keyword is used to generate the documentation of the component's
messages.
Not all the possible keywords are illustrated in our example, and, of those illustrated, only code and text are required in all circumstances. In the example, explanation and action have been specified because it is simpler at this point to do so than to leave them out, and attributes and sub-component have been specified for reasons that will be made clear later on.
This final part of the sams file also contains a series of one or more records that specify messages identifying each of the subcomponents themselves. Since our application has only one subcomponent, it contains only one such subcomponent-identifying message:
# Part IIIa
# Messages for serviceability table
start !intable undocumented
code hel_i_svc_main
text "hello_svc main"
end
The keywords have the same meanings as they did in the "Hello World" message. A couple of flags have been specified after the start keyword. The first will cause the message to not be generated in the message table, and the second means that the message does not need any explanation or action text associated with it. By specifying undocumented (with intable, to cause the message to actually be generated even though it was to be undocumented) for the Hello message, we could have eliminated the explanation and action keywords there also.