NAME

idl - Invokes the Interface Definition Language (IDL) compiler

SYNOPSIS

idl filename [options]

OPTIONS

-client file_type
Determines which client files to generate.  If you do not specify this argument, the compiler generates all client files.  The file types are as follows:

noneDoes not generate client files. 

stubGenerates only a client stub file. 

auxGenerates only a client auxiliary file.  A client auxiliary file is generated only if the interface contains any out-of-line or self-pointing types. 

allGenerates client stub and client auxiliary files.  This is the default and is the same as not specifying the −client argument. 

−server file_type
Determines which server files to generate.  If you do not specify this argument, the compiler generates all server files.  The file types are as follows:

noneDoes not generate server files. 

stubGenerates only a server stub file. 

auxGenerates only a server auxiliary file.  A server auxiliary file is generated only if the interface contains any out-of-line, self-pointing, or pipe types. 

allGenerates server stub and server auxiliary files.  This is the default and is the same as not specifying the −server argument. 

−lang language
Specifies which language to use to generate header and intermediate stub files. The valid languages are as follows:

cGenerates C files.  This is the default and is the same as not specifying the -lang argument. 

cxxGenerates C++ files. 

−no_cxxmgr
Causes the compiler to not overwrite the manager class header file.  Use this argument if you implement application-specific C++ code in the manager class header file. 

−cstub filename
Specifies a pathname for the client stub file.  When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file.  If you do not use the −cstub argument, the idl compiler appends _cstub.c to the C source file and _cstub.o to the object file.  If the -lang cxx option is used, the source file has a .cxx extension. 

−sstub filename
Specifies a pathname for the server stub file.  When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file.  If you do not use the −sstub argument, the idl compiler appends _sstub.c to the C source file and _sstub.o to the object file.  If the -lang cxx option is used, the source file has a .cxx extension. 

−caux filename
Specifies a pathname for the client auxiliary file.  When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file.  If you do not use the −caux argument, the idl compiler appends _caux.c to the C source file and _caux.o to the object file.  If the -lang cxx option is used, the source file has a .cxx extension.  This option allows makefile compatibility with OSF DCE Release 1.0.2 and earlier releases. For more information, see the caution notes in the Description section of this reference page. 

−saux filename
Specifies a pathname for the server auxiliary file.  When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file.  If you do not use the -saux argument, the idl compiler appends _saux.c to the C source file and _saux.o to the object file.  If the -lang cxx option is used, the source file has a .cxx extension.  This option allows makefile compatibility with OSF DCE Release 1.0.2 and earlier releases. For more information, see the caution notes in the Description section of this reference page. 

−header header_file
Allows you to specify a name for the generated header file.  By default the compiler takes the basename of the IDL file and appends the .h extension to it. 

−out directory
Places the output files in the directory you specify.  By default the compiler places the output files in the current working directory.

−IdirectorySpecifies a directory name that contains imported interface definition files.  You can specify more than one directory by specifying additional −Idirectory arguments on the command line.  The compiler searches the directories in the order you list them.  If a file is present in more than one directory, the compiler takes the first occurrence of the file.  The default behavior of the compiler is to first search the current directory, then all directories you specify, then the system IDL directory.  The directory you specify is also passed to the language preprocessors and compilers. 

−no_def_idir
Specifies that the compiler search only the current directory for imported files.  When you use this with −Idirectory, the compiler searches only the directories you list, not the current directory, and not the system IDL directory. 

−no_mepvCauses the compiler to not generate a manager entry point vector (EPV) in the server stub.  Use this argument if the manager code and IDL file do not use the same operation names.  If you specify this argument you must provide an EPV within the manager code that can be used when the interface is registered with the remote procedure call (RPC) server runtime.  The name of the type that you construct an EPV with is if_name_vmajor-version_minor-version_epv_t where if_name is the interface name.  It is not necessary to use this argument if the operation names in the manager code and IDL file are the same.  In this case, the compiler generates a manager EPV in the server stub by using the names of the operations in the IDL file.  (For information on registering the server, see the rpc_intro(3rpc) and rpc_server_register_if(3rpc) reference pages.  See also the OSF DCE Application Development Guide—Core Components.) 

