Previous section.

CDE 1.1: Remote Procedure Call
Copyright © 1997 The Open Group

Interface Definition Language

The Interface Definition Language (IDL) is a language for specifying operations (procedures or functions), parameters to these operations, and data types. This chapter specifies IDL and the associated Attribute Configuration Source (ACS). It includes:

Notation

The syntax of IDL and ACS is described using an extended BNF (Backus-Naur Form) notation. The meaning of the BNF notation is as follows:

Elements in the grammar that are capitalised are terminals of the grammar. For example, <Identifier> is not further expanded. Also, keywords of the language are terminals of the grammar. For example, the keyword boolean is not further expanded.

IDL Language Specification

The syntax of the IDL language is derived from that of the ISO C programming language. Where a term in this description of the IDL language is not fully defined, the C-language definition of that term is implied.

This chapter specifies both language syntax and semantics. As a result, the syntax is presented in pieces. Grammar Synopsis provides a syntax summary, with the productions in the order in which they appear in this chapter. An alphabetical cross-reference to the language syntax is also provided in Alphabetic Listing of Productions .

IDL Lexemes

The following subsections define the lexemes of the IDL language.

Keywords and Reserved Words

The IDL contains keywords, which are listed in IDL and ACS Reserved Words . Some keywords are reserved words, and must not be used as identifiers. Keywords that are not reserved may be used as identifiers, except when used as attributes (that is, within [] (brackets)).

Identifiers

Each object is named with a unique identifier. The maximum length of an identifier is 31 characters.

Some identifiers are used as a base from which the compiler constructs other identifiers. These identifiers have further restrictions on their length. Constructed Identifier Classes lists the classes and maximum lengths of identifiers that are used as bases. The character set for identifiers is the alphabetic characters A to Z and a to z, the digits 0 to 9, and the _ (underbar) character. An identifier must start with an alphabetic character or the _ (underbar) character.

The IDL is a case-sensitive language.

Restrictions on Names

Interface specifications must observe the following restrictions on names:

IDL Punctuation

The punctuation used in IDL consists of the following characters:

Alternate Representation of Braces

The { (open brace) and } (close brace) characters are defined as national replacement set characters by ISO and may not be present on all keyboards. Wherever an open brace is specified, the ??< trigraph may be substituted. Wherever a close brace is specified, the ??> trigraph may be substituted. These substitutions are the same as those specified in the ISO C standard.

White Space

White space is a character sequence that can be used to delimit any of the other low-level constructs. The syntax of white space is as follows:

A language keyword, an <Identifier> or a list of <Digit>s must be preceded by a punctuation character or by white space. A language keyword, an <Identifier> or a list of <Digit>s must be followed by a punctuation character or by white space. Any punctuation character may be preceded or followed by white space.

Comments

The /* (slash and asterisk) characters introduce a comment. The contents of a comment are examined only to find the */ (asterisk and slash) that terminate it. Thus, comments do not nest. One or more comments may occur before the first non-comment lexical element of the IDL source, between any two lexical elements of the IDL source, or after the last non-comment lexical element of the IDL source.

Interface Definition Structure

An interface definition written in IDL has the following structure:

<interface> ::= <interface_header> { <interface_body> }

Interface Header

The structure of the interface header is as follows:

<interface_header> ::= <[> <interface_attributes> <]> interface <Identifier>

where:
<interface_attributes> ::= <interface_attribute> [ , <interface_attribute> ] ... <interface_attribute> ::= uuid ( <Uuid_rep> ) | version ( <Integer_literal>[.<Integer_literal>]) | endpoint ( <port_spec> [ , <port_spec> ] ... ) | exceptions ( <excep_name> [ , <excep_name> ] ... ) | local | pointer_default ( <ptr_attr> ) <port_spec> ::= <Family_string> : <[> <Port_string> <]> <excep_name> ::= <Identifier>

If an interface defines any operations, exactly one of the uuid attribute or the local attribute must be specified. Whichever is specified must appear exactly once.

It is permissible to have neither the uuid nor the local attribute if the interface defines no operations. The version attribute may occur at most once.

The uuid Attribute

The uuid attribute designates the UUID that is assigned to the interface to identify it uniquely among all interfaces. The uuid attribute is expressed by the uuid keyword followed by a string of characters that gives the literal representation of the UUID.

The textual representation of a UUID is a string that consists of 8 hexadecimal digits followed by a dash, followed by 3 groups of 4 hexadecimal digits where the groups are separated by dashes, followed by a dash followed by 12 hexadecimal digits. Hexadecimal digits with alphabetic representations may use upper case or lower case. The following is an example of the textual representation of a UUID:

12345678-9012-b456-8001-080020b033d7

All UUIDs are machine generated in a manner that gives high guarantees of uniqueness. For an architectural definition of UUIDs and a full discussion of their guarantees, refer to Universal Unique Identifier .

The version Attribute

The version attribute identifies a specific version of a remote interface when multiple versions of the interface exist. Version semantics are specified in Remote Procedure Call Model . The version attribute is represented by the version keyword followed by a decimal integer that represents the major version number of the interface, or two decimal integers separated by a dot, where the first integer represents the major version number and the second represents the minor version number. White space is not allowed between the two integers and the dot.

Legal Values for Version Numbers

The major and minor version numbers of an interface must each have a value between 0 and 65,535, inclusive.

Version Number Defaults

The defaulting rules for interface version numbers are as follows:

The endpoint Attribute

The endpoint attribute specifies the well-known endpoint(s) on which servers that export the interface will listen. Well-known endpoint values are typically assigned by the central authority that owns the protocol.

A <port_spec> is composed of two strings separated by punctuation as described in the syntax. The <Family_string> identifies the protocol family to be used; the <Port_string> identifies the well-known endpoint designation for that family.

The actual syntax of <Port_string> is family-dependent. Registered values of <Port_string> are given in Endpoint Mapper Well-known Ports .

The exceptions Attribute
The exceptions attribute specifies a set of user-defined exceptions that can be generated by the server implementation of the interface.

The local Attribute

The local attribute provides a means to use the IDL compiler as a header generation language. When the local attribute is specified, the uuid attribute must not be specified.

Stubs are not generated for local interfaces. Checks for data transmissibility are omitted.

The pointer_default Attribute

The pointer_default attribute specifies the default treatment for pointers. If no pointer_default attribute is specified in the interface attributes, and a construct requiring a default pointer class is used, the compiler will issue an error. (See Pointers for more information.)

Interface Body

The structure of the interface body is as follows:

<interface_body> ::= [ <import> ... ] <interface_component> [ <interface_component> ... ]

where:

<import> ::= import <import_list> ; <interface_component> ::= <export> | <op_declarator> ; <export> ::= <type_declarator> ; | <const_declarator> ; | <tagged_declarator> ;

Import Declaration

The syntax of the <import_list> in an import declaration is as follows:

<import_list> ::= <import_name> [ , <import_name> ] ... <import_name> ::= "<Import_string>"

where: <Import_string> gives a system dependent name for an import source.

The IDL [??]import[??] declaration specifies another interface definition whose types and constants are used by the importing interface. It is similar to the [??]include[??] declaration in C. The imported definition must in itself adhere to all specifications in this chapter.

Constant Declaration

The following subsections specify the syntax and semantics of constant declarations.

Syntax

The syntax for a constant declaration is as follows:

<const_declarator> ::= const <const_type_spec> <Identifier> = <const_exp> <const_type_spec> ::= <primitive_integer_type> | char | boolean | void * | char * <const_exp> ::= <integer_const_exp> | <Identifier> | <string> | <character_constant> | NULL | TRUE | FALSE <integer_const_exp> ::= <conditional_exp> <conditional_exp> ::= <logical_or_exp> | <logical_or_exp> ? <integer_const_exp> : <conditional_exp> <logical_or_exp> ::= <logical_and_exp> | <logical_or_exp> <||> <logical_and_exp> <logical_and_exp> ::= <inclusive_or_exp> | <logical_and_exp> && <inclusive_or_exp> <inclusive_or_exp> ::= <exclusive_or_exp> | <inclusive_or_exp> <|> <exclusive_or_exp> <exclusive_or_exp> ::= <and_exp> | <exclusive_or_exp> ^ <and_exp> <and_exp> ::= <equality_exp> | <and_exp> & <equality_exp> <equality_exp> ::= <relational_exp> | <equality_exp> == <relational_exp> | <equality_exp> != <relational_exp> <relational_exp> ::= <shift_exp> | <relational_exp> <<> <shift_exp> | <relational_exp> <>> <shift_exp> | <relational_exp> <<=> <shift_exp> | <relational_exp> <>=> <shift_exp> <shift_exp> ::= <additive_exp> | <shift_exp> <<<> <additive_exp> | <shift_exp> <>>> <additive_exp> <additive_exp> ::= <multiplicative_exp> | <additive_exp> + <multiplicative_exp> | <additive_exp> - <multiplicative_exp> <multiplicative_exp> ::= <unary_exp> | <multiplicative_exp> * <unary_exp> | <multiplicative_exp> / <unary_exp> | <multiplicative_exp> % <unary_exp> <unary_exp> ::= <primary_exp> | + <primary_exp> | - <primary_exp> | ~ <primary_exp> | ! <primary_exp> <primary_exp> ::= <Integer_literal> | <Identifier> | '(' <const_exp> ')' <string> ::= "[<Character>] ... " <character_constant> ::= '<Character>'
Semantics and Restrictions

The <integer_size> keyword hyper must not appear in a constant declaration. <Character> is a character from the portable character set specified in Portable Character Set .

