Multiple operations can be performed using one encoding handle before the handle is released. In this case, all the encoded data is part of the same buffer system.

A single decoding handle is used to obtain the contents of the encoded data. Decoding operations must be called in the same order the encoding operations were called to create the encoded data.

The definition of the user client memory management functions, and any memory allocated by IDL encoding services using the client memory allocator, must not be modified between operations for which the same encoding handle is used.

15.6 Obtaining the Identity of an Encoding

User code that is decoding data can find out the identity of the operation used to encode the data before calling an operation to decode it.

The identity of an operation used to encode data can be determined after that operation has been called.

In both cases, this is done by calling the following routine:

void idl_es_inq_encoding_id( idl_es_handle_t h, rpc_if_id_t *if_id, idl_ulong_int *op, error_status_t *st );

The parameters for this routine are as follows:

h	A decoding handle.
if_id	The address to which the identity of the interface used to decode the operation is written. The identity information consists of the interface UUID and version.
op	The number of the operation used to encode the data. Operations are numbered in the order in which they appear in the IDL, with the first operation having number 0 (zero).
st	The address to which a status code is written.

15.7 Error Reporting

This section describes error codes returned by the IDL Encoding Services.

15.7.1 rpc_s_no_memory

This error can result from any of the following conditions:

• Insufficient memory available for an IDL Encoding Services handle to be constructed.
• The buffer supplied for fixed buffer encoding was not big enough.
• Out of memory while trying to build a dynamic encoding buffer.

This error can result from any of the following conditions:

• The buffer returned by an allocate routine is not 8-byte aligned.
• The size of buffer returned by an allocate routine is not a multiple of 8 bytes.
• The buffer supplied for fixed buffer encoding is not 8-byte aligned.
• The size of buffer supplied for fixed buffer encoding is not a multiple of 8 bytes.
• The buffer returned by an read routine is not 8-byte aligned.
• During buffer decoding, the buffer was found not to contain all the required data.

This error can result from any of the following conditions:

• Calling an operation for which only decode has been specified with an encoding handle.
• Calling an operation for which only encode has been specified with an decoding handle.
• Calling idl_es_inq_encoding_id() with an encoding handle which has not yet been used for any operation.

This error can result from the following condition:

• The decoding operation is inconsistent with the version of software used to create the encoding.

This error can result from the following condition:

• The transfer syntax of the encoding operation is not supported by the decoding operation.

This error can result from any of the following conditions:

• The interface UUID in the encoding operation does not match the interface UUID of the decoding operation.
• The interface version in the encoding operation does not match the interface version of the decoding operation.

This chapter describes IDL support for international characters.

16.1 The I-char Type

If data of a certain type is to be treated as international characters (I-chars), then that type must be given the attribute cs_char in the ACF. This attribute takes as an argument the local type to be used for this data. For example:

/* The IDL file includes the declaration typedef byte my_byte; */ typedef [cs_char(ltype)] my_byte;

When data of this type is marshalled or unmarshalled, codeset conversion routines are invoked. ltype is the local type used for the data by the application, and will usually be defined in a .h file for which an include statement occurs in the ACF, although it could be a type defined in the IDL.

Three tags are used to control the transmission of international characters. They are:

• cs_stag --- Denotes the codeset used when the client sends international characters to the server.
• cs_drtag --- Denotes the codeset the client would like the server to use when returning international characters.
• cs_rtag --- Denotes the codeset that is actually used when the server sends international characters to the client.

If the tags are to be concealed from the user of an operation, the cs_tag_rtn attribute must be applied to that operation. This attribute takes as an argument the routine that is called from a stub before marshalling starts, in order to set the tags. For example:

[cs_tag_rtn(set_tags)]

In the client stub, the cs_tag_rtn attribute is invoked before any data is marshalled. In the server stub, the cs_tag_rtn attribute is invoked after all the data has been unmarshalled and before the application code is entered.

This attribute is either an interface attribute or an operation attribute. If it is applied to an interface, the effect is as if it had been applied to every operation in the interface for which this attribute is not specified explicitly. The specified routine, in this example set_tags, is invoked by a stub before it marshalls any I-char data.

If an operation uses I-char data, the IDL parameters that act as the tags describing the I-char data must be specified using the cs_stag, cs_drtag, and cs_rtag attributes. For any operation that has in I-char data, the cs_stag attribute must be provided. For any operation that has out I-char data, the cs_rtag attribute must be provided.

Parameters to which the tag attributes are attached must be either unsigned long integer values or unsigned long integers passed by reference. For example:

/* In the IDL file operation my_op has parameters my_stag, my_drtag, my_rtag whose types are either (unsigned long) or ([ref] unsigned long *) */ my_op( [cs_stag] my_stag, [cs_drtag] my_drtag, [cs_rtag] my_rtag);

The signature of the routine named by the cs_tag_rtn attribute would have the form:

void get_tags( rpc_binding_handle_t h, /* [in] */ idl_boolean server_side, /* [in] */ idl_ulong_int *p_stag, /* [out] client side, ignored server side */ idl_ulong_int *p_drtag, /* [out] client side, [in] server side */ idl_ulong_int *p_rtag, /* ignored client side, [out] server side */ error_status_t *p_st /* [out] */ )

When this routine is called from a client stub, it is called before any in parameters are marshalled. The usage of the parameters is as follows:

