The cs_char Attribute

The cs_char attribute is very similar in function to the represent_as attribute: it associates a local data type that your application code uses with a data type defined in the IDL file. The cs_char attribute permits the application code to use the local data type for international character data, and converts between the local data type and the format specified in the IDL file when transferring international characters over the network. The cs_char ACF attribute permits the conversion of characters, arrays of characters, and strings of characters between the format in which the application code requires them and the format in which they are transmitted over the network.

As with represent_as, use of the cs_char attribute means that during marshalling and unmarshalling, conversions occur between the data type that the application code is using and the data type specified in the IDL. In the case of cs_char, the local data type is automatically converted between the local data type in the local code set encoding and the idl_byte data type in the network code set encoding. The network code set is the code set encoding that the application code, through the use of the DCE RPC automatic code set conversion routines, has selected to use when transmitting the international characters over the network.

The cs_char attribute differs from the [transmit_as] attribute in that it does not affect the network contract between the client and server. It differs from the [represent_as] attribute in that multiple data items (for example, the characters of an array or string) can be converted with a single stub call to user-written conversion code, and that the conversion can modify array size and data limit information between what is transmitted over the network and what is used by application code.

The cs_char attribute has the following syntax. (See the examples below.)

typedef [cs_char (local_type_name)] net_type_name;

The local_type_name is the local data type that the application code uses. You can define it in the IDL file or in an application header file. If you do not define it in the IDL file, use the include statement in the ACF to make its definition available to the stubs.

The net_type_name is the data type that is defined in the IDL file. When used with the cs_char attribute, this data type is always byte in the IDL file.

If you use the cs_char attribute, you must write the following stub support routines for each local type that you define:

· Routines that check the buffer storage requirements for international character data to be converted to determine whether or not more buffer space needs to be allocated to hold the converted data

· Routines to perform conversion between local and network code sets

The suffix for the routine names, the function of each, and where they are used (client or server) appear in the following list:

· local_type_name_net_size( ): Calculates the necessary buffer size for code set conversion from a local code set to a network code set. Client and server stubs call this routine before they marshal any international character data.

· local_type_name_local_size( ): Calculates the necessary buffer size for code set conversion from a network code set to a local code set. Client and server stubs call this routine before they unmarshal any international character data.

· local_type_name_to_netcs( ): Converts international character data from a local code set to a network code set. Client and server stubs call this routine before they marshal any international character data.

· local_type_name_from_netcs( ): Converts international character data from a network code set to a local code set. Client and server stubs call this routine before they unmarshal any international character data.

You specify the name for the local data type in the local_type_name portion of the function name. The name that you specify cannot exceed twenty (20) characters, because the entire generated name must not exceed the 31-character limit for C identifiers.

For each piece of international character data being marshalled, the _net_size and _to_netcs routines are called once each. For each piece of international character data being unmarshalled, the _local_size and _from_netcs routines are called once each.

DCE RPC provides buffer sizing and code set conversion routines for the cs_byte and wchar_t data types (the cs_byte type is equivalent to the byte type). If they meet the needs of your application, you can use these RPC routines (cs_byte_* and wchar_t_*) instead of providing your own routines.

If you do provide your own routines for buffer sizing and code set conversion, they must follow a specific signature. See the reference documentation for the cs_byte *(3rpc) and wchar_t *(3rpc) routines in the OSF DCE Application Development Reference for a complete description of the required signatures for these routines.

When international character data is to be unmarshalled, a stub needs to have received a description of the codeset being used before it receives the data. For this reason, the cs_char attribute cannot be applied to the base type of a pipe, or to a type used in constructing the base type of a pipe.

The cs_char attribute also cannot be applied to a type if there is an array that has this type as a base type and the array has more than one dimension, or if the attributes min_is, max_is, first_is, last_is, or string have been applied to the array. As a result, all instances of the type to which cs_char has been applied must be scalars or one-dimensional arrays. Only the length_is and/or size_is attributes can be applied to these arrays.

The following restrictions apply to the use of variables that appear in array attributes:

· Any parameter that is referenced by a size_is or length_is attribute of an array parameter whose base type has the cs_char attribute cannot be referenced by any attribute of an array parameter whose base type does not have the cs_char attribute.

· Any structure field that is referenced by a size_is or length_is attribute of an array field whose base type has the cs_char attribute cannot be referenced by any attribute of an array field whose base type does not have the cs_char attribute.

The cs_char attribute cannot interact with the transmit_as or represent_as attributes. This restriction imposes the following rules:

· The cs_char attribute cannot be applied to a type that has the transmit_as attribute, nor can it be applied to a type in whose definition a type with the transmit_as attribute is used.

· The cs_char attribute cannot be applied to a type that has the represent_as attribute, nor can it be applied to a type in whose definition a type with the represent_as attribute is used.

· The cs_char attribute cannot be applied to the transmitted type specified in a transmit_as attribute or to any type used in defining such a transmitted type.

The cs_char attribute cannot be applied to any type that is the type of the referent of a pointer that has a max_is or size_is attribute applied to it. It also cannot be applied to the base type of an array parameter that has the unique or ptr attribute applied to it.

An application that uses the cs_char ACF attribute cannot use the IDL encoding services encode and decode ACF attributes.

Examples Using the cs_char Attribute

Arrays of cs_char can be fixed, varying, conformant, or conformant varying. The treatment of a scalar cs_char is similar to that of a fixed array of one element. The following examples show the relationship between IDL declarations and declarations in the generated header file when the cs_char attribute has been applied. The examples assume that the ACF contains the type definition:

typedef [cs_char(ltype)] my_byte;

For a fixed array, if the IDL file contains:

typedef struct {

my_byte fixed_array[80];

} fixed_struct;

the declaration generated in the header file is:

typedef struct {

ltype fixed_array[80];

} fixed_struct;

The number of array elements in the local and network representations of the data must be the same as the array size stated in the IDL.

For a varying array, if the IDL file contains:

typedef struct {

long l;

[length_is(l)] my_byte varying_array[80];

} varying_struct;

the declaration generated in the header file is:

typedef struct {

idl_long_int l;

ltype varying_array[80];

} varying_struct;

Neither the number of array elements in the local representation nor the number of array elements in the network representation may exceed the array size in the IDL.

For a conformant array, if the IDL file contains:

typedef struct {

long s;

[size_is(s)] my_byte conf_array[];

} conf_struct;

the declaration generated in the header file is:

typedef struct {

idl_long_int s;

ltype conf_array[1];

} conf_struct;

The number of array elements in the local representation and the number of array elements in the network representation need not be the same. The conversions between these numbers are done in the user-provided _net_size and _local_size routines.

For a conformant varying array, if the IDL file contains:

typedef struct {

long s;

long l;

[size_is(s), length_is(l)] my_byte open_array[];

} open_struct;

the declaration generated in the header file is:

typedef struct {

idl_long_int s;

idl_long_int l;

ltype open_array[1];

} open_struct;

The maximum number of array elements in the local representation and the maximum number of array elements in the network representation need not be the same. The conversions between these numbers are done in the user-provided _net_size and _local_size routines.

For fixed or varying arrays, the size of the storage available to hold the local data is determined by the array size specified in the IDL and the local type specified in the cs_char attribute. For conformant or conformant varying arrays, you must determine the transformations between local storage size and network storage size without reference to the characters being transmitted or received. Where a variable-width character set is in use, this means making the most conservative assumption about the size of the data.