In the production <string>, no <Character> is permitted to be the " (double quote) character, which is the delimiter, unless it is immediately preceded by the \ (backslash) character. In the production <character_constant>, no <Character> may be the ' (single quote) character, which is the delimiter, unless it is immediately preceded by the \ (backslash) character.

<Integer_literal> may appear if and only if <const_type_spec> is long, short, small, unsigned long, unsigned short or unsigned small.

A <character_constant> may appear if and only if <const_type_spec> is char. NULL may appear if and only if <const_type_spec> is void*.

TRUE or FALSE may appear if and only if <const_type_spec> is boolean.

<string> may appear if and only if <const_type_spec> is char*. Within a <string> a \ (backslash) is interpreted as introducing an escape sequence, as defined in ISO C standard, Section 3.1.3.4. White space within a <string> is significant and is preserved as part of the text of the string.

An <Identifier> must have been defined in a preceding constant declaration. The type that <Identifier> was defined to be in that declaration must be consistent with the <const_type_spec> in the current declaration.

Type Declarations and Tagged Declarations

The syntax for type declarations and tagged declarations is as follows:

<type_declarator> ::= typedef [ <type_attribute_list> ] <type_spec> <declarators> <type_attribute_list> ::= <[> <type_attribute> [ , <type_attribute> ] ... <]> <type_spec> ::= <simple_type_spec> | <constructed_type_spec> <simple_type_spec> ::= <base_type_spec> | <predefined_type_spec> | <Identifier> <declarators> ::= <declarator> [ , <declarator> ] ... <declarator> ::= <pointer_opt> <direct_declarator> <direct_declarator> ::= <Identifier> | ( <declarator> ) | <array_declarator> | <function_declarator> <tagged_declarator> ::= <tagged_struct_declarator> | <tagged_union_declarator>

If a <simple_type_spec> is an <Identifier>, that <Identifier> must have been defined previously.

Base Types

The base types are the fundamental data types of the IDL. Any other data types in an interface definition are derived from these types. Syntax gives the syntax rules for the base types. Integer Types to The handle_t Type define the various types.

Syntax

The syntax rules for use of the base types are as follows:

<base_type_spec> ::= <floating_pt_type> | <integer_type> | <char_type> | <boolean_type> | <byte_type> | <void_type> | <handle_type> <floating_pt_type> ::= float | double <integer_type> ::= <primitive_integer_type> | hyper [unsigned] [int] | unsigned hyper [int] <primitive_integer_type> ::= <signed_integer> | <unsigned_integer> <signed_integer> ::= <integer_size> [ int ] <unsigned_integer> ::= <integer_size> unsigned [ int ] | unsigned <integer_size> [ int ] <integer_size> ::= long | short | small <char_type> ::= [ unsigned ] char <boolean_type> ::= boolean <byte_type> ::= byte <void_type> ::= void <handle_type> ::= handle_t
Integer Types

Integer Base Types lists the integer types and their ranges.


Type Range
hyper -263, ..., 263-1
long -231, ..., 231-1
short -215, ..., 215-1
small -27, ..., 27-1
unsigned hyper 0, ..., 264-1
unsigned long 0, ..., 232-1
unsigned short 0, ..., 216-1
unsigned small 0, ..., 28-1


Table: Integer Base Types
The char Types

The keywords char and unsigned char are synonymous. Portable Character Set contains portable character set values.

The boolean Type

The boolean keyword is used to indicate a data item that can only take one of the values TRUE and FALSE.

The byte Type

A byte data item consists of opaque data: that is, its contents are not interpreted.

The void Type

The void keyword is valid only in an operation or pointer declaration. In an operation declaration, it may be used to indicate an operation that does not return a function result value. In a pointer declaration, it must be used in conjunction with the context_handle attribute.

The handle_t Type

The handle_t type is used to declare a primitive handle object. A primitive handle can be declared in a type declaration or in a parameter list. If it is declared in a parameter list, it must be the first parameter in the list.

Constructed Types

The syntax of constructed types is as follows:

<constructed_type_spec> ::= <struct_type> | <union_type> | <enumeration_type> | <tagged_declarator> | <pipe_type>

Structures

The syntax of structures is as follows:

<tagged_struct_declarator> ::= struct <tag> | <tagged_struct> <struct_type> ::= struct { <member_list> } <tagged_struct> ::= struct <tag> { <member_list> } <tag> ::= <Identifier> <member_list> ::= <member> [ <member> ] ... <member> ::= <field_declarator> ; <field_declarator> ::= [ <field_attribute_list> ] <type_spec> <declarators> <field_attribute_list> ::= <[> <field_attribute> [ , <field_attribute> ] ... <]>

ISO C semantics apply to IDL structures.

Unions

The following subsections describe IDL unions.

Syntax

The syntax for a union definition is:

<tagged_union_declarator> ::= union <tag> | <tagged_union> <union_type> ::= union <union_switch> { <union_body> } | union { <union_body_n_e> } <union_switch> ::= switch ( <switch_type_spec> <Identifier> ) [ <union_name> ] <switch_type_spec> ::= <primitive_integer_type> | <char_type> | <boolean_type> | <Identifier> <tagged_union> ::= union <tag> <union_switch> { <union_body> } | union <tag> { <union_body_n_e> } <union_name> ::= <Identifier> <union_body> ::= <union_case> [ <union_case> ] ... <union_body_n_e> ::= <union_case_n_e> [ <union_case_n_e> ] ... <union_case> ::= <union_case_label> [ <union_case_label> ] ... <union_arm> | <default_case> <union_case_n_e> ::= <union_case_label_n_e> <union_arm> | <default_case_n_e> <union_case_label> ::= case <const_exp> : <union_case_label_n_e> ::= <[> case ( <const_exp> [ , <const_exp> ] ... ) <]> <default_case> ::= default : <union_arm> <default_case_n_e> ::= <[> default <]> <union_arm> <union_arm> ::= [ <field_declarator> ] ; <union_type_switch_attr> ::= switch_type ( <switch_type_spec> ) <union_instance_switch_attr> ::= switch_is ( <attr_var> )
Encapsulated Unions

Encapsulated unions are created with the <union_switch> production.

Note:
Encapsulated unions are so named because the discriminant and the union are tightly bound; that is, in a typical implementation they are both automatically encapsulated in a single structure.
Non-encapsulated Unions

A union that is created without the use of the <union_switch> production is a non-encapsulated union. The discriminant of a non-encapsulated union is another parameter if the union is a parameter, or another structure field if the union is a structure field.

When the non-encapsulated union is declared as a type, the <union_type_switch_attr> production must be used. When a type that is a non-encapsulated type is used to declare a structure field or a parameter, the <union_instance_switch_attr> production must be used. When a non-encapsulated union is being declared directly as a structure field or parameter, the <union_instance_switch_attr> production must be used.

Semantics and Restrictions

In encapsulated unions, if the <union_name> is omitted, the union is assigned the name tagged_union in the generated header source.

The <default_case> defines the layout of data if the discriminant variable of the switch is not equal to any of the case values.

Within a union, the type of each <union_case_label> must be that specified by the <switch_type_spec>. Likewise the type specified in the <union_type_switch_attr> and the <union_instance_switch_attr> must be the same.

A field within a union definition must not be or contain a conformant or conformant varying array. (See Arrays for descriptions of conformant and conformant varying arrays.)

A union arm that consists solely of a terminating semicolon is legal and specifies a null arm.

There must be at most one default case for a union.

When the <Identifier> alternative is used in the <switch_type_spec> production to declare a switch type, <Identifier> must identify a declared type that resolves to the primitive integer type, the char type, the boolean type, or an enum type; it cannot be a pointer, pipe, struct or array type.

Enumerated Types

The syntax of enumerated types is as follows:

<enumeration_type> ::= enum { <Identifier> [ , <Identifier> ] ... }

The <Identifier>s are mapped from left to right onto consecutive integers, beginning with the value zero.

An enumeration may have up to 32,767 <Identifier>s.

Pipes

IDL supports streams of typed data. The programming construct to support this is pipe, which is a type constructor that is similar to struct and union.

An in parameter that is a pipe allows a callee to pull an open-ended stream of typed data from a caller. An out parameter that is a pipe allows a callee to push an open-ended stream back to a caller. An in, out parameter that is a pipe allows for two-way transfer of data between callee and caller.

Syntax

The syntax used to declare a pipe type is as follows:

<pipe_type> ::= pipe <type_spec>
Semantics and Restrictions

Data types that are pipes are subject to several restrictions:

Also, an operation that has one or more pipe parameters must not have the idempotent attribute.

Arrays

The following sections describe the syntax and semantics of arrays.

Syntax

The syntax rules for array declarations are as follows:

<array_declarator> ::= <direct_declarator> <array_bounds_declarator> <array_bounds_declarator> ::= <[> [ <array_bound> ] <]> | <[> <array_bounds_pair> <]> <array_bounds_pair> ::= <array_bound> .. <array_bound> <array_bound> ::= * | <integer_const_exp> | <Identifier>
Semantics and Restrictions

The bounds of each dimension of an array are expressed inside a separate <[>, <]> (bracket) pair.

If the bracket pair contains a single <const_exp> that evaluates to n, a lower bound of zero and an upper bound of n-1 are signified.

If the bracket pair is empty or contains a single * (asterisk), a lower bound of zero and an upper bound to be determined at run time are signified.

In an <array_bounds_pair> the <array_bound> preceding the .. (dot dot) indicates the lower bound of the dimension and the <array_bound> following the .. (dot dot) indicates the upper bound.

An * (asterisk) before or after .. (dot dot) means that the corresponding bound is to be determined at run time.

Any <Identifier> appearing as an array bound must resolve to an integer constant. The base type of an array cannot be a conformant array or conformant structure.

Arrays of Arrays

