NAME
      dce_msg_intro - Introduction to the DCE messaging interface

  DESCRIPTION

  All DCE message texts are assigned a unique message ID. This is a
  32-bit number, with the special value of all-bits-zero reserved to
  indicate success.  All other numbers are divided into a
  technology/component that identifies the message catalog, and an
  index into the catalog.

  All messages for a given component are stored in a single message
  catalog generated by the sams utility when the component is built.
  (The messages may also be compiled into the application code,
  rendering the successful retrieval of message text independent of
  whether or not the message catalogs were correctly installed.)

  In typical use, a message is first retrieved from a message catalog,
  allowing localization to occur.  If this fails, the default message
  is retrieved from an in-memory table.  If this fails, a fallback text
  identifying the message number is generated.  The two most useful
  routines, dce_error_inq_text() and dce_msg_get(), and the DCE printf
  routines follow these rules.  The rest of this API gives direct access
  for special needs.

  The dce_msg_cat_xxx() routines provide a DCE abstraction to standard
  message catalog routines, mapping DCE message IDs to message catalog
  names.  They offer a convenient way of opening and accessing a message
  catalog simply by supplying the ID of a message contained in it,
  rather than the name of the catalog itself.  Once opened, the catalog
  is accessed by means of an opaque handle (the dce_msg_cat_handle_t
  typedef).

  THE DCE MESSAGING ROUTINES

  The messaging routines are as follows, listed in alphabetical order:

  dce_error_inq_text()
                      Retrieves from the installed DCE component
                      message catalogs the message text associated
                      with an error status code returned by a DCE
                      library routine.

  dce_fprintf()       Functions much like dce_printf(), except that
                      it prints the message and its arguments on the
                      specified stream.

  dce_msg_cat_close() Closes the message catalog (which was opened with
                      dce_msg_cat_open()).

  dce_msg_cat_get_msg()
                      Retrieves the text for a specified message.

  dce_msg_cat_open()  Opens the message catalog that contains the
                      specified message, and returns a handle that
                      can be used in subsequent calls to
                      dce_msg_cat_get_msg().

  dce_msg_define_msg_table()
                      Registers an in-memory table containing the
                      messages.

  dce_msg_get()       Retrieves the text for a specified message.
                      A "convenience" form of the
                      dce_msg_get_msg() routine.

  dce_msg_get_cat_msg()
                      A "convenience" form of the
                      dce_msg_cat_get_msg() routine. Unlike
                      dce_msg_cat_get_msg(), dce_msg_get_cat_msg()
                      does not require the message catalog to be
                      explicitly opened.

  dce_msg_get_default_msg()
                      Retrieves a message from the application's in-
                      memory tables.

  dce_msg_get_msg()   Retrieves the text for a specified message.

  dce_msg_translate_table()
                      The dce_msg_translate_table() routine overwrites
                      the specified in-memory message table with the
                      values from the equivalent message catalogs.

  dce_pgm_fprintf()   Equivalent to dce_fprintf(), except that it
                      prepends the program name and appends a newline.

  dce_pgm_printf()    Equivalent to dce_printf(), except that it
                      prepends the program name and appends a newline.

  dce_pgm_sprintf()   Equivalent to dce_sprintf(), except that it
                      prepends the program name and appends a newline.

  dce_printf()        Retrieves the message text associated with the
                      specified message ID, and prints the message and
                      its arguments on the standard output.

  dce_sprintf()       Retrieves the message text associated with the
                      specified message ID, and prints the message and
                      its arguments into an allocated string that is
                      returned.

  DATA TYPES AND STRUCTURES

  dce_error_string_t  An array of characters big enough to hold any
                      error text returned by dce_error_inq_text().

  dce_msg_cat_handle_t
                      An opaque handle to a DCE message catalog.
                      (Use dce_msg_cat_open() to get a handle.)

  FILES

      dce/dce_msg.h

  RELATED INFORMATION

      BOOKS: OSF DCE Application Development Guide