*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> sams (1)              


 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

              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

      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

    Input format    [Toc]    [Back]
      The input file is divided into three parts; the second part is

      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)

                          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

      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

      serviceability table name handle handle_name
      start subcomponent_list

      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

      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
          sub-component dts_s_general  "general"  dts_i_svc_general
          sub-component dts_s_provider "provider" dts_i_svc_provider

      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"

      start           !intable undocumented
      code            dts_i_svc_provider
      text            "Interactions with time-providers"

      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]

      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

      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

                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:

      code            dts_s_ok
      text            "Successful completion"
      notes           "Ok, yes, etc."
      explanation     "Operation performed."
      action          "None required."

      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)


      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:

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

      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

      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.

      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 ]
 Similar pages
Name OS Title
config Tru64 Builds system configuration files
doconfig Tru64 Builds the kernel described by system configuration files
mksas Tru64 Builds a network-bootable Standalone System (SAS) kernel
btcreate Tru64 Builds a bootable Standalone System (SAS) kernel on tape
localedef Tru64 Builds a locale from locale and character map source files
scan Tru64 produce a one-line-per-message scan listing (only available within the message handling system, mh)
alex Tru64 extract addresses from message headers (only available within the message handling system, mh)
dist Tru64 redistribute a message to additional addresses (only available within the message handling system, m...
whom Tru64 report to whom a message is addressed (only available within the message handling system, mh)
refile Tru64 file message in other folders (only available within the message handling system, mh)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service