Message Output Routines

dce_fprintf( )
Retrieves the message text associated with the specified message ID, and prints the message and its arguments on the specified stream. The message is printed without a concluding newline; if a newline is desired at the end of the message, then it should be coded (as \n) in the message definition in the sams file.

The routine determines the correct message catalog and, if neccessary, opens it. If the message catalog is inaccessible, and the message exists in an in-memory table, then this message (the default message) is printed. If for any reason the message cannot be retrieved, an error message is printed.

dce_printf( )
Performs a dce_fprintf( ) of the specified message to standard output.

dce_sprintf( )
Retrieves the message text associated with the specified message ID, and writes the message and its arguments into an allocated string (which should be freed by the caller). The routine determines the correct message catalog and, if neccessary, opens it. If the message catalog is inaccessible, and the message exists in an in-memory table, then this message (the default message) is printed. If for any reason the message cannot be retrieved, an error message is printed.

For example, assume that the following message is defined in an application's sams file:

start

code arg_msg

text "This message has exactly %d not %d argument(s)"

action "None required"

explanation "Test message with format arguments"

end

The following code fragment shows how dce_sprintf( ) might be called to write the message (with some argument values) into a string:

unsigned char *my_msg;

my_msg = dce_sprintf(arg_msg, 2, 8);

/* Process my_msg as appropriate... */

free(my_msg);

Of course, dce_printf( ) could also be called to print the message and arguments:

dce_printf(arg_msg, 2, 8);

dce_pgm_printf( )
Equivalent to dce_printf( ), except that it prefixes the program name to the message (in the standard style of DCE error messages), whereas dce_printf( ) does not. This allows clients (which do not usually use the serviceability interface) to produce error (or other) messages that automatically include the originating application's name. The message is printed with a concluding newline.

Note that the client should call dce_svc_set_progname( ) first to set the desired application name. Otherwise, the default program name will be

PID#nnnn

where nnnn is the process ID of the application making the call.

dce_pgm_sprintf( )
Equivalent to dce_sprintf( ), except that it prefixes the program name to the string (in the standard style of DCE error messages), whereas dce_sprintf( ) does not. Note that the client must call dce_svc_set_progname( ) first to set the desired application name.

Otherwise, the default name is

PID#nnnn

where nnnn is the process ID of the application making the call.

dce_pgm_fprintf( )
Equivalent to dce_fprintf( ), except that it prefixes the program name to the string (in the standard style of DCE error messages), whereas dce_fprintf( ) does not. The message is printed with a concluding newline.

Note that the client must call dce_svc_set_progname( ) first to set the desired application name. Otherwise, the default name is

PID#nnnn

where nnnn is the process ID of the application making the call.

dce_error_inq_text( )
Opens a message catalog, extracts a message identified by a message ID, and places the message in the space pointed to by the text parameter. If the message catalog is inaccessible, and there is a default message in memory, the default message is copied into the space passed. If neither the catalog nor the default message is available, a status code is placed in the status output parameter and the message is returned as a hexadecimal number; the routine always returns a printable message.

This routine existed in prior releases of DCE and has been modified for DCE Version 1.1 to use the default message arrays. Programs prior to Version 1.1 that use the routine do not need to be modified.

For example, assume that the following message is defined in an application's sams file:

start

code error_msg

text "Error: %s"

action ""

explanation "DCE error status message"

end

The following code fragment shows how dce_error_inq_text( ) could be used to retrieve the error status received from a DCE routine:

dce_error_string_t error_string;

unsigned32 status;

int error_inq_status;

uuid_t type_uuid, obj_uuid;

<. . .>

rpc_object_set_type(&obj_uuid, &type_uuid, &status);

if (status != rpc_s_ok)

{

dce_error_inq_text(status, error_string, &error_inq_status);

dce_printf(error_msg, error_string);

}