hpux sams man page on unix.com

sams(1) General Commands Manual sams(1)

NAME
sams - Builds DCE message system files

SYNOPSIS
sams [-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 contain const declarations for all message numbers. Generates one
documentation file for each message. Each filename is named by the symbolic 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 documenta-
tion entries are to be generated. The order is indicated by one of the following 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 con-
ventions because sams will automatically insert them when generating the catalog.

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 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, 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
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 tech-
nology 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 follow-
ing table. The component (and technology) headers determine part of the file names. This can be overridden by using the -n flag to spec-
ify 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
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
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: 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. Component 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 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. 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 cre-
ated. 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 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 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 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 serviceability 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 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. 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 cat-
alog. This field is used in conjunction with the attributes field. It specifies which subcomponent the message is assigned to. The ta-
ble_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 specified 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 type-
def 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 generat-
ing 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." 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-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
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)

hpux man page for sams