For our example, we will define a sams file with the minimum contents necessary to print the one brief message we want to display. (Additional information on the use of sams can be found in the OSF DCE Command Referencesams(1dce) reference page, which contains comprehensive descriptions of all aspects of the utility.)
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 messaging use is normally made up of three parts (although only two parts are needed for the short example in this topic). 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.
Each invocation of sams to process a separate .sams input file produces a complete set of output files that can be used by the DCE messaging routines to print or log messages as required. These sets of output files are organized by DCE component. (In DCE itself, these components are identical to the DCE components: RPC, DTS, and so on; for applications, the categorization of components is determined by the developer.) Each set of output files will have names in which the component name (also determined by the developer) appears.
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 message 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 (and final) part of a sams file for DCE messaging 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:
start
code hello_msg
text "Hello World"
action "None required"
explanation "Greeting message for sample messaging program"
end
The keywords specified have the following meanings:
code
Identifies the message.
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.