−cepvGenerates local routines in the client stub file (filename_cstub.c) and defines a client entry point vector (CEPV) of the name if_name_vmajor-version_minor-version_c_epv where if_name is the interface name.  The CEPV contains the addresses of the local routines.  The client code must call the routines indirectly by using the addresses in the CEPV; otherwise, the stub routines in the client stub file must have the same names as the operations in the IDL file.  (For information on registering the server, see the rpc_intro(3rpc) and rpc_server_register_if(3rpc) reference pages.)  See also the OSF DCE Application Development Guide—Core Components.) 

−cpp_cmd ’c_preprocessor_command_line’
Allows you to specify a language preprocessor other than the default.  The compiler invokes the preprocessor found in that command line.  The output of the preprocessor is an expanded version of the input file(s) containing replacement text for any preprocessor directives (for example, the #include preprocessor directive). 

−cpp_opt ’command_options’
Specifies additional options to be passed to the language preprocessor.  You can add options to the command line used to invoke the preprocessor independent of the −cpp_cmd argument.  The IDL compiler concatenates the −cpp_cmd, -cpp_opt, -D, -U, and -I arguments and the source filename into a command used to invoke the preprocessor.  The compiler repeats this process for each Attribute Configuration File (ACF) and IDL file.

−no_cppDoes not invoke the language preprocessor.  Note that the preprocessor must be run on files that contain preprocessor directives (such as #include) in the interface definition. 

−cc_cmd ’command_line’
Invokes the language compiler options you specify in the ’command_line’ argument rather than the default compiler and compiler options. 

−cc_opt ’command_options’
Specifies additional options to be passed to the C or C++ compiler.  You can add options to the command line used to invoke the compiler independent of the −cc_cmd argument.  The IDL compiler concatenates the −cc_cmd, −cc_opt, and −I arguments and the source filename into a command that invokes the language compiler.  This procedure is done for each generated stub or auxiliary file. 

−Dname[=definition]
Defines a symbol name and an optional value to be passed to the language preprocessor.  You can use this method of defining a symbol instead of using #define in the source code.  You can use more than one −Dname argument on the command line.  This argument has no effect if you use the −no_cpp argument. 

−UnameRemoves (undefines) any initial definition of a symbol name as defined by −Dname.  You can use this method to remove a symbol name instead of using #undef in the source code.  You can use more than one −Uname argument on the command line.  This argument has no effect if you use the −no_cpp argument.  If you define and undefine a name on the same command line, undefining takes precedence. 

−space_opt
Generates code for the marshalling and unmarshalling of data that is optimized for space, rather than speed.

−syntax_only
Checks only the syntax of the IDL file, but does not generate any output files.

−keep file_types
Specifies which files to retain.  To produce the object modules, the IDL compiler first creates C or C++ source modules, then invokes the target compiler to produce object modules, and finally, deletes the source modules. If you do not use −keep, only the object modules are saved.  The file types are as follows:

noneDoes not save the source or the object modules.  Does not invoke the language compiler. 

c_sourceSaves only the source modules.  Does not invoke the language compiler. 

objectSaves only the object modules. 

allSaves both the source and the object modules. 

−bug n, −no_bug n
Retains (−bug) or does not retain (−no_bug) a specified bug from earlier IDL compiler versions.  (This is an NCS compatibility argument and is not supported in DCE 1.1.) 

−stdinTakes the standard output of a previous utility as the input to the idl command.  For example:

cat my_filename.idl | idl -stdin

−versionDisplays the current version of the IDL compiler. 

−vPrints informational messages (verbose mode) on the screen while the compiler is running. 

−no_warnSuppresses compiler warning messages. 

−confirmDisplays all the idl command arguments you chose, but does not compile the source IDL file.  If you use this with the −v argument, informational messages about how the compiler behaves if you do not use −confirm are displayed but no corresponding actions are performed. 

DESCRIPTION

The idl command invokes the Interface Definition Language (IDL) compiler to convert an interface definition, written in IDL, into output files.  The possible output files include a header file, server stub file, client stub file, auxiliary files, and a manager class header file.  The compiler constructs the names of the output files by keeping the basename of the interface definition source file but replacing the filename extension with the new extension (or suffix and extension) appropriate to the newly generated type of output file.  For example, math.idl could produce math_sstub.c or math_sstub.o for the server stub. 

The idl command accepts the following input:

       •An interface definition filename. 

       •Arguments to indicate either special actions to be performed by the compiler, or special properties of the input or output files. 

The IDL compiler searches through directories for any related Attribute Configuration File (ACF).  For example, if you compile a file named source.idl, the compiler automatically searches for a file named source.acf.  The compiler also searches for any imported IDL file (and its related ACF).   The compiler searches for these files in the following order:

     1.The current working directory.  The compiler always searches this directory unless you specify the −no_def_idir and −Idirectory arguments together. 

     2.Any  imported  directory.  The  compiler  searches  each  directory you are specifying in the −Idirectory argument. 

     3.The system IDL directory.  The compiler automatically imports nbase.idl, which resides in the system IDL directory.  The compiler always searches this directory unless you specify the −no_def_idir argument. 

     4.The directory specified in the source filename.  If you explicitly specify a directory in the source IDL pathname, then that directory is searched for the corresponding ACF.  For example, the following command causes the IDL compiler to look for /path/pathname/my_source.acf if my_source.acf is not found in the directories in 1 through 3 above:

idl /path/pathname/my_source.idl

Note that this directory is not searched for any imported IDL file or its corresponding ACF.

Restrictions

The following filenames are reserved by the IDL compiler.  Naming an IDL file with one of these names may result in unexpected behavior. 

iovector.idl	lbase.idl	nbase.idl	ncastat.idl
ndrold.idl	rpc.idl	rpcbase.idl	rpcpvt.idl
rpcsts.idl	rpctypes.idl	twr.idl	uuid.idl

 

Caution:   When the IDL compiler generates C code, it is ANSI C code.  It also supports C compilers that are not fully ANSI compliant although a warning message may occur during compilation of the stubs by the C compiler.  A C compiler that is not fully ANSI compliant may generate the following warning messages:

warning: & before array or function: ignored
warning: enumeration type clash, operator =

Caution:   Makefiles created before OSF DCE Release 1.0.3 can produce a compiler warning if they reference .caux.o or .saux.o (auxiliary) files.  You can use these Makefiles without alteration and avoid warnings by forcing IDL to generate empty aux files. In the C shell, set the IDL_GEN_AUX_FILES environment variable as follows:

      setenv IDL_GEN_AUX_FILES 1

EXAMPLES

     1.Invoke the IDL compiler to compile the interface definition file test.idl and keep the generated C source modules.  Only server files are generated.  The server stub default filename is overridden by creating a file named test_ss.c for the server stub module.  The server auxiliary default filename is overridden by creating a file named test_sa.c for the server auxiliary module. 

idl test.idl -keep c_source -client none -sstub test_ss.c -saux test_sa.c

     2.Invoke the IDL compiler to compile the interface definition file test.idl, but do not run the C preprocessor.  The manager entry point vector is not defined in the generated server stub module.  The IDL compiler searches the parent directory of the current directory for any IDL files that test.idl could import.  The generated output files are located in the output subdirectory under the current directory. 

idl test.idl -no_cpp -no_mepv -I.. -out ./output

ERRORS

A representative list of errors that might be returned is not shown here.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

FILES

/lib/cppC preprocessor

dceshared/bin/idl
Compiler

dceshared/include
System IDL directory for imported files

dceshared/include/dce/nbase.idl
Predefined IDL types

dceshared/nls/msg/LANG/idl.cat
Compiler error messages

dceshared/share/include/file.ext
All .idl or .h files that are part of DCE RPC

RELATED INFORMATION

Books:  OSF DCE Application Development Guide—Core Components.