### DCE XPG4 Routines

The four routines in this group provide DCE versions of functionality of the XPG messaging routines catopen( ), catgets( ), and catclose( ).

dce_msg_cat_open( )
(DCE abstraction over catopen( )) Opens a message catalog identified by a message ID. The routine returns a handle to the open catalog from which messages will be extracted. This routine is intended for use by applications (such as user interface programs) that display many messages from a particular catalog.

The routine will fail if the message catalog is not installed or if LANG is not properly set.

The following code fragment shows how dce_msg_cat_open( ) might be called to open the message catalog containing the "Hello World" message defined for the example application earlier in this topic:

#include <dce/dce.h>

#include <dce/dce_msg.h>

#include "dcehelmsg.h"

dce_msg_cat_handle_t hel_msg_handle;

unsigned32 status;

<. . .>

hel_msg_handle = dce_msg_cat_open(hello_msg, &status);

dce_msg_cat_get_msg( )
(DCE abstraction over catgets( )) Retrieves a message from an open catalog. If the message is not available, returns NULL.

The routine will fail if the message catalog is not installed or if LANG is not properly set.

The following code fragment shows how dce_msg_cat_get_msg( ) might be called to retrieve the "Hello World" message. Note that the message catalog must first be opened.

#include <dce/dce.h>

#include <dce/dce_msg.h>

#include "dcehelmsg.h"

dce_msg_cat_handle_t hel_msg_handle;

unsigned32 status;

unsigned_char_t *msg;

<. . .>

hel_msg_handle = dce_msg_cat_open(hello_msg, &status);

msg = (unsigned_char_t *)dce_msg_cat_get_msg(hel_msg_handle,

hello_msg,

&status);

printf("Message from dce_msg_cat_get_msg == %s\n", msg);

dce_msg_get_cat_msg( )
Convenience form of previous routine. Opens a message catalog, extracts a message identified by a global message ID, and returns a pointer to malloc( )'d space containing the message. If the message catalog is inaccessible, returns an error.

The routine will fail if the message catalog is not installed or if LANG is not properly set.

The following code fragment shows how dce_msg_get_cat_msg( ) might be called to retrieve the "Hello World" message:

#include <dce/dce.h>

#include <dce/dce_msg.h>

#include "dcehelmsg.h"

unsigned32 status;

unsigned_char_t *msg;

<. . .>

msg = dce_msg_get_cat_msg(hello_msg, &status);

printf("Message from dce_msg_get_cat_msg == %s\n", msg);

dce_msg_cat_close( )
(DCE abstraction over catclose( )) Closes the catalog specified by handle.

The following code fragment shows how dce_msg_cat_close( ) might be called to close the message catalog containing the "Hello World" message:

#include <dce/dce.h>

#include <dce/dce_msg.h>

#include "dcehelmsg.h"

dce_msg_cat_handle_t hel_msg_handle;

unsigned32 status;

<. . .>

dce_msg_cat_close(hel_msg_handle, &status);

##