NAME

sams - Builds DCE message system files

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_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 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 interfaceNames the Interface Definition Language (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. 

-o output_filesSpecifies which files to generate.  The default is to generate all files. 

-s 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. 

ARGUMENTS

input_fileSpecifies 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.  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 # (number sign) 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_∗(3dce) 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 Distributed File System (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 name 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 filenames.  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 reference page
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:

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:

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. 

undocumentedDo not put this message in any generated documentation files (that is, reference pages or the OSF DCE 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 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 the following:

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 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 the dce_svc_register(3dce) reference page.) 

The subcomponent_list argument is a series of lines in the following format:

sub-component table_index subcomp full_descr_id

where:

table_indexis the name of a #define (put in the serviceability header file) that will be used as the subscript into the table. 

subcompis 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. 

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 somewhere in the third part of the file (described in the following section) that is a standard message code that contains the full text describing the subcomponent.  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 as previously described for the default header.  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 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 later in this section 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 later in this section. 

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. 

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 the dce_msg_intro(3dce) reference page).  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.  The following is an 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-than sign, prefix it with a backslash. 

Two typical message records might look like the following:

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. 

The following is a sample message definition:

start
codedts_s_out_of_range
attributes"svc_c_sev_fatal | svc_c_action_exit_bad"
subcomponentdts_s_provider
text"illegal value %ld from %s provider"
explanation"Received illegal value from local time-provider."
action"Fix provider and restart server."
end

The following is an example of using the definition to generate a serviceability message:

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 by 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 subcomponent. 

ERRORS

A representative list of errors that might be returned is not shown here.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

RELATED INFORMATION

Commands: gencat(1). 

Functions: dce_error_inq_text(3dce), dce_svc_printf(3dce).