NAME

   cs_byte_to_netcs - Converts international character data from a
                      local code set to a network code set

   Used by client and server applications.

 SYNOPSIS

   #include <dce/codesets_stub.h>

   void cs_byte_to_netcs( rpc_binding_handle_t binding,
                          unsigned32 network_code_set_value,
                          idl_byte *local_data,
                          unsigned32 local_data_length,
                          idl_byte *network_data,
                          unsigned32 *network_data_length,
                          error_status_t *status );

 PARAMETERS

   Input

   binding
       Specifies the target binding handle from which to obtain code
       set conversion information. When called from the client stub,
       this value is the binding handle of a compatible server returned
       by the rpc_ns_binding_import_next() or rpc_ns_binding_select()
       routine. When called from the server stub, this value is a
       pointer to binding information that the client stub passed in
       the RPC call.

   network_code_set_value
       The registered hexadecimal integer value that represents the
       code set to be used to transmit character data over the network.
       In general, the network'' code set is the code set that the
       client application's code sets evaluation routine has determined
       to be compatible for this client and server. When the caller is
       the client stub, this value is the sending tag. When the caller
       is the server stub, this value is the receiving tag.

   local_data
       A pointer to the international character data to be transmitted,
       in the local code set encoding.

   local_data_length
       The number of idl_byte data elements to be converted. For a
       varying array or a conformant varying array, this value is the
       local value of the length_is variable. For a conformant array,
       this value is the local value of the size_is variable.  For a
       fixed array, the value is the array size specified in the
       interface definition.

   Output

   network_data
       A pointer to the converted data, in units of idl_byte.

   network_data_length
       A pointer to the length of the converted data, in units of
       idl_byte.  Specify NULL if a fixed or conformant array is to
       be converted.

   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:

       rpc_s_ok       Success.

       rpc_s_ss_incompatible_codesets
                      The specified code set does not match the code set
                      specified in the sending tag in the binding handle.
                      If this error occurs in the server stub, an
                      exception is raised to the client application.

   When running the host converter, the following errors can occur:

       rpc_s_ss_invalid_char_input

       rpc_s_ss_short_conv_buffer

       rpc_s_ss_iconv_error (HP-UX reference platform only)

       rpc_s_ss_no_memory (HP-UX reference platform only)

   When invoked from the server stub, the routine calls the
   dce_cs_loc_to_rgy() routine and the host converter routines.  If
   these routines return an error, an exception is raised to the
   client application.

 DESCRIPTION

   The cs_byte_to_netcs() routine belongs to a set of DCE RPC routines
   for use by client and server applications that are transferring
   international character data in a heterogeneous character set and
   code sets environment.

   The cs_byte_to_netcs() routine is one of the DCE RPC stub code set
   conversion routines that RPC stubs use before they marshall or
   unmarshall data to convert international character data to and from
   local and network code sets.

   Client and server stubs call the cs_byte_*_netcs() routines when
   the cs_byte type has been specified as the local data type using
   the cs_char attribute in the attribute configuration file for the
   application.  (The cs_byte type is equivalent to the byte type.)

   Client and server stubs call the cs_byte_to_netcs() routine before
   they marshall any data. The routine takes a binding handle, a code
   set value that identifies the code set to be used to transfer
   international character data over the network, the address of the
   data to be converted, and the length of the data to be converted,
   in units of idl_byte.

   The routine compares the code set specified as the network code set
   to the local code set currently in use. If the routine finds that
   code set conversion is necessary, (because the local code set differs
   from the code set specified to be used on the network), it determines
   which host code set converter to call to convert the data and then
   invokes that converter.

   The routine then returns the converted data, in idl_byte format.
   If the data is a varying, conformant, or conformant varying array,
   the routine also returns the length of the converted data, in units
   of idl_byte.

   Applications can specify local data types other than cs_byte and
   wchar_t (the local data types for which DCE RPC supplies stub code
   set conversion routines) with the cs_char ACF attribute. In this
   case, the application must also supply local_type_to_netcs() and
   local_type_from_netcs() stub conversion routines for this type.

   Permissions Required

   No permissions are required.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: cs_byte_from_netcs
              wchar_t_from_netcs
              wchar_t_to_netcs