NAME
   dce_printf
   dce_fprintf
   dce_sprintf - Formatted DCE message output routines

 SYNOPSIS

   #include <dce/dce.h>

   int dce_printf( unsigned32 messageid, . . . );

   int dce_fprintf( FILE *stream, unsigned32 messageid, . . . );

   unsigned char *dce_sprintf( unsigned32 messageid, . . . );

 PARAMETERS

   Input

   messageid
             The message ID, defined in the message's code field in
             the sams file.

   stream    An open file pointer.

   . . .     Any format arguments for the message string.

 DESCRIPTION

   The dce_printf() routine retrieves the message text associated with
   the specified messageid, and prints the message and its arguments on
   the standard output. The routine determines the correct message
   catalog and, if necessary, opens it. If the message catalog is
   inaccessible, and the message exists in an in-memory table, then this
   message is printed. If neither the catalog nor the default message is
   available, a default message is printed.

   The dce_fprintf() routine functions much like dce_printf(), except
   that it prints the message and its arguments on the specified stream.

   The dce_sprintf() routine retrieves the message text associated with
   the specified messageid, and prints the message and its arguments into
   an allocated string that is returned. The routine determines the
   correct message catalog and, if necessary, opens it.  If the message
   catalog is inaccessible, and the message exists in an in-memory table,
   then this message is printed. If neither the catalog nor the default
   message is available, a default message is printed.  The
   dce_pgm_printf() routine is equivalent to dce_printf(), except that it
   prefixes the program name to the message (in the standard style of DCE
   error messages), and appends a newline to the end of the message.  For
   more information, see the dce_pgm_printf reference page.

 EXAMPLES

   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);
            puts(my_msg);
            free(my_msg);

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

            dce_printf(arg_msg, 2, 8);

 ERROR CODES

   See dce_msg_get.

 NOTES

   The final formatted string generated by dce_sprintf() must not
   exceed 1024 bytes.

 RELATED INFORMATION

   Functions: dce_msg_get_msg
              dce_svc_set_progname