Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Apropos / Subsearch:
optional field

 sams(1)		  Open Software Foundation		     sams(1)

      sams - Builds DCE message system files

      sams [-d dest_dir] [-f] [-I interface] [-m] [-n output_name]
      [-o output_files] [-s sort_style] [-t table] [-x] file

      -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 <&lt&lt&lt;a|b>&gt&gt&gt; 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

 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.

      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

      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

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

 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

 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

 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

 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 <&lt&lt&lt;a|b>&gt&gt&gt; 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 <&lt&lt&lt;%s|func>&gt&gt&gt; failed, status=<&lt&lt&lt;0x%8.8lx|code>&gt&gt&gt;"

		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

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

 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