The user may declare types that are arrays and then declare arrays of objects of such types. The semantics of an m-dimensional array of objects of a type defined to be an n-dimensional array are the same as the semantics of an m+n-dimensional array.

Type Attributes

The following sections describe type attributes.

Syntax

The syntax for type attributes is as follows:

<type_attribute> ::= transmit_as ( <xmit_type> ) | handle | <usage_attribute> | <union_type_switch_attr> | <ptr_attr> <usage_attribute> ::= string | context_handle <xmit_type> ::= <simple_type_spec>
Semantics and Restrictions

Attributes that are specified for a type in a typedef statement are inherited by declarations that specify that type. A parameter of a call inherits the attributes of its corresponding type.

The transmit_as Attribute

The transmit_as attribute associates a presented type in the target language with an IDL transmitted type, <xmit_type>. The user must supply routines that perform conversions between the presented and transmitted types, and that release memory used to hold the converted data.

The <xmit_type> in a transmit_as attribute must be either a <base_type_spec>, a <predefined_type_spec> or an <Identifier> from a <type_declarator> that was previously defined.

The following types must not have the transmit_as attribute:

Interaction of IDL transmit_as and IDL handle Attributes for the interaction of the transmit_as and handle attributes.

The handle Attribute

The handle attribute specifies that a type may serve as a customised handle. Customised handles permit the design of handles that are meaningful to an application. The user must provide binding and unbinding routines to convert between the custom handle type and the primitive handle type, handle_t.

The string Attribute

The string attribute is provided to preserve the string property of data so that it may be appropriately processed by application components written in languages that support a string data type.

The string attribute only applies to one-dimensional arrays. The element type of such an array is limited to one of the following:

  1. char

  2. byte

  3. A structure all of whose members are of type byte, or a named type that resolves to byte. For this purpose, the NULL-terminated string construct supported in C through the str... library routines serves as a string data type. If the base type of a string is larger than one byte, then the required NULL terminator must be composed of the same number of bytes as the base type.

  4. unsigned short

  5. unsigned long

  6. A named type that resolves to one of items 1, 2, 3, 4, or 5.

Note that strings of element type char or byte are terminated by the NULL character, while those of element type unsigned short or unsigned long are terminated by the array element zero (0).

For further information on objects with the string attribute, see Field Attributes in String Declarations .

The context_handle Attribute

In many interfaces, a called procedure needs to maintain state between calls. This is done by means of a context handle. A context handle is a void* with the context_handle attribute.

There are several restrictions on the use of context handles:

Field Attributes

The following sections describe the syntax and semantics of field attributes.

Syntax

The syntax for declaring field attributes is as follows:

<field_attribute> ::= first_is ( <attr_var_list> ) | last_is ( <attr_var_list> ) | length_is ( <attr_var_list> ) | min_is ( <attr_var_list> ) | max_is ( <attr_var_list> ) | size_is ( <attr_var_list> ) | <usage_attribute> | <union_instance_switch_attr> | ignore | <ptr_attr> <attr_var_list> ::= <attr_var> [ , <attr_var> ] ... <attr_var> ::= [ [ * ] <Identifier> ]
Semantics and Restrictions

A <usage_attribute> must not be applied to an item of a type that resolves to a type with a <usage_attribute> in its declaration. For the form *<Identifier>, the <Identifier> in the <attr_var> must be a pointer to a <primitive_integer_type>. The context_handle attribute is not permitted on fields. Therefore, the <usage_attribute> must not resolve to context_handle in this production.

The ignore Attribute

The ignore attribute is used for a pointer, contained within a structure, that must not be dereferenced. The ignore attribute is restricted to pointer members of structures.

Field Attributes in Array Declarations

Field attributes are used in conjunction with array declarations to specify either the size of the array, or the portion of the array that contains valid data. To do this, they associate another parameter or structure field with the array. The associated datum contains the extra information. Array parameters must associate with another parameter, and array structure fields must associate with another field. Array parameters with field attributes are not allowed to have a transmit_as attribute associated with their type. Since an array parameter with one or more of the field attributes min_is, max_is, size_is, first_is, last_is or length_is is fully described only in the presence of another parameter, it cannot be properly processed by the <type_id>_to_xmit_type routine.

Conformant Arrays

An array is called conformant if it has an <array_bounds_declarator> that is empty or contains an * (asterisk). Conformant arrays have one of the attributes min_is, max_is, or size_is. If the lower bound of any dimension of an array is unspecified, the array must have the min_is attribute; if the upper bound of any dimension of an array is unspecified, the array must have the either the max_is attribute or the size_is attribute, but not both.

The min_is Attribute

The min_is attribute is used to specify the minimum array indexes in each dimension of an array. Each <attr_var> in a min_is clause specifies the minimum array index in one dimension.

An <attr_var> must be non-NULL if and only if the lower bound of the corresponding dimension is empty or is an * (asterisk). At least one <attr_var> in a min_is clause must be non-NULL.

An <attr_var> must be present for each dimension of an array for which the lower bound is unspecified. The <attr_var>s in a min_is clause are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.

The max_is Attribute

The max_is attribute is used to specify the maximum array indexes in each dimension of an array. Each <attr_var> in a max_is clause specifies the maximum array index in one dimension.

An <attr_var> must be non-NULL if and only if the upper bound of the corresponding dimension is empty or is an * (asterisk). At least one <attr_var> in a max_is clause must be non-NULL.

An <attr_var> must be present for each dimension of an array for which the upper bound is unspecified. The <attr_var>s in a max_is clause are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.

If a declaration has the max_is attribute, it must not have the size_is attribute. (See The size_is Attribute for the relationship between these two attributes.)

The size_is Attribute

The size_is attribute is used to specify the number of data elements in each dimension of an array. Each <attr_var> in a size_is clause specifies the number of data elements in one dimension.

An <attr_var> must be non-NULL if and only if the upper bound of the corresponding dimension is empty or contains an * (asterisk). At least one <attr_var> in a size_is clause must be non-NULL.

An <attr_var> must be present for each dimension of an array for which the upper bound is unspecified. The <attr_var>s in a size_is are in a one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.

If a declaration has a size_is attribute, it must not have a max_is attribute. A given conformant array may be declared using either the max_is or size_is attribute but not both. The relationship between the values of these attributes for a given array can be derived as follows: in the mth dimension of the array, the lowest index to be used in this dimension is specified by lower_bound_m. For a declaration using the max_is attribute, call the the mth <attr_var> max_value_m. For a declaration of the same array using the size_is attribute, call the mth <attr_var> size_value_m. For equivalent declarations, the relationship between these attribute values is then given by the equation:

size_value_m = max_value_m - lower_bound_m + 1
Varying and Conformant Varying Arrays

An array is called varying if none of its <array_bounds_declarator> components is empty or contains an * (asterisk), and it has either a last_is, first_is or length_is attribute. An array is called conformant varying if it is conformant and it has a last_is, first_is or length_is attribute.

The last_is Attribute

The last_is attribute is used to define the upper index bounds for significant elements in each dimension of an array. Each <attr_var> in a last_is clause indicates the highest index, in a given dimension, whose element value is significant both to the caller and the callee. Elements in a given dimension with indexes higher than the dimension's <attr_var> are not meaningful to caller and callee.

If the <attr_var> corresponding to a dimension in an array is null, then the value used is the corresponding dimension found in either the associated type definition for a varying array, or the value of the max_is or size_is parameter for a conformant varying array.

The <attr_var>s are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.

If a declaration has a last_is attribute, it must not have a length_is attribute. (See The length_is Attribute for the relationship between these two attributes.)

The first_is Attribute

The first_is attribute is used to define the lower index bounds for significant elements in each dimension of an array. Each <attr_var> in a first_is clause indicates the lowest index, in a given dimension, whose element value is significant both to the caller and the callee. Elements in a given dimension with indexes lower than the dimension's <attr_var> are not meaningful to caller and callee.

A NULL <attr_var> indicates that the lower bound for that dimension is to be used as the first_is value for that dimension. At least one <attr_var> in a first_is clause must be non-NULL.

The <attr_var>s are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.

The length_is Attribute

The length_is attribute is used to define the number of significant elements in each dimension of an array. Each <attr_var> in a length_is clause indicates the number of elements, in a given dimension, whose element value is significant both to the caller and the callee.

Significant elements in a given dimension are counted from the lowest significant index for that dimension. This may be the fixed lower bound for this dimension or may be specified by using a first_is clause.

At least one <attr_var> in a length_is clause must be non-NULL.

If a declaration has a length_is attribute, it must not have a last_is attribute.

A given varying array may be declared using either the last_is or length_is attribute. The relationship between the values of these attributes for a given array is derived as follows: in the mth dimension of the array, the lowest index to be used in this dimension is specified by lowest_index_m. For a declaration using the last_is attribute, call the the mth <attr_var> last_value_m. For a declaration of the same array using the length_is attribute, call the mth <attr_var> length_value_m. For equivalent declarations, the relationship between these attribute values is then given by the equation:

length_value_m = last_value_m - lowest_index_m + 1
Relationships Between Attributes

The following rules apply to the relationship between the max_is, first_is and last_is values for a dimension:

Negative Size and Length Specifications

If the size_is or length_is value is negative, the behaviour is undefined.

Field Attributes in String Declarations

The string attribute provides guidance to the stub generator that an array must be treated as a string when generating stubs for languages that support strings. When generating stubs for languages that do not support strings, they are treated simply as an array of the base type; that is, the string attribute is ignored.

When declaring a string, it is necessary to declare space for one more than the maximum number of characters the string is to hold.

The following subsections describe the use of each of the field attributes with strings.

The first_is, last_is and length_is Attributes

An array with the string attribute must not have any of the varying attributes; that is, first_is, last_is or length_is.

