dce_error_inq_text(3dce)

Synopsis

#include <dce/dce_error.h>

void dce_error_inq_text(

error_status_t status_to_convert,

dce_error_string_t error_text,

int *status);

Parameters

Input

status_to_convert
DCE status code for which text message is to be retrieved.

Output

error_text
The message text associated with the status_to_convert.

status
Returns the status code from this operation. The status code is set to 0 on success, and to -1 on failure.

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

All DCE message texts are assigned a unique 32-bit message ID. The special value of all-bits-zero is reserved to indicate success.

The dce_error_inq_text( ) routine uses the message ID as a series of indices into the correct DCE component's message catalog; the text found by this indexing is the message that explains the status code that was returned by the DCE or DCE application routine.

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 component code, rendering the successful retrieval of message text independent of whether or not the message catalogs were correctly installed.)

If the user sets their LANG variable and has the correct message catalog files installed, the user can receive translated messages. That is, the text string returned by dce_error_inq_text( ) is dependent on the current locale.

Examples
The following code fragment shows how dce_error_inq_text( ) can be used to retrieve the message text describing the status code returned by a DCE RPC library routine:

dce_error_string_t error_string;
error_status_t status;
int print_status;

rpc_server_register_if(application_v1_0_s_ifspec, &type_uuid,
(rpc_mgr_epv_t)&manager_epv, &status);
if (status != rpc_s_ok) {

dce_error_inq_text(status, error_string, &print_status);

fprintf(stderr," Server: %s: %s\en", caller, error_string);

}