dce_cs_rgy_to_loc(3rpc)
Maps a code set value in the code set registry to the local name for a code set
Used by client and server applications.
Synopsis
#include <dce/rpc.h>
void dce_cs_rgy_to_loc(
unsigned32 *rgy_code_set_value,
idl_char **local_code_set_name,
unsigned16 *rgy_char_sets_number,
unsigned16 **rgy_char_sets_value,
error_status_t *status);
Parameters
Input
rgy_code_set_value
The registered hexadecimal value that uniquely identifies the code set.
Output
local_code_set_name
A string that specifies the name that the local host's locale environment uses to refer to the code set. The string is a maximum of 32 bytes: 31 character
data bytes and a terminating NULL character.
rgy_char_sets_number
The number of character sets that the specified code set encodes. Specifying NULL in this parameter prevents the routine from returning this value.
rgy_char_sets_value
A pointer to an array of registered integer values that uniquely identify the character set(s) that the specified code set encodes. Specifying NULL
in this parameter prevents the routine from returning this value. The routine dynamically allocates this value.
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.
Description
The dce_cs_rgy_to_loc( ) routine is a DCE function that maps a unique identifier for a code set in the code set registry to the operating system-specific
name for the code set, if it exists in the code set registry.
The routine is currently used by the DCE RPC routines for character and code set interoperability, which permit DCE applications to transfer international characters in a heterogeneous character and code sets environment.
The dce_cs_rgy_to_loc( ) routine takes as input a registered integer value of a code set and returns a string that holds the operating system-specific, or local name, of the code set.
If the local code set name does not exist in the registry, the routine returns the status dce_cs_c_unknown and returns an undefined string.
The routine also returns the number of character sets that the code set encodes and the registered integer values that uniquely identify those character sets. Specifying NULL in the rgy_char_sets_number and rgy_char_sets_value[] parameters prevents the routine from performing the additional search for these values. Applications that want only to obtain a local code set name from the code set registry can specify NULL for these parameters in order to improve the routine's performance. If the value is returned from the routine, application developers should free the rgy_char_sets_value array after it is used.
In general, client and server applications that use the DCE RPC character and code set interoperablity features do not need to call this routine directly; the DCE RPC stub support routines provided for code set conversion call this routine on the client or server application's behalf to obtain the string name that matches the name of the host code set converter that they will call to perform the actual code set conversion.
However, application programmers who are developing their own RPC stub support routines for code set conversion may want to include this routine in their conversion code to map code set values sent in code set tags into the local names for the code sets so that they can locate the correct operating system code set converter.
Permissions Required
No permissions are required.
Return Values
No value is returned.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
dce_cs_c_ok
dce_cs_c_cannot_allocate_memory
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
dce_cs_c_unknown
dce_cs_c_not_found
Related Information
Commands:
csrc(8dce)
rpc_cs_char_set_compat_check(3rpc)
rpc_cs_eval_with_universal(3rpc)
rpc_cs_eval_without_universal(3rpc)