The max_is Attribute

The max_is attribute names a parameter or record field that holds one more than the highest allowable index for a data character of a string.

The min_is Attribute

The min_is attribute must not exceed the initial length of the declared sting.

The size_is Attribute

A size_is attribute is an alternative mechanism for defining the maximum amount of string data that may be present. If a declaration has a size_is attribute, it must not have a max_is attribute.

The usage of size_is and its relationship to max_is may be derived from the discussion contained in The size_is Attribute by using the obvious analogy between arrays with the string property and those without.

Pointers

The following sections describe pointers in IDL.

Syntax

The syntax for a pointer declaration is as follows:

<declarator> ::= <pointer_opt> <direct_declarator> <pointer_opt> ::= [<pointer>] <pointer> ::= *...

Elsewhere in the grammar, attributes are applied to entities involving pointer declarations. The production for pointer attributes is:

<ptr_attr> ::= ref | unique | ptr

A <ptr_attr> may be applied only to declarations with an explicit pointer declaration, or to the implicit pointer present for array parameters.

Semantics and Restrictions

Pointers are used in applications in a wide variety of ways. IDL currently supports three different levels of pointer capability:

Description of Reference Pointers

A reference pointer is one that is used for simple indirection. It has the following characteristics in any language that supports pointers:

If these restrictions are not met, the effects are undefined.

Description of Unique Pointers

A unique pointer is more flexible than a reference pointer. However, reference and unique pointers share several important characteristics.

The characteristics of a unique pointer are as follows:

Like a reference pointer, a unique pointer must not cause any aliasing of data within the operation. As with a reference pointer, data returned from the callee is written into the existing referent specified by the pointer (if it did not have the value NULL).

Description of Full Pointers

A full pointer has a wider range of capabilities. The characteristics of a full pointer are as follows:

Attributes Applicable to Pointers

The following IDL attributes are used to indicate the supported pointer classes:

ref
Representing reference pointers

unique
Representing unique pointers

ptr
Representing full pointers

These attributes may be used on parameters, structure and union members, and in type definitions.

Pointer Attributes in the Interface Header

At most, one <ptr_attr> may appear in the interface header. (This appears with the pointer_default attribute. See The pointer_default Attribute .) A <ptr_attr> must appear if any of the following is true:

If a <ptr_attr> that is not required according to the preceding rules appears in the interface header, it is ignored.

Pointer Attributes on Parameters

By default, the first1 indirection operator (an *, asterisk) in a parameter declaration is treated as a reference pointer. This is the pointer that accomplishes what is commonly termed "pass by reference". If there are multiple indirection operators in a parameter declaration, all but the first have the characteristic specified by <ptr_attr> in the interface header.

Any pointer attributes placed on a parameter (that is, directly in the syntax of an operation declaration) affect only the first pointer declaration. To affect any others, intermediate named types must be used.

Pointer Attributes on Function Results

If an operation returns a pointer to a type, then ptr is permitted as an operation attribute to describe the properties of the pointer. Even in the absence of this attribute, the meaning is that a full pointer is returned by the function. No pointer attribute other than ptr is permitted as an operation attribute.

Pointer Attributes in Member Declarations

By default, pointers in structure member and union arm declarations are interpreted as specified by the interface pointer attribute. In these contexts, the pointer attributes ref, ptr and unique may be applied to override the default for the top-level pointer in the pointer declaration.

Pointer Attributes in typedefs

Pointer attributes are allowed in typedefs. Pointer declarators at the top level of a typedef with a pointer attribute are always treated in accordance with the specified pointer attribute. Pointer declarators at the top level of a typedef without a pointer attribute and non-top-level pointers are interpreted according to the <ptr_attr> in the interface header of the interface in which it is defined.

Pointer attributes may only be applied where an explicit pointer declaration occurs. There is no way to override the pointer attribute of a declared type at the reference site.

Varying Arrays of Pointers

Varying arrays of pointers bear special attention because there may be more valid elements on the return from the call than there were at the start of the call.

Varying Arrays of ref Pointers

Because a reference pointer must not have the value NULL, special requirements apply to varying or conformant varying arrays of reference pointers. If:

then all array elements that are valid at the time of the call (the in, out case) or may be valid at the time of the return from the call must point to storage that can be written with the returned referents.

Unless the client and server have made some private arrangement, outside the IDL, that is binding on all client and server implementations, the caller must initialise all pointers of the array to point to valid memory, even those outside the limit specified by the last_is, first_is or length_is variable at the time of the call.

On the callee side, the callee stub must instantiate storage for each pointer in the varying array, regardless of the value of the associated last_is, first_is, or length_is variable at the time of the call, provided that the layout of the pointed-to storage can be determined at compile time; that is, the pointed to storage must contain no full pointers, unions, conformant arrays, conformant structures, and so on.

Varying Arrays of unique and ptr Pointers

Varying arrays of unique and full pointers are treated differently. Again, consider the case cited above: an in, out or out varying or conformant varying array whose associated <attr_var> (last_is, first_is or length_is) is also in, out or out.

When the array elements are unique or full pointers, array elements past the limit established by the associated last_is, first_is or length_is variable need not be initialised before the call on the caller side.

The callee stub does must initialise the array elements past the limit established by the associated last_is, first_is or length_is variable. If the called user code increases the number of valid elements, it must initialise those elements before the call returns to the called stub code.

On return from a call, array elements that were not valid at the time of a call are treated as uninitialised.

Restrictions on Pointers

The pointer support IDL provides is very powerful and flexible. At times this flexibility collides with other features of IDL, resulting in the following restrictions:

Pointers as Arrays

When declaring a conformant array parameter, IDL provides an alternative to using [] (brackets). A parameter that is a pointer to a type is treated as an array of that type if the parameter has any of the array attributes min_is, max_is, size_is.

Note that this equivalence of arrays and pointers is true only in parameter lists. As structure or union members, arrays and pointers are distinct. A structure or union member declared with bracket notation declares an array contained within the structure. A member declared to be a pointer is a pointer to a data element. If a structure field is a pointer and has a size_is, min_is, or max_is attribute, then it is a pointer to an array of data.

Because of parsing ambiguities, the language does not allow mixing pointer and bracket notation when declaring a pointer to a conformant array. The language does not allow declaring a pointer to a varying array. A pointer to a structure that contains a varying array must be used instead.

The array attributes controlling the valid range of elements may be applied to arrays declared as pointers, just as they apply to arrays declared with brackets; the size_is, min_is, max_is, last_is and length_is attributes may be applied to pointers, just as they may be to arrays.

Pointers with the string Attribute

A pointer to any of the base types specified in Base Types may have the string attribute. Its meaning is that the pointer is a pointer to a string of the base type. Such a string is equivalent to a conformant array, and is treated in accordance with the rules for a conformant array with the string attribute.

Possible Ambiguity Resolved

When dealing with an operation such as:

void op ([in] long s, [in, size_is(s)] long * * myarray);
a possible ambiguity arises. Is myarray a pointer to an array of longs, or an array of pointers to longs? IDL defines this signature to be an array of pointers to longs. The max_is and size_is attributes always apply to the top-level, or rightmost, * (asterisk) in the IDL signature of the parameter.

Operations

The syntax of an operation declaration is as follows:

<op_declarator> ::= [ <operation_attributes> ] <simple_type_spec> <Identifier> <param_declarators>

The syntax for operation attributes is:

<operation_attributes> ::= <[> <operation_attribute> [ , <operation_attribute> ] ... <]> <operation_attribute> ::= idempotent | broadcast | maybe | reflect_deletions | <usage_attribute> | <ptr_attr>

If none of idempotent, broadcast, maybe is present, at-most-once semantics are applied; the operation is executed no more than one time. If a remote call fails, it is not be retried automatically if there is any chance that the called code has started execution.

When used as an <operation_attribute>, the <ptr_attr> must not be the ref or unique attributes. (See Pointer Attributes on Function Results for more information on <ptr_attr> as an <operation_attribute>.)

An operation must not have an array type result.

The idempotent Attribute

The idempotent attribute indicates that the operation does not modify any state and/or yields the same result on each invocation.

An operation with the idempotent attribute must not have any pipe parameters.

The broadcast Attribute

The broadcast attribute specifies that the operation may be invoked multiple times concurrently as the result of a single RPC. This is different from the idempotent attribute, which specifies that a call may be retried in the event of failure. Operations with the broadcast attribute may be sent to multiple servers, effectively concurrently. The output arguments that the caller receives are taken from the first reply to return successfully. An operation with the broadcast attribute is implicitly an idempotent operation.

An operation with the broadcast attribute must not have any pipe parameters.

Depending on the network services in use, there may be some limitations on the availability and semantics of this attribute.

The maybe Attribute

The maybe attribute specifies that the operation's caller must not require and must not receive a response or fault indication. An operation with the maybe attribute must not contain any output parameters and is implicitly an idempotent operation.

An operation with the maybe attribute must not have any pipe parameters.

The reflect_deletions Attribute

The reflect_deletions attribute specifies that memory occupied by targets of pointers on the client will be released when the corresponding targets of pointers on the server are released. This is true only for targets that are components of in parameters of the operation.

Parameter Declarations

The following sections describe the syntax and semantics of parameter declarations.

Syntax

The syntax rules for parameter declarations are as follows:

<param_declarators> ::= ( [ <param_declarator> 
	[ , <param_declarator> ] ... ] )
	| ( void )
<param_declarator> ::= <param_attributes> <type_spec> <declarator>
<param_attributes> ::= <[> <param_attribute> 
	[ , <param_attribute> ] ... <]>

<param_attribute> ::= <directional_attribute>  
	| <field_attribute>
<directional_attribute> ::= in  
	| out 