h	Indicates the binding handle used for the call. It is expected that the user can obtain codeset information from this parameter if an RPC call is being made. The mechanism by which this may be done is outside the scope of this document. If the cs_tag_rtn attribute is being called from an IDL Encoding Services stub, this parameter is NULL.
server_side	Will be idl_false.
p_stag	Indicates the address to which the routine writes the value that designates the codeset being used on the wire for I-char data being sent to the server. If no cs_stag parameter has been specified for the operation, this value is discarded.
p_drtag	Indicates the address to which the routine should write the value that designates the codeset that it would prefer the server to use when returning I-char data to the client. If no cs_drtag parameter has been specified for the operation, this value is discarded.
p_rtag	This parameter is ignored.
p_st	Indicates the address to which a status value must be written. This value usually is error_status_ok.

When this routine is called from a server stub, it is called after all the out parameters have been unmarshalled, and before the application manager code is invoked. The usage of the parameters is as follows:

h	Indicates the binding handle being used for the call. It is expected that the user can obtain codeset information from this parameter.
server_side	Will be idl_true.
p_stag	This parameter is ignored.
p_drtag	Indicates the address at which the routine finds the value that designates the codeset that it wants the server to use when returning I-char data to the client. If no cs_drtag parameter has been specified for the operation, this value is 0 (zero).
p_rtag	Indicates the address to which the routine should write the value that designates the codeset being used on the wire for I-char data being sent to the client. If no cs_rtag parameter has been specified for the operation, this value is discarded.
p_st	Indicates the address to which a status value must be written. If the codeset(s) specified by the client make it impossible for the server to handle the call, this status value should be set to rpc_s_ss_incompatible_codesets.

If an operation that uses I-char data has the cs_tag_rtn attribute, the parameters marked as tags will not appear in the definition of the operation in the generated header file. Otherwise, it is the responsibility of application code to give the tags appropriate values before data is marshalled.

16.3 Example Use of Attributes

If an IDL file contains:

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[] );

The associated ACF contains:

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 );

Then the generated header file contains the following:

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[] );

In the server stub, a_op calls set_tags before any data is marshalled. For b_op, it is the function of the application code to ensure that the tags are set correctly before any data is marshalled.

16.4 Restrictions on the Use of Attributes

The following sections describe restrictions on the attributes used to manipulate I-char data in the IDL.

16.4.1 Data Order Constraints

When I-char 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:

• A cs_stag parameter must occur in an operation's parameter list before any in I-char data.
• A cs_rtag parameter must occur in an operation's parameter list before any out I-char data.

The requirement that a tag must be received before the data it relates to also imposes the following rules:

• A customized binding handle cannot include I-chars. This is because a binding handle must be the first parameter in a parameter list.
• The cs_char attribute cannot be applied to the base type of a pipe, or a type used in constructing the base type of a pipe.

The cs_char attribute 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.
• Any of the attributes min_is, max_is, first_is, last_is, or string have been applied to the array.

This means that 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.

In addition, there are the following restrictions on the use of variables that appear in array attributes can be used, as follows:

• 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.

No interaction between the I-char attribute and the transmit_as, represent_as, v1_struct or v1_array attributes is allowed.

This imposes the following rules:

• cs_char cannot be applied to a type which has the transmit_as attribute.
• cs_char cannot be applied to a type in whose definition a type with the transmit_as attribute is used.
• cs_char cannot be applied to a type which has the represent_as attribute.
• cs_char cannot 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.
• An array with the v1_array attribute cannot have a base type to which the cs_char attribute is applied.
• A structure that has the v1_struct attribute cannot have as a field an array whose base type has the cs_char attribute applied to it.

The following rules apply:

• 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.
• The cs_char attribute cannot be applied to the base type of an array parameter that has the unique or ptr attribute applied to it.

The routine name specified in a cs_tag_rtn attribute must be distinct from any type name, procedure name, constant name, or enumeration name appearing in the interface definition.

16.7 Local and Network Types

This section shows the relationship between IDL declarations and declarations in the generated header file in the presence of 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 assume that the ACF contains the type definition:

typedef [cs_char(ltype)] my_byte;

16.7.1 Fixed Array

If the IDL 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 on-the-wire representations of the data must be the same as the array size stated in the IDL.

16.7.2 Varying Array

If the IDL 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 on-the-wire representation may exceed the array size in the IDL.

16.7.3 Conformant Array

If the IDL 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 on-the-wire representation need not be the same. The conversions between these numbers is done in the user-provided _net_size and _local_size routines (see the section describing Codeset Conversion Routines for more information).

16.7.4 Conformant Varying Array

If the IDL 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 on-the-wire representation need not be the same. The conversions between these numbers is done in the user-provided _net_size and _local_size routines (see the section describing Codeset Conversion Routines for more information).

16.7.5 Storage Management Considerations

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, the you must determine the transformations between local storage size and on-the-wire storage size without reference to the characters being transmitted/received. Where a variable-width character set is in use, this means making the most pessimistic assumption about the size of the data.

16.8 Codeset Conversion Routines

The names of the user-supplied routines that are called to perform codeset conversion are formed by adding the extensions _net_size, _to_netcs, _local_size, _from_netcs to the type name, which appears in an cs_char attribute. Note that this limits the name of such a type to 20 characters.

For the purpose of discussing the signatures of these routines, assume that the ACF contains the following declaration:

typedef [cs_char(ltype)] my_byte;