The cs_tag_rtn attribute is an ACF attribute for use in RPC applications that handle international character data. This attribute specifies the name of a user-written routine that the client and server stubs will call to set an operation's code set tag parameters to specific code set values. The cs_tag_rtn attribute is an optional ACF attribute that you can use to provide code set tag transparency for callers of your interface's operations. If an operation that transfers international character data has the cs_tag_rtn attribute applied to it in the corresponding ACF, the code set tag parameters will not appear in the operation's definition within the generated header file. If the cs_tag_rtn attribute is not used, the operation's caller must provide appropriate values to the operation's code set tag parameters before international character data is marshalled.
The cs_tag_rtn attribute has the following syntax. (See the example below.)
For an interface:
[cs_tag_rtn(tag_set_routine)] interface interface_name
For an operation:
[cs_tag_rtn(tag_set_routine)] operation_name ([parameter_list]);
When used as an ACF interface attribute, the cs_tag_rtn attribute applies to all operations defined in the corresponding IDL file. When used as an ACF operation attribute, the cs_tag_rtn attribute applies only to the operation you specify.
The tag_set_routine is the name of the stub support routine that the client and server stubs will call to set the operation's code set tag parameters. The IDL compiler will generate a function prototype for tag_set_routine in the generated header file.
Applications can specify the DCE RPC tag-setting routine rpc_cs_get_tags( ), if it meets their applications' needs, or they can write their own tag-setting routines. The routine name must be distinct from any type name, procedure name, constant name, or enumeration name appearing in the interface definition. It must also have a specific calling signature. See the description of the rpc_cs_get_tags( ) routine in the OSF DCE Application Development Reference for a complete description of the required routine signature.
When the tag-setting routine is called from a client stub, it is called before any in parameters are marshalled. When called from a server stub, it is called before any out parameters are marshalled. For more information on the cs_tag_rtn attribute and its use in internationalized RPC applications, see Writing Internationalized RPC Applications .
Example Using the cs_tag_rtn Attribute
As shown in the following example, the cs_tag_rtn attribute is used in conjunction with the cs_char, cs_stag, cs_drtag and cs_rtag ACF attributes. In the example, the stub generated for a_op will call the tag-setting routine set_tags to set the code set tag parameters to specific values before any data is marshalled. For b_op, it is the responsibility of the operation's caller to ensure that the code set tag parameters are set correctly before any data is marshalled.
IDL File
typedef byte my_byte;
void a_op(
[in] unsigned long stag,
[in] unsigned long drtag,
[out] unsigned long *p_rtag,
[in] long s,
[in, out] long *p_l,
[in, out, size_is(s), length_is(*p_l)] my_byte a[]
);
void b_op(
[in] unsigned long stag,
[in] unsigned long drtag,
[out] unsigned long *p_rtag,
[in] long s,
[in, out] long *p_l,
[in, out, size_is(s), length_is(*p_l)] my_byte a[]
);
ACF
typedef [cs_char(ltype)] my_byte;
[cs_tag_rtn(set_tags)] a_op( [cs_stag] stag,
[cs_drtag] drtag,
[cs_rtag] p_rtag );
b_op( [cs_stag] stag,
[cs_drtag] drtag,
[cs_rtag] p_rtag );
Generated Header File
typedef byte my_byte;
void a_op(
/* [in] */ idl_long_int s,
/* [in, out] */ idl_long_int *p_l,
/* [in, out, size_is(s), length_is(*p_l)] */ ltype a[]
);
void b_op(
/* [in] */ idl_ulong_int stag,
/* [in] */ idl_ulong_ing drtag,
/* [out] */ idl_ulong_int *p_rtag,
/* [in] */ idl_long_int s,
/* [in, out] */ idl_long_int *p_l,
/* [in, out, size_is(s), length_is(*p_l)] */ ltype a[]
);