Semantics and Restrictions

If the <param_declarators> production consists of only a pair of parentheses, the semantics are the same as if the keyword void appeared between the parentheses. The remote operation has no parameters.

Directional Attributes

At least one directional attribute must be specified for each parameter. IDL Directional Attributes gives the meanings of the directional attributes.


Attribute Meaning
in The parameter is passed from the caller to the callee.
out The parameter is passed from the callee to the caller.


Table: IDL Directional Attributes

A parameter with the out attribute must be either an array or an explicitly declared pointer. An explicitly declared pointer is declared by a pointer declarator, rather than by a <declarator> with a named parameter as its type_spec.

Any parameter from which the binding for a call is to be derived must have the in attribute. If an operation has an in handle_t, in customised handle (handle) or in context handle (context_handle), and also contains an in, out context handle, the in, out context handle may be null. If an operation does not have an in handle_t, in customised handle or in context handle, but does contain one or more in, out context handles, at least one of the in, out context handles must be non-null.

Aliasing in Parameter Lists

If two pointer parameters in a parameter list point at the same data item, or at data structures that have some items in common, parameter aliasing is said to occur.

Aliasing is supported only for full pointers; both parameters involved in the aliasing must be full pointers. Full pointers are aliases when:

  1. They have the same value.

  2. They are declared to point to the same type.

  3. The size of the pointed-to type, as determined at or before run time, is the same.

The scope of aliasing is a single instance of an RPC call. Aliasing is not preserved across nested RPCs.

Aliasing of reference pointers is not supported and yields unspecified results. Aliasing is not supported for the case where the target of one pointer is a component (for example, a structure field or array element) of another pointer. This yields unspecified results.

Function Pointers

The following sections describe the syntax, semantics and restrictions of function pointers.

Syntax

The syntax for declaration of a function pointer is:

<function_declarator> ::= <direct_declarator> <param_declarators>
Semantics

An instance of a function pointer type allows functions to be referenced indirectly.

Restrictions

Function pointers are permitted only within interfaces declared with the local attribute.

Predefined Types

Predefined types are data types derived from the base types that are intrinsic to the IDL language. The syntax for predefined types is as follows:

<predefined_type_spec> ::= error_status_t | <international_character_type> <international_character_type> ::= ISO_LATIN_1 | ISO_MULTILINGUAL | ISO_UCS

The error_status_t Type

The error_status_t type is used to declare an object in which communications and fault status information can be held. This is the appropriate type for objects with the comm_status or fault_status attributes.

Note:
The error_status_t type is transmitted as an IDL unsigned long. However, implementations may choose to unmarshal this type as a local operating system error type instead of unsigned long.

International Character Types

The following types may be used to represent alternative character sets:

ISO_LATIN_1 ISO_MULTI_LINGUAL ISO_UCS

Data of type char is subject to ASCII/EBCDIC conversion when it is transmitted by the RPC mechanism. The predefined international character types are protected from data representation format conversion.

Anonymous Types

An enumeration type is said to be anonymous if it is not a type named through a typedef statement. A structure or union type is said to be anonymous if it does not have a tag and is not named through a typedef statement. The following rules apply to the usage of anonymous types:

The Attribute Configuration Source

The Attribute Configuration Source (ACS) is used to specify details of a stub to be generated. ACS is used to create a separate attribute configuration source that accompanies an IDL specification. The ACS specification affects the interface between the application code and the stub; for example, it can specify whether an explicit binding handle parameter is used. The ACS specification also affects the way stub code is generated. The ACS specification does not affect the way the data is transmitted or received during a remote procedure call; this is determined entirely by the IDL specification.

Comments

Comments in ACS conform to the same rules as IDL comments.

Identifiers

Each ACS source is associated with some IDL source. The following associations apply:

Syntax

The syntax of an ACS specification is as follows:

<ACS_interface> ::= <ACS_interface_header>  { <ACS_interface_body> } 
where 

<ACS_interface_header> ::= [ <ACS_interface_attr_list> ] interface <ACS_interface_name> <ACS_interface_attr_list> ::= <[> <ACS_interface_attrs> <]> <ACS_interface_attrs> ::= <ACS_interface_attr> [ , <ACS_interface_attr> ] ... <ACS_interface_attr> ::= <ACS_code_attr> | <ACS_nocode_attr> | <ACS_explicit_handle_attr> | <ACS_implicit_handle_attr> | <ACS_auto_handle_attr> | <ACS_cs_tag_rtn_attr> | <ACS_extern_exceps_attr> | <ACS_binding_callout_attr> <ACS_explicit_handle_attr> ::= explicit_handle <ACS_implicit_handle_attr> ::= implicit_handle ( <ACS_named_type> <Identifier> ) <ACS_auto_handle_attr> ::= auto_handle <ACS_extern_exceps_attr> ::= extern_exceptions ( <ACS_ext_excep_list> ) <ACS_ext_exceps_list> ::= <ACS_ext_excep> [ , <ACS_ext_excep> ] ... <ACS_ext_excep> ::= <Identifier> <ACS_binding_callout_attr> ::= binding_callout ( <ACS_bind_call_rtn_name> ) <ACS_bind_call_rtn_name> ::= <Identifier> <ACS_interface_name> ::= <Identifier> <ACS_interface_body> ::= [ <ACS_body_element> ] ... <ACS_body_element> ::= <ACS_include> ; | <ACS_type_declaration> ; | <ACS_oper> ; <ACS_include> ::= include <ACS_include_list> <ACS_include_list> ::= <ACS_include_name> [ , <ACS_include_name> ] ... <ACS_include_name> ::= "<Import_string>" <ACS_type_declaration> ::= typedef [ <ACS_type_attr_list> ] <ACS_named_type> <ACS_named_type> ::= <Identifier> <ACS_type_attr_list> ::= <[> <ACS_type_attrs> <]> <ACS_type_attrs> ::= <ACS_type_attr> [ , <ACS_type_attr> ] ... <ACS_type_attr> ::= <ACS_repr_attr> | <ACS_cs_char_attr> | <ACS_heap_attr> <ACS_repr_attr> ::= represent_as ( <ACS_repr_type> ) <ACS_cs_char_attr> ::= cs_char C ( <ACS_cs_char_type> ) <ACS_cs_char_type> ::= <ACS_named_type> <ACS_repr_type> ::= <Identifier> <ACS_oper> ::= [ <ACS_oper_attr_list> ] <Identifier> ( [ <ACS_params> ] ) <ACS_oper_attr_list> ::= <[> <ACS_oper_attrs> <]> <ACS_oper_attrs> ::= <ACS_oper_attr> [ , <ACS_oper_attr> ] ... <ACS_oper_attr> ::= <ACS_commstat_attr> | <ACS_faultstat_attr> | <ACS_code_attr> | <ACS_nocode_attr> | <ACS_explicit_handle_attr> | <ACS_enable_alloc_attr> | <ACS_cs_tag_rtn_attr> <ACS_cs_tag_rtn_attr> ::= cs_tag_rtn ( <acf_cs_tag_rtn_name> ) <ACS_cs_tag_rtn_name> ::= <Identifier> <ACS_params> ::= <ACS_param> [ , <ACS_param> ] ... <ACS_param> ::= [ <ACS_param_attr_list> ] <Identifier> <ACS_param_attr_list> ::= <[> <ACS_param_attrs> <]> <ACS_param_attrs> ::= <ACS_param_attr> [ , <ACS_param_attr> ] ... <ACS_param_attr> ::= <ACS_commstat_attr> | <ACS_faultstat_attr> | <ACS_cs_stag_attr> | <ACS_cs_drtag_attr> | <ACS_cs_rtag_attr> | <ACS_heap_attr> <ACS_code_attr> ::= code <ACS_nocode_attr> ::= nocode <ACS_cs_stag_attr> ::= cs_stag <ACS_cs_drtag_attr> ::= cs_drtag <ACS_cs_rtag_attr> ::= cs_rtag <ACS_commstat_attr> ::= comm_status <ACS_faultstat_attr> ::= fault_status <ACS_heap_attr> ::= heap <ACS_enable_alloc_attr> ::= enable_allocate

Include Declaration

The include statement specifies one or more header sources that are are included in generated stub code, for example, via C-preprocessor #include statements. The user must supply the header sources. A C-language definition source (.h file) must always be provided for use when compiling the stubs. If the stubs are being generated for another language, then a definition source for that language must be provided as well. The same ACS source may not work with different target languages.

If the include statements do not fully specify the location of the header sources, the compiler uses implementation-specific searching mechanisms to locate them. Similarly, if the file extension is not specified, then the compiler appends the appropriate file extension for the language of choice.

Include statements are necessary if, in the ACS source, there occur one or more types specified in the represent_as clause's <ACS_named_type> or the implicit_handle or cs_char attribute's <type_spec> that are not types defined in the interface definition (or any imported interfaces). Since the definitions of such types are needed by the generated stub code, the user must supply them in this manner.

Specifying Binding Handles

The means of providing binding information to the RPC run-time system is the binding handle. Binding handles (or simply, handles) may be passed as parameters of the operation or fetched by the generated stub from a static area. A handle passed as an operation parameter is termed an explicit handle. If an explicit handle is used, it is always the first parameter of an operation. Explicit handles may be declared in the IDL source, in which case both the client and server must use the explicit handle. Explicit handles may also be declared in the ACS source, in which case the two sides (client and server) may make the decision to use an explicit handle separately.

When an interface contains one or more operations whose first parameter is not an explicit handle, and which do not have an in or in, out context handle, a means of providing a handle is needed. The implicit_handle and auto_handle attributes provide this capability.

