DCE, dce_intro, dce_msg_intro
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
/sys$common/syshlp/helplib.hlb DCE, dce_intro, dce_msg_intro *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
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
Additional Information (explode) :
|
|
