sams(1)sams(1)NAMEsams - Builds DCE message system files
SYNOPSISsams [-d dest_dir] [-f] [-I interface] [-m] [-n output_name]
[-o output_files] [-s sort_style] [-t table] [-x] file
ARGUMENTS
Specifies the directory in which files are to be created. The default
is the current directory. Turns off text-field filtering for the <a|b>
construct (described below). Names the IDL interface that is to con‐
tain const declarations for all message numbers. Generates one docu‐
mentation file for each message. Each filename is named by the sym‐
bolic message code. Specifies the base name of the output files. See
below. Specifies which files to generate. See below. The default is
to generate all files. Specifies the order in which documentation
entries are to be generated. The order is indicated by one of the fol‐
lowing letters: Alphabetic by message name. Numeric by message number.
Alphabetic by message text. Generates an in-core message table that
includes only those messages that are in the specified table. The
default is to include all messages. Checks each message string that
contains more than one printf-style argument specification to make sure
that it follows the XPG4 convention of %d$, where d is a digit. Note
that message text should normally not have to use the XPG4 conventions
because sams will automatically insert them when generating the cata‐
log.
DESCRIPTION
The sams utility reads the specified input file and creates a number of
output files. The name sams stands for ``symbols and message
strings'', which is what the program manipulates. The input file con‐
sists of keywords, numbers, and text. Whitespace, except in quoted
strings, is used only to separate tokens. If the text is a simple
word, it can be entered unquoted. Text that is a keyword or that spans
multiple lines must be enclosed within quotes. Within such quoted
text, leading and trailing newlines are ignored, and the usual C
escapes (for example, \t for a tab) are accepted. In addition, spaces
and tabs after a newline are ignored. If you need leading whitespace,
use the two-character sequence \n followed by the spaces.
An unquoted # (number sign) introduces a comment. Everything from the
# to the end of the line is ignored.
Generated Output
A DCE message identifier is a 32-bit number that is divided into three
parts: a technology, a component, and the message code. The technol‐
ogy and component fields are assigned by OSF; the message code is
assigned by sams or specified in the input file.
The technology and component determine the name of all files generated
by sams, including the message catalog. The dce_msg routines know how
to parse a message identifier and reconstruct the message catalog name
and retrieve the desired text by using the code field.
For DCE and DFS source code, the technology will be ``dce'' or ``dfs''
and the component will be a three-letter name. For application code,
the technology is part of the component, which is a number specified by
OSF, but the word ``dce'' is always used.
The sams utility creates a number of output files, as specified by the
-o flag. This flag takes a set of letters, picked from the following
table. The component (and technology) headers determine part of the
file names. This can be overridden by using the -n flag to specify the
base name. Note that this does not replace the name under which the
message catalog must be installed. For example, given dce as the tech‐
nology and XXX as the component name, the following files would be cre‐
ated: Letter File Description
c dceXXX.cat Catalog created by gencat; the message file is
assumed to have already been generated
d dceXXXmsg.man Subset of a Unix-style manpage
h dceXXXmsg.h Header file mapping codes to message numbers
i interface.idl IDL file defining message identifier constants
m dceXXX.msg Message file for gencat program
p dceXXXmsg.sml Problem determination guide
s dceXXXsvc.c Serviceability table
S dceXXXsvc.h Serviceability header file
t dceXXXmsg.c Table mapping message numbers to short text;
this is the in-core table of default message
texts u dceXXXmac.h Serviceability-use convenience macros
x dceXXX.idx Index file for building a problem determina‐
tion book
Input format
The input file is divided into three parts; the second part is
optional.
The first part of the input file specifies a set of headers in the fol‐
lowing format: header value They must be chosen from the following
set: The number of messages in each collection (see below). The
default value is 100. The name of the component for which the messages
are being generated for the DCE or DFS technology provided by OSF. Com‐
ponent names must be three characters long. The numeric value of the
component, for application code. The default flags that should be
assigned to all messages that do not specify their own flags. The
flags should be chosen from the following set: Put the message in the
message catalog Put the message in the in-core text table Message text
is long, usually meaning it will not be returned as a status code, but
instead used only as a message to be displayed to the user Do not put
this message in any generated documentation files (that is, man pages
or Problem Determination Guide) Reserve a number for this message but
do not output any reference to it Same action as obsolete
Each flag may be preceeded by the word not or a ! (exclamation point)
to reverse its meaning. This header is optional; the default value is
intable incatalog not undocumented not obsolete. The name of the tech‐
nology provided by OSF for which the messages are being generated. This
header may be omitted; the default value is dce. Technology names must
be three characters long. The low-order bits of the status code to be
assigned to messages. This header may be omitted; the default value is
1. The name of the in-core message table that is created. This header
may be omitted; the default value is XXX_msg_table where XXX is the
component name or just msg_table for application code.
A typical header might look like this: technology dce component dts
table dts_msg_table
The optional second part of the input file is used to specify the DCE
serviceability table and handle. It should appear in the following
format: serviceability table name handle handle_name start subcompo‐
nent_list end The table specifies the name of the subcomponent table,
as described in the service.idl interface. The handle field specifies
the name of the serviceability handle to be used with this component.
(For more information, see dce_svc_register(3).)
The subcomponent_list argument is a series of lines in the following
format: sub-component table_index subcomp full_descr_id Where ta‐
ble_index is the name of a #define (put in the serviceability header
file) that will be used as the subscript into the table. The subcomp
part is a single word (in quotes, if needed, so that it will not be
mistaken for a sams keyword) that names the subcomponent and is used to
``group'' related messages. The full_descr_id is the code for the mes‐
sage that contains the full description of the subcomponent. For exam‐
ple: serviceability table dst_svc_table handle dts_svc_handle start
sub-component dts_s_general "general" dts_i_svc_general
sub-component dts_s_provider "provider" dts_i_svc_provider end This
indicates that there are two subcomponents.
Note that each sub-component must have an entry somewhere in the third
part of the file that is a standard message code that contains the full
text describing the sub-component. For example: ## Messages for ser‐
viceability table start !intable undocumented
code dts_i_svc_general text "General administra‐
tive actions" end
start !intable undocumented
code dts_i_svc_provider text "Interactions with
time-providers" end
The third part of the input file is usually the largest part. It con‐
sists of a series of records where each record specifies one message.
Each record is of the following form: start [flags]
field_list end The flags are optional and are described for the
default header above. If specified, they are used instead of the
default value. A common mistake is to believe that they act as addi‐
tions to the default flags specified in the first part of the file.
The field_list is a set of key-value pairs from the following list: The
text describes the action that should be taken when this error occurs.
The text appears in the generated documentation. This field is
optional and ignored if the message is undocumented. The text
describes the attributes for this message. If this field and the sub-
component field described below are both present, then a convenience
macro will be generated that provides all of the arguments to the ser‐
viceability messaging routine. This is described in more detail below.
This is the symbolic name of the message. It is used to create a
header file that has #define statements that map all symbolic message
names to their numeric value. It also appears in the generated docu‐
mentation. An optional value may be given when needed to ensure com‐
patibility with older message versions. By default, values are
assigned by a simple counter in the order in which messages appear in
the file. This is used to specify the software engineer responsible
for the code where this message could occur. This field is optional
and is never output. This is a verbose description of the message; it
can be blank if the message is not for an error condition. It appears
in the documentation files and should provide additional information
that can be used for fault isolation. This field is optional if the
message is undocumented. Optional notes for translators. This text,
if it exists, appears as comments in the message catalog. This field
is used in conjunction with the attributes field. It specifies which
subcomponent the message is assigned to. The table_index must be one
of the indices that is specified in the serviceability table portion of
the file. If a single component is used for several executables, the
message table can get unreasonably large, containing texts that will
never be used. This keyword may be used to specify a space-separated
list of tables for which the message is appropriate; the table to be
generated is specified by the -t flag. If this keyword is not used or
if the -t flag is not given, then the message will appear in the table.
Otherwise, the message will appear in the table only if the table spec‐
ified by the flag is also specified on this line. The message itself.
It is stored in the in-core message table (unless the not intable flag
is given) and in the message catalog. It is intended to be returned by
dce_error_inq_text() and related routines (see dce_msg_intro(3)).
Unless the longtext flag is given, the text must be shorter than the
size of the dce_error_string_t typedef defined in dce/dce_error.h. The
text field is used as a printf-style format string and is generated in
documentation. To support this dual-use, sams provides a <a|b> con‐
struct. When generating message strings to be used in a program, the
``a'' text is used; when generating documentation, the ``b'' text is
used. For example text "Function <%s|func> failed, sta‐
tus=<0x%8.8lx|code>" If the text includes a space, you must enclose it
in double quotes. Newlines are removed and whitespace is changed to one
space. To write a single less-then sign, prefix it with a backslash.
Two typical message records might look like this: start
code dts_s_ok text "Successful completion"
notes "Ok, yes, etc." explanation "Operation performed."
action "None required." end
start code dts_s_bad_timestring text "Invalid
time string" explanation "The given string could not be parsed as a
valid time specification." action "Correct
input and try again." end
In addition, the following constructs are accepted, but ignored. This
is for compatibility with other systems that might need such fields:
administrator response text operator response text programmer response
text severity text system response text user response text vendor name
text
Many messages can also be assigned to a single subcomponent and used
with a single set of attributes. This is the largest part of the ser‐
viceabilty work. If a message has both the attributes and sub-compo‐
nent fields specified, then a convenience macro will be generated that
specifies the initial parameters to the dce_svc_printf() call.
Here is a sample message definition: start
code dts_s_out_of_range attributes "svc_c_sev_fatal |
svc_c_action_exit_bad" sub-component dts_s_provider
text "illegal value %ld from %s provider" explana‐
tion "Received illegal value from local time provider."
action "Fix provider and restart server." end An example of
using it to generate a serviceability message is this:
dce_svc_printf(DTS_S_OUT_OF_RANGE_MSG, 123, "Sundial");
Allowing for Growth
It is good practice to group related messages together, but you should
leave space to allow additional messages to be added later. The sams
utility provides two ways to do this.
First, the message numbering can be explicitly set using the following
construct: set value = number
Note that the number used in this construct specifies the code field as
in the value header, and not the full message identifier, as can be
assigned by giving a value in the code field.
Second, messages can group into a collection, which is similar to an
XPG4 message catalog set. To indicate the start of a collection use
the following construct: start collection number
This is equivalent to using the first construct, except that the number
is multiplied by the collection size. A common practice is to have at
least one collection for each serviceability sub-component.
RELATED INFORMATION
Functions: dce_error_inq_text(3), dce_svc_printf(3).
Commands: gencat(1) in the OSF/1 Command Reference.
sams(1)
