NAME
   dce_error_inq_text - Retrieves message text associated with a DCE
                        error code

 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
   dependant 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\n",
                         caller,
                         error_string );

        }