VMS Help DCE_RPC, Application Routines, cs_byte_local_size  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME

   cs_byte_local_size - Calculates the necessary buffer size for code
                        set conversion from a network code set to a
                        local code set

   Used by client and server applications.

 SYNOPSIS

   #include <dce/codesets_stub.h>

   void cs_byte_local_size( rpc_binding_handle_t binding,
                            unsigned32 network_code_set_value,
                            unsigned32 network_buffer_size,
                            idl_cs_convert_t *conversion_type,
                            unsigned32 *local_buffer_size,
                            error_status_t *status );

 PARAMETERS

   Input

   binding
       Specifies the target binding handle from which to obtain buffer
       size evaluation 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 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 receiving tag. When the caller is
       the server stub, this value is the sending tag.

   network_buffer_size
       The size, in units of idl_byte, of the buffer that is allocated
       for the international character data. For a conformant or
       conformant varying array, this value is the network value of the
       size_is variable for the array; that is, the value is the size
       of the unmarshalled string if no conversion is done.

   Output

   conversion_type
       A pointer to the enumerated type defined in dce/idlbase.h that
       indicates whether data conversion is necessary and whether or
       not the existing buffer is sufficient for storing the results
       of the conversion. The conversion type can be one of the
       following values:

       idl_cs_no_convert
                      No code set conversion is required.

       idl_cs_in_place_convert
                      Code set conversion can be performed in the
                      current buffer.

       idl_cs_new_buffer_convert
                      The converted data must be written to a new buffer.

   local_buffer_size
       A pointer to the buffer size that needs to be allocated to
       contain the converted data, in units of idl_byte. This value
       is to be used as the local value of the size_is variable for
       the array, and is non-NULL only if a conformant or conformant
       varying array is to be unmarshalled.  A value of NULL in this
       parameter indicates that a fixed or varying array is to be
       unmarshalled.

   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 invoked from the server stub, this routine calls the routines
   dce_cs_loc_to_rgy() and rpc_rgy_get_max_bytes().  If either of these
   routines returns an error, the cs_byte_local_size() routine raises
   an exception to the client application.

 DESCRIPTION

   The cs_byte_local_size() 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_local_size() routine is one of the DCE RPC buffer sizing
   routines that RPC stubs use before they marshall or unmarshall data
   to determine whether or not the buffers allocated for code set
   conversion need to be enlarged to hold the converted data.  The buffer
   sizing routines determine the type of conversion required and
   calculate the size of the necessary buffer (if a new one is required);
   the RPC stub then allocates a buffer of that size before it calls one
   of the code set conversion routines.

   Client and server stubs call the cs_byte_*_size 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.

   Applications do not call cs_byte_local_size() routine directly.
   Client and server stubs call the routine before they unmarshall any
   data.  The stubs pass the routine a binding handle and a code set
   value that identifies the code set that was used to transfer
   international character data over the network. The stubs also
   specify the network storage size of the data, in units of idl_byte,
   if a conformant or conformant varying array is to be unmarshalled,
   or they specify NULL if a fixed or varying array is to be marshalled.

   When called from a client stub, the cs_byte_local_size() routine
   determines the value of conversion_type from the client and server's
   code set tag information stored in the binding handle by a code sets
   evaluation routine or a tag-setting routine.  If the conversion type
   specified in the handle is idl_cs_new_buffer_convert, the routine sets
   the conversion_type parameter to this value and, if a conformant or
   conformant varying array is to be unmarshalled, calculates a new
   buffer size by multiplying the value of local_buffer_size by the
   c_max_bytes value for the code set specified in network_code_set_value.
   The routine returns the new buffer size in the local_buffer_size
   parameter. The size is specified in units of cs_byte, which is the
   local representation used for international character data (and is
   equivalent to the byte data type). For fixed and varying arrays, the
   routine assumes that network_buffer_size is sufficient to store the
   converted data.

   If the handle information specifies idl_cs_convert_in_place or
   idl_cs_no_convert, the routine assumes that network_buffer_size can
   store the converted data (or that no conversion is necessary) and
   returns idl_cs_convert_in_place (or idl_cs_no_convert) in the
   conversion_type parameter. The routine also returns the value of
   network_buffer_size in local_buffer_size if a conformant or
   conformant varying array is to be marshalled.

   In cases where the binding handle does not contain the results of
   character and code sets evaluation, or where it is being called from
   the server stub, the cs_byte_local_size() routine determines the
   value of conversion_type itself using the local code set value and
   the code set value passed in the network_code_set_value parameter and
   returns the appropriate conversion_type value.  If a conformant or
   conformant varying array is to be unmarshalled, and the routine finds
   that a new buffer is required to hold the converted data, the routine
   calculates the size of this new buffer (by multiplying the value of
   network_buffer_size by the local code set c_max_bytes value) and
   returns the results, in units of cs_byte, in local_buffer_size.

   Permissions Required

   No permissions are required.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: cs_byte_net_size
              wchar_t_local_size
              wchar_t_net_size