If an interface has an operation requiring an implicit handle, and no ACS source is supplied, or the supplied ACS source does not specify either implicit_handle or auto_handle, then the default auto_handle attribute is applied. The auto_handle attribute is also applied in the event that a operation has an in, out context handle but no other binding handle mechanism.

When the auto_handle attribute is applied, the binding_callout attribute allows the client application using automatic binding to modify the binding handle obtained by the client stub before the remote procedure call is initiated.

The explicit_handle Attribute

When used as an interface attribute, the explicit_handle attribute is applied to all operations in the interface. When used as an operation attribute, it is applied to only the specified operation.

The explicit_handle attribute specifies that the operation has an additional first parameter of type handle_t and named IDL_handle, even if one is not explicitly declared in the IDL source. Customised binding handles must be declared in the IDL source. The explicit_handle attribute may occur as an interface attribute only if the implicit_handle attribute and auto_handle attribute do not occur.

The implicit_handle Attribute

The implicit_handle attribute is one of the methods for specifying handles. Under the implicit_handle method, the handle used on calls to operations without a handle in the first parameter position is the data object specified in the implicit_handle attribute.

The implicit_handle attribute must occur at most once in the ACS source. The implicit_handle attribute may occur only if the auto_handle attribute does not occur and the explicit_handle attribute does not occur as an interface attribute.

The <type_spec> specified in the implicit_handle attribute need not be specified in the associated interface definition source. If it is specified, then the definition specified in the IDL source is used; it must be either a type that resolves to the type handle_t or a type with the handle attribute. If it is not a type defined in the interface definition source, then the ACS source must contain an include statement, specifying a definition source that defines the <type_spec>. The type is treated as a customised handle; that is, as if it had the handle attribute applied to it.

The auto_handle Attribute

The auto_handle attribute indicates that any operations needing handles are automatically bound; that is, a client that makes a call on that operation makes no specification as to which server the operation may execute on.

The environment variable RPC_DEFAULT_ENTRY must be set to the name of the namespace entry from which the stub will import bindings to be used when an operation is invoked.

The auto_handle attribute must occur at most once.

The auto_handle attribute may occur only if the implicit_handle attribute does not occur and the explicit_handle attribute does not occur as an interface attribute.

The binding_callout Attribute
The binding_callout attribute specifies a routine that the client stub is to call automatically to modify a server binding handle before it initiates a remote procedure call and is intended for use with automatic binding through the auto_handle attribute. Without the binding_callout attribute, the binding handle may not be modified before the client attempts to initiate a call to the selected server. A typical use is to augment automatic binding handles with security context so that authenticated RPC is employed between client and server.

The binding callout routine provided must have a specific routine signature.

The binding_callout attribute must occur at most once.

The binding_callout attribute applies to all operations in the interface.

The represent_as Attribute

The represent_as attribute associates a named local type in the target language (<ACS_repr_type>) with a transfer type (<ACS_named_type>) that is transferred between caller and callee.

There are some restrictions on the types to which the represent_as attribute may be applied. The following types must not have the represent_as attribute:

The code and nocode Attributes

At most, one of the code and nocode attributes may appear in the interface attribute list. If neither is present, the effect is as if code is present.

The nocode attribute is only honoured when generating a client stub. Servers must support all defined operations.

If code appears in the interface attribute list, stub code is be generated for any operation in the interface that does not appear in the ACS source with nocode in its operation attribute list.

If nocode appears in the interface attribute list, stub code is only generated for those operations in the interface that appear in the ACS source with code in their operation attribute lists.

At most, one of code and nocode may appear in an operation attribute list. If both the interface and the operation have a code or nocode attribute, the attribute applied to the operation overrides the attribute applied to the interface.

Return Statuses

Two attributes, comm_status and fault_status, are available to provide a status return mechanism for certain error conditions that occur during the execution of remote routines. Portable applications must include an ACS specification that specifies these attributes.

The comm_status Attribute

The comm_status attribute must occur at most once per operation. It may appear as an operation attribute for the operation, or as a parameter attribute for one of the parameters of the operation.

If the comm_status attribute appears as an operation attribute, the operation must have been defined to deliver a result of type error_status_t. If the run-time system detects that some communications error (for example, a broken connection or a timeout) has occurred during execution of the operation, the error code is returned as the operation result. If the run-time system does not detect a communications failure, then the operation result has the value returned by the manager routine.

If the comm_status attribute appears as a parameter attribute, the <Identifier> associated with it need not be the <Identifier> of a parameter defined in the IDL. If the comm_status attribute does specify the <Identifier> of a parameter defined in the IDL, then the parameter must be an out parameter of type error_status_t*. In the event that the remote call completes successfully, the parameter has the value assigned by the called procedure.

If the <Identifier> associated with the comm_status attribute is not the <Identifier> of a parameter defined in the IDL, then an extra out parameter of type error_status_t* is created. This follows the last parameter defined in the IDL, unless a parameter with the fault_status attribute is present. If a parameter with the fault_status attribute is present, then the parameters are defined in the order they appear in the ACS. In the case of successful completion of the call, the extra parameter has the value error_status_ok.

If a communications error occurs during execution of the operation, the error code is returned in the parameter with the comm_status attribute.

For a summary of which errors are reported through the comm_status mechanism when enabled, refer to Reject Status Codes and Parameters .

The fault_status Attribute

The fault_status attribute is similar to the comm_status attribute. However, it deals with certain failures of the remote routine rather than communications errors.

The fault_status attribute must occur at most once per operation. It may appear as an operation attribute for the operation, or as a parameter attribute for one of the parameters of the operation.

If the fault_status attribute appears as an operation attribute, the operation must have been defined to deliver a result of type error_status_t. If the remote procedure fails in a way that causes a fault PDU to be returned, the error code is returned as the operation result. If a failure is not detected, then the operation result has the value returned by the manager routine.

If the fault_status attribute appears as a parameter attribute, the <Identifier> associated with it need not be the <Identifier> of a parameter defined in the IDL. If the fault_status attribute does specify the <Identifier> of a parameter defined in the IDL, then the parameter must be an out parameter of type error_status_t*. In the event that the remote call completes successfully, the parameter has the value assigned by the called procedure.

If the <Identifier> associated with the fault_status attribute is not the <Identifier> of a parameter defined in the IDL, then an extra out parameter of type error_status_t* is created. This follows the last parameter defined in the IDL unless a parameter with the com_status attribute is present. If a parameter with the com_status attribute is present, then the parameters are defined in the order in which they appear in the ACS. In the case of successful completion of the call, the extra parameter has the value error_status_ok.

If a suitable error occurs during execution of the operation, the error code is returned in the parameter with the fault_status attribute.

For a summary of which exceptions are reported through the fault_status mechanism when enabled, refer to Reject Status Codes and Parameters .

Interaction of the comm_status and fault_status Attributes

It is possible for one operation to have both the fault_status and the comm_status attributes, either as operation attributes or as parameter attributes.

If both attributes are applied as operation attributes, or both attributes are applied to the same parameter, then the operation or parameter has the value error_status_ok if no error occurred. Otherwise, it has the appropriate comm_status or fault_status value. Since the values returned in parameters with the comm_status attribute are disjoint from the values returned in parameters with the fault_status attribute, and it is not possible for a single call to result in two failures, there is no ambiguity in interpreting the returned status value.

If both attributes are specified for an operation, and each attribute refers to an <Identifier> that is not defined in the IDL source, then two extra parameters are defined after the last parameter defined in the IDL source. These parameters are defined in the order in which they appear in the ACS source.

The extern_exceptions Attribute

By default, the IDL compiler declares and initializes in the stub code all exceptions specified by the exceptions interface attribute. The extern_exceptions attribute indicates that the exceptions it specifies are not declared by the stub code but defined and initialized in some other external manner. They may be predefined exceptions that were provided by another interface, or exceptions that are defined and initialized explicitly by the application itself.

If the extern_exceptions attribute appears without parameters, it specifies all IDL-defined exceptions.

The heap Attribute

The heap attribute specifies that the server copy of the parameter or parameter of the type so specified will always be allocated in heap memory, rather than on the stack.

Any identifier occurring as a parameter name within an operation declaration in the ACS source must also be a parameter name within the corresponding operation declaration in IDL.

The heap attribute is ignored for pipes, context handles, and scalars.

The enable_allocate Attribute

The enable_allocate attribute causes the stub to initialise stub memory management in conditions where it otherwise would not do so. It has no effect if the stub would perform the initialisation for other reasons.

International Character Transfer

Five attributes-cs_char, cs_stag, cs_drtag, cs_rtag and cs_tag_rtn-are available for use in conjunction with the automatic code set conversion routines to provide a mechanism for ensuring character and code set interoperability between clients and servers transferring characters not contained in the Portable Character Set (PCS). (For information on the code set conversion routines see Internationalisation Support Model , Internationalisation Support Operations , and the routines described in RPC API Manual Pages ; for information on the PCS, see Portable Character Set .)

The cs_char Attribute

The cs_char attribute associates a local data type with a data type defined in the IDL source. This permits, during marshalling and umarshalling, the conversion of characters, arrays of characters, and strings of characters between the format in which application code uses them and the format in which they are transmitted over the network. The data is automatically converted between the local data type in the local code set encoding and the 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 does not affect the network contract between client and server. 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. 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 local data type is defined in either the IDL source or an application header file. If it is not defined in the IDL source, the ACS must contain an include statement to make its definition available to the stubs.

The network data type is defined in the IDL source. When the cs_char attribute is used, this data type is always byte.

The cs_char attribute requires the following stub support routines for each local date type defined:

Buffer sizing and code set conversion routines are provided for the cs_byte and wchar_t data types. The cs_byte data type is equivalent to the byte type, while the wchar_t data type is a platform-dependent data type whose range of values can represent encodings for all members of the largest international character set that exists within the set of character/code sets supported on a host.

