NAME

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

   Used by client and server applications.

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

 RELATED INFORMATION

   Commands: csrc

   Functions: 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