Operations that specify international characters as input and output parameters declare special code set tag parameters (see Writing the Interface Definition File ). The purpose of these parameters is to hold the unique identifier for the code set into which the input or output data is to be encoded when it is transferred over the network.
The function of the tag-setting routine is to provide a way to set an operation's code set tag parameters to specific code set values from within the stubs rather than in the application code. The application specifies the name of the tag-setting routine as the argument to the cs_tag_rtn ACF attribute; the client and server stubs call this routine when the operation is invoked to set the tag parameters to specific network code set values before they call the stub support routines for buffer sizing and code set conversion. The stubs use the network code set values returned by the tag-setting routine as input to the buffer sizing and conversion routines. In turn, these routines compare the network code set values to be used for input and output data the local code set in use for the data, and determine whether or not new buffer allocation and code set conversion are necessary.
When called from the client stub, the tag-setting routine sets the sending tag parameter to the code set to use for input character data. If the client expects output character data from the server, the routine also sets the desired receiving tag parameter to the code set that the client prefers the server to use for sending back the output data. On the client side, the local_type_name_net_size( ) buffer sizing routine and the local_type_name_to_netcs( ) code set conversion routines use the value in the sending tag as the network code set value to use for transmitting the input data. When the input data arrives at the server side, the server stub uses the sending tag as input to the local_type_name_local_size( ) buffer sizing routine and the local_type_name_from_netcs( ) code set conversion routines, which use the value to determine whether or not new buffer allocation and conversion is necessary from the network code set to the local code set.
When called from the server stub, the tag-setting routine sets the receiving tag parameter to the code set to use for transmitting the output character data back to the server. The routine can use the desired receiving tag value as input to determine the most appropriate code set in which to encode output data for the client. On the server side, the local_type_name_net_size( ) buffer sizing routine and the local_type_name_to_netcs( ) code set conversion routines use the value in the receiving tag as the network code set value to use for transmitting the output data. When the output data arrives at the client side, the client stub uses the receiving tag as input to the local_type_name_local_size( ) buffer sizing routine and the local_type_name_from_netcs( ) code set conversion routines, which use the value to determine whether or not new buffer allocation and conversion is necessary from the network code set to the local code set.
DCE RPC provides one tag-setting routine named rpc_cs_get_tags( ) that applications can use to set code set tag values within the stubs. To use this routine, specify its name as the argument to the cs_tag_rtn attribute and link your application with the DCE library. The example ACF for the cs_test interface specifies the rpc_cs_get_tags( ) routine.
Note that the rpc_cs_get_tags( ) routine always sets the receiving tag value on the server side to the value that the client specified in the desired receiving tag. See the rpc_cs_get_tags(3rpc) reference page in the OSF DCE Application Development Reference for an explanation of this routine's signature and function.
RPC application programmers who are developing their own tag-setting routines can also refer to the rpc_cs_get_tags(3rpc) reference page in the OSF DCE Application Development Reference to obtain the required signature for their user-written routine.
The tag-setting routine generally obtains the code set tag values from the binding handle. These values are usually determined by the character and code sets evaluation routine invoked during the server binding import process, although they can be explicitly set in the binding handle by using the rpc_cs_binding_set_tags( ) routine. However, applications can design the tag-setting routine to perform evaluation within the stubs rather than in the application (client) code. For example, when called from the client side, the DCE RPC tag-setting routine rpc_cs_get_tags(~) performs character and code set compatibility evaluation itself if it does not find the tag values in the binding handle. See Writing the Evaluation Routine for more information on deferred evaluation.