The encode and decode attributes are used in conjunction with IDL encoding services routines (idl_es*) to enable RPC applications to encode data types in input parameters into a byte stream and decode data types in output parameters from a byte stream without invoking the RPC runtime. Encoding and decoding operations are analogous to marshalling and unmarshalling, except that the data is stored locally, and is not transmitted over the network.
The stubs that perform encoding or decoding operations are different from the stubs that perform RPC operations. The ACF attributes encode and decode direct the IDL compiler to generate encoding or decoding stubs for operations defined in a corresponding IDL interface rather than generating RPC stubs for those operations.
The encode and decode attributes have the following syntax. (See the example at the end of this topic.)
For an interface:
[encode] | [decode] | [encode,decode] interface interface_name
For an operation:
[encode] | [decode] | [encode,decode] operation_name ([parameter_list]);
When used as an ACF interface attribute, the encode and decode attributes apply to all operations defined in the corresponding IDL file. When used as an ACF operation attribute, encode and decode apply only to the operation you specify. If you apply the encode or decode attribute to an ACF interface or operation, you must not use the auto_handle or the implicit_handle ACF attributes.
When you apply the encode or decode attribute to an operation, the IDL compiler generates IDL encoding services stubs that support encoding or decoding, depending on the attribute used, in the client stub code, and does not generate stub code for the operation in the server stub. To generate an IDL encoding services stub that supports both encoding and decoding, apply both attributes to the operation.
If you apply the encode or decode attribute to all of the operations in an interface, no server stub is generated. If you apply the encode and decode attributes to some, but not all, of the operations in an interface, the stubs for the operations that do not have the encode and decode attributes applied to them are generated as RPC stubs into the server stub module.
When data encoding takes place, only the operation's in parameters provide data for the encoding. When data decoding takes place, the decoded data is delivered only to the operation's out parameters.
If data is being both encoded and decoded, you generally declare all of the operation's parameters to be in,out. However, you can encode data using the in parameters of one operation, and decode it using the out parameters of another operation if the types and order of the in and out parameters are the same. For equivalence, the IDL encoding services treat a function result as an out parameter that appears after all other out parameters.
In the following example, the IDL compiler generates IDL encoding services stub code for the in_array_op1, out_array_op1, and array_op2 operations, but not for the array_op3 operation. The stub code generated for the in_array_op1 operation supports encoding, the stub code generated for the out_array_op1 operation supports decoding, and the stub code generated for the array_op2 operation supports both encoding and decoding. The stub code generated for the array_op3 is an RPC client stub. For further information on using the IDL encoding services, see Creating Portable Data via the IDL Encoding Services and the reference pages for the idl_es*(3rpc) routines in the OSF DCE Application Development Reference.
Example Using the encode and decode Attributes
ACF
interface es_array
{
[encode] in_array_op1();
[decode] out_array_op1();
[encode, decode] array_op2();
}
IDL File
[uuid(20aac780-5398-11c9-b996-08002b13d56d), version(0)]
interface es_array
{
void in_array_op1([in] handle_t h, [in] long arr[100]);
void out_array_op1([in] handle_t h, [out] long arr[100]);
void array_op2([in] handle_t h, [in,out] long big[100]);
void array_op3([in] handle_t h, [in,out] long big[100]);
}