IDL(1)

NAME
idl - ORBacus IDL-to-C++ Translator
jidl - ORBacus IDL-to-Java Translator
hidl - ORBacus IDL-to-HTML Translator
ridl - ORBacus IDL-to-RTF Translator
irserv - ORBacus Interface Repository Server
irfeed - ORBacus Interface Repository Feeder
irdel - ORBacus Interface Repository Deleter
irgen - ORBacus Interface Repository C++ Code Generator

SYNOPSIS
idl [ options ] idl-files ...
jidl [ options ] idl-files ...
hidl [ options ] idl-files ...
ridl [ options ] idl-files ...
irserv [ options ] [ idl-files ... ]
irfeed [ options ] repository-IOR idl-files ...
irdel [ options ] repository-IOR scoped-name ...
irgen [ options ] repository-IOR name-base

DESCRIPTION
idl is the ORBacus IDL-to-C++ translator. It translates IDL files into C++ files. For each IDL file, four C++ files are generated. For example
        idl MyFile.idl produces the files:

MyFile.h
    Header file containing MyFile.idl's translated data types and interface stubs.

MyFile.cpp
    Source file containing MyFile.idl's translated data types and interface stubs.

MyFile_skel.h
    Header file containing skeletons for MyFile.idl's interfaces.

MyFile_skel.cpp
    Source file containing skeletons for MyFile.idl's interfaces.

jidl translates IDL files into Java files. For every construct in the IDL file that maps to a Java class or interface, a separate class file is generated. Directories are automatically created for those IDL constructs that map to a Java package (e.g., a module).

