NAME
dce_msg_intro - Introduction to the DCE messaging interface
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
1 – dce_error_inq_text
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 );
}
2 – dce_msg_cat_close
NAME
dce_msg_cat_close - DCE message catalog close routine
SYNOPSIS
#include <dce/dce_msg.h>
void dce_msg_cat_close( dce_msg_cat_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle
The handle (returned by dce_msg_cat_open()) to the catalog
that is to be closed.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_cat_close() routine closes the message catalog (which
was opened with dce_msg_cat_open()). On error, it fills in status
with an error code.
ERROR CODES
See dce_msg_get
RELATED INFORMATION
Functions: dce_msg_cat_get_msg
dce_msg_cat_open
dce_msg_get_cat_msg
dce_msg_get
dce_msg_get_msg
3 – dce_msg_cat_get_msg
NAME
dce_msg_cat_get_msg - DCE message text retrieval routine
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_cat_get_msg( dce_msg_cat_handle_t handle,
unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
The ID of the message to be retrieved.
handle
A handle (returned by dce_msg_cat_open()) to an opened message
catalog.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
Once the catalog has been opened with the dce_msg_cat_open() routine,
the dce_msg_cat_get_msg() routine can be used to retrieve the text
for a specified message (which is a 32-bit DCE message ID as described
in dce_error_inq_text). If the specified message cannot be found
in the catalog, the routine returns a NULL and fills in status with
the appropriate error code.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_cat_close
dce_msg_cat_open
dce_msg_get_cat_msg
dce_msg_get
dce_msg_get_msg
4 – dce_msg_cat_open
NAME
dce_msg_cat_open - DCE message catalog open routine
SYNOPSIS
#include <dce/dce_msg.h>
dce_msg_cat_handle_t dce_msg_cat_open( unsigned32 message_ID,
error_status_t *status );
PARAMETERS
Input
message_ID
The ID of the message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_cat_open() routine opens the message catalog that
contains the specified message_ID. It returns a handle that can
be used in subsequent calls to dce_msg_cat_get_msg(). On error,
it returns NULL and fills in status with an appropriate error code.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_cat_close
dce_msg_cat_get_msg
dce_msg_get_cat_msg
dce_msg_get
dce_msg_get_msg
5 – dce_msg_define_msg_table
NAME
dce_msg_define_msg_table - Adds a message table to in-memory table
SYNOPSIS
#include <dce/dce_msg.h>
void dce_msg_define_msg_table( dce_msg_table_t *table,
unsigned32 count,
error_status_t *status );
PARAMETERS
Input
table A message table structure (defined in a header file generated
by sams during compilation (see the EXAMPLES section).
count The number of elements contained in the table.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component
(application) is built.
However, the messages may also be compiled directly into the
component code, thus rendering the successful retrieval of message
text independent of whether or not the message catalogs were
correctly installed. Generation of in-memory message tables is
specified by the incatalog flag in the sams file in which the
message text is defined (see SAMS for more information on sams
files). If the messages have been generated at compile time with
this option specified, the dce_msg_define_msg_table() routine can be
called by the application to register an in-memory table containing
the messages.
The table parameter to the call should identify a message table
structure defined in a header file generated by sams during
compilation (see the EXAMPLES section). The count parameter
specifies the number of elements contained in the table. If an
error is detected during the call, the routine will return an
appropriate error code in the status parameter.
EXAMPLES
The following code fragment shows how an application (whose
serviceability component name is app) would set up an in-memory
message table:
#include <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#include "dceappmsg.h" /* defines app_msg_table */
error_status_t status;
The following call adds the message table to the in-memory table.
Note that you must include <dce/dce_msg.h>. You also have to link
in dceappmsg.obj and dceappsvc.obj (object files produced by
compiling sams-generated .c files), which contain the code for the
messages and the table, respectively.
dce_msg_define_msg_table( app_msg_table,
sizeof(app_msg_table) /
sizeof(app_msg_table[0]),
&status );
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_get
dce_msg_get_msg
dce_msg_get_default_msg
6 – dce_msg_get
NAME
dce_msg_get - Retrieves text of specified DCE message
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get( unsigned32 message );
PARAMETERS
Input
message
ID of message to be retrieved.
DESCRIPTION
The dce_msg_get() routine is a convenience'' form of the
dce_msg_get_msg() routine. Like dce_msg_get_msg(), dce_msg_get()
retrieves the text for a specified message (which is a 32-bit DCE
message ID as described in dce_msg_intro). However, dce_msg_get()
does not return a status code; it either returns the specified
message successfully or fails (aborts the program) with an
assertion error if the message could not be found or memory could
not be allocated.
The routine implicitly determines the correct message catalog in
which to access the specified message, and opens it; the caller
only has to call this routine.
The routine first searches the appropriate message catalog for the
message, and then (if it cannot find the catalog) searches the in-
memory message table, if it exists.
The message, if found, is returned in allocated space to which the
routine returns a pointer. The pointed-to space must be freed by the
caller using free.
ERROR CODES
msg_s_bad_id
Invalid message ID
A message ID with an invalid technology or component was
specified.
msg_s_no_cat_open
Could not open the message catalog for the specified
message ID.
msg_s_no_cat_perm
Local file permissions prevented the program from opening
the message catalog for the specified message ID.
msg_s_no_catalog
The message catalog for the specified message ID does not
exist.
msg_s_no_default
Could not find the default message for the specified status
code in the internal tables.
msg_s_no_memory
Could not allocate memory for message table, string copy,
or other internal requirement.
msg_s_not_found
Could not find the text for the specified status code in
either the in-core message tables or the message catalogs.
msg_s_ok_text
The operation was performed successfully.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
dce_msg_get_msg
dce_msg_get_default_msg
7 – dce_msg_get_cat_msg
NAME
dce_msg_get_cat_msg - Opens message catalog and retrieves message
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get_cat_msg( unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
ID of message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_get_cat_msg() routine is a "convenience" form of the
dce_msg_cat_get_msg() routine. The difference between it and the
latter routine is that dce_msg_get_cat_msg() does not require the
message catalog to be explicitly opened; it determines the correct
catalog from the message parameter (which is a 32-bit DCE message
ID as described in dce_error_inq_text), opens it, retrieves the
message, and returns a pointer to malloc()'d space containing the
message. If the message catalog is inaccessible, the routine returns
an error. (See the routine dce_msg_get() for a description of the
return value.)
The routine will fail if the message catalog is not correctly
installed.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_cat_close
dce_msg_cat_get_msg
dce_msg_cat_open
dce_msg_get
dce_msg_get_msg
8 – dce_msg_get_default_msg
NAME
dce_msg_get_default_msg - Retrieves DCE message from in-memory tables
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get_default_msg( unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
ID of message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_get_default_msg() routine retrieves a message from the
application's in-memory tables. It returns a pointer to static space
that should not be freed. If the specified message (which is a 32-bit
DCE message ID as described in dce_error_inq_text) cannot be found in
the in-memory tables, the routine returns NULL and fills in status
with the appropriate error code.
This routine should be used only for message strings that will never
have to be translated (see dce_msg_translate_table).
All messages for a given component are stored in a single message
catalog generated by the sams utility when the component is built.
Messages may also be compiled directly into the component code, thus
rendering the successful retrieval of message text independent of
whether or not the message catalogs were correctly installed.
Generation of in-memory message tables is specified by the incatalog
flag in the sams file in which the message text is defined. (See sams
for more information on sams files.) If the messages have been
generated at compile time with this option specified, the
dce_msg_define_msg_table() routine can be called by the application to
set up an in-memory table containing the messages.
EXAMPLES
The following code fragment shows how dce_msg_get_default_msg() might
be called to retrieve the in-memory copy of a message defined by a DCE
application (whose serviceability component name is app):
#include <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#include "dceappmsg.h" /* "test_msg" is defined in this file */
unsigned char *my_msg;
error_status_t status;
<. . .>
my_msg = dce_msg_get_default_msg(test_msg, &status);
printf("Message is: %s\n", my_msg);
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
dce_msg_get
dce_msg_get_msg
9 – dce_msg_get_msg
NAME
dce_msg_get_msg - Retrieve a DCE message from its ID
SYNOPSIS
#include <dce/dce_msg.h>
unsigned char *dce_msg_get_msg( unsigned32 message,
error_status_t *status );
PARAMETERS
Input
message
ID of message to be retrieved.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_get_msg() routine retrieves the text for a specified
message (which is a 32-bit DCE message ID as described in
dce_error_inq_text). The routine implicitly determines the correct
message catalog in which to access the message, and opens it; the
caller only has to call the routine.
The routine first searches the appropriate message catalog for the
message, and then (if it cannot find the catalog) searches the in-
memory message table. If the message cannot be found in either of
these places, the routine returns a default string and fills in
status with an error code. This routine thus always returns a string,
even if there is an error (except for msg_s_no_memory).
The message, if found, is returned in allocated space to which the
routine returns a pointer. The pointed-to space must be freed by the
caller using free. If memory cannot be allocated, the routine returns
NULL and fills in status with the msg_s_no_memory error code.
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
dce_msg_get
dce_msg_get_default_msg
10 – dce_msg_translate_table
NAME
dce_msg_translate_table - Translates all in-memory messages in
a table
SYNOPSIS
#include <dce/dce_msg.h>
void dce_msg_translate_table( dce_msg_table_t *table,
unsigned32 count,
error_status_t *status );
PARAMETERS
Input
table A message table structure (defined in a header file generated
by sams during compilation (see "EXAMPLES" below), the
contents of which are to be translated.
count The number of elements contained in the table.
Output
status
Returns the status code from this operation. The status code
is a value that indicates whether the routine completed
successfully and if not, why not.
DESCRIPTION
The dce_msg_translate_table() routine overwrites the specified
in-memory message table (that is, updates the in-memory table with
the contents of a message table, which has changed for some reason;
for example, because of a change in locale).
If any in-memory message is not found in the message catalog, all
in-memory messages are left unchanged.
EXAMPLES
The following code fragment shows how dce_msg_translate_table()
might be called (in an application whose serviceability component
name is app) to translate a DCE application's in-memory message
table, set up by an earlier call to dce_msg_define_msg_table():
#include <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#include "dceappmsg.h"
char *loc_return;
error_status_t status;
<. . .>
dce_msg_translate_table (app_msg_table,
sizeof(app_msg_table) /
sizeof(app_msg_table[0]),
&status );
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_msg_define_msg_table
11 – dce_pgm_printf
NAME
dce_pgm_printf
dce_pgm_fprintf
dce_pgm_sprintf - Formatted DCE message output routines
SYNOPSIS
#include <dce/dce.h>
int dce_pgm_printf( unsigned32 messageid, . . . );
int dce_pgm_fprintf( FILE *stream, unsigned32 messageid, . . . );
unsigned char *dce_pgm_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_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. The routine dce_printf() does neither. This allows clients
(which do not usually use the serviceability interface) to produce
error (or other) messages which automatically include the originating
application's name. Note that the application 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.
The dce_pgm_sprintf() routine is similarly equivalent to
dce_sprintf(), and the dce_pgm_fprintf() routine is similarly
equivalent to dce_fprintf().
ERROR CODES
See dce_msg_get.
RELATED INFORMATION
Functions: dce_fprintf
dce_msg_get_msg
dce_printf
dce_sprintf
dce_svc_set_progname
12 – dce_printf
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