sams(1) Open Software Foundation sams(1)
NAME [Toc] [Back]
sams - Builds DCE message system files
SYNOPSIS [Toc] [Back]
sams [-d dest_dir] [-f] [-I interface] [-m] [-n output_name]
[-o output_files] [-s sort_style] [-t table] [-x] file
ARGUMENTS [Toc] [Back]
-d dest_dir
Specifies the directory in which files are to be created. The
default is the current directory.
-f Turns off text-field filtering for the <a|b> construct
(described below).
-I interface
Names the IDL interface that is to contain const declarations
for all message numbers.
-m Generates one documentation file for each message. Each
filename is named by the symbolic message code.
-n output_name
Specifies the base name of the output files. See below.
-o output_list
Specifies which files to generate. See below. The default is
to generate all files.
-s sort_style
Specifies the order in which documentation entries are to be
generated. The order is indicated by one of the following
letters:
a Alphabetic by message name.
n Numeric by message number.
t Alphabetic by message text.
-t table
Generates an in-core message table that includes only those
messages that are in the specified table. The default is to
include all messages.
-x 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
Hewlett-Packard Company - 1 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
that message text should normally not have to use the XPG4
conventions because sams will automatically insert them when
generating the catalog.
DESCRIPTION [Toc] [Back]
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
consists 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 [Toc] [Back]
A DCE message identifier is a 32-bit number that is divided into three
parts: a technology, a component, and the message code. The
technology 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
technology and XXX as the component name, the following files would be
created:
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
Hewlett-Packard Company - 2 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
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 determination
book
Input format [Toc] [Back]
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
following format:
header value
They must be chosen from the following set:
collection size value
The number of messages in each collection (see below). The
default value is 100.
component comp
The name of the component for which the messages are being
generated for the DCE or DFS technology provided by OSF.
Component names must be three characters long.
component code value
The numeric value of the component, for application code.
default flags
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:
incatalog Put the message in the message catalog
intable Put the message in the in-core text table
longtext 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
Hewlett-Packard Company - 3 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
undocumented
Do not put this message in any generated
documentation files (that is, man pages or Problem
Determination Guide)
obsolete Reserve a number for this message but do not
output any reference to it
reserved 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.
technology tech
The name of the technology 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.
value start
The low-order bits of the status code to be assigned to
messages. This header may be omitted; the default value is
1.
table varname
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 subcomponent_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
Hewlett-Packard Company - 4 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
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 table_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 message that contains the full description of the subcomponent.
For example:
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 serviceability table
start !intable undocumented
code dts_i_svc_general
text "General administrative 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
consists 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 additions to the default flags
Hewlett-Packard Company - 5 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
specified in the first part of the file.
The field_list is a set of key-value pairs from the following list:
action text
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.
attributes text
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 serviceability
messaging routine. This is described in more detail below.
code name [=value]
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 documentation. An optional value
may be given when needed to ensure compatibility with older
message versions. By default, values are assigned by a
simple counter in the order in which messages appear in the
file.
engineer text
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.
explanation text
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.
notes text
Optional notes for translators. This text, if it exists,
appears as comments in the message catalog.
sub-component table_index
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.
Hewlett-Packard Company - 6 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
tables (name ...)
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 specified by the flag is also specified on
this line.
text text 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> construct. 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, status=<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."
Hewlett-Packard Company - 7 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
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
serviceabilty work. If a message has both the attributes and sub-
component 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"
explanation "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 [Toc] [Back]
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.
Hewlett-Packard Company - 8 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
sams(1) Open Software Foundation sams(1)
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 [Toc] [Back]
Functions: dce_error_inq_text(3), dce_svc_printf(3).
Commands: gencat(1) in the OSF/1 Command Reference.
Hewlett-Packard Company - 9 -OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96 [ Back ] |
