Converting IDL3 to IDL2
                            =======================
                            
Introduction
============

This directory contains a test for the executable
tao_idl3_to_idl2, which inputs a single IDL file and
outputs a single IDL file which has the IDL3 declarations
from the input file converted to the corresponding 'implied
IDL' declarations specificed by the mapping in the CCM
document.

This utility can be used in conjunction with some IDL compiler
that does not support IDL3 keywords and syntax. The output of
the utility can be processed by such a compiler, yielding code
in the target programming language equivalent to that which
would have been generated in one step by a CCM-aware IDL compiler.

The tao_idl3_to_idl2 executable itself is built in
CIAO_ROOT/tools/IDL3_to_IDL2. It uses the TAO IDL compiler
front end parsing engine and the TAO IDL compiler driver
files, so it depends on ACE. The IDL generation is 
accomplished by a custom backend library.

Running The Test
================

This test is only to determine that the generated IDL files
are valid. So once the converted IDL file (having the
extension _IDL2.idl) is generated by tao_idl3_to_idl2, the
TAO IDL compiler is executed on the generated IDL file and
the resulting C++ files compiled. If the compilation is
successful for all such files, the test is a success.

Notable Build Features
======================

Two features of the MPC file for this test are of interest:

1.
Two of the three IDL files in the test, pass_through.idl and
include.idl, contain no IDL3 constructs, but merely test the
executable's regeneration of IDL2 constructs. Since one IDL
file is included in the other, there is a dependency that
requires both IDL files to be processed before running the
IDL compiler on pass_through_IDL2.idl. The line

    pass_through_IDL2.idl << include_IDL2.idl

indicates this dependency to the MPC tool, ensuring the correct
order of execution.

2.
The -Sm option passed to the IDL compiler must be used when
processing an IDL file resulting from the execution of
tao_idl3_to_idl2. This option disables the action of the 
tao_idl backend 'preprocessor' (which is 'on' by default)
that adds implied IDL nodes to the Abstract Syntax Tree
for subsequent C++ code generation. In the case of an eventtype,
the CCM spec requires additional code generation for a corresponding
implied 'event consumer' IDL interface, as well as for the
eventtype itself. The tao_idl3_to_idl2 executable adds this
interface explicitly to the generated IDL file, along with the
original eventtype. Without the -Sm option, the event consumer
interface would appear redundantly in both explicit and implied
IDL, resulting in a name clash. Since the IDL compiler cannot
know the origin of the IDL file it is processing, the -Sm
option encapsulates that knowledge.