jidl can also add comments from the IDL file starting with /** to the generated Java files. This allows you to use the javadoc tool to produce documentation from the generated Java files. See USING JAVADOC below.

hidl creates HTML files from IDL files. An HTML file is generated for each module and interface defined in an IDL file. Comments in the IDL file are preserved and javadoc style keywords are supported. The section DOCUMENTING IDL FILES provides more information.

ridl creates RTF files from IDL files. An RTF file is generated for each module and interface defined in an IDL file. Comments in the IDL file are preserved and javadoc style keywords are supported. The section DOCUMENTING IDL FILES provides more information.

irserv is the Interface Repository Server. Together with irfeed, a program that feeds the Interface Repository with IDL code, and irgen, the Interface Repository C++ Code Generator, it is possible to generate C++ code directly from the contents of an Interface Repository. See IDL AND THE INTERFACE REPOSITORY below.

OPTIONS FOR IDL

-h, --help
    Show a short help message.

-v, --version
    Show the ORBacus version number.

-e, --cpp NAME
    Use NAME as the preprocessor program.

-d, --debug
    Print diagnostic messages. This option is for ORBacus internal debugging purposes only.

-DNAME
    Defines NAME as 1. This option is directly passed to the preprocessor.

-DNAME=DEF
    Defines NAME as DEF. This option is directly passed to the preprocessor.

-UNAME
    Removes any definition for NAME. This option is directly passed to the preprocessor.

-IDIR
    Adds DIR to the include file search path. This option is directly passed to the preprocessor.

--no-skeletons
    Don't generate skeleton classes.

--no-type-codes
    Don't generate type codes and insertion and extraction functions for the any type. Use of this option will cause the translator to generate more compact code.

--locality-constrained
    Generate locality-constrained objects.

--tie
    Generate tie classes for delegate-based interface implementations. Tie classes depend on the corresponding skeleton classes, i.e., you must not use --no-skeletons in combination with --tie

--c-suffix SUFFIX
    Use SUFFIX as the suffix for source files. The default value is .cpp.

--h-suffix SUFFIX
    Use SUFFIX as the suffix for header files. The default value is .h.

--all
    Generate code for included files instead of inserting #include statements. See INCLUDE STATEMENTS below.

--no-relative
    When generating code, idl assumes that the same -I options that are used with idl are also going to be used with the C++ compiler. Therefore idl will try to make all #include statements relative to the directories specified with -I . The option --no-relative suppresses this behavior, in which case idl will not to make #include statements for included files relative to the paths specified with the -I option.

--header-dir DIR
    This option can be used to make #include statements for header files relative to a specific directory.

--other-header-dir DIR
    This option works like --header-dir, but it only applies to header files for included IDL files.

OPTIONS FOR JIDL

-h, --help

-v, --version

-e, --cpp NAME

-d, --debug

-DNAME

-DNAME=DEF

-UNAME

-IDIR

--no-skeletons

--locality-constrained

--all

--tie
    These options are the same as for the idl command.

--no-comments
    The default behavior of jidl is to add any comments from the IDL file starting with /** to the generated Java files. Specify this option if you don't want these comments added to your Java files.

--package PKG
    Specifies a package name for the generated Java classes. Each class will be generated relative to this package.

--prefix-package PRE PKG
    Specifies a package name for a particular prefix. Each class with this prefix will be generated relative to the specified package.

--auto-package
    Derives the package names for generated Java classes from the IDL prefixes. The prefix ooc.com, for example, results in the package com.ooc.

--output-dir DIR
    Specifies a directory where jidl will place the generated Java files. Without this option the current directory is used.

--clone
    Generates a clone method for struct, union, enum and exception types.

OPTIONS FOR HIDL

-h, --help

-v, --version

-e, --cpp NAME

-d, --debug

-DNAME

-DNAME=DEF

-UNAME

-IDIR
    These options are the same as for the idl command.

--no-sort
    Don't sort symbols alphabetically.

--output-dir DIR
    Write HTML files to the directory DIR.

OPTIONS FOR RIDL

-h, --help

-v, --version

-e, --cpp NAME

-d, --debug

-DNAME

-DNAME=DEF

-UNAME

-IDIR
    These options are the same as for the idl command.

--no-sort
    Don't sort symbols alphabetically.

--output-dir DIR
    Write RTF files to the directory DIR.

--single-file FILE
    Create a single RTF file called FILE.

--with-index
    Create index entries.

--font NAME
    Use font NAME as font for the text body.

--literal-font NAME
    Use font NAME as font for literals.

--title-font NAME
    Use font NAME as font for the title.

--heading-font NAME
    Use font NAME as font for headings.

--font-size SIZE
    Text body font size in points.

--literal-font-size SIZE
    Literal font size in points.

--title-font-size SIZE
    Title font size in points.

--heading-font-size SIZE
    Heading font size in points.

OPTIONS FOR IRSERV

-h, --help

-v, --version

-e, --cpp NAME

-d, --debug

-DNAME

-DNAME=DEF

-UNAME

-IDIR
    These options are the same as for the idl command.

--ior
    Print the stringified IOR of the Interface Repository on standard output.

The arguments to irserv are zero or more IDL files. If you do not wish to specify any IDL files on the command line, you can still feed IDL files to the Interface Repository server using the irfeed command.

OPTIONS FOR IRFEED

-h, --help

-v, --version

-e, --cpp NAME

-d, --debug

-DNAME

-DNAME=DEF

-UNAME

-IDIR
    These options are the same as for the idl command.

The arguments to irfeed are the stringified IOR of the Interface Repository server, and one or more IDL files.

OPTIONS FOR IRDEL

-h, --help

-v, --version
    These options are the same as for the idl command.

The arguments to irdel are the stringified IOR of the Interface Repository server, and one or more scoped names. A scoped name has the form X::Y::Z. For example, an interface I defined in a module M can be identified by the scoped name M::I.

OPTIONS FOR IRGEN

-h, --help

-v, --version

--no-skeletons

--no-type-codes

--locality-constrained

--tie

--c-suffix SUFFIX

--h-suffix SUFFIX

--header-dir DIR

--other-header-dir DIR
    These options are the same as for the idl command.

The arguments to irgen are the stringified IOR of the Interface Repository server, and the pathname to use as the base name of the output filenames. For example, if the pathname you supply is output/MyIDL, then irgen will produce output/file.cpp, output/file.h, output/file_skel.cpp and output/file_skel.h.

Note that irgen will generate code for all of the type definitions contained in the Interface Repository server.

IDL AND THE INTERFACE REPOSITORY
The ORBacus IDL-to-C++ and IDL-to-Java translators internally use the Interface Repository for generating code. That is, these programs have their own private Interface Repository that is fed with the specified IDL files. All code is generated from that private Interface Repository. It is also possible to generate code from a global Interface Repository. First, the command irserv must be used to start the Interface Repository. Then the Interface Repository must be fed with the IDL code, using the command irfeed. The irgen command can then be used to generate the actual C++ code. For example:
        irserv --ior > IntRep.ref &
        irfeed `cat IntRep.ref` file.idl
        irgen `cat IntRep.ref` file The IDL-to-C++ translator idl performs all these steps at once, in a single process with a private Interface Repository. Thus, you just have to issue:
        idl file.idl

INCLUDE STATEMENTS
If you use the #include statement in your IDL code, the ORBacus IDL-to-C++ translator idl will not create code for included IDL files. The translator will insert the appropriate #include statements in the generated header files instead. Please note that there are several restrictions on where to place the #include statements in your IDL files for this feature to work properly:

1)  #include may only appear at the beginning of your IDL files. All #include statements must be placed before the rest of your IDL code. Preprocessor statements like #define or #ifdef may be placed before your #include statements.

2)  Type definitions, such as interface or struct definitions, may not be split among several IDL files. In other words, no #include statement may appear within such definitions.

If you don't want these restrictions to be applied, you can use the translator option --all with idl. With this option the IDL-to-C++ translator treats code from included files as if the code appeared in your IDL file at the position where it is included. This means that the compiler will not place #include statements in the automatically-generated header files, regardless of whether the code comes directly from your IDL file or from files included by your IDL file.

Note that when generating code from an Interface Repository using irgen, the translator behaves identically to idl with the --all option. In other words, the irgen command will not generate #include statements in the generated files, but rather generates code for all IDL definitions in the Interface Repository.

DOCUMENTING IDL FILES
With the ORBacus IDL-to-HTML and IDL-to-RTF translators, hidl and ridl, you can easily generate HTML and RTF files containing IDL interface descriptions. The translators will generate a nicely-formatted file for each module and interface.

The formatting syntax supported by hidl and ridl is similar to that used by javadoc. The following keywords are recognized:

@author author
    Denotes the author of the interface.

@exception exception-name description
    Adds an exception description to the exception list of an operation.

@member member-name description
    Adds a member description to the member list of a struct, union, enum or exception type.

@param parameter-name description
    Adds a parameter description to the parameter list of an operation.

@return description
    Adds descriptive text for the return value of an operation.

@see reference
    Adds a `See also' note.

@since since-text
    Comment related to the availability of new features.

@version version
    The interface's version number.

Like javadoc, hidl and ridl use the first sentence in the documentation comment as the summary sentence. This sentence ends at the first period that is followed by a blank, tab or line terminator, or at the first @.

USING JAVADOC
If not explicitly suppressed with the --no-comments option, the ORBacus IDL-to-Java translator jidl adds comments starting with /** from the IDL file to the generated Java files, so that javadoc can be used to generate documentation (as long as the comments are in a format compatible with javadoc). Here is an example showing how to include documentation in an IDL interface description file. Let's assume we have an interface I in a module M:
    // IDL
    module M
    {
    /**
     *
     * This is a comment related to interface I.
     *
     * @author Uwe Seimet
     *
     * @version 1.0
     *
     **/
    interface I
    {
        /**
         *
         * This comment describes exception E.
         *
         **/
        exception E { };
        /**
         *
         * The description for operation S.
         *
         * @param arg A dummy argument.
         *
         * @return A dummy string.
         *
         * @exception E Raised under certain circumstances.
         *
         **/
        string S(in long arg)
            raises(E);
    };
    }; When running jidl on this file the comments will automatically be added to the generated Java files M/I.java and M/IPackage/E.java. For I.java the generated code looks as follows:
    // Java
    package M;
    //
    // IDL:M/I:1.0
    //
    /**
     * This is a comment related to interface I.
     *
     * @author Uwe Seimet
     *
     * @version 1.0
     *
     **/
    public interface I extends org.omg.CORBA.Object
    {
        //
        // IDL:M/I/S:1.0
        //
        /**
         *
         * The description for operation S.
         *
         * @param arg A dummy argument.
         *
         * @return A dummy string.
         *
         * @exception M.IPackage.E Raised under certain circumstances.
         *
         **/
        public String
        S(int arg)
            throws M.IPackage.E;
    } Note that jidl automatically inserts the fully-qualified Java name for the exception E, in this case M.IPackage.E. These are the contents of IPackage/E.java:
    // Java
    package M.IPackage;
    //
    // IDL:M/I/E:1.0
    //
    /**
     *
     * This comment describes exception E.
     *
     **/
    final public class E extends org.omg.CORBA.UserException
    {
        public
        E()
        {
        }
    } Now you can use javadoc to extract the comments from the generated Java files and produce nicely-formatted HTML documentation. For additional information please refer to the javadoc documentation.

SEE ALSO
For more information on the ORBacus IDL-to-C++ and IDL-to-Java translator tools, please see the ORBacus manual.

COPYRIGHT
idl, jidl, hidl, ridl, irserv, irfeed, irdel and irgen are Copyright (C) 1998 by Object-Oriented Concepts, Inc.