dce_cs_loc_to_rgy(3rpc)

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 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 plus a terminating NULL character.

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 parameter.

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 parameter. 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_loc_to_rgy( ) routine is a DCE function that maps operating system-specific names for character/code set encodings to their unique identifiers in the code set registry.

The routine is currently used by the DCE RPC routines for character and code set interoperability, which permit DCE RPC clients and servers to transfer international character data in a heterogeneous character set and code sets environment.

The dce_cs_loc_to_rgy( ) routine takes as input a string that holds the host-specific "local name'' of a code set and returns the corresponding integer value that uniquely identifies that code set, as registered in the host's code set registry. If the integer value does not exist in the registry, the routine returns the status dce_cs_c_unknown. 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 code set value 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 array after it is used, since the array is dynamically allocated.

The DCE RPC code sets compatibility evaluation routines rpc_cs_eval_with_universal( ), rpc_cs_eval_without_universal( ), and rpc_cs_character_set_compat_check( ) use this routine to obtain registered integer values for a client and server's supported character sets in order to ensure that the server supports a character set that is compatible with the client. The DCE RPC stub support routines for code set conversion can use this routine to obtain the registered code set value that corresponds to the code set they are currently using; that is, the local code set specified in their host's locale environment. The stub routines for code set conversion then compare their local code set value to the code set value specified in the sending tag for the call to determine whether code set conversion is necessary.

In general, programmers who are developing RPC applications that transfer international characters do not need to call this routine directly; the DCE RPC routines provided for code sets evaluation and the DCE RPC stub support routines for code set conversion call this routine on the client or server application's behalf.

However, programmers who are developing their own stub support routines for code set conversion may want to include this routine in their conversion code to map their current locale information to a code set value in order to perform local-to-sending tag code set comparison.

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) in OSF DCE Command Reference

Functions: dce_cs_rgy_to_loc(3rpc)

rpc_cs_char_set_compat_check(3rpc)

rpc_cs_eval_with_universal(3rpc)

rpc_cs_eval_without_universal(3rpc)

rpc_rgy_get_codesets(3rpc)