NAME

dce_cs_loc_to_rgy- maps a local name for a code set to a code set value in the code set registry

SYNOPSIS

#include <dce/rpc.h>

void dce_cs_loc_to_rgy(
	idl_char *local_code_set_name,
	unsigned32 *rgy_code_set_value,
	unsigned16 *rgy_char_sets_number,
	unsigned16 **rgy_char_sets_value,
	error_status_t *status);

PARAMETERS

Input

local_code_set_name

A string that specifies the name used by the local host's locale environment to refer to the code set. The string is a maximum of 32 bytes (31 character data bytes plus a terminating NULL).

Output

rgy_code_set_value

The registered integer value that uniquely identifies the code set specified by local_code_set_name.

rgy_char_sets_number

The number of character sets that the specified code set encodes. Specifying NULL prevents this routine from returning this argument.

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 prevents this routine from returning this argument. 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.

Possible status codes and their meanings include:

dce_cs_c_ok

Code set registry access succeeded.

dce_cs_c_cannot_allocate_memory

Cannot allocate memory for code set info

dce_cs_c_cannot_open_file

Cannot open the code set registry file

dce_cs_c_cannot_read_file

Cannot read the code set registry file

dce_cs_c_unknown

Value not found in the code set registry

dce_cs_c_not_found

No local code set name exists in the code set registry

DESCRIPTION

The dce_cs_loc_to_rgy() routine maps an operating system-specific (local) name for a character/code set encoding to its unique identifier in the code set registry. The routine is one of those used for character and code set interoperability, which permits clients and servers to transfer international character data in a heterogeneous character set and code sets environment.

If no rgy_code_set_value can be obtained from the registry, the dce_cs_loc_to_rgy() routine returns the status dce_cs_c_unknown.

Specifying NULL in the rgy_char_sets_number and rgy_char_sets_value arguments prevents the routine from performing the additional search for these values. If the rgy_char_sets_value value is returned by the routine, the application should free the rgy_char_sets_value array after it is used.

The code and characfter sets compatibility evaluation routines rpc_cs_eval_with_universal(), rpc_cs_eval_without_universal(), and rpc_cs_character_set_compat_check() use the dce_cs_loc_to_rgy() routine to ensure that the server supports a character set that is compatible with the client. The stub support code set conversion routines cs_byte_from_netcs(, cs_byte_to_netcs(, wchar_t_from_netcs(, and wchar_t_to_netcs( can use this routine to obtain the registered code set value that corresponds to the local code set specified in their host's locale environment and then compare it to the code set value specified in the sending tag for the call to determine whether code set conversion is necessary.

In general, applications that transfer international characters do not need to call this routine directly. However, any further code set conversion implementations may need to call this routine in order to make code set comparisons and identify the appropriate local code set.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

cs_byte_from_netcs()
cs_byte_local_size()
cs_byte_net_size()
cs_byte_to_netcs()
dce_cs_rgy_to_loc()
rpc_cs_char_set_compat_check()
rpc_cs_eval_with_universal()
rpc_cs_eval_without_universal()
rpc_rgy_get_code_sets()
wchar_t_from_netcs()
wchar_t_local_size()
wchar_t_net_size()
wchar_t_to_netcs().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.