NAME

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