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

−d dest_dirSpecifies the directory in which files are to be created.  The default is the current directory. 

-fTurns off text-field filtering for the <a|b> construct (described below). 

-I interfaceNames the IDL interface that is to contain const declarations for all message numbers. 

-mGenerates one documentation file for each message.  Each filename is named by the symbolic message code. 

-n output_nameSpecifies the base name of the output files.  See below. 

-o output_listSpecifies which files to generate.  See below.  The default is to generate all files. 

-s sort_styleSpecifies the order in which documentation entries are to be generated.  The order is indicated by one of the following letters:

aAlphabetic by message name. 

nNumeric by message number. 

tAlphabetic by message text. 

-t tableGenerates an in-core message table that includes only those messages that are in the specified table.  The default is to include all messages. 

-xChecks 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 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, \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 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:

LetterFileDescription
cdceXXX.catCatalog created by gencat; the message file is
assumed to have already been generated
ddceXXXmsg.manSubset of a Unix-style manpage
hdceXXXmsg.hHeader file mapping codes to message numbers
iinterface.idlIDL file defining message identifier constants
mdceXXX.msgMessage file for gencat program
pdceXXXmsg.smlProblem determination guide
sdceXXXsvc.cServiceability table
SdceXXXsvc.hServiceability header file
tdceXXXmsg.cTable mapping message numbers to short text;
this is the in-core table of default message texts
udceXXXmac.hServiceability-use convenience macros
xdceXXX.idxIndex 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:

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 flagsThe 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:

incatalogPut the message in the message catalog

intablePut the message in the in-core text table

longtextMessage 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, man pages or Problem Determination Guide)

obsoleteReserve a number for this message but do not output any reference to it

reservedSame 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 startThe 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:

technologydce
componentdts
tabledts_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 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
codedts_i_svc_general
text"General administrative actions"
end
 start!intable undocumented
codedts_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:

action textThe 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 textThis 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 textOptional 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.

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 textThe 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
codedts_s_ok
text"Successful completion"
notes"Ok, yes, etc."
explanation"Operation performed."
action"None required."
end
 start
codedts_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 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
codedts_s_out_of_range
attributes"svc_c_sev_fatal | svc_c_action_exit_bad"
sub-componentdts_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.

Hewlett-Packard Company  —  OSF DCE 1.1/HP DCE 1.5