Buffer sizing and code set conversion routines must follow specific signatures. See RPC API Manual Pages for descriptions.

Restrictions

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 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:

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

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

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 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 cs_stag, cs_drtag, and cs_rtag Attributes

The cs_stag, cs_drtag, and cs_rtag attributes are parameter ACS attributes that correspond to the sending tag, desired receiving tag, and receiving tag parameters defined in operations in the IDL source that handle international character data. These operation parameters tag international characters being passed in the operation's input and output parameters with code set identifying information. The cs_stag, cs_drtag, and cs_rtag attributes declare the tag parameters in the corresponding operation definition to be special code set parameters.

The cs_stag attribute identifies the code set used when the client sends international characters to the server. Operations defined in the IDL source that specify international characters in in parameters must use the cs_stag attribute in the associated ACS.

The cs_drtag attribute identifies the code set the client would like the server to use when returning international characters.

The cs_rtag attribute identifies the code set that is actually used when the server sends international characters to the client. Operations defined in the IDL file that specify international characters in out parameters must apply the cs_rtag attribute in the associated ACF.

The cs_tag_rtn Attribute

The optional cs_tag_rtn attribute specifies the name of a routine that the client and server stubs will call to set an operation's code set tag parameters to specific code set values. The rpc_cs_get_tags() routine or a user-provided routine may be specified.

The generated header file includes a function prototype for the specified routine. If an operation that transfers international character data has the cs_tag_rtn attribute applied to it in the corresponding ACS, 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.

When used as an ACF interface attribute, the cs_tag_rtn attribute applies to all operations defined in the corresponding IDL source. When used as an ACF operation attribute, the cs_tag_rtn attribute applies only to the operation you specify.

The specified 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 tagmref_rpc_cs_get_tags for a 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.

IDL Grammar Synopsis

The following sections give a synopsis of the IDL grammar for quick reference.

Grammar Synopsis

This section provides a synopsis of the IDL productions discussed in Interface Definition Language .

(1) <interface> ::= <interface_header> { <interface_body> }
(2) <interface_header> ::= <[>  <interface_attributes> <]> interface 
	<Identifier>
(3) <interface_attributes> ::= <interface_attribute> 
	[ , <interface_attribute> ] ...

(4) <interface_attribute> ::= uuid ( <Uuid_rep> )
	| version ( <Integer_literal>[.<Integer_literal>]) 
	| endpoint ( <port_spec> [ , <port_spec> ] ... ) 
	| exceptions ( <excep_name> [ , <excep_name> ] ... )
	| local
	| pointer_default ( <ptr_attr> )
(5) <port_spec> ::=  <Family_string> :  <[> <Port_string> <]>
(5.01) <excep_name> ::= <Identifier>
(6) <interface_body> ::= [ <import> ... ] <interface_component>
	[ <interface_component> ... ]
(7) <import> ::= import <import_list> ;
(8) <interface_component> ::= <export> | <op_declarator> ;
(9) <export> ::= <type_declarator> ; 
	| <const_declarator> ;
	| <tagged_declarator> ;
(10) <import_list> ::= <import_name> [ , <import_name> ] ...
(11) <import_name> ::=  "<Import_string>"
(12) <const_declarator> ::= const <const_type_spec> <Identifier> = <const_exp>
(13) <const_type_spec> ::= <primitive_integer_type> 
	| char
	| boolean
	| void *
	| char *
(14) <const_exp> ::= <integer_const_exp> 
	| <Identifier> 
	| <string> 
	| <character_constant>
	| NULL 
	| TRUE 
	| FALSE
(14.01) <integer_const_exp> ::= <conditional_exp>
(14.02) <conditional_exp> ::= <logical_or_exp>
	| <logical_or_exp> ? <integer_const_exp> : <conditional_exp>
(14.03) <logical_or_exp> ::= <logical_and_exp>
	| <logical_or_exp> <||> <logical_and_exp>
(14.04) <logical_and_exp> ::= <inclusive_or_exp>
	| <logical_and_exp> && <inclusive_or_exp>
(14.05) <inclusive_or_exp> ::= <exclusive_or_exp>
	| <inclusive_or_exp> <|> <exclusive_or_exp>
(14.06) <exclusive_or_exp> ::= <and_exp>
	| <exclusive_or_exp> ^ <and_exp>
(14.07) <and_exp> ::= <equality_exp>
	| <and_exp> & <equality_exp>
(14.08) <equality_exp> ::= <relational_exp>
	| <equality_exp> == <relational_exp>
	| <equality_exp> != <relational_exp>
(14.09) <relational_exp> ::= <shift_exp>
	| <relational_exp> <<> <shift_exp>
	| <relational_exp> <>> <shift_exp>
	| <relational_exp> <<=> <shift_exp>
	| <relational_exp> <>=> <shift_exp>
(14.10) <shift_exp> ::= <additive_exp>
	| <shift_exp> <<<> <additive_exp>
	| <shift_exp> <>>> <additive_exp>
(14.11) <additive_exp> ::= <multiplicative_exp>
	| <additive_exp> + <multiplicative_exp>
	| <additive_exp> - <multiplicative_exp>

(14.12) <multiplicative_exp> ::= <unary_exp>
	| <multiplicative_exp> * <unary_exp>
	| <multiplicative_exp> / <unary_exp>
	| <multiplicative_exp> % <unary_exp>
(14.13) <unary_exp> ::= <primary_exp>
	| + <primary_exp>
	| - <primary_exp>
	| ~ <primary_exp>
	| ! <primary_exp>
(14.14) <primary_exp> ::= <Integer_literal>
	| <Identifier>
	| '(' <const_exp> ')'
(15) <string> ::= "[<Character>] ... "
(16) <character_constant> ::= '<Character>'
(17) <type_declarator> ::= typedef [ <type_attribute_list> ] <type_spec> 
	<declarators>
(18) <type_attribute_list> ::= <[> <type_attribute> 
	[ , <type_attribute> ] ... <]>
(19) <type_spec> ::= <simple_type_spec>
	| <constructed_type_spec>
(20) <simple_type_spec> ::= <base_type_spec> 
	| <predefined_type_spec>
	| <Identifier>
(21) <declarators> ::= <declarator> [ , <declarator> ] ...
(23) <declarator> ::= <pointer_opt> <direct_declarator>
(24) <direct_declarator> ::= <Identifier> 
	| ( <declarator> ) 
	| <array_declarator> 
	| <function_declarator> 
(26) <tagged_declarator> ::= <tagged_struct_declarator> 
	| <tagged_union_declarator>
(27) <base_type_spec> ::= <floating_pt_type> 
	| <integer_type>
	| <char_type>
	| <boolean_type>
	| <byte_type>
	| <void_type>
	| <handle_type>
(28) <floating_pt_type> ::= float
	| double
(29) <integer_type> ::= <primitive_integer_type>
	| hyper [unsigned] [int]
	| unsigned hyper [int]
(29.1) <primitive_integer_type> ::= <signed_integer> 
	| <unsigned_integer>
(30) <signed_integer> ::= <integer_size> [ int ]
(31) <unsigned_integer> ::= <integer_size> unsigned [ int ]
	| unsigned <integer_size> [ int ]
(32) <integer_size> ::= long
	| short
	| small
(33) <char_type> ::= [ unsigned ] char
(34) <boolean_type> ::= boolean
(35) <byte_type> ::= byte
(36) <void_type> ::= void
(37) <handle_type> ::= handle_t
(38) <constructed_type_spec> ::= <struct_type> 
	| <union_type> 
	| <enumeration_type> 
	| <tagged_declarator>
	| <pipe_type>
(39) <tagged_struct_declarator> ::= struct <tag> 
	| <tagged_struct>
(40) <struct_type> ::= struct  { <member_list> }
(41) <tagged_struct> ::= struct <tag> { <member_list> }
(42) <tag> ::= <Identifier>
(43) <member_list> ::= <member> [ <member> ] ...
(44) <member> ::= <field_declarator> ;
(45) <field_declarator> ::= [ <field_attribute_list> ] <type_spec> 
	<declarators>
(46) <field_attribute_list> ::= <[> <field_attribute> 
	[ , <field_attribute> ] ... <]>
(47) <tagged_union_declarator> ::= union <tag> 
	| <tagged_union>
(48) <union_type> ::= union <union_switch> { <union_body> } 
	| union { <union_body_n_e> }
(48.1) <union_switch> ::= switch ( <switch_type_spec> <Identifier> )
	[ <union_name> ]
(49) <switch_type_spec> ::= <primitive_integer_type> 
	| <char_type>
	| <boolean_type>
	| <Identifier>
(50) <tagged_union> ::= union <tag> <union_switch> { <union_body> }
	| union <tag> { <union_body_n_e> }
(51) <union_name> ::= <Identifier>
(52) <union_body> ::= <union_case> [  <union_case> ] ...
(52.1) <union_body_n_e> ::=  <union_case_n_e> [ <union_case_n_e> ] ...
(53) <union_case> ::= <union_case_label> [ <union_case_label> ] ... 
	<union_arm>
	| <default_case>
(53.1) <union_case_n_e> ::= <union_case_label_n_e> <union_arm>
	| <default_case_n_e>
(54) <union_case_label> ::= case <const_exp> :
(54.1) <union_case_label_n_e> ::= <[> case ( <const_exp> 
	[ , <const_exp> ] ... ) <]>
