sams(1dce)

Synopsis

sams [-d dest_dir] [-f] [-g gencat_command] [-I interface] [-m] [-n output_name]
[-o output_files] [-s style] [-t table] [-x] input_file

Options

-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 later in this reference page).

g gencat_command
Invokes the platform-specific gencat command specified by gencat_command. Enclose gencat command strings that contain spaces in single quotes. For example, to invoke gencat when sams is invoked, use the -g option in the form: -g 'gencat -m'.

-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 file name is named by the symbolic message code.

-n output_name
Specifies the base name of the output files.

-o output_list
Specifies which files to generate. 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 that message text should normally not have to use the XPG4 conventions because sams automatically inserts them when generating the catalog.

Arguments

input_file
Specifies the message input file.

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. White space, 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 escape sequences (for example, \t for a tab) are accepted. In addition, spaces and tabs after a newline are ignored. If you need leading white space, 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 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 is dce or dfs and the component is 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
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

This set must be chosen from the following set:

collection size value
The number of messages in each collection. 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
Puts the message in the message catalog.

intable
Puts 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.

undocumented
Do not put this message in any generated documentation files (that is, manpages or the OSF DCE Problem Determination Guide).

obsolete
Reserves a number for this message but do not output any reference to it.

reserved
Same action as obsolete.

Each flag may be preceded 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 can 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 looks like this:

technology dce
component dts
table dts_msg_table

The optional second part of the input file specifies 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 name field specifies the name of the subcomponent table, as described in the service.idl interface. The handle handle_name field specifies the name of the serviceability handle to be used with this component. (For more information, see dce_svc_register(3dce).)

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 is used as the subscript into the table.

subcomp
is a single word (in quotes, if needed, so that it is not mistaken for a sams keyword) that names the subcomponent and is used to group related messages.

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
subcomponent dts_s_general "general" dts_i_svc_general
subcomponent dts_s_provider "provider" dts_i_svc_provider
end

This indicates that there are two subcomponents.

Note that each subcomponent must have an entry in the third part of the file that is a standard message code that contains the full text describing the subcomponent. 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 as previously described for the default header. If specified, the flags 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:

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 subcomponent field are both present, then a convenience macro is generated that provides all the arguments to the serviceability messaging routine.

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 can 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
Specifies 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 with the attributes field. It specifies the subcomponent that the message is assigned to. The table_index must be one of the indices that is specified in the serviceability table part of the file.

tables (name ...)
If a single component is used for several executables, the message table can get unreasonably large, containing texts that are never used. This keyword can 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 appears in the table. Otherwise, the message appears 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(3dce)). 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 white space is changed to one space. To write a single less-than 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 serviceability work. If a message has both the attributes and subcomponent fields specified, then a convenience macro is generated that specifies the initial parameters to the dce_svc_printf( ) call.

The following 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 be grouped 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 subcomponent.

More:

Errors

Related Information