rpc_cs_get_tags(3rpc)
Retrieves code set tags from a binding handle; used by client and server applications
Synopsis
#include <dce/codesets_stub.h>
void rpc_cs_get_tags(
rpc_binding_handle_t binding,
boolean32 server_side,
unsigned32 *sending_tag,
unsigned32 *desired_receiving_tag,
unsigned32 *receiving_tag,
error_status_t *status);
Parameters
Input
binding
Specifies the target binding handle from which to obtain the code set tag 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( ) routines.
server_side
Indicates whether a client stub or a server stub is calling the routine.
desired_receiving_tag
(Server stub only) Specifies the code set value for the code set in which the client prefers data to be encoded when sent back from the server. The client
stub passes this value in the RPC call. If the routine is retrieving code set tags for an operation that does not specify a desired receiving tag parameter (the cs_drtag ACF parameter
attribute has not been applied to one of the operation's parameters), this value is NULL.
Output
sending_tag
(Client stub only) Specifies the code set value for the code set in which client data to be sent to the server is to be encoded. If the routine is retrieving code
set tags for an operation that does not specify a sending tag parameter (the cs_stag ACF parameter attribute has not been applied to one of the operation's parameters), this value is
NULL.
desired_receving_tag
(Client stub only) Specifies the code set value for the code set in which the client prefers to receive data sent back to it from the server. If the
routine is retrieving code set tags for an operation that does not specify a desired receiving tag parameter (the cs_drtag ACF parameter attribute has not been applied to one of the
operation's parameters), this value is NULL.
receiving_tag
(Server stub only) Specifies the code set value for the code set in which the server is to encode data to be sent back to the client. If the routine is retrieving
code set tags for an operation that does not specify a receiving tag parameter (the cs_rtag ACF parameter attribute has not been applied to one of the operation's parameters), this value is
NULL.
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. If code set compatibility
evaluation is performed, error values can also be returned from the following routines:
· rpc_rgy_get_codesets( )
· rpc_ns_binding_inq_entry_name( )
· rpc_ns_mgmt_read_codesets( )
Description
The rpc_cs_get_tags( ) 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 rpc_cs_get_tags( ) routine is a DCE RPC routine that RPC stubs can use to retrieve the code set values to be used to tag' international character data to be sent over the network. In general, the code set values to be used as tags are determined by a character and code sets evaluation routine, which is invoked from the client application code. However, application programmers can use other methods to establish values for code set tags.
RPC stubs call the rpc_cs_get_tags( ) routine before they call the buffer sizing routines *_net_size( ) and the code set conversion routines _netcs( ). The rpc_cs_get_tags( ) routine provides the stubs with code set values to use as input to the buffer sizing routines (to determine whether or not buffer storage needs to be allocated for conversion) and as input to the code set conversion routines (to determine whether conversion is necessary, and if so, which host code set converter to invoke).
Client and server stubs call the rpc_cs_get_tags( ) routine before they marshall any data. When called from the client stub, the boolean value server_side is set to FALSE to indicate that the client stub has invoked the routine. The binding handle is the handle to a compatible server returned by the rpc_ns_binding_import_next( ) or rpc_ns_binding_select( ) routines. If the client has added a code sets evaluation routine to the binding import procedure (by calling the routine rpc_ns_import_ctx_add_eval( )), the binding handle will contain the conversion method and the code set values to set for the client's sending tag and desired receiving tag. If the binding handle does not contain the results of an evaluation, the rpc_cs_get_tags( ) routine will perform the character/code sets evaluation within the client stub and set the client code set tag values itself.
On the client side, the output of the routine is the code set value that represents the client's sending tag and the code set value that represents the client's desired receiving tag. If the conversion method is "client makes it right'' (CMIR), the sending tag and desired receiving tags will be set to the code set value of the server's local code set. If the conversion method is "server makes it right'' (SMIR), the sending tag and desired receiving tag will be set to the client's local code set value. If the conversion method is "receiver makes it right'' (RMIR), the sending tag is the client's code set, and the desired receiving tag is the server's code set.
When called from the server stub, the boolean value server_side is set to TRUE to indicate that the server stub has invoked the routine.
The server stub specifies the code set value given in the client's desired receiving tag as input to the routine. The rpc_cs_get_tags( ) routine sets the code set value in desired_receiving_tag to receiving_tag and returns this value as output to the server stub. The server stub will then use the code set value in receiving_tag as the code set to use for data it sends back to the client.
Application programmers who want their applications to use the rpc_cs_get_tags( ) routine to retrieve code set tag information as part of the automatic code set conversion process specify the routine name as the argument to the ACF attribute cs_tag_rtn when developing their internationalized RPC application.
Application programmers can also write their own code set tags retrieval routine that RPC stubs can call; in this case, they specify the name of this routine as the argument to the ACF attribute cs_tag_rtn instead of specifying the DCE RPC routine rpc_cs_get_tags( ). Application programmers can also use the automatic code conversion mechanism, but design their applications so that the code set tags are set explicitly in the application instead of in the stubs.
Permissions Required
No permissions are required.
Return Values
No value is returned.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_ss_invalid codeset tag
The result of the client-side evaluation used an invalid code set tag.
Related Information
Functions: cs_byte_from_netcs(3rpc)
Book: OSF DCE Application Development Guide - Core Components