(55) <default_case> ::= default : <union_arm>
(55.1) <default_case_n_e> ::= <[> default <]> <union_arm>
(55.2) <union_arm> ::= [ <field_declarator> ] ;
(55.3) <union_type_switch_attr> ::= switch_type ( <switch_type_spec> )
(55.4) <union_instance_switch_attr> ::= switch_is ( <attr_var> )
(57) <enumeration_type> ::= enum { <Identifier> [ , <Identifier> ] ... }
(58) <pipe_type> ::= pipe <type_spec>
(59) <array_declarator> ::= <direct_declarator> <array_bounds_declarator>
(61) <array_bounds_declarator> ::= <[> [ <array_bound> ] <]>
	| <[> <array_bounds_pair> <]>
(62) <array_bounds_pair> ::= <array_bound> .. <array_bound> 
(63) <array_bound> ::= *  
	| <integer_const_exp> 
	| <Identifier>
(64) <type_attribute> ::= transmit_as ( <xmit_type> ) 
	| handle
	| <usage_attribute>
	| <union_type_switch_attr>
	| <ptr_attr>
(65) <usage_attribute> ::= string 
	| context_handle
(66) <xmit_type> ::= <simple_type_spec> 
(67) <field_attribute> ::= first_is ( <attr_var_list> ) 
	| last_is ( <attr_var_list> ) 
	| length_is ( <attr_var_list> ) 
	| min_is ( <attr_var_list> ) 
	| max_is ( <attr_var_list> ) 
	| size_is ( <attr_var_list> ) 
	| <usage_attribute> 
	| <union_instance_switch_attr> 
	| ignore 
	| <ptr_attr>
(68) <attr_var_list> ::= <attr_var> [ , <attr_var> ] ...
(69) <attr_var> ::= [ [ * ] <Identifier> ] 
(70) <pointer_opt> ::= [<pointer>]
(70.1) <ptr_attr> ::= ref
	| unique
	| ptr
(70.2) <pointer> ::= *... 
(71) <op_declarator> ::= [ <operation_attributes> ] 
	<simple_type_spec> <Identifier> <param_declarators>
(72) <operation_attributes> ::= <[>  <operation_attribute> 
	[ , <operation_attribute> ] ... <]>
(73) <operation_attribute> ::= idempotent 
	| broadcast 
	| maybe 
	| reflect_deletions
	| <usage_attribute>
	| <ptr_attr>
(74) <param_declarators> ::= ( [ <param_declarator> 
	[ , <param_declarator> ] ... ] )
	| ( void )
(75) <param_declarator> ::= <param_attributes> <type_spec> <declarator>
(76) <param_attributes> ::= <[> <param_attribute> 
	[ , <param_attribute> ] ... <]>
(77) <param_attribute> ::= <directional_attribute>  
	| <field_attribute>
(78) <directional_attribute> ::= in  
	| out 
(79) <function_declarator> ::= <direct_declarator> <param_declarators>
(80) <predefined_type_spec> ::= error_status_t 
	| <international_character_type>
(81) <international_character_type> ::= ISO_LATIN_1 
	| ISO_MULTI_LINGUAL
	| ISO_UCS

Alphabetic Listing of Productions

Alphabetic Listing of Productions lists the terminals and non-terminals of the grammar in alphabetic order, with their numbers and the numbers of all productions that use them.

Table: Alphabetic Listing of Productions

Production Name Number Used In
<additive_exp> 14.11 14.10
<and_exp> 14.07 14.06
<array_bound> 63 61 62
<array_bounds_declarator> 61 59
<array_bounds_pair> 62 61
<array_declarator> 59 24
<attr_var> 69 55.4 68
<attr_var_list> 68 67
<base_type_spec> 27 20
<boolean_type> 34 27 49
<byte_type> 35 27
<char_type> 33 27 49
<Character> Terminal 15 16
<character_constant> 16 14
<conditional_exp> 14.02 14.01
<const_declarator> 12 9
<const_exp> 14 12 14.14 54 54.1
<const_type_spec> 13 12
<constructed_type_spec> 38 19
<declarator> 23 21 24 75
<declarators> 21 17 45
<default_case> 55 53
<default_case_n_e> 55.1 53.1
<direct_declarator> 24 23 59 79
<directional_attribute> 78 77
<enumeration_type> 57 38
<equality_exp> 14.08 14.07
<excep_name> 5.01 4
<exclusive_or_exp> 14.06 14.05
<export> 9 8
<Family_string> Terminal 5
<field_attribute> 67 46 77
<field_attribute_list> 46 45
<field_declarator> 45 44 55.2
<floating_pt_type> 28 27
<function_declarator> 79 24
<handle_type> 37 27
<Import_string> Terminal 11
<Identifier> Terminal 2 5.01 12 14 14.14 20 24 42 48.1 49 51 57 63 69 71
<import> 7 6
<import_list> 10 7
<import_name> 11 10
<inclusive_or_exp> 14.05 14.04
<integer_const_exp> 14.01 14 14.02 63
<Integer_literal> Terminal 4 14.14
<integer_size> 32 30 31
<integer_type> 29 27
<interface> 1 GOAL
<interface_attribute> 4 3
<interface_attributes> 3 2
<interface_body> 6 1
<interface_component> 8 6
<interface_header> 2 1
<international_character_type> 81 80
<logical_and_exp> 14.04 14.03
<logical_or_exp> 14.03 14.02
<member> 44 43
<member_list> 43 40 41
<multiplicative_exp> 14.12 14.11
<op_declarator> 71 8
<operation_attribute> 73 72
<operation_attributes> 72 71
<param_attribute> 77 76
<param_attributes> 76 75
<param_declarator> 75 74
<param_declarators> 74 71 79
<pipe_type> 58 38
<pointer> 70.2 70
<pointer_opt> 70 23
<port_spec> 5 4
<Port_string> Terminal 5
<predefined_type_spec> 80 20
<primary_exp> 14.14 14.13
<primitive_integer_type> 29.1 13 29 49
<ptr_attr> 70.1 4 64 67 73
<relational_exp> 14.09 14.08
<shift_exp> 14.10 14.09
<signed_integer> 30 29.1
<simple_type_spec> 20 19 66 71
<string> 15 14
<struct_type> 40 38
<switch_type_spec> 49 48.1 55.3
<tag> 42 39 41 47 50
<tagged_declarator> 26 9 38
<tagged_struct> 41 39
<tagged_struct_declarator> 39 26
<tagged_union> 50 47
<tagged_union_declarator> 47 26
<type_attribute> 64 18
<type_attribute_list> 18 17
<type_declarator> 17 9
<type_spec> 19 17 45 58 75
<unary_exp> 14.13 14.12
<union_arm> 55.2 53 53.1 55 55.1
<union_body> 52 48 50
<union_body_n_e> 52.1 48 50
<union_case> 53 52
<union_case_n_e> 53.1 52.1
<union_case_label> 54 53
<union_case_label_n_e> 54.1 53.1
<union_instance_switch_attr> 55.4 67
<union_name> 51 48.1
<union_switch> 48.1 48 50
<union_type> 48 38
<union_type_switch_attr> 55.3 64
<unsigned_integer> 31 29.1
<usage_attribute> 65 64 67 73
<Uuid_rep> Terminal 4
<void_type> 36 27
<xmit_type> 66 64

IDL Constructed Identifiers

Constructed Identifier Classes lists the various classes of identifiers that are used to construct other identifiers. It shows the various strings that are applied to the identifier to build new identifiers. The table also gives the maximum length that a user-supplied identifier is permitted to have in order for the resulting identifier have 31 characters or less. Identifiers of 31 characters or less fall within the ISO C "minimum maximum" requirement for identifiers. This value need not be meaningful for other target languages. The length specified for interface names assumes a single digit major and minor version number. The actual length allowed for interface names is:

(19 -((digits-in-major-version) + (digits-in-minor-version)))
Table: Constructed Identifier Classes

    Max
Class of ID Constructed IDs Length
Interface name <interface>_v<major_version>_<minor_version>_c_ifspec 17
  <interface>_v<major_version>_<minor_version>_s_ifspec  
  <interface>_v<major_version>_<minor_version>_epv_t  
  <interface>_v<major_version>_<minor_version>_c_epv  
  <interface>_v<major_version>_<minor_version>_s_epv  
Type with <type_id>_to_xmit 21
transmit_as <type_id>_from_xmit  
attribute <type_id>_free_inst  
  <type_id>_free_xmit  
Type with <type_id>_bind 24
handle <type_id>_unbind  
attribute    
Type with <type_id>_rundown 23
context_handle    
attribute    
Type with <type_id>_to_local 20
represent_as <type_id>_from_local  
attribute <type_id>_free_inst  
  <type_id>_free_local  


IDL and ACS Reserved Words

Reserved words are keywords of the language that must not be used as user identifiers. IDL reserved words are given in the following list:

boolean byte case char
const default double enum
FALSE float handle_t hyper
import int interface long
NULL pipe short small
struct switch TRUE typedef
union unsigned void  

The following list gives the IDL keywords that are reserved when in the context of an attribute: that is, between [] (brackets):

broadcast case context_handle endpoint
exceptions first_is handle idempotent
ignore in last_is length_is
local max_is maybe min_is
out ptr pointer_default ref
reflect_deletions size_is string switch_is
switch_type transmit_as unique uuid
version      

The following are ACS reserved words: include, interface, typedef.

The following list gives the ACS keywords that are reserved when in the context of an attribute: that is, between [] (brackets):

auto_handle binding_callout code comm_status
cs_char cs_drtag cs_rtag cs_stag
cs_tag_rtn enable_allocate extern_exceptions explicit_handle
fault_status heap implicit_handle nocode
represent_as      


Footnotes

1.
Since indirection operators associate left to right, as in C, the "first" indirection operator is the rightmost one in the IDL source.


[??] Some characters or strings that appear in the printed document are not easily representable using HTML.


Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents Next section Index