dce_cs_rgy_to_loc- maps a code set value in the code set registry to the local name for a code set
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);
- The registered hexadecimal value that uniquely identifies the code set.
- A string that specifies the name used by the local host's locale environment to refer to the code set specified by rgy_code_set_value. The string is a maximum of 32 bytes (31 character data bytes and a terminating NULL character).
- The number of character sets that the specified code set encodes. Specifying NULL prevents the routine from returning this argument.
- 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 argument prevents the routine from returning this argument. The routine dynamically allocates this value.
- 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:
- Code set registry access succeeded.
Cannot allocate memory for code set info
Cannot open the code set registry file
Cannot read the code set registry file
Value not found in the code set registry
No local code set name exists in the code set registry
The dce_cs_rgy_to_loc() routine maps a unique identifier for a character/code set encoding in the code set registry to its operating system-specific (local) name. 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 local_code_set_name can be obtained from the registry, the routine returns the status dce_cs_c_unknown and an undefined string.
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 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_rgy_to_loc() 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( use this routine to obtain the string name that matches the name of the host code set converter that they will call to perform a code set conversion.
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.
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.