NAME

   dce_cs_rgy_to_loc - 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.  The possible status codes and their meanings
       are as follows:

       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

 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.

 RELATED INFORMATION

   Commands: csrc.

   Functions: dce_cs_loc_to_rgy
              rpc_cs_char_set_compat_check
              rpc_cs_eval_with_universal
              rpc_cs_eval_without_universal
              rpc_rgy_get_code_sets