OS/2 Shareware BBS: 10 Tools/10-Tools.zip/makedce1.zip/MAKEDCE.INF

OS/2 Help File | 1995-04-20 | 258KB | 5,007 lines

ΓòÉΓòÉΓòÉ 1. Version Notice ΓòÉΓòÉΓòÉ

First Edition (December 1993)

The following paragraph does not apply to the United Kingdom or any country
where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS
MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  Some states
do not allow disclaimer of express or implied warranties in certain
transactions; therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication.  IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time.

It is possible that this publication may contain reference to, or information
about, IBM products (machines and programs), programming, or services that are
not announced in your country.  Such references or information must not be
construed to mean that IBM intends to announce such IBM products, programming,
or services in your country.

Requests for copies of this publication and for technical information about IBM
products should be made to your IBM Authorized Dealer or your IBM Marketing
Representative.


ΓòÉΓòÉΓòÉ 2. Authors ΓòÉΓòÉΓòÉ

            Uri Shani and Israel Gold

    IBM Israel Haifa Research Laboratory
    MATAM - Center for Advance Technology
    Haifa, Israel 31905

    phone: [phone]
    VNET: SHANI at HAIFASC3
    email: [e-mail]


ΓòÉΓòÉΓòÉ 3. Notices ΓòÉΓòÉΓòÉ

References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM licensed program in this publication is not
intended to state or imply that only IBM's licensed program may be used. Any
functionally equivalent product, program or service that does not infringe any
of IBM's intellectual property rights may be used instead of the IBM product,
program, or service. Evaluation and verification of operation in conjunction
with other products, except those expressly designated by IBM, is the user's
responsibility.

IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director
of Commercial Relations, IBM Corporation, Purchase, NY 10577.

This publication contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include
the names of individuals, companies, brands, and products. All of these names
are fictitious and any similarity to the names and addresses used by an actual
business enterprise is entirely coincidental.

The following terms, denoted by an asterisk (*), used in this publication, are
trademarks or service marks of IBM Corporation in the United States or other
countries:

ZDDDDDDDDDDDDBDDDDDDDDDDDDBDDDDDDDDDDDD?
3 AIX     3 IBM     3 OS/2    3
@DDDDDDDDDDDDADDDDDDDDDDDDADDDDDDDDDDDDY
The following terms, denoted by two asterisks (**), used in this publication,
are trademarks or service marks of other corporations:

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDD?
3 Open Software Foundation  3 OSF     3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 4. Preface ΓòÉΓòÉΓòÉ

This book introduces you to two newly developed tools that are designed to
simplify the development of client-server applications for the Distributed
Computing Environment* (DCE). These tools are provided in MakeDCE. MakeDCE
tools complement the DCE basic toolset and are operational on both OS/2* and
AIX* platforms.

This book describes the DCE MakeDCE tools, what they do and how to use them.


ΓòÉΓòÉΓòÉ 4.1. Audience ΓòÉΓòÉΓòÉ

This book is intended for DCE application developers or programmers needing to
convert existing applications for DCE. The book assumes you have a working
knowledge of DCE and its requirements.


ΓòÉΓòÉΓòÉ 4.2. Purpose ΓòÉΓòÉΓòÉ

After reading this manual, you will

o Understand the relationship of MakeDCE tools to DCE.
o Understand how the MakeDCE tools do their job.
o Be able to use the MakeDCE tools effectively.


ΓòÉΓòÉΓòÉ 4.3. Organization of this Document ΓòÉΓòÉΓòÉ

The book is organized as follows:

o MakeDCE - DCE Application Development Tools, gives you an overview of DCE and
  the roles played by MakeDCE tools.  It introduces the two MakeDCE tools:
  idlgen and gluegen.

o idlgen - An IDL Extractor, describes the workings of idlgen and provides
  complete instructions (along with several examples) on how to use it.

o gluegen - Glue-Code Generator, describes the workings of gluegen and provides
  complete instructions (along with several examples) on how to use it.

o idlgen Messages, lists the messages produced by idlgen.

o gluegen Messages, lists the messages produced by gluegen.

o gluelib Messages, lists the gluelib messages.

A glossary and index are also included.

Note:  Examples in the book are shown for the AIX environment.  Remarks in
       parentheses explain the slight differences needed for the OS/2
       environment.


ΓòÉΓòÉΓòÉ 4.4. Related Documents ΓòÉΓòÉΓòÉ

For information about the DCE environment in general, and DCE application
development in particular, refer to the following documents:

o OSF DCE Introduction to DCE

o OSF DCE User's Guide and Reference

o OSF DCE Application Development Guide


ΓòÉΓòÉΓòÉ 5. MakeDCE - DCE Application Development Tools ΓòÉΓòÉΓòÉ

MakeDCE is a set of productivity tools that speed up the development of DCE
client-server applications and relieve the developer from details. MakeDCE
tools complement the DCE basic toolset and are operational on OS/2* and AIX*
platforms.

DCE applications can be developed by retrofitting existing (old) applications
to the client-server model or by writing new applications from scratch. In
either case, the developer has to write Interface Definition Language (IDL)
files for the server side of the application. It is beneficial, therefore, to
separate the application logic into DCE-independent and DCE-specific sections.
It is also useful to separate the algorithmic part of the application from its
DCE-administration aspects (where the server runs, how to advertise it, how to
bind a client to it, and so on). In all cases, a tool to help develop IDL files
and maintain them against their corresponding application sources is desirable.

MakeDCE provides two tools: idlgen and gluegen.

o idlgen is instrumental in developing IDL files from C files and in
  maintaining the affinity between these two types of separate, though
  parallel, sources.
o gluegen is instrumental in bringing the DCE services into the application
  using a small high-level specification language which frees the programmer
  from using DCE runtime support.

idlgen is a compiler that reads IDL and C sources and produces a new, modified
IDL file. idlgen extracts the interface-relevant information from its input
files and checks that all relevant declarations are present and do not
introduce any conflicts. Wherever needed, idlgen generates IDL attributes and
declarations, and when needed it converts IDL-incompatible constructs in C into
equivalent IDL-compatible constructs. idlgen incorporates into IDL files the
changes made to their corresponding C sources, and vice versa.  It analyzes
implications of changes made to the IDL file by the user.

To use idlgen to develop an IDL file from a collection of C sources, take the
following steps:

 1. Decide the functions that will become IDL operations.
 2. Invoke idlgen to generate an IDL file.
 3. Verify that the generated file answers the requirements.

An application developed with idlgen can be coupled with a non-DCE equivalent
that runs on a single processor, while a distributed DCE version is maintained
in parallel and shares many C sources.

gluegen is a complementing tool that generates the glue or coupling device.
Together with the stubs generated by the idl compiler, gluegen can make up an
operational and meaningful DCE application.  This is depicted in MakeDCE flow
diagram.

This chapter discusses DCE in general and its requirements.  Later chapters
will discuss MakeDCE and how it can help the application developer.


ΓòÉΓòÉΓòÉ 5.1. DCE Background ΓòÉΓòÉΓòÉ

The Open System Foundation** (OSF**) DCE manuals and development guides
describe DCE RPC programming. A central component of the DCE RPC mechanism is
the communication handle, which allows clients to invoke remote operations in
servers.  To establish a handle on the client side, the client has to bind
itself to a server somewhere on the communication network. The server must be
running on that network and has to be listening for incoming calls. The server
could also register itself on a DCE directory service of one kind or another.

Both the client and server sides must perform numerous operations to obtain a
legal handle.  The approach presented here organizes the relevant information
in objects and defines a few high-level, generic operations (methods) on these
objects. If the communication handle is not needed explicitly, there is very
little DCE-oriented activity in the application code. Otherwise, a reference to
a DCE communication handle can be obtained from these objects.


ΓòÉΓòÉΓòÉ 5.2. DCE Application Models ΓòÉΓòÉΓòÉ

DCE building blocks for distributed applications allow the development of
rather complicated and intricate solutions. An operational DCE application is
best represented in the general case as a dynamic graph consisting of nodes and
links. Nodes are client and server programs, each running on some machine, and
links are bindings between clients and servers. A link can represent a
potential binding between two nodes, a connection, or an on-going remote
procedure call (RPC). It is essential to emphasize that in DCE, a link is
represented by means of an interface, as described in a particular IDL file.

The topology of an application can change while it is running. Nodes can appear
and disappear, move (that is, be assigned to different hosts at different
times), connect and disconnect in various ways, have multiple connections at a
time, gain parallel access or be serialized, and so on. The most general
situation can only be implemented by coding a program in a general-purpose
language that uses the DCE RPC primitives.

Although the general task of DCE programming is very broad, a formal
description of this task is needed so that generic templates can be prepared
ahead of time and can be used to easily build useful DCE applications in a
short time.

Two domains are observed in DCE applications:

Static node domain - Represents the static part of DCE applications where each
                    DCE node can be described by the potential connections it
                    can have with the rest of the world.
Dynamic node domain - Represents the dynamic behavior of DCE applications where
                    connections can be defined and formed dynamically.

An Application level exists where both dynamic and static domains can coexist,
and an Interface level exists, which can be static, dynamic, or both (at
different times).

The  static domain of DCE applications is demonstrated by Distributed
Application Graph. A distributed application can be viewed as a directed graph
of Application Nodes. An edge in the graph represents a collection of
operations that can use RPC.  It is named after the DCE interface describing
these operations. The edge arrowhead represents the direction of an RPC; an
edge directed from node B to node A specifies that interface is imported by
node B (source of edge) and exported by node A (target of edge).

When an application node imports a given interface, it is said to be a client
of that interface.  When it exports a given interface, it is said to be a
server of that interface. An application node cannot import and export the same
interface.

To summarize, there are two major goals:

o To define the details of a single interface (link) between DCE nodes of which
  the IDL file is a major component.

o To combine multiple interfaces into DCE applications.

Given a distributed application graph, it can be described by an Interface
Mapping Table that lists for each application node the interface that is
exported or imported by it. For example, the following is the interface mapping
table of the Distributed Application Graph.

ZDDDDDDDDDDDDDDBDDDDDDDDBDDDDDDDDBDDDDDDDDBDDDDDDDD?
3 Interface   3 Node A 3 Node B 3 Node C 3 Node D 3
CDDDDDDDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDD4
3 I1      3 Im   3 Im   3     3 Ex   3
CDDDDDDDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDD4
3 I2      3 Ex   3 Im   3 Ex   3 Im   3
CDDDDDDDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDD4
3 I3      3 Ex   3     3     3 Im   3
CDDDDDDDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDDEDDDDDDDD4
3 I4      3     3 Im   3 Ex   3     3
@DDDDDDDDDDDDDDADDDDDDDDADDDDDDDDADDDDDDDDADDDDDDDDY


          Legend:
       Im - Imported interface
       Ex - Exported interface

Interface mapping table.

A single application node can be an importer, an exporter, or an
importer-exporter of multiple interfaces.  Moreover, a particular interface can
be exported by several application nodes. In the example, interface I2 is
exported by nodes A and C.


ΓòÉΓòÉΓòÉ 5.2.1. Application Node Types ΓòÉΓòÉΓòÉ

Application nodes are characterized by the combination of interfaces they
import, export, or both. The following node types are defined:

ZDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDBDDDDDDDDDDDDDD?
3 Case Number  3 Node Type      3 Num of    3 Num of    3
3        3           3 Exports    3 Imports.   3
CDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDEDDDDDDDDDDDDDD4
3 1       3 Server       3 1       3 0       3
CDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDEDDDDDDDDDDDDDD4
3 2       3 Client       3 0       3 1       3
CDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDEDDDDDDDDDDDDDD4
3 3       3 M-Server      3 Multiple   3 0       3
CDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDEDDDDDDDDDDDDDD4
3 4       3 M-Client      3 0       3 Multiple   3
CDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDEDDDDDDDDDDDDDD4
3 5       3 M-Client-Server   3 Multiple   3 Multiple   3
@DDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDADDDDDDDDDDDDDDY

DCE Application Node Types.

The node types are the following:

Server node - An application node that exports a single interface.
Client node - An application node that imports a single interface.
M-server node - An application node that exports multiple interfaces.
M-client node - An application node that imports multiple interfaces.
M-client-server node - An application node that exports and imports multiple
          interfaces. MakeDCE supports only a specific M-client-server node
          type, which is termed a chaining-server.  See The Glue APIs for more
          information.

For example, the following are displayed in Distributed Application Graph:

o Node C is an M-server.

o Node B is an M-client.

o Nodes A and D are M-client-servers.
The general view of an M-client-server node is as follows:

M-Client-Server Application Node


ΓòÉΓòÉΓòÉ 5.3. MakeDCE Operational Environment ΓòÉΓòÉΓòÉ

When introducing an application into the DCE environment, you, as a DCE
applications programmer, are responsible for writing the IDL file that enables
the server to export the appropriate operations in response to the client RPC.
You have to ensure that functions in the server correctly correspond to the
exported operations.

Then you have to create the glue that binds the client and the server together.
This entails producing application interface code through which the client can
access the application by calling the server.

MakeDCE provides you with two tools that simplify the work involved in creating
the IDL file and glue code:

o idlgen

o gluegen


ΓòÉΓòÉΓòÉ 5.3.1. idlgen ΓòÉΓòÉΓòÉ

MakeDCE idlgen is a powerful tool that aids you in developing an IDL file from
a set of C source files.

In DCE terms, the set of C source files constitutes the front end of interface
implementation, which is also termed the manager of a server. The source files
can be a new application that you are developing.  It can also be an existing
application that needs to be retrofitted for a DCE client-server application
that also needs changes because of limitations in the DCE client-server runtime
conditions.

MakeDCE supports this process with the idlgen tool, which scans C sources and
extracts declarations relevant to the IDL development from them.

When you invoke idlgen, an iterative process evolves in which the IDL file is
refined. At various points in the process, idlgen offers you information about
the IDL syntax and legal possibilities. Whenever the C sources are modified or
the IDL file is edited, the files are matched against each other to recover and
report any conflicts.

Conflicts can cause runtime errors when an implementation of an exported
operation and its definition in the IDL file do not agree. For instance, if the
application uses global variables, which are not supported in DCE, idlgen
issues a warning to draw your attention to this problem.

idlgen does not introduce a new language to learn; rather, it aids you in
learning the IDL language.  In fact, you can learn what you need to know of IDL
while developing your first DCE Server using idlgen.

Although there is no new language to learn, idlgen does introduce some meta
comments that help to maintain information in the IDL file relevant to the C
sources but which the idl compiler does not process.


ΓòÉΓòÉΓòÉ 5.3.2. gluegen ΓòÉΓòÉΓòÉ

The MakeDCE gluegen tool enables you to generate the glue code necessary to
make a complete client-server application.  For this you need to provide
gluegen with a description of the application topology.  You define the
application topology using a set of parameters.  Some of the parameters are
detailed in the DCE documentation; others are specific to gluegen.

The parameters are organized in two levels: Interface Profile and Application
Profile. gluegen uses a simple formal language, Application Profile (APF), to
compound these parameters and use them to generate glue code, which performs
the desired job.


ΓòÉΓòÉΓòÉ 5.3.3. MakeDCE Process Flow ΓòÉΓòÉΓòÉ

The typical processing path of MakeDCE is depicted in MakeDCE flow diagram. A
simple C program such as

     f(a,b){return a+b;}
can provide an immediate demonstration of generating a legal IDL file by idlgen
as follows.

User
                    echo 'f(a,b){return a+b;}' | idlgen -id -o immediate.idl

System
                    MakeDCE 1.0 - Enabling tool for DCE
                    IBM Corporation (c) 1992

                    No input file - reading from standard input
                    Processing file '-stdin'...... C source file.
                    Output idl file is 'standard output (stdout)'.
                    Successful completion

The following IDL file is produced.

User
                    type immediate .idl

System
                    interface noname {
                    /*@;****************************************************************
                        * This file built with the MakeDCE facility for DCE ver 1.0    *
                        *     - A DCE Application-Development Enabling Tool            *
                        *                                                              *
                        * Initially generated on Sun Jan 31 08:45:12 1993              *
                        *         Last update on Sun Jan 31 08:45:12 1993              *
                        *                                                              *
                        * IBM Corporation 1992                                         *
                        ****************************************************************/
                    /*@[export] f ;     file -stdin */

                    long int f (
                       [  in] long int a,
                       [  in] long int b
                    );

                    }


ΓòÉΓòÉΓòÉ 6. idlgen - An IDL Extractor ΓòÉΓòÉΓòÉ

The idlgen tool enables you to update old IDL files to accommodate improved
existing applications or to generate IDL files for new applications. It is a
language translator that takes source files (C and IDL) as input and outputs a
new IDL source file - ready for the idl compiler.

You invoke idlgen from the command line.  A number of command line options and
switches are available for tailoring idlgen operations.

This chapter describes the idlgen tool in terms of what it does and how you use
it.


ΓòÉΓòÉΓòÉ 6.1. idlgen Operation ΓòÉΓòÉΓòÉ

The purpose of this section is to give you some background into the inner
workings of idlgen. This will enable you to make optimum use of the command and
its various switches.  Also, it will help you to understand the results that
you get from running idlgen.

idlgen data and control flow is a schematic of idlgen operation.


ΓòÉΓòÉΓòÉ 6.1.1. Parse Command Line Parameters ΓòÉΓòÉΓòÉ

The general format of the idlgen command is idlgen input-files switches
(complete details of all switches are given in The idlgen Command Syntax).  You
can enter the command with only the input specified, with the input and one or
more switches, or with no parameters at all.

The command you enter is scanned for:

o Correct syntax
o Input source
o Output destination
o Command switches.

If there is a syntax error, idlgen gives you an error message and exits without
incident.

Input Source

The input source can be either files or standard input.

You can enter a list of file names.  idlgen determines that they are input file
names because they are not preceded by any switch triggering character.  The
input files can be either C source files, IDL files, or both. idlgen checks
that each file exists and builds a file name list, which it reads sequentially.

If you invoke idlgen specifying -stdin, standard input is considered as the
input file (in fact, if you invoke idlgen without any parameters at all, idlgen
automatically assumes standard input as the input source).

Using the standard input as the source enables you to pipe the output of
another command into idlgen.

Output Destination

The output of idlgen is always a single IDL file. If you do not specify
otherwise, idlgen writes its output to the standard output.  Using the -o
switch with a file name, you can designate a file name that idlgen writes the
data into.  Using -o by itself causes idlgen to overwrite the input IDL file
with the new data.

Command Switches

idlgen checks all the command switches that you included in the command line
and sets its actions accordingly. Complete details on all of the command
switches are found in The idlgen Command Syntax.

Getting Help

idlgen provides you with several aids:

o Entering the command idlgen -help (or -h) displays an extended help providing
  short descriptions of all command line switches, their format, parameters,
  and use.

o Entering the command idlgen -confirm displays the currently active switches
  and their values.

o Including the switch -v in the command line puts idlgen in the verbose mode
  that prints informational messages while idlgen is running.  The verbose mode
  is the idlgen default mode, so you need to include -v only if you have
  previously turned the mode off (by means of +v).


ΓòÉΓòÉΓòÉ 6.1.2. Parse Source Files ΓòÉΓòÉΓòÉ

To prepare files for input, you need to know what idlgen expects.

The idlgen source file parser consists of grammar rules, semantic actions, and
a symbol table manager.  However, the parser's grammar rules relate only to
certain elements of C and IDL syntax.  Consequently, you cannot depend on it to
detect all C or IDL syntax errors.  idlgen assumes the following about the
input files:

o The C file is correct in the sense that a C compiler will not report any
  syntax or semantic errors.

o The C file is preprocessed so that all macros and #include directives have
  been expanded (idlgen pre-activates the C preprocessor internally).

o The IDL file is correct or is a product of idlgen.

The parser parses declarations only at the file level.  This is the only level
in an IDL file.  In C files, the body of functions is ignored. Each declaration
is internally represented in a data structure that can accommodate the extended
information as defined for IDL. When a C declaration is parsed, the IDL-related
fields remain empty.

Whenever an IDL file imports another IDL file, the name is searched through the
list of paths (if the -I switch is included) built in the first stage. Symbols
defined in import files are marked as such and do not become part of the
generated IDL file. These symbols are used, however, to resolve internal
declaration dependencies.

Each declaration entered into the symbol table is attached to a name.  Symbols
in the symbol table are the following:

o Names of variables and functions in C and operations in IDL

o Typedefs in IDL and C

o Tag names of aggregates (like struct, union, and enum) in C (see also
  Aggregate C Types)

o enum fields

o Names of constants in IDL

o Interface names

o Import file names.

Each symbol is associated with two separately maintained structures:

o Structures associated with the symbol, coming from C files
o Structures associated with the symbol, coming from the IDL file.

If the same symbol is defined more than once in the C files, the latest version
takes precedence. A symbol can be defined more than once when you scan multiple
C files, all of which include the same header file. The old and new data are
compared, however, and a warning is reported if incompatibilities are found
(see also Type Matching). The file name and line number where the symbol is
defined are also recorded.

Constants can have numeric values.  In this case, the values are computed and
stored both numerically and as a character-string representation of the value.

For C, array sizes are also computed and stored in their numerical values, as
well as in their character-string representation. See also The Case of sizeof()
and enum-items for more information.

For functions in C and operations in IDL having parameters, the parameters are
not stored in the symbol table but are link-listed to the data associated with
the function (or operation) name.

For aggregate-type fields, the fields are not listed in the symbol table but,
like function parameters, are link-listed to the data associated with the tag
name of the type definition.

For objects not directly stored as symbols in the symbol table (such as
function parameters and aggregate fields), file names and line numbers are
associated with them for error reporting, if needed.

Comments in IDL files are stored for the main IDL file only so that they can be
reproduced when the output IDL file is generated. When comments are reproduced,
they always occupy their own line. However, changes to the IDL files can cause
misses and redundancies in the reproduction of comments.


ΓòÉΓòÉΓòÉ 6.1.3. Check and Modify ΓòÉΓòÉΓòÉ

idlgen performs the check and modify activity only if there is an input IDL
file that has at least one declaration in its interface body. Otherwise, it
skips this activity and begins generating a new IDL file (see Generate IDL
File).

The first step for idlgen in this activity is to mark all symbol table entries
relevant to the IDL being generated. It does this by first scanning all symbols
of variables, functions, and operations that are declared in the input C
sources or in the IDL input file.  idlgen mards as relevant those it finds that
are marked export and not marked noexport in the meta comment of the IDL file.
idlgen warns you whenever it finds names of global variables not marked
noexport.

idlgen goes over each marked name until all symbols needed by the interface are
marked. Each marked symbol (of function, operation, typedef, or aggregate type)
is checked by comparing the associated IDL data with the associated C data.  If
either of these structures is missing, idlgen takes one of the following
actions:

o If the IDL part is missing, a default IDL definition is generated.  It
  consists of a basic template, the details of which you might need to fill in
  later. idlgen puts in special IDL keywords to prevent the IDL compiler from
  processing the file until you have corrected the missing definition.  See
  Special New IDL Keywords.

  You can disable the insertion of the keywords by using the command line
  switch -d.

o If the symbol is missing in the C data, idlgen assumes that the symbol is
  unique to the IDL file and is legal as is.

If both C and IDL data are present, idlgen compares the definitions in both for
inconsistencies and reports any that it finds.  You can control the comparisons
and actions taken by including either the -conformC or the -conformIDL switch
on the command line.


ΓòÉΓòÉΓòÉ 6.1.4. Generate IDL File ΓòÉΓòÉΓòÉ

idlgen generates two types of IDL files, depending on the input it had to work
on.  The types are:

o Initial IDL File
o Modified IDL File


ΓòÉΓòÉΓòÉ 6.1.4.1. Initial IDL File ΓòÉΓòÉΓòÉ

idlgen generates an initial IDL file if you have not entered an IDL file for
input or if the interface body of the input IDL file is empty. For initial
interface files, idlgen generates meta comments (see Meta Comments in IDL
Files) for all global symbols found in the input C source files. For function
symbols, an export line is generated, with a comment indicating the C input
file it came from. For global variables, a noexport line is generated, also
with a comment indicating the C input file it came from.

You can have idlgen ignore all globals by using the -g switch. You can skip the
initial IDL file stage with the -i switch.

The notion of an initial IDL file is encountered also when the file is modified
and new symbols are introduced. The later situation can occur, for instance,
when an IDL file is modified against a new C file, which is different from the
C file used originally to generate the IDL file.


ΓòÉΓòÉΓòÉ 6.1.4.2. Modified IDL File ΓòÉΓòÉΓòÉ

For an IDL file with an interface body that is not empty, idlgen generates a
modified IDL file.  idlgen scans the symbol table and outputs a legal IDL file
(unless the input IDL file has undergone the process described in Check and
Modify and has the special keywords embedded in it).

idlgen re-generates all meta comments and re-enters all regular comments into
their proper places as much as possible.

The IDL file that idlgen outputs has a pretty-print style that, in general,
offers a readable appearance.


ΓòÉΓòÉΓòÉ 6.2. Meta Comments in IDL Files ΓòÉΓòÉΓòÉ

C declarations and the IDL language do not fully overlap. Information generated
during idlgen processing needs to be maintained. This information relates to
differences between the two sources and to idlgen-specific needs. One solution
is to maintain a side-looking file and associate it with the IDL file (such as
.acf files in DCE). But to avoid all the bookeeping and busy work of dealing
with additional files, idlgen keeps this information in the IDL file itself as
meta comments. For the idl compiler, a meta comment is merely another comment
to be ignored. However, it provides information that makes the code in the IDL
file more comprehensible to users.

Meta comment types are few in number and easy to master.  They are a very
small, transparent addition to the IDL language.

Meta comments have the following general format:

  /*@ [ meta-statement ] ; [ comment ] */
During parsing, idlgen checks the meta-statement for correct syntax but ignores
the comment.

Meta comments serve idlgen for three main purposes:

 1. For a disclaimer header, which identifies idlgen as the generator of the
    file contents and provides its generation date 1 and last modification date
    2.

         interface noname {
        /*@;*********************************************************************
            * This file built with the MakeDCE facility for DCE ver 1.0         *
            *     - A DCE Application-Development Enabling Tool                 *
            *                                                                   *
            * Initially generated on Sun Jan 31 08:45:12 1993 1                             *
            *         Last update on Sun Jan 31 08:45:12 1993 2                             *
            *                                                                   *
            * IBM Corporation 1992                                              *
            *********************************************************************/

 2. For a list of export and noexport symbols.

        /*@[export] f ; file -stdin */

 3. For retaining C-contextual information in the IDL file that would otherwise
    be rejected by the idl compiler.  At the present time, this feature is used
    for retaining enum tags which are not valid for IDL files (see enum Tags).


ΓòÉΓòÉΓòÉ 6.2.1. Export and Noexport Meta Comments ΓòÉΓòÉΓòÉ

idlgen matches the IDL input files with the C source files. However, not
everything exportable from C is exportable in an IDL file.  One such problem
area is symbols defined as global.  For instance, C keywords static and extern
in front of a function or variable declaration make the declarations
non-exportable. The only symbols that IDL can export are functions (or
operations in DCE terminology). Global variables cannot be passed automatically
between DCE clients and servers in an RPC.

When idlgen scans a C souce file (that has been preprocessed, so that all
#include directives are expanded), it examines all the symbols and divides them
into exportable and non-exportable.  It flags them, as appropriate, and lists
them in a meta comment.  This meta comment provides information on what you
must alter in the C source code so that all globals are included as explicit
parameters in some (or all) of the operations.

idlgen considers exportable symbols on the following basis:

o For variables - all exportable symbols defined in the file and imported
  symbols defined elsewhere (that have the extern storage class).

o For functions - only exportable symbols defined in the file.

When an input IDL file exists, it may already define some exported operations.
When a new IDL file is being built, a list of the functions to be included as
export candidates must be generated. idlgen maintains this list in the IDL file
in meta comments. When a new IDL file is initially generated, all global names
in the C sources are entered into the generated IDL file. Function names are
marked as candidates for export, while global variables are marked for
no-export.

You also can make use of the meta comment in the IDL file to control what
idlgen examines for export.  Using the noexport flag causes idlgen to skip the
symbol.  Flagging a symbol with export causes idlgen to export it.

idlgen generates a warning message whenever a C source contains globals that
are not excluded by means of a meta comment unless you use the -g switch in the
command line.

An export or noexport meta comment can be displayed anywhere in the file, but
it is always placed by idlgen at the beginning of the output IDL file. idlgen
produces one meta comment line for each name in meta comments of the input IDL
file.

A idlgen meta comment has the following syntax.

Export/noexport meta comments syntax diagram

                 ZD,DDDD?
                     3
>>DD/*@DD[DDBDexportDDDDDDDDBDD]DDDDnameDADD;DDBDDDDDDBDD*/DDDDDDDDDDDDDDDDDDD><
      CDnoexportDDDDDD4          @DtextDY
      CDtbd(export)DDD4
      @Dtbd(noexport)DY

/*@ ... */  Delimits the meta comment

            */ should not be used anywhere inside a meta comment.
export      Designates that subsequent symbol names are to be exported.
noexport    Designates that subsequent symbol names are to be excluded from
            export in the IDL file.
tbd(...)    Designates that the symbol has been added to the meta comment list
            for an existing IDL input file and must be considered by the user,
            with the value in the parentheses as the recommended one. The
            possible values are export and noexport.
name        A symbol name.  All symbols in this list share the same designation
            as the one specified in the statement head.
text        Optional free text following the ending semicolon, a kind of
            internal comment.  idlgen initially places the name of the source
            file where the symbol has been declared here. If you change this
            text, idlgen retains your text.

Following is an example.

/*@ [ export ] Advance, GetRecord, PutRecord ;  from test. c */

/*@ [ noexport ] count, state ;  from tools.c */
Here the functions Advance, GetRecord, and PutRecord are designated as export
candidates and have been declared in the C source file TEST.C. However, the
global variables count and state, which have been declared in tools.c, are
excluded from exportation.


ΓòÉΓòÉΓòÉ 6.2.2. Export Decision Making ΓòÉΓòÉΓòÉ

A symbol is considered for noexport under the following rules:

o Symbols defined as static or extern are either local or import, respectively,
  and cannot be exported.

o Global symbols that are not marked noexport cause an error message (unless -g
  is set) and are not exported.

  On the other hand, operations defined in an IDL file and not marked noexport
  will be exported.  idlgen will generate a meta comment for them, marking them
  export in the output IDL file.

  Also, functions in C sources marked export in a meta comment in an IDL file
  are exported.

o Illegal functions in C, which cannot be used as remote operations - currently
  only those that use a variable number of arguments (for instance, void foo
  (int a,...)) are marked as noexport in new IDL files and tbd(noexport) in
  additions to old IDL files. If an IDL file marks such a function as export,
  an error message is issued.

In the following example, idlgen extracts all global functions defined in the
source file and makes them exportable operations in the generated IDL file.

   uuidgen -i > test.idl 1
   idlgen test.idl test.c -o 2
   idlgen test.idl test.c -o 3

Explanations: The first line generates a skeleton IDL file 1. The first time
idlgen runs 2, it generates an initial IDL file containing meta comments
excluding all global variables and including all global functions defined in
the file test.c as exportable. The second time that idlgen runs 3, it places in
test.idl all needed declarations for the exported operations, based on the
functions that implement them in the C source.


ΓòÉΓòÉΓòÉ 6.3. The idlgen Command Syntax ΓòÉΓòÉΓòÉ

The idlgen command has the following free-form syntax:

idlgen command syntax

>>DDidlgenDDBDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD><
      3 ZDDDDDDDDDDDDDD? 3
      3         3 3
      @DDBDinput-fileDBADY
        @DswitchDDDDDY

The general format of the command is:

   idlgen [[file-name|-stdin]...] [-o [output-file]]
          [-I path[;path...]] [-D name] [-U name]
          [-no_cpp] [-cpp_cmd cmd] [-cpp_opt opt]
          [-g] [-b] [-d] [-i] [-dceV10 | -dceV11]
          [-conformC | -conformIdl] [-interface new-name]
          [-h] [-help] [-no_warn] [-confirm] [-v]
          [-errfmt { native | emacs } ]

An explanation of the elements follows.


ΓòÉΓòÉΓòÉ 6.3.1. file-name and -stdin ΓòÉΓòÉΓòÉ

file-name can be one or more names of the input files for idlgen.  These files
can be C source files, an IDL file, or both. You can list any number of C
source files as input but only one IDL file.

Normally, if you are using idlgen to generate an initial IDL file, all of the
input files are C sources.  On subsequent iterations of the IDL file, you would
include it with the C source files. Usually, C sources have a .c extension, and
IDL files have an .idl extension.  idlgen determines the input file type from
its content.

The order of input files on the command line is the order in which idlgen
processes them.  You should remember that although IDL and C sources can be
listed in any desired mix on the command line, using different ordering on
subsequent invocations of idlgen can result in different error and warning
messages. This difference is due to the change in the order of input
declarations. A good practice is to place the input IDL source before the C
sources on the command line.

Using -stdin tells idlgen that standard input is an input file.  This enables
you to use the standard output of a previous command. -stdin can be used alone
or with a file list. For example, entering

   uuidgen -i | idlgen -stdin test.c
pipes the output of uuidgen into idlgen that, in turn, merges it with TEST.C to
produce a new IDL file.

If no file name is present in the command line, idlgen assumes -stdin by
default.


ΓòÉΓòÉΓòÉ 6.3.2. idlgen Switches ΓòÉΓòÉΓòÉ

The idlgen switches enable you to tailor the operation of idlgen. You can enter
the switches in any order; however, they are case sensitive.

There are four types of idlgen switches:

o A single letter that takes no arguments
o A single letter that takes an argument
o A single word that takes no arguments
o A single word that takes an argument.

An argument can be assigned to a single-letter switch in three different ways:

o Attached (-sArg)
o Separated by white space (-s Arg)
o Separated by an equal sign with or without white space (-s=Arg, or -s= Arg).

An argument can be assigned to a single-word switch in two possible ways:
separated by white space (-switch Arg) or by an equal sign with or without
white space (-switch=Arg, or -switch= Arg).

A helpful feature is to place those switches you commonly use into the IDLGEN
environment variable.  See The IDLGEN Environment Variable. These switches are
then automatically invoked when you run idlgen.

Note:  Switches are prefaced by a flag:  - (minus) or + (plus). You can
       override the environment variable setting by including the switch in the
       command line with an opposite flag.

You can combine single-letter switches that take no arguments into a single
string with a single flag for the entire string, such as -ibdo or +ibd.

The following switch descriptions are divided into four functional groups:
Output Selection, Generation Switches, Preprocessing Switches, and Help and
Information.


ΓòÉΓòÉΓòÉ 6.3.2.1. Output Selection ΓòÉΓòÉΓòÉ

-o [ output_file ]

Omitting this switch causes idlgen to output to the standard output.

-o

Without an argument, this causes idlgen to overwrite the input IDL file (see
step Examples of idlgen Switches). With an argument, this causes idlgen to
overwrite output_file.

+o

Prevents idlgen from overwriting the IDL file (normally used to override -o in
the environmental variable).


ΓòÉΓòÉΓòÉ 6.3.2.2. Generation Switches ΓòÉΓòÉΓòÉ

The following switches affect the generation mode of IDL output:

-b
          Sets an IDL generation mode in which long indirections are broken
          into more than one typedef so that appropriate IDL attributes can be
          set.

-d
          Prevents idlgen from entering the MK_DEFAULT special attribute into
          generated IDL files. The same effect can be achieved by running a
          second pass of idlgen on the resulting IDL file.

-i
          Skips the intermediate phase of generating initial IDL file where
          lists of candidate symbols are entered in meta comments marked as [
          export ] or [ noexport ]. An initial IDL file is generated when there
          is no input IDL file to idlgen or when the input IDL file has no
          operations declared in it.  When you merge an existing IDL file with
          a new C file and find new functions in it, these functions are also
          entered in meta comments. This switch affects them too. When initial
          IDL phase is skipped, the definitions of new functions found are
          expanded in the output IDL file. Otherwise, a second pass of idlgen
          over the resulting IDL file and the C sources is required.

-conformC and  -conformIdl
          Are generation switches that control how idlgen modifies IDL
          declarations according to the C declarations when they do not match.
          For instance, for -conformC, when a new parameter is added to a
          function, idlgen adds it in the IDL operation declaration too,
          leaving the other parameters untouched, as found in the input file.
          When a parameter is removed in the C source, it is also removed from
          the resulting IDL file. The same is done with fields of union,
          struct, and enum. However, if matching parameters or fields in IDL
          and C have contradicting types, dimensions, and so on, idlgen issues
          an error message. For -conformIdl, such updates are disallowed, and
          warnings are issued for cases of mismatches. The variants +conformC
          and +conformIdl are illegal. The default is -conformC.

-dceV10 and -dceV11
          Are generation switches that control the type of new constructs
          generated for the output IDL file. -dceV10 limits it the type to
          comply with IDL for DCE Ver 1.0. The only effect currently is to
          generate encapsulating unions. This limitation of DCE Ver 1.0
          requires you to write additional code to convert DCE transmission
          types for unions to application types and also the reverse. -dceV11,
          on the other hand, allows the generation of none-encapsulating unions
          when idlgen takes advantage of the extended capability of DCE Ver
          1.1. The variants +dceV10 and +dceV11 are illegal. The default is
          -dceV10.

-g
          Causes idlgen to ignore all global variables in C sources being
          scanned regardless of the contents of the input IDL file. When
          scanning a C source with global variables, idlgen generates meta
          comments to signal that these symbols are not to be considered for
          export. -g prevents this.

-interface new_name
          Sets the interface name in the output IDL to new_name. This is useful
          when the interface name in the IDL file input to idlgen has to be
          changed. For example, the command uuidgen -i generates an IDL header
          with an empty interface named INTERFACENAME. When this header is fed
          into idlgen, -interface can be used to change INTERFACENAME to a more
          meaningful name.


ΓòÉΓòÉΓòÉ 6.3.2.3. Preprocessing Switches ΓòÉΓòÉΓòÉ

The -I, -D and -U switches play the same role for idlgen as for the C
preprocessor and are passed as is to that preprocessor.

-I dir[;dir...]
          Specifies a directory path for import IDL files, as well as for
          preprocessor include files. It is possible to specify more than one
          path for the same -I switch separated with a semicolon (;), or by
          additional -I dir switches on the command line. Note that for the
          first choice, you may want to enclose the list of paths in quotes.
          The directories are searched in the order listed. If a file is
          present in more than one directory, the first occurrence of the file
          is taken.  The default behavior of idlgen is first to search the
          current directory and then to search all specified directories, in
          order. Use -confirm to display the default search paths.

-D name[=definition]
          Defines a symbol name and an optional value to be passed to the C
          preprocessor.  This method can be used for defining symbols instead
          of using the #define directive in the source code.  You can use more
          than one -D name argument on the command line.  This switch has no
          effect if -no_cpp option is included. There are no defaults.

-U name
          Makes the symbol name undefined for the C preprocessor. This method
          can be used for removing symbol definitions instead of using the
          #undef directive in the source code.  You can use more than one -U
          name argument on the command line.  This switch has no effect if
          -no_cpp option is included. There are no defaults.

-cpp_cmd 'cpp-command'
          Invokes the C preprocessor you specify in 'cpp-command' rather than
          the default, which can be viewed using -confirm.

-cpp_opt 'cpp-options'
          Specifies additional options to be passed to the C preprocessor. You
          can add options to the command line used to invoke the C preprocessor
          independent of the -cpp_cmd switch. idlgen concatenates the -cpp_cmd,
          -cpp_opt, -D, -U, and -I arguments and the source C files into a
          command that invokes the C preprocessor. Use -confirm to display the
          default cpp options.

-no_cpp
          Prevents invoking the C preprocessor. Note that the C processor must
          be run on input files (C and IDL) that contain preprocessor
          directives (such as #define or #include).


ΓòÉΓòÉΓòÉ 6.3.2.4. Help and Information ΓòÉΓòÉΓòÉ

-h
          Displays a brief syntactic help on the command options, the same as
          that shown in idlgen command syntax.

-help
          Displays an extended help containing a short description of the
          command options.

-v
          Sets verbose mode, which prints informational messages while idlgen
          is running.  To turn verbose mode off, use +v. The default is -v.

-no_warn
          Suppresses all warning messages.

-confirm
          Displays all active values of idlgen command options. It does not
          process the input files.

-errfmt errfmt-choice
          Selects message format for errors and warnings where file locations
          are present. The errfmt-choice is between emacs, and native. emacs
          format can than be used to browse back into the source file using the
          emacs editor when editing the stderr file. The native format is the
          one presented here in the "messages" chapters at the end of this
          book.


ΓòÉΓòÉΓòÉ 6.3.3. Examples of idlgen Switches ΓòÉΓòÉΓòÉ

 1. Generate a simple, correct, and complete IDL file by typing:

           echo "f(a){};" | idlgen -id

 2. Call idlgen to process the C file TEST.C and generate an initial IDL file
    to the standard output.

           idlgen test.c

 3. Call idlgen to process the C file TEST.C and generate an initial IDL file,
    TEST.IDL. If TEST.IDL already exists, it will be overwritten.

           idlgen test.c -o test.idl

 4. Call idlgen as in the previous example, except that an existing IDL
    TEST.IDL is merged with the C source TEST.C; the resulting IDL file
    overwrites TEST.IDL.

           idlgen test.idl test.c -o

 5. Call idlgen to process three input C sources and one input IDL source.  The
    result of this merge is written to the file NEWTEST.IDL. Note that the IDL
    file precedes the C files on the command line.

           idlgen test.idl util.c lib.c test.c -o newtest.idl

 6. Use standard input and output to combine several steps into one. The
    skeleton IDL file generated by uuidgen is piped into idlgen where an
    initial IDL file for the source S.C is generated and immediately piped into
    a second idlgen stage where it is merged into the same source file to
    produce an IDL file.  The final output is written to the standard output.

           uuidgen -i | idlgen -stdin s.c | idlgen -stdin s.c

 7. Use in the same way as in Example 5 but with multiple phases:

        idlgen test.idl util.c | idlgen -stdin lib.c |
             idlgen -stdin test.c -o newtest.idl

 8. Use in the same way as in Example 6 but omit the intermediate step of
    generating an initial IDL file and write the final output to S.IDL using
    the shell redirection.

           uuidgen -i | idlgen -stdin -i s.c >! s.idl


ΓòÉΓòÉΓòÉ 6.3.4. The IDLGEN Environment Variable ΓòÉΓòÉΓòÉ

You can make use of the IDLGEN environment variable to hold switches and
parameters. If this variable is present in the environment, idlgen first scans
its contents and sets various defaults according to the switches and parameters
defined by it before processing the command line options.

Using the IDLGEN environment variable, you can reduce the size and complexity
of the idlgen command line. You can also use it to contain switches and
parameters you frequently use with idlgen. For example, on OS/2, this feature
can be used as follows:

   set IDLGEN=switches-and-parms
   idlgen more-switches-and-parms
This is equivalent to the following:

   idlgen switches-and-parms more-switches-and-parms

The idlgen command produces two standard output streams, which can be
redirected through pipes:

o The stderr stream producing messages, warnings, and errors

o The stdout stream producing the new IDL file generated by idlgen.


ΓòÉΓòÉΓòÉ 6.4. Command Addendum ΓòÉΓòÉΓòÉ

This command addendum contains notes on various idlgen aspects that provide
expanded information on the preceding descriptions and discussions.


ΓòÉΓòÉΓòÉ 6.4.1. Number of Input IDL Files ΓòÉΓòÉΓòÉ

Although idlgen allows only one IDL input file, multiple IDL files can be
processed when included as import statements in the IDL input file. When the
IDL file is regenerated, the declarations in import files are not reproduced in
the output file. Only import statements for these files are generated.

A more complicated case occurs when there are multiple input IDL files at the
command-line level. In this case, there are three classes of IDL files:

o The main IDL file, which is the only IDL file in the file list that a new
  version will be reproduced for at the end.

o The example IDL files, which are used to fill in declarations that may be
  needed in the generated file and cannot be found in any of the import files
  thereof. Example files are distinguished by a special -xmp switch.

  Note:  example files are not supported in this version.

o The import files, which occur in the main or in example IDL files or which
  are recursively imported in other import files.


ΓòÉΓòÉΓòÉ 6.4.2. Order of Input Files ΓòÉΓòÉΓòÉ

When input files are scanned, symbols are encountered and inserted into the
symbol table. The initial order of insertion in this table is preserved and is
used as a basis for generating the output IDL file.

Different C files can define symbols in different orders.  You can also alter
the order of declarations (as long as they do not introduce IDL errors) in the
IDL file by using a text editor. To preserve the order of declarations in the
input IDL file, ensure that the declarations are the first input file name in
the command line.


ΓòÉΓòÉΓòÉ 6.4.3. Aggregate C Types ΓòÉΓòÉΓòÉ

In IDL, all type definitions come in the form of constants, typedefs, and
operations. Typedefs are actually a declaration of a new name for an existing
type. In the C language, aggregates can also be defined as pure types with no
connection to any typedef nor with relation to a file-level variable. When you
scan a C file, you can define a parameter of a function using a basic form of
an aggregate (for example, void foo( struct s parm );).  When you convert to
IDL declarations, change these aggregates to typedefs. Since if there is no
name for a typedef, it has to be generated by idlgen. The new names are
composed from contextual information so that they are unique in the file but
are generated in the same way for additional files with the same context. A
consistent naming convention is required in order to properly identify symbols
to be matched in related files. For example, the aggregate:

   struct s...;
is redefined as

   typedef struct s...s_MKGEN...;


ΓòÉΓòÉΓòÉ 6.4.4. Anonymous C Aggregates ΓòÉΓòÉΓòÉ

When a C aggregate has no tag, one is created for it by idlgen in a way that
depends on its context and ensures consistent matching for that type between
the C and IDL files. For instance, the anonymous structure in this function
prototype:

   void foo( struct { int i;} x) ...
is converted to a tagged struct as follows:

  typedef struct foo_MKAGGR_x {
      long int i;
  } foo_MKAGGR_x_MKGEN;

  void foo( [in] foo_MKAGGR_x_MKGEN x);


ΓòÉΓòÉΓòÉ 6.4.5. Type Matching ΓòÉΓòÉΓòÉ

When two input C files include the same .h file, the same declaration occurs
twice. In this case, they are exactly the same. In other cases, because of
careless programming practices, same declarations can occur in separate C
sources as two distinct objects (having two separate sources). In the latter
case, the two types may not be exactly compatible. Currently, the latest
declaration takes precedence, but the two declarations (new and old) are
compared, and a warning is issued if they are incompatible.

In the case of the same include file, both declarations are the same. A method
to help in the processing of duplicate include files is to record names of
processed include files and ignore include files that have already been
processed. Note that since multiple (preprocessed) C sources are scanned, the
common method recommended for C programs to prevent duplicate inclusions of C
includes by defining (and undefining) specific preprocessor symbols cannot be
used.


ΓòÉΓòÉΓòÉ 6.4.6. The Case of sizeof() and enum-items ΓòÉΓòÉΓòÉ

To check compatibility of array sizes in C declarations and IDL files, idlgen
computes the constant expressions in IDL and in C sources. In case the program
uses sizeof(), which is a compiler-specific internal operator, to set the size
of an array, it cannot be used in an IDL file.  idlgen issues an appropriate
warning message that size comparison cannot be done. When the size expression
involves enumeration items, the expression cannot be part of the IDL file. If
the IDL file is still generated with such expressions, an error is reported.


ΓòÉΓòÉΓòÉ 6.4.7. Breaking Long Indirections ΓòÉΓòÉΓòÉ

C allows declarations to have a chain of indirections of any length. In IDL
there are certain limitations on indirections and arrays. It is also impossible
to specify different addressing attributes to the various levels of
indirections unless they are separated into simple cases. This can be done by
breaking long chains of indirections into chains of typedefs. If the -b switch
is set in the command line, this is automatically done by idlgen.  Otherwise, a
warning message is issued.

In a specific case, when a function returns a pointer, it is always converted
to a newly defined typedef where the indirection is hidden. This occurs because
the current idl compiler does not accept IDL files with pointer function
values, although the documentation does not preclude the case.


ΓòÉΓòÉΓòÉ 6.4.8. Special New IDL Keywords ΓòÉΓòÉΓòÉ

When new IDL attributes are needed for a newly generated IDL declaration, which
has been extracted from a C source, idlgen can generate a reasonably correct
declaration. This is processed correctly by the IDL compiler, but it may not be
the correct choice. Therefore, idlgen generates a new IDL declaration using new
keywords, which indicates that you must enter something or approve what idlgen
generated. If you pass the resulting IDL file with no changes to the idl
compiler, syntax errors can occur. If you re-input it to idlgen, it removes
these keywords and generates attributes it assumes are acceptable to you.

idlgen uses two such special keywords currently:  MK_DEFAULT and MK_ERROR. The
former is used whenever it generates IDL attributes and the latter when idlgen
detects an apparent incompatibility between a declaration in the IDL file and
its corresponding C counterpart. When an input IDL file to idlgen has special
keywords, the MK_DEFAULT keywords are removed, but the MK_ERROR keywords are
left for you to remove after you make the proper corrections.

Another method to get rid of the MK_DEFAULT special keyword is to use the -d
command-line switch as discussed on page Generation Switches.


ΓòÉΓòÉΓòÉ 6.4.9. Function Pointers as Parameters and Aggregate Fields ΓòÉΓòÉΓòÉ

Parameters and aggregate fields can be function pointers. Such parameters and
aggregate fields are illegal for IDL; they need to be detected in the C files
and should not be used in the IDL file.  idlgen issues error messages when IDL
operations make use of such declarations directly or indirectly.


ΓòÉΓòÉΓòÉ 6.4.10. Matching Unions ΓòÉΓòÉΓòÉ

Unions in C and IDL match even when their fields have different orders.  Unions
in IDL have selection information and attributes.

   typedef union _u switch(long s) {
      case 0: long int i;
      case 1: double   d;
   } u;
When a union in a C file is changed and new fields are added, the IDL union
attributes need to be extended and applied also to the new union fields.  For
the preceding example, if a new field char c is added, it is automatically
entered as:

     case 2: char      c;


ΓòÉΓòÉΓòÉ 6.4.11. enum Tags ΓòÉΓòÉΓòÉ

IDL language does not accept enum with tags. All enum aggregates must have a
typedef and must have their tags removed. To maintain affinity between the IDL
file and its C source, the tag is entered into the IDL declaration inside a
meta comment (see the preceding example). The idl compiler ignores this as a
comment, while idlgen reads the tag name and is able to associate it with the
corresponding C source construct for type matching. Carrying the tag name into
the IDL file also creates a helpful piece of information for you.


ΓòÉΓòÉΓòÉ 6.4.12. Bit Fields ΓòÉΓòÉΓòÉ

The IDL language does not accept bit fields in struct and union aggregates.
idlgen removes these parts of the structure before generating the IDL file.
Alignment (nameless, or 0-length) fields are removed, and other bit fields are
left without their bit location part. In cases where two structures with bit
fields in C files are compared, bit-field location values are compared as well.
When a structure in a C file with bit fields is compared with a corresponding
IDL structure, idlgen issues a warning message.


ΓòÉΓòÉΓòÉ 6.4.13. Long Identifiers ΓòÉΓòÉΓòÉ

The IDL language limits identifiers length below the length permitted in C.
idlgen has no limitation on the identifier length, but will check identifiers
in input C files against the IDL limit. Moreover, idlgen generates new
identifiers in output IDL files, which can be very long since they are
generated as a combination of C identifiers.

To prevent IDL syntax errors, idlgen generates #define statements in the output
IDL file where long names are defined as short names. When the file is
processed by idl compiler, only the short names are seen. When processed by
idlgen, the long names are used. This is needed to properly identify and match
C and IDL sources.

An example is the following C source:

User
                    type long.c

System
                    typedef struct very_long_struct_name_in_C {
                       int very_long_struct_field_name;
                    } very_long_typedef_name_in_C;

                    very_long_function_name 1 (
                       very_long_typedef_name_in_C very_long_parameter_in_C
                    ){};


The IDL file is generated using idlgen.

User
                    idlgen long.c -idbo long.idl

System

                    MakeDCE 1.2 - Enabling tool for DCE
                    IBM Corporation (c) 1992, 1993

                    Running the C preprocessor  '... long.c ...' 2
                    Processing file 'long.c'...... C source file.
                    Output IDL file is 'long.idl'.
                    Successful completion


The resulting IDL file defines short names for the long names in the C source.

User
                    type long.idl

System
                    interface noname {
                    /*@;*****************************************************************
                        * This file built with the MakeDCE facility for DCE ver 1.0     *
                        *     - A DCE Application-Development Enabling Tool             *
                        *                                                               *
                        * Initially generated on Mon Sep 20 14:35:41 1993               *
                        *         Last update on Mon Sep 20 14:35:41 1993               *
                        *                                                               *
                        * IBM Corporation 1992, 1993                                    *
                        *****************************************************************/

                    #ifndef IDLGEN 3
                    #   define function_name 4 MKSHORT_0 5
                    #   define very_long_parameter_in_C MKSHORT_1
                    #   define very_long_typedef_name_in_C MKSHORT_2
                    #   define very_long_struct_name_in_C MKSHORT_3
                    #   define very_long_struct_field_name MKSHORT_4
                    #endif

                    /*@[export] function_name ; file long.c */


                    typedef struct very_long_struct_name_in_C  6  {
                       long int very_long_struct_field_name;
                    } very_long_typedef_name_in_C;

                    long int
                    function_name (
                       [  in] very_long_typedef_name_in_C
                           very_long_parameter_in_C
                    );

                    }


Explanation for long identifiers

The long function name 1 in the C source long.c is defined 4 in the resulting
IDL file as a shorter name SHORT_0 5. In the idl compiler the symbol IDLGEN 3
should not be defined so that the name of the very_long_struct 6 is converted
by the C preprocessor to the short name. When the file is processed 2 by
idlgen, the symbol IDLGEN 3 is defined (not shown in the execution log above),
so that it sees the original long name.


ΓòÉΓòÉΓòÉ 6.4.14. Differences between -dceV10 and -dceV11 ΓòÉΓòÉΓòÉ

The differences are currently only limited to how idlgen processes unions.


ΓòÉΓòÉΓòÉ 6.4.14.1. Using -dceV10 ΓòÉΓòÉΓòÉ

User
                    type u.c 1

System
                    void foo (   2
                       union { int i; float f; } U) {}

User
                    icc -c u.c 3

System
                    4

User
                    idlgen u.c -dceV10 -ido u.idl 5

System
                     ... 6

User
                    type  u.idl 7

                    interface noname {

                       . . .       8

                    /*@[export] foo ;    file u.c */  9

                    /*Manufactured typedef for an aggregate by MakeDCE */  10
                    typedef union foo_MKAGGR_U switch 11 (long MK_TEMP 12)  {
                       13 case 0: long int i;
                            case 1: float f;
                    } foo_MKAGGR_U_MKGEN; 14

                    void
                    foo (
                       [  in] foo_MKAGGR_U_MKGEN U  15
                    );

                    }

Explanation for using -dceV10

Displaying the source file u.c 1 reveals that there is a single function having
a union parameter 2. File compilation 3 completes successfully 4. idlgen
processes a single C input and produces an IDL file, u.idl, in one step 5.
idlgen message trace is not shown 6.  The resulting IDL file is displayed 7,
skipping the disclaimer meta comment header 8. One function 9 is exported.  The
function has a single parameter, U, which uses an anonymous union. To assign
IDL attributes, the union is assigned a name foo_MKAGGR_U 11, enclosed in a
typedef whose name is also generated by idlgen: foo_MKAGGR_U_MKGEN 14.  These
names are composed from the context where the union is defined originally:  the
parameter U, of the function foo.  The generated typedef is preceded by a
comment generated by idlgen 9.  The non-encapsulating union has the proper
format, designating a long discriminator named formally as MK_TEMP 12. Two case
of 0 and 1 mark the two possible fields of the union 13.  The reference to the
new typedef becomes the new type of the original parameter 15.


ΓòÉΓòÉΓòÉ 6.4.14.2. Using -dceV11 ΓòÉΓòÉΓòÉ

User
                    idlgen u.c -dceV11 -ido u.idl1 1

System
                     ...

User
                    type u.idl1

System
                    interface noname {

                     . . .

                    /*@[export] foo ;     file u.c */

                    /*Manufactured typedef for an aggregate by MakeDCE */
                    typedef union foo_MKAGGR_U  {
                       2   [case( 0)] long int i;
                             [case( 1)] float f;
                    } foo_MKAGGR_U_MKGEN;

                    void
                    foo (
                       [  in, switch_is( MK_TEMP 3)] foo_MKAGGR_U_MKGEN U
                    );

                    }

Explanation for using -dceV11

idlgen is activated with the -dceV11 switch in the same context as the previous
example, resulting in an IDL file containing an encapsulating union. As in the
previous example, a new union and typedef are defined for the anonymous union
originally found in the C source file.  The new format defines the case values
only for the two alternative fields of the union 2.  In the function header, a
[switch_is:] attribute is added with a temporary discriminator, MK_TEMP 3,
which has to have a correct name of another parameter for the function (missing
in this example).


ΓòÉΓòÉΓòÉ 6.4.15. Dependencies Considerations ΓòÉΓòÉΓòÉ

When idlgen reads input, it builds a dependency graph of all language elements
of the resulting IDL file and outputs only those that are needed to fully
define the file.  In the following example, an IDL input file has some
redundant declarations, which idlgen filters out of its output.  When input is
C files, there are many declarations that are not needed for the IDL.
Considering only the system include .h files is enough rationale to use idlgen.

User
                    type orig.idl 1

System
                    [
                    uuid(0004CF04-AF11-1B28-8C80-10005AA8B716),
                    version(1.0)
                    ]
                    interface INTERFACENAME
                    {
                       const int a = 3;  2
                       const int b = a + 4;  3
                       const int c = a+b; 4
                       typedef int A[b*2];  5
                       void foo(A A);  6
                    }

User
                    idlgen orig.idl -o new.idl 7

System
                     ...

User
                    type new.idl

System
                    [
                    uuid(0004CF04-AF11-1B28-8C80-10005AA8B716),
                    version(1.0)
                    ] interface INTERFACENAME {

                     . . .  8

                    /*@[export] foo ; c.idl */  9

                    const int a= 3;  10
                    const int b= a + 4; 11

                    typedef int A[b*2];  12

                    void
                    foo (
                       A A  13
                    );

                    }

Explanation for dependencies

The original IDL file is displayed 1.  The file defines several constants 2 - 4
that are used to define the single foo operation 6. The function has a single
parameter whose type 5 uses the constant b, which uses 3 the constant a 2.
Apparently, the constant c 4 is not used anywhere.

When you process this file with idlgen 7, the new file is reformatted, a
disclaimer meta comment is added to it 8 (not shown), and an export meta
comment for the foo operation is added 9.  Only the constants a 10 and b 11 are
included, since they are needed to fully define the parameter type 12 and 13.


ΓòÉΓòÉΓòÉ 6.4.16. Special MakeDCE keywords ΓòÉΓòÉΓòÉ

MakeDCE introduces MK_DEFAULT and MK_ERROR keywords. An example of the
MK_DEFAULT is given in idlgen Invocation Example.  In the following example, a
C source file is used to generate an IDL file and is then changed in a way that
triggers idlgen to flag the change as a suspected error.

User
                    type orig.c 1

System
                    struct s {
                       int i 2; float f 3;};
                    void foo( struct s S){};

User
                    idlgen orig.c -ido orig.idl 4

System
                     ... 5

User
                    type orig.idl

System
                    interface noname {
                      . . .
                    /*@[export] foo ;    file s.c */ 6

                    /*Manufactured typedef for an aggregate by MakeDCE */
                    typedef struct s  {
                       long int i; 7
                       float f; 8
                    } s_MKGEN;

                    void
                    foo (
                       [ in ] s_MKGEN S
                    );
                    }

struct s {

User
                    type new.c 9

System
                    struct s {
                       float i 10; float f 11;};
                    void foo( struct s S){};

User
                    idlgen orig.idl new.c -o new.idl 12

System
                     ...

User
                    type new.idl 13

System
                    interface noname {
                      . . .
                    /*@[export] foo ;     file s.c */

                    typedef struct s  {
                       [  MK_ERROR 14] long int  i;
                       float f;
                    } s_MKGEN;

                    void
                    foo (
                       [ in ] s_MKGEN S
                    );
                    }

Explanation for special MakeDCE keywords

The original C file orig.c is displayed 1.  The file defines a single function
with one parameter, which is a structure of two fields, int 2 and float 3. An
IDL file orig.idl is generated from the original C file 4, skipping the idlgen
execution trace 5 and displaying the generated IDL file. A meta comment
declares the exported function 6 and includes the structure declaration with
the two fields as in the original file, where the int is extended with a long
modifier 7.  The float field remains as is 8.

The C file is changed to new.c and displayed 9, revealing that the first field
changed its type (but not the name) from int 2 to float 10. The second field 11
remains as it was 3. The original IDL and and the modified C file 12 are
merged, generating a new IDL file, new.idl, and displaying it 13. Since the
first field in the structure has the same name, but a different type in the two
input (C and IDL) files, this is marked as an error in the resulting file with
the special keyword MK_ERROR 14.  An error message is also displayed (not shown
here).


ΓòÉΓòÉΓòÉ 6.5. idlgen Invocation Example ΓòÉΓòÉΓòÉ

Steps for invoking idlgen follow.

 1. List the C source file

 2. Run the initial IDL file

 3. In the second phase, expand exported functions

 4. In the third phase, clean up special keywords

 5. Do everything in one step

 6. Perform the full process from uuidgen to idl


ΓòÉΓòÉΓòÉ 6.5.1. List the C source file ΓòÉΓòÉΓòÉ

User
                    type init.c 0

System

                    f(a){} 1
                    int x= 5; 2
                    static int g(int a, float b){}; 3
                    extern float h(int a); 4
                    int f1(char c); 5
                    int g1(char *s); 6
                    int f1(char c) { }; 7


User
                    icc -c init.c 8

System
                    9

Explanation of Listing the C source file

Listing the source file init.c 0 shows that the file defines two global
functions 1 and 7, one of which is preceded with a prototype 5.  One function
is local (static) 3, one function is only a prototype (has no body) 6, and one
function is a prototype of a function defined elsewhere 4. There is also one
global variable 2.  When the file is compiled 8, there are no detected
compilation errors 9.


ΓòÉΓòÉΓòÉ 6.5.2. Run the initial IDL file ΓòÉΓòÉΓòÉ

User
                    idlgen init.c -o init.idl1 -interface test 1

System

                    MakeDCE 1.2 - Enabling tool for DCE
                    IBM Corporation (c) 1992, 1993  2

                    Running the C preprocessor  '... init.c ...' 3
                    Processing file 'init.c'...... C source file. 4
                    Output IDL file is 'init.idl1'. 5
                    Initial IDL file generation -- completed. 6

User
                    type init.idl1 7

System
                    interface test { 8
                    /*@;***************************************************************
                        * This file built with the MakeDCE facility for DCE ver 1.0   *
                        *     - A DCE Application-Development Enabling Tool           *
                        *                                                             *
                        * Initially generated on Mon May 24 20:24:37 1993 9         *
                        *         Last update on Mon May 24 20:24:37 1993 10        *
                        *                                                             *
                        * IBM Corporation 1992, 1993                                  *
                        ***************************************************************/
                    /*@[export] f;  file init.c */     11
                    /*@[noexport] x;     file init.c */   12
                    /*@[export] f1;      file init.c */    13
                    }

Explanation for running the initial IDL file

Running idlgen takes one C input file, init.c, and produces IDL output into
file init.idl1 designated with the -o switch 1.  This is also reported during
the running of idlgen when the input file type is automatically determined as a
C file 4 and the output file name is acknowledged 5. The C preprocessor is
activated automatically on the input file using the default cpp command and
switches 3, and idlgen runs without errors 6. Displaying the resulting IDL file
7 shows an empty interface header with a new name test 8 as requested in the
command line using the -interface switch 1. Following the header is a
disclaimer meta comment including the generation date and time 9 and the date
and time of the last update 10, which are the same for the first time.  The
list of symbols designation in meta comments recognizes the two functions
defined in file f 11 and file f1 13. The global variable x is marked as
noexport 12.


ΓòÉΓòÉΓòÉ 6.5.3. In the second phase, expand exported functions ΓòÉΓòÉΓòÉ

User
                    idlgen init.idl1 init.c -o init.idl2 1

System

                    MakeDCE 1.2 - Enabling tool for DCE
                    IBM Corporation (c) 1992, 1993

                    Running the C preprocessor  '/...init.idl1...'  2
                    Processing file 'init.idl1'...... IDL file. 3
                    Importing IDL file '"dce\nbase.idl"' 4
                    Running the C preprocessor  '... dce\nbase.idl ...' 5
                    Running the C preprocessor  '... init.c ...' 6
                    Processing file 'init.c'...... C source file.  7
                    Output IDL file is 'init.idl2'.
                    Successful completion 8

User
                    type init.idl2 9

System
                    interface test {
                    /*@;***************************************************************
                        * This file built with the MakeDCE facility for DCE ver 1.0   *
                        *     - A DCE Application-Development Enabling Tool           *
                        *                                                             *
                        * Initially generated on Mon May 24 20:24:37 1993             *
                        *         Last update on Mon May 24 20:25:39 1993 10        *
                        *                                                             *
                        * IBM Corporation 1992, 1993                                  *
                        ***************************************************************/
                    /*@[export] f ;     file init.c */
                    /*@[noexport] x ;     file init.c */
                    /*@[export] f1 ;     file init.c */

                    long int MK_DEFAULT 11
                    f (
                       [  in, MK_DEFAULT] 12 long int MK_DEFAULT 13
                    );


                    long int MK_DEFAULT 14
                    f1 (
                       [  in, MK_DEFAULT] 15 char c
                    );

                    }

Explanation for expanding exported functions

Running idlgen to merge an IDL and a C file takes the IDL file first and then
the C file.  Based on the -o switch argument, an init.idl2 is selected for
output 1 (instead of init.idl1 - the IDL input file). The first file init.idl1
is preprocessed 2 and automatically recognized as an IDL file 3.  For the IDL
file, idlgen automatically imports the DCE base file nbase.idl 4, which is
located at the DCE installation base (whose path is stored in the NIDLDIR
environment variable) and preprocess this file as well 5. As in the first
stage, the C input file init.c is preprocessed 6 and recognized as a C file 7.
idlgen successfully completes 8, writing its output to the designated output
file init.idl2, which is subsequently listed 9.  The resulting IDL file has an
updated date and time in the header disclaimer 10 and an expansion of the two
exportable functions f and f1. The special keyword MK_DEFAULT is entered in
places where idlgen adds attributes 12 and 15 and where idlgen extends the C
types 11, 13, and 14 to the accuracy required by the idl compiler.


ΓòÉΓòÉΓòÉ 6.5.4. In the third phase, clean up special keywords ΓòÉΓòÉΓòÉ

User
                    idlgen init.idl2 init.c -o init.idl3 1

System

                    MakeDCE 1.2 - Enabling tool for DCE
                    IBM Corporation (c) 1992, 1993    2

                    Running the C preprocessor  '... init.idl2...'
                    Processing file 'init.idl2'...... IDL file.
                    Importing IDL file '"dce\nbase.idl"'
                    Running the C preprocessor  '... dce\nbase.idl ...'
                    Running the C preprocessor  '... init.c ...'
                    Processing file 'init.c'...... C source file.
                    Output IDL file is 'init.idl3'.
                    Successful completion

User
                    type init.idl3

System
                    interface test {
                    /*@;***************************************************************
                        * This file built with the MakeDCE facility for DCE ver 1.0   *
                        *     - A DCE Application-Development Enabling Tool           *
                        *                                                             *
                        * Initially generated on Mon May 24 20:24:37 1993             *
                        *         Last update on Mon May 24 20:26:00 1993  3        *
                        *                                                             *
                        * IBM Corporation 1992, 1993                                  *
                        ***************************************************************/
                    /*@[export] f ;     file init.c */
                    /*@[noexport] x ;     file init.c */
                    /*@[export] f1 ;     file init.c */

                    long int          4
                    f (
                       [  in] long int a
                    );


                    long int
                    f1 (              5
                       [  in] char c
                    );
                    }

User
                    idl -syntax_only init.idl3 6

System
                     7
                    Operation f has no binding handle parameter; [auto_handle] assumed
                    Operation f1 has no binding handle parameter; [auto_handle] assumed
                    idl: File init.idl3, line 1: interface noname {
                    Interface UUID must be specified 8

Explanation for cleaning up special keywords

The third running of idlgen merges the resulting IDL file from the previous
stage, init.idl2, with the original C source, init.c, and writes the result to
a new IDL file, init.idl3 1. The trace of the run 2 is very similar to the
previous stage where all input files are preprocessed and their types
automatically recognized. The resulting file has a new date and time stamp for
the update in the header disclaimer 3, and the exported functions have been
cleaned 4 and 5 of the special keywords for processing by the idl compiler 6
and 7.

Note:  The requirement for a UUID 8 could be met by using uuidgen -i at the
start.


ΓòÉΓòÉΓòÉ 6.5.5. Do everything in one step ΓòÉΓòÉΓòÉ

User
                    idlgen init.c -id 1

System

                    MakeDCE 1.2 - Enabling tool for DCE
                    IBM Corporation (c) 1992, 1993

                    Running the C preprocessor  '... init.c ...'
                    Processing file 'init.c'...... C source file. 2
                    Output IDL file is 'standard output (stdout)'. 3
                    Successful completion
                    interface noname {
                    /*@;***************************************************************
                        * This file built with the MakeDCE facility for DCE ver 1.0   *
                        *     - A DCE Application-Development Enabling Tool           *
                        *                                                             *
                        * Initially generated on Mon May 24 20:40:58 1993             *
                        *         Last update on Mon May 24 20:40:58 1993             *
                        *                                                             *
                        * IBM Corporation 1992, 1993                                  *
                        ***************************************************************/
                    /*@[export] f ;     file init.c */
                    /*@[noexport] x ;     file init.c */
                    /*@[export] f1 ;     file init.c */

                    long int
                    f (
                       [  in] long int a
                    );


                    long int
                    f1 (
                       [  in] char c
                    );

                    }

Explanation for doing everything in one step

Note that the command switches -i and -d are combined. They force idl to skip
the init and default insertion steps 1. There is only one input file 2,
recognized as a C file, and the output goes to standard-output 3, where it is
displayed (and is the same in content as the file that resulted from all the
steps above).


ΓòÉΓòÉΓòÉ 6.5.6. Perform the full process from uuidgen to idl ΓòÉΓòÉΓòÉ

User
                    uuidgen -i | idlgen -stdin 1 test.c -id -interface test |
                        idl -stdin 2

System
                    MakeDCE 1.2 - Enabling tool for DCE 3
                    IBM Corporation (c) 1992, 1993

                    Running the C preprocessor  '....' 5
                    Processing file '-stdin'...... IDL file. 6
                    Importing IDL file '"dce\nbase.idl"'
                    Running the C preprocessor  '... dce\nbase.idl ...' 7
                    Running the C preprocessor  '... init.c ...' 8
                    Processing file 'init.c'...... C source file. 9
                    Output IDL file is 'standard output (stdout)'. 10
                    Successful completion
                    Operation f has no binding handle parameter; [auto_handle] assumed 11
                    Operation f1 has no binding handle parameter; [auto_handle] assumed


Explanation for performing the full process

The single-line call invokes three tools, uuidgen, idlgen, and the IDL
compiler. uuidgen generates a skeleton IDL file including a UUID and pipes its
output to idlgen.  The -stdin switch 1 tells idlgen to read its first input
from the standard input, which is the uuidgen output.  idlgen recognizes this
first input as an IDL file 6, which it preprocesses 5, and then imports the
base IDL import, preprocessing it as well 7.  Last in is the C source file,
which idlgen preprocesses 8 and then displays the information message that it
recognizes the file as a C file 9. The IDL output goes to standard output 10,
and idlgen completes successfully.

The output is piped into the third tool, the idl compiler, which reads its
input from standard input 2 and generates the stubs for it, reporting that it
assumes auto_handles for both operations 11.


ΓòÉΓòÉΓòÉ 7. gluegen - Glue-Code Generator ΓòÉΓòÉΓòÉ

This chapter details the operation and use of the MakeDCE gluegen tool.

gluegen takes as input your application topology defined by a set of
parameters. gluegen uses a simple formal language to compound the parameters
and generate the appropriate glue-code. Parameters that are not specific to
gluegen are defined in the DCE documentation. Those specific to gluegen are
detailed here.

In the discussion that follows, the nature of the input to gluegen is discussed
as well as what happens to the input. A detailed presentation is given on the
gluegen command line and options, as well as the formal gluegen language -
Application Profile (APF) Language.


ΓòÉΓòÉΓòÉ 7.1. gluegen Profile Objects ΓòÉΓòÉΓòÉ

The DCE parameters used by gluegen are discussed before the gluegen language is
introduced. One set of parameters is used to define the Interface Profile. One
or more interface profiles, with additional parameters, are combined into a
single Application Profile.


ΓòÉΓòÉΓòÉ 7.1.1. Interface Profile ΓòÉΓòÉΓòÉ

The interface profile parameters affect the initialization process and the
binding method that an application node uses with respect to a given interface.
Client and Server nodes of a given interface may have different interface
profiles; however, proper binding of the two at runtime is guaranteed only by
using compatible or identical profiles.

The interface profile parameters fall into two categories: compile-time
parameters and runtime parameters. Values of compile-time parameters must be
specified by the interface profile itself. Values of runtime parameters can be
specified initially by the profile or later at runtime upon invocation of the
Client and Server applications.

The following list describes the interface profile parameters. The notation
parameter = value is used to describe a parameter and its possible values. The
names and terminology used here are taken as much as possible from the DCE
books (see Related Documents for a list).

o protseq = protcol-sequence
  A runtime parameter that defines a valid combination of communication
  protocols that may take one of the following string values: ncadg_ip_udp or
  ncaca_ip_tcp.

o host = host-addr
  A runtime parameter that identifies a specific host system that exports the
  interface services. The format of host-addr depends on the network protocol
  in protseq, for example, 129.35.65.233 for ncadg_ip_udp.

o ep = endpoint
  A runtime parameter that defines a communication endpoint for the specific
  server instance that exports the interface services. A unique endpoint is
  required for each protocol that a server uses, for example, 1027. If not
  specified, the endpoint is allocated dynamically by the system.

o eptype = endpoint-type
  A runtime parameter that controls endpoint allocation and may take one of two
  values:  shared or unique. A shared endpoint can be used by multiple
  interfaces; unique endpoint can be shared by none. By default, endpoint-type
  is shared.

o obj = object-id
  A runtime parameter that specifies a particular object universal unique
  identifier (UUID) to be used for binding the proper server. When the
  specified interface is associated with multiple server instances, the obj
  parameter can be used to refine the selection of the requested server
  instance, for example, 30DBEEA0-FB6C-11C9-8EEA-08002B0F4528.

o nse = name-service-entry
  A runtime parameter that specifies the path name of an entry stored in the
  Cell Directory Service database, which can be used to bind with proper
  server. The path of the named entry can be global CDS name, which contains
  the /... prefix, or relative CDS name, which contains the /.: prefix.  An
  example is /.:/hrg/server-1.

o bindtype = binding-method
  A compile-time parameter that defines the method for obtaining the binding
  information for the binding parameters previously described. The
  binding-method can be one of the following: string, lepm, repm, or ns.

  Note:  This parameter identifies the set of binding parameters (previously
  defined) that are used to bind that interface at runtime. The minimal
  required set of binding parameters is protseq, host, and ep. Other binding
  parameters like interface UUID and Version are determined automatically. The
  obj parameter is optional, and the nse parameter is required only when using
  the Name Service database.

   string    Denotes that the binding method used is full-string binding. The
             user should supply the binding parameters (possibly at runtime)
             and none is determined automatically. The minimal required binding
             parameters are protseq, host, and ep. In this binding type, the
             Client and the Server can run on different hosts. The Server
             requires only the protseq parameter and may need to output its
             dynamically allocated endpoint.  The output method to be used is
             defined in the application profile. See the following discussion.
             The Client requires all three binding parameters previously
             mentioned to accomplish full-string binding; some parameters can
             be specified by the interface profile and others at runtime.
   lepm      Denotes that the Server endpoint is allocated dynamically and
             should be resolved by clients using the local endpoint map
             maintained by the RPC daemon (rpcd). The obj parameter, if
             defined, is used for resolving the Server endpoint. In this
             binding type, the Client and the Server are assumed to run on the
             same host. The host parameter is determined automatically, and
             only the protseq parameter is required by both Client and Server.
             The Server job is to register its endpoint in the local endpoint
             map, and the Client has to resolve its partial server binding
             using the same endpoint map.
   repm      Denotes that the Server endpoint is allocated dynamically and
             should be resolved using a remote endpoint map. The obj parameter,
             if defined, is used to resolve the Server endpoint. In this
             binding type, the Client and the Server can run on different
             hosts. Only the protseq and host parameter are required. The
             Server job is to register its dynamically allocated endpoint in
             its local endpoint map, and the Client has to query the remote
             endpoint map, using the host parameter, to obtain the Server
             endpoint.
   ns        Denotes that the binding parameters protseq, host, and ep are
             resolved automatically using the Name Service database. The nse
             parameter must be specified and, together with the obj parameter,
             is used to resolve the binding information stored in the name
             service database. In this binding type, the Client and the Server
             can run on different hosts, and the cdsclerk programs on both
             hosts should be running.  Using the nse parameter, the Server has
             to export its binding information into the name service database
             and the Client has to import that information from the database.

o handle = handle-type
  A compile-time parameter that defines the type of handle to be used by the
  interface. Handle type can be implicit, explicit, or auto (see the OSF DCE
  Application Development Guide).

   - The implicit handle type informs DCE that binding to the Server is managed
     by the application using a global variable. The presence of a binding
     handle parameter in the interface operations is not required.

   - The explicit handle type informs DCE that binding to the Server is managed
     by the application and that a binding handle parameter is included in each
     interface operation.

   - The auto handle type informs DCE to automatically manage the binding to
     the Server by using a name service. The presence of a binding handle
     parameter in the interface operations is not required.

o idl = idl-file
  A compile-time parameter that specifies the name of the IDL file describing
  the services provided by the interface. The relevant information is stored in
  the IDL file header and includes:

   version, idl version  Major and minor version numbers are needed for
                         internally identifying implicit handles.
   interface name        This name is also used to construct the internal name
                         identifying implicit interface handles.

Interface Profile Example

Consider the distributed application graph in Distributed Application Graph.
Notice that interface I1 is exported only by node D. To model dynamic endpoint
allocation and binding for I1, the following interface profile can be used.

         interface profile for I{1}

          protseq  = ncadg_ip_udp
          host     = nodeD
          bindtype = repm
          handle   = explicit
          idl      = "I1.idl"

Note:  This is not a file.  The organization of such information in an
       interface object is done formally using information found in Application
       Profile Specification Language.


ΓòÉΓòÉΓòÉ 7.1.2. Application Profile ΓòÉΓòÉΓòÉ

gluegen configures DCE applications using application profiles. To form an
application profile, one or more interface profiles are combined with
additional global parameters, possibly overwriting some interface profile
parameters.

As in the preceding description of the interface profile, the notation
parameter = value is used to denote a parameter and its possible values. Note
that this is not the actual syntax used by gluegen to define application
profiles. To formally define the interface and application profiles, use the
Application Profile Language discussed in Application Profile Specification
Language.

o nthreads = n
  Specifies the maximum number of service threads to be used by a Server
  application. This number can be smaller, or higher, than the number of
  interfaces exported by the application. By default, n is 1, which means that
  service requests are processed serially.

o finput = input-file
  Names an input file for obtaining values of interface profile parameters at
  runtime. Examples of interface runtime parameters are protseq, host, ep, and
  so on. The input file is read as part of the Client/Server initialization
  process and prior to any binding attempt of importing interfaces. Parameter
  values retrieved from the input file can be overwritten by command line
  arguments.

  The input-file assumes the following values:

   stdin         Denotes that parameter values are read from standard input.
   null          Denotes that finput is to be ignored (default).
   file-name     Denotes that parameter values are read from file file-name.
   "file-name"   Denotes that runtime parameters are read from file file-name;
                 for instance, "stdin" is taken as a file named stdin rather
                 than the standard input.

o foutput = output-file
  A runtime parameter that names a file for writing values of binding
  parameters, such as those obtained during runtime by a Server exporting an
  interface. The output file is generated as part of the Client/Server
  initialization process, after all binding operations of imported and exported
  interfaces have been completed. The file is written using a compatible format
  for the finput parameter and can serve as an input file on the Client side.

  The output-file can assume the following values:

   stdout        Denotes that parameter values are written to the standard
                 output (default).
   stderr        Denotes that parameter values are written to the standard
                 error file.
   null          Denote that foutput is to be ignored.
   file-name     Denotes that parameter values are written to the file
                 file-name.
   "file-name"   Denotes that runtime parameters will be written to the file
                 file-name; for instance, stdout is taken as a file named
                 stdout rather than the standard output.

o import = interface-profile

o export = interface-profile
  Associates an interface profile with the specified application, having an
  import, or export roles, respectively. The profile describes the
  initialization process and binding method to be used by the application, with
  respect to the specified interface.

The interface parameters can have multiple occurrences, each associating the
application with a different interface.


ΓòÉΓòÉΓòÉ 7.1.2.1. Parsing Command Arguments - Example ΓòÉΓòÉΓòÉ

Applications generated by gluegen parse their command arguments at runtime,
assuming that the values of the interface profile parameters are specified as
pairs:

          -interface.parm value
For example an application named client that imports interface I1 can be
invoked by the following:

         client -I1.protseq ncadg_ip_udp -I1.host 129.35.65.223
If the interface part of the parameter specifications is omitted, for example

         client -protseq ncadg_ip_udp -host 129.35.65.223
the value for these parameters is taken as default for all interfaces.

The same holds for application profile parameters.  For example, redirection of
input and output files for binding parameters can be done at runtime as
follows:

         server  -foutput binding_file
         client  -finput  binding_file


ΓòÉΓòÉΓòÉ 7.1.3. Application Profile Specification Language ΓòÉΓòÉΓòÉ

Formal specification of application profiles is facilitated by means of an
Application Profile Language (APF Language). Complete syntax of the language is
provided in APF Language Grammar. An informal description of the language is
given here by means of some application profile examples.

An application profile generally contains two types of statements. An interface
statement defines an interface profile, and an application statement defines a
collection of interfaces together with additional global parameters.

For example, look at the distributed application graph in Distributed
Application Graph. Application node A imports interface I1 and exports
interfaces I2 and I3.  The definition of application node A using the APF
Language would look like the following (keywords are in bold letters):

      /* Application Profile for Node A */

      interface I1 {
           protseq = ncadg_ip_udp;
           host = nodeD;
           bindtype = repm;
           handle = explicit;
           idl = "I1.idl";
        }

     interface I2 {
          protseq = ncadg_ip_udp;
          bindtype = lepm;
          handle = explicit;
          idl = "I2.idl";
     }

     interface I3 {
          protseq = ncadg_ip_udp;
          bindtype = lepm;
          handle = explicit;
          idl = "I3.idl";
     }

     applicationappA {.
         finput = null;
         foutput = stdout;
         nthreads = 1;
         import I1;
         export I2;
         export I3;
     }
The preceding application profile defines an application named appA. The
(interface) binding parameters for appA, some provided with command arguments
and some resolved at runtime, are written to the standard output. No binding
information is read from the input file.


ΓòÉΓòÉΓòÉ 7.1.3.1. Application Profile using Preprocessor Directives ΓòÉΓòÉΓòÉ

You can gain more flexibility by separating the definition of interfaces from
the definition of applications. To this end, the Application Profile Language
can contain include and define statements, which have the same meaning as for
the C language macro-processor.

For example, let the interface statements for I1, I2, and I3 of appA be stored
in files I1.ipf, I2.ipf, and I3.ipf, respectively. An equivalent application
profile for appA looks like the following:

      /* Application Profile for Node A  using
      ** interface profiles: I1.ipf, I2.ipf and I3.ipf
      */
      #include "I1.ipf"
      #include "I2.ipf"
      #include "I3.ipf"

      applicationappA {.
         finput = null;
         foutput = stdout;
         import I1;
         export I2;
         export I3;
     }


ΓòÉΓòÉΓòÉ 7.1.3.2. Application Profile using the Like Statement ΓòÉΓòÉΓòÉ

Similar interface profiles can be defined using the like statement. For
example, the definition of interface I3, above, can be based on I2 as follows:

      /* Application Profile for Node A  using
      ** I1.ipf, I2.ipf and the LIKE statement
      */
      #include "I1.ipf"
      #include "I2.ipf"

      interface I3 like I2 { idl = "I3.idl" }

      applicationappA {.
         finput = null;
         foutput = stdout;
         import I1;
         export I2;
         export I3;
     }


ΓòÉΓòÉΓòÉ 7.1.3.3. Application Profile for Simple Client and Server ΓòÉΓòÉΓòÉ

Consider the case of Client and Server applications running on the same host,
where the Server exports interface I1 and the Client imports that interface.
The application profile for the two applications might look like the following:

      /* Application Profile for Simple Client and Server
      ** running on the same host
      */
     interface I1 {
          protseq = ncadg_ip_udp;
          bindtype = lepm;
          handle = implicit;
          idl = "I1.idl";
     }

     application Server {.
         foutput = stdout;
         export I1
     }

     application Client {.
         foutput = stdout;
         import I1
     }


ΓòÉΓòÉΓòÉ 7.2. Glue-Code Generation ΓòÉΓòÉΓòÉ

The MakeDCE gluegen tool generates application glue-code. It is convenient to
view the gluegen tool as being parallel to the DCE/RPC idl compiler (see
Client/Server component overview in MakeDCE environment).

Code generaged by gluegen has three components:

glue-code                Generated by gluegen from information in the APF file
                        and consisting of the main() entry points to the Client
                        or Server applications. These are simple programs that
                        make very few calls to routines in glue runtime library
                        (see The Glue APIs).
glue-stub                Generated by gluegen from information in the APF file,
                        building internal structures where all the information
                        is stored and where references are defined for global
                        variables declared in the DCE stubs generated by the
                        idl compiler. This portion can be viewed as parallel to
                        the RPC stubs generated by the idl compiler.

                        Note:  gluegen generates a single glue-stub for each
                               application, whereas idl generates multiple DCE
                               stubs - one for each interface in the
                               application. Also, as side effect of glue-stub
                               generation, gluegen creates an ACF file for each
                               interface that uses an implicit handle.


glue runtime library    Supports the glue-code and glue-stubs generated by
                        gluegen. It has a role similar to the DCE runtime
                        library, which supports the RPC stubs generated by the
                        idl compiler. The glue runtime library also uses the
                        DCE runtime library.


ΓòÉΓòÉΓòÉ 7.3. The gluegen Command ΓòÉΓòÉΓòÉ

This section discusses the gluegen command line syntax.  The general format of
the command follows:


gluegen app_profile app_name
  [-help] [-no_main] [-fmain func_name] [-Idir]
  [-cpp_cmd cpp] [-cpp_opt cppOpt] [-no_cpp]
  [-cc_cmd cc] [-cc_opt ccOpt] [-Dname] [-Uname]
  [ -keep {c_source | object | both} ] [-v]

The gluegen command invokes the glue-code generator to convert an application
named app_name and specified by means of the application profile app_profile
(.apf file) into a DCE program. The output files produced by gluegen include a
glue-stub file, ACF file (.acf) for each interface imported or exported by
app_name (when implicit handles are used), and a main program.

The glue-code generator constructs the name of the glue-stub by appending the
extension _gstub to app_name. For example, if an application is named client,
the corresponding glue-stub object file is named client_gstub.o.


The gluegen command accepts the following input:

o An application profile (.apf file).

o The name of an application defined in the application profile.

o Arguments to indicate either special action to be performed by the glue-code
  generator or special properties for the input or output files.

Programs that make use of the glue-stubs generated by gluegen should be linked
with two libraries.

o For AIX, the glue library libglue.a and the DCE library libdce.a.

o For OS/2, the glue library glue.lib and the DCE library dceos2.lib.


ΓòÉΓòÉΓòÉ 7.3.1. gluegen Options ΓòÉΓòÉΓòÉ

The following options are available for controlling gluegen operations. You can
include a number of options on the same line.  The order is not important.
However, they are case-sensitive. When the same option is specified multiple
times, the last one is taken.

-no_main
          This option suppresses the generation of the application main module.
          When this option is specified, gluegen generates only the
          application's glue-stub.

-fmain func_name
          gluegen uses func_name as the name of the function to be called by a
          Client application after all initialization process and binding
          operations have been completed. This function should represent the
          actual activity of the Client application, usually in the form of
          main() for non-DCE applications. If this option is not specified,
          gluegen assumes a default function named fmain.


          func_name (as well as the default function fmain) should have the
          following prototype:


                    void func_name(int argc, char **argv, char **env);

-Idir
          Use this option to specify a directory path for include files. You
          can specify more than one path by including additional -Idir
          arguments on the command line. The directories are searched in the
          order you list them. If a file is present in more than one directory,
          the first occurrence of the file is taken. The default behavior of
          gluegen is to search the current directory first and then to search
          all specified directories.

-cpp_cmd 'cpp-command'
          Invokes the C preprocessor you specify in 'cpp-command' rather than
          the default. The preprocessor command you specify should direct its
          output to the standard output.

-cpp_opt 'cpp-options'
          Specifies additional options to be passed to the C preprocessor. You
          can add options to the command line used to invoke the C preprocessor
          independent of the -cpp_cmd option. gluegen concatenates the
          -cpp_cmd, -cpp_opt, -D, -U, and -I arguments and the APF file name
          into a command that calls the C preprocessor.

-no_cpp
          Prevents calling the C preprocessor. Note that the C processor must
          be run on .apf files that contain preprocessor directives (such as
          #define or #include).

-cc_cmd 'cc-command'
          Invokes the C compiler and the compiler options you specify in
          'cc-command' rather than the default.

-cc_opt 'cc-options'
          Specifies additional options to be passed to the C compiler. You can
          add options to the command line used to call the C compiler
          independent of the -cc_cmd option. gluegen concatenates the -cc_cmd,
          -cc_opt, and -I arguments and the source filename into a command that
          calls the C compiler.

-Dname[=definition]
          Use this option to define a symbol name and an optional value to be
          passed to the C preprocessor. You can use this method for defining
          symbols instead of the #define directive in the source code. You can
          use more than one -Dname argument on the command line. This argument
          has no effect if the -no_cpp option is in use.

-Uname
          This is the reverse of the -D option; it undefines a symbol name for
          the C preprocessor. You can use this method for removing symbol
          definitions instead of using the #undef directive in the source code.
          You can use more than one -Uname argument on the command line. This
          argument has no effect if the -no_cpp option is in use. If you define
          and undefine a name on the same command line, undefining takes
          precedence.

-keep file_types
          This option tells gluegen the file types to retain. To produce object
          modules, gluegen first creates C source modules, then calls the C
          compiler to produce object modules, and finally deletes the C source
          modules. If the keep argument is not used, only the object modules
          are saved.


          The file_type values are the following:

   c_source  Saves only the C source modules. Does not invoke the C compiler.
   object    Saves only the object modules.
   both      Saves both the C source and the object modules.


ΓòÉΓòÉΓòÉ 7.3.2. Getting Help in gluegen ΓòÉΓòÉΓòÉ


gluegen provides you with two aids:

-help     If you invoke gluegen with just this option, you get a display with
          short descriptions of the command line options and arguments.
-v        Similar to the IDL compiler, gluegen runs silently. If you want
          informational messages to display while gluegen is running, include
          -v in the command line. -v turns on the verbose mode.


ΓòÉΓòÉΓòÉ 7.3.3. Cautions ΓòÉΓòÉΓòÉ

When using implicit handles, gluegen generates an ACF file (.acf) for each
imported or exported interface. This ACF file corresponds to the IDL file for
the given interface (see the following example). To generate proper DCE stubs,
you have to run gluegen prior to invoking the IDL compiler.


ΓòÉΓòÉΓòÉ 7.3.4. Example ΓòÉΓòÉΓòÉ

This example assumes that the application profile binop.apf contains the
following client and server profiles:


    /*  binop.apf : application profile defining
    **    client and server applications for the "binop" interface
    */
    interface binop_if {
        protseq = ncadg_ip_udp;
        bindtype = lepm;
        handle = implicit;
        idl= "binop.idl";
    }

    application server { export binop_if }
    application client { import binop_if }

Type the following to invoke the glue-code generator in order to generate DCE
application programs and glue-stubs for the client and server applications and
keep the generated C source modules:

    gluegen binop.apf client -v -keep c_source -no_cpp
    gluegen binop.apf server -v -keep c_source -no_cpp

The generated application programs are client.c and server.c. The generated
glue-stubs are client_gstub.c and server_gstub.c. The client (server)
application imports (exports) an interface that uses an implicit handle.
gluegen also generates an ACF file, binop.acf (for binop.idl).


ΓòÉΓòÉΓòÉ 7.4. Glue Run-Time Library ΓòÉΓòÉΓòÉ

The Glue runtime library provides a set of APIs that support DCE programs based
on gluegen generated glue-stubs. This section presents the Glue APIs and
demonstrates the relationships between the Glue and DCE components that make up
a DCE application.

In addition to the APIs described in this section, the Glue library contains
some internal functions that are beyond the scope of this book and are not
documented here.


ΓòÉΓòÉΓòÉ 7.4.1. The Glue APIs ΓòÉΓòÉΓòÉ

The Glue APIs are functions of the form IFxxxxx(), which make use of data
structures defined in the header file <glue.h>. Most of the APIs use the
following data types:

mk_if_handle_t   Handle to interface structure containing the interface profile
                together with public methods for executing DCE operations
mk_app_profile_t  Handle to application profile, which is a data structure
                containing internal representation of an application profile
                defined in an APF file.
The APIs are divided into three groups:

o Application APIs
o Binding APIs
o Glue-stub API

  The glue-stub API is generated automatically by gluegen into the glue-code
  and is not part of the Glue library.

A description of each API follows.

o Application APIs

    void IFClient( mk_app_profile_t app,
            VoidFunc fmain,
            int *argc,
            char **argc,
            char **env  )

      The IFClient function implements an M-Client application model that
      imports multiple interfaces. The function processes the application
      profile, app, resolves the unspecified binding parameters, does all
      required binding operations, and calls the fmain routine. The function
      uses static binding and exits if an attempted binding to one of its
      servers fails.

      Return Value - None.

      void IFServer( mk_app_profile_t app,
              VoidFunc fmain,
              int *argc,
              char **argc,
              char **env )

      The IFServer function implements an M-Server application model that
      exports multiple interfaces. The function processes the application
      profile, app, and calls the fmain routine as part of its initialization.
      After the initialization is completed, the function performs the required
      operations to register and export its interfaces and listens for incoming
      requests.

      Return Value - None.

      void IFChainingServer( mk_app_profile_t app,
                  VoidFunc fmain,
                  int *argc,
                  char **argc,
                  char **env )

      The IFChainingServer function implements an M-Client-Server application
      model that imports and exports multiple interfaces. The function
      processes the application profile, app, and calls the fmain routine as
      part of its initialization. After the initialization is completed, the
      function performs the required operations to import and export its
      interfaces and listens for incoming requests.

      A ChainingServer application exports operations that may call (be clients
      of) operations exported by other servers. For instance, the application
      exports the function F():

            F() {
               ...
               g();
               ...
            }
      where g() is exported by another server.

      Return Value - None.

o Binding APIs

   - mk_if_handle_t IFHandleI( int I )

      Gets the MakeDCE interface handle number I of the current application.
      Interface handle numbers range from 0 to n.

      Return Value - Interface handle on success; NULL otherwise.

   - mk_if_handle_t IFHandleIN( char *Name )

      Gets the MakeDCE interface handle for an interface named 'Name' of the
      current application. Interface names are defined in the interface
      statements of the underlying APF file.

      Return Value - Interface handle on success; NULL otherwise.

   - rpc_binding_handle_t IFBindingHandle( mk_if_handle_t ifh )

      Gets the DCE binding handle stored by MakeDCE interface ifh.

      Return Value - DCE binding handle on success; NULL otherwise.

o Glue-stub API

   - mk_app_profile_t glue_app_profile( void )

      Returns the internal representation of an application profile. This
      function is generated by gluegen for a particular application defined in
      a given APF file. This function forms the major portion of the glue-stub
      for that application.

      Return Value - Application profile handle.


ΓòÉΓòÉΓòÉ 7.4.2. Using Explicit Handles ΓòÉΓòÉΓòÉ

When using explicit handles, you can reference in the binding handle associated
with each interface in your application. This is facilitated by two functions:
IFHandleI()and IFBindingHandle(). For example, the function handle returns the
binding handle of interface number i.

     #include <glue.h>

     rpc_binding_handle_t handle(int i)
     {
         return ( IFBindingHandle(IFHandleI(i)) );
     }


ΓòÉΓòÉΓòÉ 7.4.3. Putting It All Together ΓòÉΓòÉΓòÉ

To demonstrate the relationships and sources of the components that make up a
DCE application, the following figure: Splitting a stand-alone application into
Client and Server roles shows a stand-alone application being split into two
programs serving in the roles of a Client and a Server.


ΓòÉΓòÉΓòÉ 7.5. MakeDCE Application Development Steps ΓòÉΓòÉΓòÉ

The following section describes the MakeDCE application development steps.
Step-by-step instructions are shown for converting a simple application (the
binop program) into a DCE Client/Server application. The IDL file generated by
idlgen is discussed, as well as the glue-code and the glue-stubs generated by
gluegen.


ΓòÉΓòÉΓòÉ 7.5.1. The binop program ΓòÉΓòÉΓòÉ

     Program files:
         main.c  - main module of the binop program which calls the
                   binop_add() function.
         binop.c - module containing the binop_add() function.


     Objective:
         Create a DCE application in which the Client side is based
         on main.c and the Server side is based on binop.c


     binop.c file:

     /*
     **   binop program functions
     */
     void binop_add(a, b, c)
     long a, b, *c;
     {
         *c = a + b;
     }

     main.c file:

     /*
     **   binop program main() entry point
     */
     #include <stdio.h>

     main(int argc, char *argv[], char *envp[])
     {
         char *msg = "Binop Application Completed";
         int i, n, pass, failures=0, PASSES=10, CALLS=10;

         for (pass = 1; pass <= PASSES; pass++) {
            printf("PASS (%d):", pass);
            for (i = 1; i <= CALLS; i++) {
              binop_add(i, i, &.n);
               if (n != i+i) {
                  printf("Two times %ld is NOT %ld\n", i, n);
                  failures++;
               }
               printf(".");
            }
            printf("\n");
         }

         printf("%s: %d calls, %d failures\n", msg, PASSES*CALLS, failures);
     }


ΓòÉΓòÉΓòÉ 7.5.2. Step 1: Generate IDL file for the Server side using idlgen ΓòÉΓòÉΓòÉ

The first step is to generate the IDL file, binop.idl, describing the Server
functions defined in binop.c. This can be done using uuidgen and idlgen, as
shown in the following example.

User
                    uuidgen -i | idlgen -stdin binop.c -ibd -interface binop > binop.idl

System
                    ...

User
                    type binop.idl

System

                         [
                         uuid(0096BF68-065E-1BE6-B951-10005AA8B716),1
                         version(1.0)
                         ] interface binop {

                         ...
                         /*@[export] binop_add;      file binop.c */

                         void
                         binop_add (
                            [  in] long a,
                            [  in] long b,
                            [  in, out, ref] long *c
                         );

                         }

The -stdin flag tells idlgen to treat the data streaming from the pipe as an
input file. Placing this flag before binop.c on the command line causes idlgen
to process the IDL skeleton generated by uuidgen before binop.c. (See file-name
and -stdin and Order of Input Files). Note that uuidgen creates a new UUID 1 on
each invocation.


ΓòÉΓòÉΓòÉ 7.5.3. Step 2: Create an APF file (.apf) for the Client and Server sides ΓòÉΓòÉΓòÉ

The second step is to write an application profile, binop.apf, describing to
gluegen the Client and Server sides of the distributed application. The
contents of binop.apf could resemble the following example.


    binop.apf file:

    /*  binop.apf : application profile defining
    **    client and server applications for the "binop" program
    */
    interface I1 {
        protseq = ncadg_ip_udp;
        bindtype = lepm;
        handle = implicit;
        idl= "binop.idl";
    }

    application server { export I1 }
    application client { import I1 }


ΓòÉΓòÉΓòÉ 7.5.4. Step 3: Generate Glue-code and Glue-stubs using gluegen ΓòÉΓòÉΓòÉ

Invoke gluegen to generate glue-code (DCE application programs) and glue-stubs
for the client and server applications defined in binop.apf. To generate the C
source modules only, type the following:


     gluegen binop.apf client -v -keep c_source -no_cpp
     gluegen binop.apf server -v -keep c_source -no_cpp


The first gluegen command generates the client glue-code and glue-stub,
client.c and client_gstub.c respectively. Because the Client application
imports an interface that uses an implicit handle, gluegen also generates an
ACF file binop.acf (for binop.idl). The second gluegen command generates the
server glue-code and glue-stub, server.c and server_gstub.c respectively.


ΓòÉΓòÉΓòÉ 7.5.5. Step 4: Generate DCE stubs using the IDL compiler ΓòÉΓòÉΓòÉ

Call the IDL compiler to generate DCE stubs for the Client and Server side of
the distributed application, using the IDL file binop.idl generated in Step 1.
To generate only the C source modules, type the following:


     idl binop.idl -v -keep c_source -no_cpp -server none
     idl binop.idl -v -keep c_source -no_cpp -client none


The first line generates the client DCE stub binop_cstub.c; the second line
generates the server DCE stub binop_sstub.c.


ΓòÉΓòÉΓòÉ 7.5.6. Step 5: Convert your main program into a function. ΓòÉΓòÉΓòÉ

The module client.c contains the new main() entry point for the Client side of
the distributed application. Unless specified otherwise (see the -fmain option
of gluegen), the old main() entry point in main.c is treated now as a function
named fmain()  (see also Client Program Using Glue APIs). Therefore, you can
edit the C module main.c and convert the string main into fmain. Write the
edited file into a new file named fmain.c.


ΓòÉΓòÉΓòÉ 7.5.7. Step 6: Compile and link the Client Side ΓòÉΓòÉΓòÉ

This step compiles and links the Client side of the distributed application.
The Client source files are:

    client.c       - main program generated by gluegen (Step 3)
    client_gstub.c - glue-stub generated by gluegen (Step 3)
    binop_cstub.c  - DCE stub generated by IDL  (Step 4)
    fmain.c        - fmain() generated manually (Step 5)

    In AIX compile and link as follows:

    cc_r client.c fmain.c client_gstub.c binop_cstub.c -ldce -lglue -o client

    The comparable in OS/2 is more complicated. See in the MakeDCE
    example directory:  %MAKEDCE%\EXAMPLES\RULES.MAK


ΓòÉΓòÉΓòÉ 7.5.8. Step 7: Compile and link the Server Side ΓòÉΓòÉΓòÉ

This step compiles and links the Server side of the distributed application.
The Server source files follow:

    server.c       - main program generated by gluegen (Step 3)
    server_gstub.c - glue-stub generated by gluegen (Step 3)
    binop_sstub.c  - DCE stub generated by IDL  (Step 4)
    binop.c        - Manager function for binop.idl

    In AIX, type the following:

    cc_r server.c server_gstub.c binop_sstub.c binop.c -ldce -lglue -o server

    The comparable in OS/2 is more complicated. See in the MakeDCE
    example directory:  %MAKEDCE%\EXAMPLES\RULES.MAK


ΓòÉΓòÉΓòÉ 7.5.9. Step 8: Execute the distributed application ΓòÉΓòÉΓòÉ

To run the distributed application, call the server process in one window and
the client process in another window. The binding method used in binop.apf is
lepm (see page Interface Profile for details.  Therefore, the RPC daemon
process, rpcd, must be running prior to invoking the server.  Correct client
output will resemble the following:

User
                    client

System

                    -protseq ncadg_ip_udp -host host-name -ep
                    ep-number

                    PASS(1):..........
                    PASS(2):..........
                    PASS(3):..........
                    PASS(4):..........
                    PASS(5):..........
                    PASS(6):..........
                    PASS(7):..........
                    PASS(8):..........
                    PASS(9):..........
                    PASS(10):..........
                    Binop Application Completed: 100 calls, 0 failures


In the preceding example, host-name is your host name and ep-number is the
entry point number allocated to the server by rpcd.


ΓòÉΓòÉΓòÉ 7.5.10. Examples of Code Generated by gluegen ΓòÉΓòÉΓòÉ

The following examples show the glue-code and the glue-stubs generated by
gluegen for the distributed binop application.


ΓòÉΓòÉΓòÉ 7.5.10.1. Client Program Using Glue APIs ΓòÉΓòÉΓòÉ

Using the glue-stubs generated by gluegen and the Glue library APIs, a Client
program, client.c, that imports multiple interfaces could resemble the
following example.

    client.c file:

    /******************************************************************
    * This file was generated by the MakeDCE GLUEGEN facility         *
    *       - A DCE Application Development Tool                      *
    *                                                                 *
    * Generated on Sun Jun 27 12:01:16 1993                           *
    *                                                                 *
    * (c) Copyright IBM Corporation  1992, 1993                       *
    *******************************************************************/

    #include <makedce/glue.h>

    #ifdef IBMOS2
    #pragma handler (main)
    #endif

    void fmain(int argc, char **argv, char **env);

    main(int argc, char **argv, char **env)
    {
       IFClient(glue_app_profile(), fmain, &.argc, argv, env);
    }
 Unless specified otherwise (see the -fmain option of gluegen), the fmain()
function now represents the old main entry point of the non-distributed
application.  The fmain() function should be prototyped as follows:

      /*
      ** fmain() - model of non DCE application
      */

      void fmain (int argc, char **argv, char **env)
      {
           .
           .
           call server_functions();
           .
           .
      }


ΓòÉΓòÉΓòÉ 7.5.10.2. Server Program Using Glue APIs ΓòÉΓòÉΓòÉ

Using the glue-stubs generated by gluegen and the Glue library APIs, a Server
program, server.c, that exports multiple interfaces should resemble the
following example.

    server.c file:

    /******************************************************************
    * This file was generated by the MakeDCE GLUEGEN facility         *
    *       - A DCE Application Development Tool                      *
    *                                                                 *
    * Generated on Sun Jun 27 12:04:15 1993                           *
    *                                                                 *
    * (c) Copyright IBM Corporation  1992, 1993                       *
    *******************************************************************/

    #include <makedce/glue.h>

    #ifdef IBMOS2
    #pragma handler (main)
    #endif


    main(int argc, char **argv, char **env)
    {
       IFServer(glue_app_profile(), NULL, &.argc, argv, env);
    }


ΓòÉΓòÉΓòÉ 7.5.10.3. Glue-stub for a Simple Server Program ΓòÉΓòÉΓòÉ

The following glue-stub, server_gstub.c, is generated for the Server
application defined in binop.apf  (see Step 2: Create an APF file (.apf) for
the Client and Server sides). The IDL file, binop.idl, describing the Server
operations, is shown in Step 1: Generate IDL file for the Server side using
idlgen.

#include <makedce/glue.h>

extern rpc_if_handle_t      glue_server_ifspec(binop,1,0);

static struct IFProfileRec I1 = {
  1"I1"                /* name */
  2"export",           /* role */
  3"binop.idl",        /* idl file */
  4"implicit",         /* handle   */
  5"lepm",             /* bindtype */
  6"ncadg_ip_udp",     /* protseq */
  7NULL,               /* host */
   NULL,                 /* endpoint */
   "shared",             /* eptype */
   NULL,                 /* obj */
   NULL,                 /* nse */
  8&.glue_server_ifspec(binop,1,0),   /* ifspec  address */
   NULL,/* handle address */
   NULL
};


static mk_if_profile_t if_profile_vector[] = {
  9&.I1,
   NULL
};

static struct APProfileRec Server = {
  10"server",              /* appname */
  111,                     /* nthreads */
  12"null",                /* finput */
  13"stdout",              /* foutput */
  141,                     /* ifcount */
  15if_profile_vector      /* if_profile_vector */
};

mk_app_profile_t 16 glue_app_profile(void) {
   return (&.Server);
};


Explanation :

The symbolic name of the interface 1 is used to reference information
associated with an interface object; for instance, in getting runtime
parameters as shown in Parsing Command Arguments - Example. The interface
object defined here, I1, is exported 2, uses implicit handles 4, binds using a
local entry-point mapper 5, uses the ncadg_ip_udp protocol sequence 6, and
refers to the IDL defined in binop.idl 3. The parameters host, endpoint, obj,
and nse are not needed at compile time 7. The internal reference to the
implicit handle is constructed from information in the IDL file through a macro
constructor 8, which combines the interface name binop and version numbers 1.0
from the IDL file binop.idl.

The set of (single) interface objects is stored in a list of such objects 9,
and the list, along with other application-level parameters, is stored in an
application object 10 through 15.

The function glue_app_profile 16 returns a pointer to the application profile
and serves as initialization entry point to the server glue-code (see Server
Program Using Glue APIs).


ΓòÉΓòÉΓòÉ 7.5.10.4. Glue-stub for a Simple Client Program ΓòÉΓòÉΓòÉ

The following glue-stub, client_gstub.c, is generated for the Client
application defined in binop.apf  (see Step 2: Create an APF file (.apf) for
the Client and Server sides). The IDL file binop.idl describing the Server
operations is shown in Step 1: Generate IDL file for the Server side using
idlgen.

#include <makedce/glue.h>

extern rpc_if_handle_t         glue_client_ifspec(binop,1,0);
extern rpc_binding_handle_t 1 glue_implicit_handle(binop,1,0);

static struct IFProfileRec I1 = {
   "I1",                    /* name */
2"import",                /* role */
   "binop.idl",             /* idl file */
   "implicit",              /* handle   */
   "lepm",                  /* bindtype */
   "ncadg_ip_udp",          /* protseq */
   NULL,                    /* host */
   NULL,                    /* endpoint */
   "shared",                /* eptype */
   NULL,                    /* obj */
   NULL,                    /* nse */
   &.glue_client_ifspec(binop,1,0),    /* ifspec  address */
3&.glue_implicit_handle(binop,1,0),  /* handle address */
   NULL
};

static mk_if_profile_t if_profile_vector[] = {
   &.I1,
   NULL
};

static struct APProfileRec client = {
4"client",                  /* appname */
   1,                         /* nthreads */
   "null",                    /* finput */
   "stdout",                  /* foutput */
   1,                         /* ifcount */
   if_profile_vector          /* if_profile_vector */
};

mk_app_profile_t 5 glue_app_profile(void) {
   return (&.Client);
};


Explanation :

This stub differs a little from the Server stub previously shown. A reference
to an RPC binding handle, whose name is derived from the IDL file header 1, is
also imbedded in the interface profile 3. The interface role is import 2. The
application name is "client" 4. The initialization entry point to the glue-code
is glue_app_profile (see Client Program Using Glue APIs).


ΓòÉΓòÉΓòÉ 7.6. APF Language Grammar ΓòÉΓòÉΓòÉ

o Application profile can include C preprocessor directives.

o Application Profile can include C comment statements.
Annotations:

<id>      id is a meta symbol in the grammar.
::=       The right-hand side is a definition of the left-hand side.
|         A vertical bar separates alternatives of a possible right-hand side.
[ opt ]   opt is an optional component of the right-hand side.
...       An ellipsis shows that previous entities can be repeated as a list
          with a possibly optional separator symbol.

All other symbols and letters are part of the language, except for the free
English description of the right-hand side, such as for <idl-filename> and so
on.



      <apf>         ::= <interface> | <application> |
                        <interface> <apf> |  <application> <apf>

      <interface>   ::= interface <id> [ like] <id> {
                          <i-attribute> [ ; ] ...
                        }

      <application> ::= application <id> {
                          <a-attribute> [ ; ] ...
                        }

      <i-attribute> ::= protseq  = <protseq-val> |
                        bindtype = <bind-type> |
                        handle   = <handle-val> |
                        host     = <host-id> |
                        ep       = <integer>  |
                        eptype   = <ep-type> |
                        idl      = "<idl-filename>" |
                        obj      = <obj-uuid> |
                        nse      = <string>


      <a-attribute> ::= finput   = <finput-id> |
                        foutput  = <foutput-id>  |
                        nthreads = <integer> |
                        import <id> [ { <i-attribute> [ ; ] ... } ] |
                        export <id> [ { <i-attribute> [ ; ] ... } ]


      <protseq-val> ::= ncadg_ip_udp | ncaca_ip_tcp
      <handle-val>  ::= implicit | explicit | auto
      <bind-type>   ::= string | lepm | repm | ns
      <host-id>     ::= <id> | <ip_address> | <string>
      <ip-address>  ::= <integer>.<integer>.<integer>.<integer>
      <finput-id>   ::= null | stdin  | <id> | "<id>"
      <foutput-id>  ::= null | stdout | stderr | <id> | "<id>"
      <ep-type>     ::= shared | unique
      <idl-filename>::= legal IDL file name
      <id>          ::= legal C identifier
      <obj-uuid>    ::= DCE uuid value
      <integer>     ::= <digit>...
      <string>      ::= "<letter>... "
      <digit>       ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
      <letter>      ::= any printable character

 A syntax chart for this grammar follows.

  ZDDD APF LANGUAGE DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
  3                                        3
  3   ZDDDDDDDDDDDDDDDDDDD?                           3
  3             3                           3
  3 >>DDDBD4 Interface CDDDBADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD>< 3
  3    @D4 Application CDY                           3
  3                                        3
  3 INTERFACE:                                  3
  3                   ZD;DDDDDDDDDDDDDDD?            3
  3                            3            3
  3 CDDinterfaceDDidDDBDDDDDDDDDDBDD{DDDD4 I Attribute CDADD}DDDDDDDDDDDDDDDDDD4 3
  3          @DlikeDDidDY                        3
  3                                        3
  3 APPLICATION:                                 3
  3             ZD;DDDDDDDDDDDDDDD?                  3
  3                      3                  3
  3 CDDapplicationDDidDD{DDDD4 A Attribute CDADD}DDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4 3
  3                                        3
  3 I ATTRIBUTE:                                 3
  3 CDDBDprotseqDD=DDBDncadg_ip_udpDBDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4 3
  3   3       @Dncaca_ip_tcpDY 3                      3
  3   CDbindtypeDD=DDBDstringDBDDDDDD4                      3
  3   3        CDlepmDDD4    3                      3
  3   3        CDrepmDDD4    3                      3
  3   3        @DnsDDDDDY    3                      3
  3   CDhandleDD=DDBDimplicitDBDDDDDD4                      3
  3   3       CDexplicitD4    3                      3
  3   3       @DautoDDDDDY    3                      3
  3   CDhostDD=DDBDidDDDDDDDDDDDDDBDD4                      3
  3   3      CD4 IP Address CD4  3                      3
  3   3      @D4 String CDDDADY  3                      3
  3   CDepDD=DDintegerDDDDDDADDDDDDDD4                      3
  3   CDeptypeDD=DDBDsharedDBDDDDDDDD4                      3
  3   3       @DuniqueDY     3                      3
  3   CDidlDD=DD"DDIDL file nameDD"DD4                      3
  3   CDobjDD=DD4 DCE uuid value CDDD4                      3
  3   @DnseDD=DD4 String CDDDDDDDADDDY                      3
  3                                        3
  3 IP ADDRESS:                                  3
  3 CDDintegerDDzDDintegerDDzDDintegerDDzDDintegerDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4 3
  3                                        3
  3 DCE UUID VALUE:                                3
  3 CDDhexaDDzDDhexaDDzDDhexaDDzDDhexaDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4 3
  3                                        3
  3 A ATTRIBUTE:                                 3
  3 CDDBDfinputDD=DDBDnullDDBDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDD4 3
  3   3       CDstdinD4              3             3
  3   3       CDidDDDD4              3             3
  3   3       @D"id"DDY              3             3
  3   CDfoutputDD=DDBDnullDDDBDDDDDDDDDDDDDDDDDDDDDDDD4             3
  3   3       CDstdoutD4             3             3
  3   3       CDstderrD4             3             3
  3   3       CDidDDDDD4             3             3
  3   3       @D"id"DDDY             3             3
  3   CDnthreadsDD=DDintegerDDDDDDDDDDDDDDDDDDDDDDDDDD4             3
  3   @DBDimportDBDDidDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDBDY             3
  3    @DexportDY    3   ZD;DDDDDDDDDDDDDDD?   3              3
  3            3            3   3              3
  3            @D{DDDD4 I Attribute CDADD}DY              3
  3                                        3
  3 STRING:                                    3
  3    ZDDDDDDDD?                               3
  3         3                               3
  3 CDD"DDDDletterDADD"DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4 3
  3                                        3
  @DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 8. idlgen Messages ΓòÉΓòÉΓòÉ

There are three categories of messages reported by idlgen:

 o Information
 o Warnings
 o Errors

 Information messages give you indications of various idlgen activities while
 it is running. They enable you to track what idlgen is doing. You can suppress
 them by including +v in the command line. This turns off verbose mode

 idlgen issues warning messages when it detects deviations from the expected.
 The nature of the deviations is not serious enough to prevent idlgen from
 generating the IDL output file; however, you need to perform some corrective
 action on the files later. Warning messages are displayed preceded by the word
 Warning. You can suppress them by including -no_warn in the command line.

 idlgen issues error messages whenever it detects a situation that prevents it
 from generating the IDL output file or when your intentions as portrayed in
 the command line switches are incomplete or ambiguous. Conditions that trigger
 error messages include syntax errors in the input files and command line,
 inability to locate input files, and inability to correctly process input
 files. Error messages are preceded by the word Error.

 Note:  There is one special Error message:  Bug. If it occurs, record the
        circumstances and report it to IBM.

 idlgen keeps a running tally of warnings and errors. When idlgen exits, it
 displays the number of each.

 When a message relates to specific locations in source files, there can be two
 forms of location references:

 single-location - Has the form:  "in the file 'file'(line/pos)", where file,
                line, and pos (for position) have the obvious meanings.
 double-location - has the form: "in the file 'file'(line/pos) and
                'file'(line/pos)".  Two locations in two different files are
                referenced.

 When the message subject is a symbol, the location is that of the first
 character of the symbol. For syntax errors, there is no specific explanation
 for the reason, and the location is in close proximity, pointing at the token
 that was scanned when the error occurred.


ΓòÉΓòÉΓòÉ 8.1. idlgen Information Messages ΓòÉΓòÉΓòÉ

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Command line switch -o ignored.             3 When the input IDL file comes from standard  3
3                             3 input, the -o switch is meaningless and    3
3                             3 therefore ignored.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Importing IDL file 'file'                3 An import "file" statement in an IDL file is  3
3                             3 being interpreted.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 An initial IDL file generation - completed.       3 The initial IDL file is generated when there  3
3                             3 is no IDL input file to IDLGEN, or the IDL   3
3                             3 input file has an empty body (for example,   3
3                             3 one generated by UUIDGEN with the -i switch). 3
3                             3 This stage can be skipped by using the IDLGEN 3
3                             3 switch -i.                   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Initial IDL file generation - completed with errors.   3 Similar to the preceding message except that  3
3                             3 some errors were reported.  There were prob-  3
3                             3 ably caused by syntax errors in input files.  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 MakeDCE version - Enabling tool for DCE IBM Corporation 3 An opening product disclaimer message for   3
3 (c) 1992, 1993, 1994                   3 IDLGEN.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 No input file - reading from standard input       3 When no input files are present in the     3
3                             3 command line, there is always one input file  3
3                             3 that is read from the standard input.  If the 3
3                             3 -stdin switch is present, one of the input   3
3                             3 files (or the only one) comes from the     3
3                             3 standard input, and this message is not    3
3                             3 reported.                   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 No output generated due to errors            3 Errors were reported during processing which  3
3                             3 prevent the generation of a correct IDL file. 3
3                             3 Although IDLGEN errors are not marked with a  3
3                             3 severity level, some are more severe than   3
3                             3 others.  Specifically, locations of some    3
3                             3 reported errors can be marked in the gener-  3
3                             3 ated IDL file with the special keyword     3
3                             3 MK_ERROR, allowing you to correct them later. 3
3                             3 In cases of errors which are more severe than 3
3                             3 that, no output is generated.         3
3                             3                        3
3                             3 Erroneous input files that will not pass com- 3
3                             3 pilation may cause IDLGEN errors that prevent 3
3                             3 the generation of an output IDL file.     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Output IDL file is 'file'.                3 Tells you the name of the output IDL file.   3
3                             3 It can also be the standard output.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Processing file 'file'...                3 When starting to process each input file, its 3
3                             3 name is reported, followed by two possible   3
3                             3 complementary messages giving IDLGEN determi- 3
3                             3 nation of its type (IDL or C).         3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 ... C source file.                    3 IDLGEN has determined that the file being   3
3                             3 processed is a C file.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 ... idl file.                      3 IDLGEN has determined that the file being   3
3                             3 processed is an IDL file.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Running the C preprocessor  'C prep. command'      3 Each input file is preprocessed (unless the  3
3                             3 -no_cpp is set) using the C prep. command as  3
3                             3 listed here.                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Successful completion                  3 Concluding message for successful completion  3
3                             3 without errors, although warnings could have  3
3                             3 been reported.                 3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 num errors num warnings found              3 Concluding message with the number of errors  3
3                             3 and warnings encountered during execution.   3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 8.2. idlgen Warning Messages ΓòÉΓòÉΓòÉ

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Array boundaries illegal, in the file      3 Array boundaries in IDL file are illegal; the 3
3 'file'(line/pos)                     3 lower bound is bigger than the upper bound.  3
3                             3 This also causes an IDL compiler error.    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Array dimensions are different for 'symbol'.  3 Array dimensions in C and IDL for the same   3
3 in the file 'file'(line/pos) and 'file'(line/pos)    3 symbol declaration do not match.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Bitfields are not allowed in IDL - ignored for 3 Bit fields in C structures and unions have no 3
3 'symbol', in the file 'file'(line/pos)          3 equivalent in IDL and are ignored.  This    3
3                             3 leads to type incompatibility in the applica- 3
3                             3 tion and should be corrected by changing the  3
3                             3 C application accordingly.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: C declarations mismatch: 'symbol' in the file  3 More than one C input file defines the same  3
3 'file'(line/pos) and 'file'(line/pos)          3 symbol differently.  The declaration in the  3
3                             3 last file takes precedence.          3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: C preprocessing problem. Keyword 'symbol', in  3 Sources (C and IDL) that have not been pre-  3
3 the file 'file'(line/pos)                3 processed, but contain preprocessing direc-  3
3                             3 tives, produce this message.  Also, erroneous 3
3                             3 preprocessor commands that are ignored by the 3
3                             3 preprocessor will cause this. IDLGEN ignores  3
3                             3 such lines and continues.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Cannot compare dimensions for 'symbol'.  in   3 Array dimensions in C and IDL declarations of 3
3 the file 'file'(line/pos) and 'file'(line/pos)      3 same symbol cannot be compared because the C  3
3                             3 dimensions cannot be computed independently  3
3                             3 of the compiler.                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Cannot invoke the C preprocessor        3 Something is wrong with the CPP command (-cpp 3
3                             3 switch) that is causing the internal running  3
3                             3 of this tool to fail.  Either change the -cpp 3
3                             3 switch or set the -no_cpp switch to disable  3
3                             3 preprocessing altogether.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Constant 'symbol' in array bound has wrong   3 Not all constant types can be used in con-   3
3 type, in the file 'file'(line/pos)            3 stant expressions of array dimensions.     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Declarator 'symbol' has more than one indi-   3 C declarator has long indirection and the -b  3
3 rection.  in the file 'file'(line/pos)          3 switch is not set. Including -b causes IDLGEN 3
3                             3 to break the declaration in question into   3
3                             3 simpler declarations using typedefs.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Identifier 'symbol' is a reserved word in IDL  3 Legal identifiers in C can conflict with IDL  3
3 (or idlgen).  Renamed to 'new-symbol', in the file    3 keywords and cannot be used as identifiers in 3
3 'file'(line/pos)                     3 generated IDL files.  IDLGEN appends a     3
3                             3 special suffix when it renames IDL files as  3
3                             3 reported in this message.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Identifier 'symbol' too-long for IDL.      3 Function identifiers cannot be converted to  3
3                             3 arbitrary short names since they provide the  3
3                             3 hook between the client code and the stubs   3
3                             3 generated by the IDL compiler.  You must    3
3                             3 shorten the identifier.            3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Illegal error format 'format', using native   3 The switch -errfmt can take two possible    3
3 mode                           3 values:  NATIVE, and EMACS.  The default is  3
3                             3 NATIVE.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Illegal preprocessor keyword. Token 'symbol',  3 Sources (C and IDL) which have not been pre-  3
3 in the file 'file'(line/pos)               3 processed (but contain preprocessing direc-  3
3                             3 tives that start with an unrecognized     3
3                             3 preprocessor verb) produce this message.    3
3                             3 IDLGEN ignores such lines and continues.    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: NIDLDIR environment variable not defined    3 The NIDLDIR environment variable must be set  3
3                             3 in a correctly installed DCE operational    3
3                             3 environment.  This variable sets up the path  3
3                             3 to DCE standard header and import files,    3
3                             3 which are needed to correctly parse input IDL 3
3                             3 files.  There is an internally defined     3
3                             3 default path used by IDLGEN, but errors can  3
3                             3 subsequently occur if that path is not the   3
3                             3 correct one.                  3
@ DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY
ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Warning: No operations to do in IDL file         3 At the conclusion of processing input files,  3
3                             3 the output IDL file does not contain any    3
3                             3 operations.  This situation can occur when   3
3                             3 input C files do not contain any exportable  3
3                             3 operations or when all exportable operations  3
3                             3 are marked as NOEXPORT in meta comments.    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Undefined constant (or enumeration) 'symbol'.  3 Some constant expressions rely on other con-  3
3 in the file 'file'(line/pos)               3 stants (in IDL) or ENUMs (in C), which are   3
3                             3 undefined in the input files.  This can lead  3
3                             3 to more errors.                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Warning: Variable declarations are not supported in   3 There is no equivalent to C global and static 3
3 IDL.  Declaration of 'symbol' ignored,  in the file   3 declarations in IDL.  Such symbols are     3
3 'file'(line/pos)                     3 ignored and are note reproduced in the output 3
3                             3 IDL file.                   3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 8.3. idlgen Error Messages ΓòÉΓòÉΓòÉ

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Aggregate containing conformant array can be   3 DCE rules dictate this limitation but also   3
3 passed only by reference, for 'symbol', in the file   3 dictate that the symbol has to be passed, or  3
3 'file'(line/pos)                     3 has the attribute for, PTR.  This conflict is 3
3                             3 reported here.                 3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Aggregate 'symbol' was not printed yet in proper 3 Because of C syntax rules, a reference to an  3
3 context.  in the file 'file'(line/pos) and        3 aggregate symbol is made in a location that  3
3 'file'(line/pos)                     3 is illegal for IDL. This situation leads to  3
3                             3 an IDL compiler error.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Array 'symbol'. Only the first dimension can be  3 A DCE limitation is not met by a C declarator 3
3 conformant.  in the file 'file'(line/pos)        3 that has to be included in the output IDL   3
3                             3 file.  This leads to an IDL compiler error.  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Bad switch in command line 'switch' at 'char-   3 An illegal IDLGEN switch was scanned in the  3
3 acter' DD> Use -h switch for help.            3 IDLGEN invocation command line.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Bad switch in environment variable 'IDLGEN':   3 An illegal IDLGEN switch was scanned in the  3
3 'switch' at 'character' DD> Use -h switch for help.   3 environment variable IDLGEN before the     3
3                             3 command line can be scanned.          3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Cannot access an input file: 'file'        3 IDLGEN cannot read the specified input file.  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Cannot export function 'symbol' which is static, 3 The C function is not defined in the input   3
3 or prototype only.  in the file 'file'(line/pos)     3 IDL file as an operation.  It is designated  3
3                             3 as EXPORT in a meta comment in the input IDL  3
3                             3 file and must have an actual definition in an 3
3                             3 input C file, which is not STATIC. Actual   3
3                             3 definition means that it has a body (for    3
3                             3 instance, int foo( ) { ...};).         3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Cannot export global 'symbol'.  in the file    3 symbol is designated in a meta comment of an  3
3 'file'(line/pos)                     3 input IDL file as EXPORT.  It is a global   3
3                             3 variable and not a function.  There is no   3
3                             3 support for global variables in DCE.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Cannot write to output IDL file 'file'      3 IDLGEN cannot read the specified output file. 3
3                             3 The output IDL file name is chosen as the   3
3                             3 input IDL file name if the -o switch is set.  3
3                             3 If a specific name is assigned to that     3
3                             3 switch, it becomes the name of the output IDL 3
3                             3 file.                     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Comment is mixed within a meta comment.  in the  3 Meta comments use the /* ....*/ C comment   3
3 file 'file'(line/pos)                  3 delimiters, so these delimiters cannot be   3
3                             3 used inside a meta comment.  The following   3
3                             3 situation for instance, causes this message:  3
3                             3 /*@ .... ; /*  */.              3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Conflict in symbol between C and IDL files:    3 A declaration of a symbol in C and in IDL are 3
3 'symbol' in the file 'file'(line/pos) and        3 incomparably different. For instance, one is  3
3 'file'(line/pos)                     3 a typedef, and one is a structure.  You have  3
3                             3 to correct the C and IDL sources.       3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Conformant array 'symbol' can only be last in   3 A DCE limitation is detected by IDLGEN and   3
3 struct.  in the file 'file'(line/pos)          3 reported here.                 3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Conformant array 'symbol' cannot be part of a   3 A DCE limitation is detected by IDLGEN and   3
3 union.  in the file 'file'(line/pos)           3 reported here.                 3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Declarator 'symbol' cannot be an IDL declarator. 3 A legal C declarator cannot be an IDL     3
3 in the file 'file'(line/pos)               3 declarator - either as a parameter or an    3
3                             3 operation.  Examples are functions with a   3
3                             3 variable number of arguments, a function    3
3                             3 pointer in an aggregate field, or a function  3
3                             3 parameter.                   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Duplicate name 'symbol' in the file        3 symbol is reused in the same file.       3
3 'file'(line/pos)                     3                        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Empty input file (file)              3 The input file exists but is empty.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Function header/prototype mismatch: 'symbol' in  3 A situation exists in C where the function   3
3 the file 'file'(line/pos)                3 header of the actual declaration and the    3
3                             3 function prototype differ.           3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY
ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Error: Function 'symbol' cannot export - changed to   3 C functions have been designated as EXPORT in 3
3 tbd(noexport).  in the file 'file'(line/pos)       3 the input IDL file, but cannot export (for   3
3                             3 instance, they have variable number of argu-  3
3                             3 ments or have a function pointer parameter).  3
3                             3 The meta comment entry for them is changed as 3
3                             3 reported in the message.            3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Global variable 'symbol' cannot be exportable.  3 A global symbol has been designated in the   3
3 in the file 'file'(line/pos)               3 input IDL file as EXPORT.  This is illegal.  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: IDL declaration doesn't match C source: 'symbol' 3 Declarations of a symbol in C and in IDL are  3
3 in the file 'file'(line/pos) and 'file'(line/pos)    3 different.  Some of the incompatibilities can 3
3                             3 be corrected by updating the IDL declaration. 3
3                             3 The -conformC switch automatically updates   3
3                             3 the IDL file according to changes in the C   3
3                             3 file.  However, not all changes can be traced 3
3                             3 and corrected.                 3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Import file 'file' is not an IDL file.      3 IDLGEN recognizes the kind of input file from 3
3                             3 its contents.  In this case, an import file  3
3                             3 was found, but it is not the correct type.   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Import file name w/path is too long: 'full-file- 3 IDLGEN builds an import file name from the   3
3 name' File not imported.                 3 name in the IMPORT statement and the search  3
3                             3 paths (from the -I switch).  However, the   3
3                             3 resulting string is too long to process.    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Import file 'file' not found.           3 An import file name was not found anywhere in 3
3                             3 the search paths.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Invalid dimension expression (for an IDL array)  3 Array dimensions must be computable independ- 3
3 on 'symbol'.  in the file 'file'(line/pos)        3 ently of the C compiler.  C constant      3
3                             3 expressions that make this impossible trigger 3
3                             3 this message.                 3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Missing value for argument 'switch' in environ-  3 The IDLGEN environment variable has a switch  3
3 ment variable 'IDLGEN'.                 3 that requires an argument, but no argument   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Missing value for command line argument      3 The IDLGEN command line has a switch that   3
3 'switch'.                        3 requires an argument, but no argument was   3
3                             3 given.                     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: More than two input IDL files.          3 Only one input IDL file is allowed.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Needs to specify conformant array size or max,  3 DCE requires conformant arrays to have the   3
3 but context is NOT an operation or an aggregate.  For  3 [max] or [size] attributes but only in proper 3
3 'symbol' (or derived typedefs), in the file       3 contexts where other fields or parameters can 3
3 'file'(line/pos)                     3 be used as arguments to these attributes.   3
3                             3 With IDLGEN, which generates new typedefs   3
3                             3 from complex C declarations, this can display 3
3                             3 in the wrong context (usually within      3
3                             3 typedefs) where fields and parameters are not 3
3                             3 available.                   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: No definition for aggregate (struct, union, or  3 An aggregate in C can be referenced without  3
3 enum): 'symbol' in the file 'file'(line/pos)       3 having its actual definition present.  This  3
3                             3 is not allowed in DCE, which has to have a   3
3                             3 precise definition for all symbols involved  3
3                             3 in an RPC.                   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: No definition for typedef: 'symbol' in the file  3 This is a rare error where a typedef is ref-  3
3 'file'(line/pos) and 'file'(line/pos)          3 erenced but has no definition.         3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: No IDL operation declared for C function     3 This a rare error where no IDL operation was  3
3 'symbol'.  in the file 'file'(line/pos)         3 declared in the input IDL file or automat-   3
3                             3 ically generated by IDLGEN for a C function  3
3                             3 that has been designated for EXPORT.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: No output IDL name specified and cannot be con-  3 This a rare error where IDLGEN is unable to  3
3 cluded - since there is no input IDL parameter      3 output the IDL file because of an earlier   3
3                             3 error.                     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Order of declarations in typedef list is bad at  3 This a rare error resulting from a conflict  3
3 symbol 'symbol' in the file 'file'(line/pos)       3 in the internal ordering of symbols by     3
3                             3 IDLGEN.                    3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY
ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Error: [ref] attribute of 'symbol' should be [ptr] due  3 IDL requires that pointers have the full    3
3 to use in union.  in the file 'file'(line/pos)      3 pointer attribute ([ptr]) when referenced in  3
3                             3 unions.  When IDLGEN generates these attri-  3
3                             3 butes initially, the proper considerations   3
3                             3 are taken to use the [ref] attribute only   3
3                             3 where it is allowed.  However, when an attri- 3
3                             3 bute in an input IDL file needs to be CHANGED 3
3                             3 from ref to ptr, IDLGEN makes the change and  3
3                             3 reports it to the user.            3
3                             3                        3
3                             3 This message format is used when the error is 3
3                             3 found in the immediate context of its cause.  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: [ref] attribute of 'symbol' should be [ptr] due  3 This is similar to the preceding message, but 3
3 to use in union field 'symbol'.  in the file       3 it also points to the union field which trig- 3
3 'file'(line/pos) and 'file'(line/pos)          3 gered this situation.  Note that there can be 3
3                             3 more than one such trigger, but only one is  3
3                             3 reported.                   3
3                             3                        3
3                             3 This message format is used when the error is 3
3                             3 found in a different location than the     3
3                             3 trigger.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Output IDL file 'file' exists.  Must specify -o  3 This a rare error resulting from internal   3
3 to overwrite it                     3 IDLGEN conflicts.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Symbol 'symbol' cannot be redefined, in the file 3 symbol is used in the same file for two dif-  3
3 'file'(line/pos)                     3 ferent and conflicting purposes.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Symbol 'symbol' not defined.  in the file     3 This a rare error resulting from internal   3
3 'file'(line/pos)                     3 IDLGEN conflicts when an aggregate is refer-  3
3                             3 enced, but has no actual declaration.     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error (Syntax) 'symbol', in the file 'file'(line/pos)  3 A parser error resulted from scanning a C or  3
3                             3 IDL file.  Input file scanning stops upon   3
3                             3 this error, and IDLGEN starts processing the  3
3                             3 next file in line.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Trailing switches 'switches' ignored in combined 3 An error was encountered in a combined string 3
3 switch 'switch'                     3 of single-letter switches. The rest of the   3
3                             3 string is ignored.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Undefined const symbol or enum item 'symbol'   3 A constant expression for a given symbol ref- 3
3 used by symbol 'symbol'.  in the file 'file'(line/pos)  3 erences other symbols that have to be consts  3
3                             3 or enums.  However, these symbols are unde-  3
3                             3 fined.                     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Unexpected end-of-file in the file        3 The parser encountered an end-of-file before  3
3 'file'(line/pos)                     3 parsing was completed.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error: Wrong IDL language indicator '%  C or Pascal'.  3 IDL files can have a language indicator    3
3 in the file 'file'(line/pos)               3 before the IDL header. IDLGEN checks these to 3
3                             3 be either C or Pascal but processes C IDL   3
3                             3 files only.  IDLGEN removes this indicator   3
3                             3 from the output IDL files it produces.     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Fatal error: string "text string" is too long.  in the  3 This a rare error caused bu internal con-   3
3 file 'file'(line/pos)                  3 flicts in IDLGEN when a string constant is   3
3                             3 too long.                   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 line line(file): BUG(function - file - Lline:      3 This is a rare internal IDLGEN error that   3
3 description                       3 should never occur and that points at a    3
3                             3 IDLGEN bug that must be reported to IBM.    3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 9. gluegen Messages ΓòÉΓòÉΓòÉ

gluegen, like idlgen. also reports three kinds of messages:

 o Information
 o Warnings
 o Errors

 gluegen generates several types of outputs, but errors can prevent the
 production of some of these outputs.

 To distinguish gluegen messages from other tools used in the development of a
 DCE application, most are preceded with an arrow: "-->" in the left margin.


ΓòÉΓòÉΓòÉ 9.1. gluegen Information Messages ΓòÉΓòÉΓòÉ

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot open glue stub module name, writing to stdout   3 The file name is not write-accessible, so   3
3                             3 output for the glue stub goes to standard   3
3                             3 output.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Compiling module name: C-compile-cmd           3 This message is displayed when the -keep    3
3                             3 switch is included in the command line to   3
3                             3 select object or both.  It indicates that   3
3                             3 module name was generated by GLUEGEN and is  3
3                             3 being compiled.  The compilation generates a  3
3                             3 new object file.                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Creating acf file file (for name)            3 GLUEGEN generates an ACF file, file, for a   3
3                             3 given IDL file, name, when such a file is   3
3                             3 needed for running the IDL compiler cor-    3
3                             3 rectly.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Creating app main module file              3 A main module (containing the main() entry   3
3                             3 point) for an application is being generated  3
3                             3 and written into file.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Creating glue stub module file              3 GLUEGEN is generating a glue stub file for   3
3                             3 the client or the server sides.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Deleting application module file             3 Displays if -keep switch has specified     3
3                             3 keeping only object files.  It indicates that 3
3                             3 the source for the application module file is 3
3                             3 being erased.                 3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Deleting stub module file                3 This message is displayed if -keep switch has 3
3                             3 specified keeping only object files.  It    3
3                             3 indicates that the source for the stub module 3
3                             3 file is being erased.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 MakeDCE(gluegen) version - Enabling tool for DCE IBM   3 An opening product disclaimer message for   3
3 Corporation (c) 1992                   3 GLUEGEN.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Reading app-profile from file, app-name is name     3 This message indicates that GLUEGEN is     3
3                             3 reading the APF file from file and that the  3
3                             3 application is name.  This provides assurance 3
3                             3 that you have specified the correct file and  3
3                             3 name in the command line.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Running the C preprocessor  C prep. command       3 This message is displayed if you have not   3
3                             3 included the -no_cpp switch.  It indicates   3
3                             3 that the C prep. command is being used to   3
3                             3 preprocess the APF file.            3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 num errors num warnings reported             3 This is a concluding message reporting the   3
3                             3 number of errors and warnings encountered   3
3                             3 when GLUEGEN is run.              3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 9.2. gluegen Warning Messages ΓòÉΓòÉΓòÉ

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Warning: C preprocessor problem, keyword 'token' in  3 This is usually the result of an incorrect   3
3 the file 'file'(line/pos)                3 preprocessing directive embedded in the APF  3
3                             3 file that the preprocessor did not recognize  3
3                             3 and left in place during preprocessing.    3
3                             3 GLUEGEN ignores such lines and continues.   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Warning: APF protseq 'value' differs from IDL     3 GLUEGEN compared values in the APF file with  3
3 protseq 'value' Interface = 'name', IDL file = 'file'  3 corresponding attributes in IDL files that   3
3                             3 are used by interfaces defined in the APF   3
3                             3 file.  It found an inconsistency in the    3
3                             3 protseq attribute.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Warning: APF endpoint 'value' differs form IDL    3 GLUEGEN compared values in the APF file with  3
3 endpoint 'value' Interface = 'name', IDL file = 'file'  3 corresponding attributes in IDL files that   3
3                             3 are used by interfaces defined in the APF   3
3                             3 file.  It found an inconsistency in the    3
3                             3 endpoint attribute.              3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Warning: Cannot invoke the C preprocessor       3 Unless you have included the -no_cpp option  3
3                             3 in the command, GLUEGEN automatically calls  3
3                             3 the C preprocessor.  This warning displays if 3
3                             3 something is wrong with the cpp command that  3
3                             3 is causing the internal execution of this   3
3                             3 tool to fail.  Either change the -cpp_cmd   3
3                             3 option or use the -no_cpp option to disable  3
3                             3 preprocessing altogether.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Warning: Cannot open catalog file file        3 Catalog file file is needed for generating   3
3                             3 GLUEGEN messages.  If GLUEGEN cannot find   3
3                             3 this file (this can be caused by environment  3
3                             3 variables NLSDIR and LANG improperly set or  3
3                             3 GLUEGEN installation not complete), it uses  3
3                             3 internal English text for messages.      3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 9.3. gluegen Error Messages ΓòÉΓòÉΓòÉ

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Must run preprocessor prior to gluegen invo-  3 This is usually the result of inputting an   3
3 cation.  Keyword 'token', in the file 'file'(line/pos)  3 APF file that contains preprocessor direc-   3
3                             3 tives and that has not been preprocessed at  3
3                             3 all.                      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Cannot access IDL file 'file' in interface   3 GLUEGEN cannot access and read the IDL file  3
3 'name'                          3 file.  The IDL file is defined for interface  3
3                             3 name in the input APF file.          3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Cannot access input file file         3 GLUEGEN cannot access and read the input file 3
3                             3 file.                     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Cannot generate name of ACF file form IDL   3 ACF files names are derived from their corre- 3
3 file 'file' current interface is 'name'         3 sponding IDL file names. An attempt to gen-  3
3                             3 erate such a name for IDL file file has    3
3                             3 failed. The IDL file is defined for interface 3
3                             3 name in the input APF file.          3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Cannot open ACF file file for interface    3 GLUEGEN cannot access and write to the ACF   3
3 'name'                          3 file 'file'.  The ACF file name was generated 3
3                             3 for an IDL file defined in interface name in  3
3                             3 the input APF file.              3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Cannot open glue application file 'file'    3 GLUEGEN cannot access and write to the output 3
3                             3 glue application file file.  The file name is 3
3                             3 derived from the application name in the    3
3                             3 command line, which is also defined in the   3
3                             3 input APF file.                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Cannot open glue stub file 'file'       3 GLUEGEN cannot access and write to the output 3
3                             3 glue-stub file file.  The file name is     3
3                             3 derived from the application name in the    3
3                             3 command line, which must be defined in the   3
3                             3 input APF file.                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Compilation of glue stub module file, Failed  3 A glue-stub was generated, but the -keep    3
3                             3 switch specified object or both, and internal 3
3                             3 activation of the compiler failed.       3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Compilation of application module file,    3 An application module was generated, but the  3
3 Failed                          3 -keep switch specified object or both, and   3
3                             3 internal activation of the compiler failed.  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Duplicate interface definition 'name', in the 3 An interface in the input APF file is defined 3
3 file 'file'(line/pos)                  3 twice.  The last definition location is    3
3                             3 shown.                     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Empty input file (file)            3 The input file (APF or IDL) is empty.     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Application 'name' can not have empty body,  3 The application name in the input APF file   3
3 in the file 'file'(line/pos)               3 has an empty body: {}.  The last definition  3
3                             3 location is shown.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Interface 'name' can not have empty body, in  3 The interface name in the input APF file has  3
3 the file 'file'(line/pos)                3 an empty body: {}.  The last definition    3
3                             3 location is shown.               3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: APF contains no application definition  3 APF files must have at least one application  3
3                             3 statement to produce output.          3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: Application stack overflow        3 An internal error has occurred in GLUEGEN.   3
3                             3 Report the circumstances to IBM.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: Cannot generate glue code 'name' Appli- 3 Application name was specified in command   3
3 cation is undefined in 'file'              3 line, but is not defined in the input APF   3
3                             3 file (also specified in command line).     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: cannot parse APF definitions in file   3 A rare internal complication occurred in    3
3 'file'                          3 GLUEGEN.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: cannot parse IDL definitions in file   3 A rare internal complication occurred in    3
3 'file'                          3 GLUEGEN.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: invalid interface in application 'name' 3 A rare internal complication occurred in    3
3 Probably an internal GLUGEN error.            3 GLUEGEN.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: Interface stack overflow         3 An internal error occurred in GLUEGEN.     3
3                             3 Report the circumstances to IBM.        3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY
ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 DD>Fatal ERROR: Application stack overflow        3 An internal error occurred in GLUEGEN.     3
3                             3 Report the circumstances to IBM.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: NIDLDIR environment variable not     3 This message is displayed only in OS/2.  The  3
3 defined                         3 NIDLDIR environment variable must be set in a 3
3                             3 correctly installed DCE operational environ-  3
3                             3 ment.  This variable sets up the path to DCE  3
3                             3 standard header and import files, which are  3
3                             3 needed to correctly compile stubs generated  3
3                             3 by GLUEGEN.  You cannot use GLUEGEN unless   3
3                             3 DCE is properly installed.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: no interface is imported/exported by   3 A application does not use any interface and  3
3 application 'name'                    3 is therefore meaningless.           3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Fatal ERROR: string "text string" is too long.  in  3 An internal error has occurred in GLUEGEN.   3
3 the file 'file'(line/pos)                3 Report the circumstances to IBM.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: 'import name' will generate duplicate     3 The same interface name and version numbers  3
3 implicit handle, IDL files: 'file1' for interface    3 in IDL files are defined for two different   3
3 'name1', and 'file2' for interface 'name2' define the  3 interfaces in the input APF file.  Implicit  3
3 same DCE interface and the same version numbers.     3 handle names are derived from an IDL inter-  3
3                             3 face name and its version numbers.  These   3
3                             3 must be distinct for different interfaces.   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: 'import name' will generate duplicate ACF   3 ACF file names are derived from the corre-   3
3 file.  interfaces 'name1' and 'name2' reference the   3 sponding IDL file names.  The interfaces in  3
3 same IDL file 'file'                   3 question reference the same IDL file.     3
3                             3 Because both use an implicit handle, an    3
3                             3 attempt to generate duplicate ACF file was   3
3                             3 made.                     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Missing IDL file specification in interface  3 The interface name in the input APF file is  3
3 'name'                          3 not associated with an IDL file.        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3                             3 APF file or an IDL file whose name is associ- 3
3                             3 ated with an interface in the APF file.  Only 3
3                             3 the header of IDL files is parsed.       3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Too many -D arguments on command line     3 An internal limitation on the number of -D   3
3                             3 switches is violated.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Too many -I arguments on command line     3 An internal limitation on the number of -I   3
3                             3 switches is violated.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Too many -U arguments on command line     3 An internal limitation on the number of -U   3
3                             3 switches is violated.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Undefined interface 'name', in the file    3 An interface name is referenced in the input  3
3 'file'(line/pos)                     3 APF file but was not previously defined in   3
3                             3 that file.                   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Undefined interface 'name' in application   3 An application references an interface in the 3
3 'file'                          3 input APF file, but the interface has not   3
3                             3 been previously defined in that file.     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Unsupported option 'option = value' in inter- 3 Not all APF language features are supported  3
3 face 'name'                       3 yet.                      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Invalid input file definition 'finput=name',  3 The definition of the finput file is not    3
3 in the file 'file'(line/pos)               3 valid.  This error can result from an incor-  3
3                             3 rect definition, such as 'finput=stdout'.   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: Invalid output file definition         3 The definition of the foutput file is not   3
3 'foutput=name', in the file 'file'(line/pos)       3 valid.  This error can result from an incor-  3
3                             3 rect definition, such as 'foutput=stdin'.   3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 DD>Error: duplicate unique endpoint 'value', interfaces 3 The user has defined a fixed endpoint for   3
3 'name1' and 'name2' define the same unique endpoint   3 interface 'name1'.  This type of this     3
3                             3 endpoint is unique and can not be shared by  3
3                             3 other interfaces, such as 'name2'.       3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 10. gluelib Messages ΓòÉΓòÉΓòÉ

The gluelib contains functions that report runtime errors when applications
generated by gluegen fail to run some DCE operation or whenever they run into a
situation that obstructs normal running. Some rare problems are due to memory
allocation failures.  These will probably never occur.  If they do, please
report them to IBM.


ΓòÉΓòÉΓòÉ 10.1. gluelib Error Messages ΓòÉΓòÉΓòÉ

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFInputBegin(): Cannot begin input            3 User error.  Check the implementation of the  3
3                             3 finput function specified in the APF file for 3
3                             3 GLUEGEN.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFInputDone(): Cannot terminate input          3 User error.  Check the implementation of the  3
3                             3 finput function specified in the APF file for 3
3                             3 GLUEGEN.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFOutputBegin(): Cannot begin output           3 User error.  Check the implementation of the  3
3                             3 foutput function specified in the APF file   3
3                             3 for GLUEGEN.                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFOutputDone(): Cannot terminate output         3 User error.  Check the implementation of the  3
3                             3 foutput function specified in the APF file   3
3                             3 for GLUEGEN.                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFCreate('ifname'): Invalid bindtype 'bindtype'     3 User error.  Check the binding method used in 3
3                             3 your application profile.  The bindtype value 3
3                             3 should be string, lepm, repm, or ns.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFBind('ifname'): Invalid binding mode 'bindtype'    3 User error.  Check the binding method used in 3
3                             3 your application profile.  The bindtype value 3
3                             3 should be string, lepm, repm, or ns.      3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFBind(): failed on binding interface 'ifname' to    3 A Client application failed on binding to a  3
3 Server on host 'hostname'                3 Server on hostname. ifname is the name of the 3
3                             3 imported interface in your application     3
3                             3 profile.  Ensure that the Server is running.  3
3                             3 If it is, verify that the endpoint reported  3
3                             3 by the Client is the one allocated to the   3
3                             3 Server.  Additional error messages, which may 3
3                             3 be reported, explain the the nature of the   3
3                             3 problem.                    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFUnbind(): failed on terminating Server connection   3 An internal GLUELIB error.  Notify IBM.    3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFRegister(): Cannot register interface 'ifname'     3 A Server application failed to register its  3
3                             3 interface to the RPCD. Additional error mes-  3
3                             3 sages, which may be reported, explain the   3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFImport(): Cannot import name service information for  3 A Client application failed to import host   3
3 'ifname'                         3 information from name service.  Additional   3
3                             3 error messages, which may be reported,     3
3                             3 explain the the nature of the problem.     3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFUnregister(): Failed to unregister interface 'ifname' 3 A Server application failed to remove the   3
3                             3 information it has registered by the RPCD.   3
3                             3 Additional error messages, which may be    3
3                             3 reported, explain the nature of the problem.  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFExport(): Failed to export interface 'ifname' to name 3 A Server application failed to export its   3
3 service                         3 information to the name service.  Additional  3
3                             3 error messages, which may be reported,     3
3                             3 explain the nature of the problem.       3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFHandleI('number'): Cannot find interface handle    3 User error.  The interface number provided is 3
3                             3 out of range.  Check the number of interfaces 3
3                             3 in your application.  Interface numbers range 3
3                             3 from 0 to n.                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Server failed on listening                3 A Server application failed on listening to  3
3                             3 incoming requests.  Additional error mes-   3
3                             3 sages, which may be reported, explain the   3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 ***FAILURE***: unexpected CMA exception - 'text'     3 An undefined EXCEPTION event that could not  3
3                             3 be caught by the application occurred.     3
3                             3 Report the error to IBM.            3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot get string binding - 'text'            3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot parse string binding - 'text'           3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY
ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Cannot compose string binding - 'text'          3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot check protocol sequence - 'text'         3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot Inquire bindings - 'text'             3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot use protocol sequence - 'text'          3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot get binding from string binding 'string' -    3 GLUELIB failed to run a DCE function.  text  3
3 'text'                          3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot register interface - 'text'            3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot register endpoint - 'text'            3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Error on listening: 'text'                3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot delete endpoint registration - 'text'       3 GLUELIB failed to run a DCE function.  text  3
3                             3 is the DCE error message explaining the    3
3                             3 nature of the problem.             3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 NULL host parameter, cannot bind to remote host     3 Self-explanatory                3
3 Cannot compose binding string: NULL endpoint       3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Protocol sequence 'protseq' is not valid         3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot generate obj_uuid from obj = 'objid'       3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot generate new type_uuid              3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot register object/type uuid association, obj =   3 Self-explanatory                3
3 'objid'                         3                        3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 10.2. gluelib Allocation Errors ΓòÉΓòÉΓòÉ

The following errors are rare allocation problems which should never occur at
runtime.  If they do, report them to IBM.

ZDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD?
3 Message                         3 Explanation                  3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot allocate application profile, exiting ...     3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot allocate application interface vector       3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot create application, exiting ...          3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot allocate input buffer, exiting ...        3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 Cannot reallocate input buffer, exiting ...       3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFInitialize(): Cannot allocate application, exiting   3 Self-explanatory                3
3 ...                           3                        3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFInitialize(): Cannot initialize application profile  3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFCreate(): Cannot allocate interface, exiting ...    3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFCreate(): Cannot initialize interface profile     3 Self-explanatory                3
CDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD4
3 IFCreate(): Cannot initialize interface methods for   3 Self-explanatory                3
3 'ifname'                         3                        3
@DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDY


ΓòÉΓòÉΓòÉ 11. Send Us Your Comments ΓòÉΓòÉΓòÉ

Was the MakeDCE - Application Development Tools User's Guide Version useful,
clear, and accurate? Please let us know by completing this form and sending it
to the following address:


Uri Shani
IBM Israel Science and Technology
Haifa Research Laboratory
MATAM - Advanced Technology Center
Haifa, Israel 31905
Fax: [phone]

ZDDDDDDDDDDDDDDDDBDDDDDDDDDDBDDDDDDDDDDBDDDDDDDDDDBDDDDDDDDDDBDDDDDDDDDD?
3         3 Strongly 3 Agree   3 Neutral  3 Disagree 3 Strongly 3
3         3 agree   3      3      3      3 disagree 3
CDDDDDDDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDD4
3 I am satisfied 3      3      3      3      3      3
3 with this    3      3      3      3      3      3
3 information   3      3      3      3      3      3
CDDDDDDDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDD4
3 The informa-  3      3      3      3      3      3
3 tion is tech-  3      3      3      3      3      3
3 nically     3      3      3      3      3      3
3 accurate    3      3      3      3      3      3
CDDDDDDDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDD4
3 The informa-  3      3      3      3      3      3
3 tion is com-  3      3      3      3      3      3
3 plete      3      3      3      3      3      3
CDDDDDDDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDD4
3 Specific    3      3      3      3      3      3
3 topics are   3      3      3      3      3      3
3 easy to find  3      3      3      3      3      3
CDDDDDDDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDD4
3 Examples are  3      3      3      3      3      3
3 clear and    3      3      3      3      3      3
3 useful     3      3      3      3      3      3
CDDDDDDDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDDEDDDDDDDDDD4
3 The format is  3      3      3      3      3      3
3 attractive and 3      3      3      3      3      3
3 useful     3      3      3      3      3      3
@DDDDDDDDDDDDDDDDADDDDDDDDDDADDDDDDDDDDADDDDDDDDDDADDDDDDDDDDADDDDDDDDDDY


What would you like to see included in the product or the information?

              _______________________________________________

              _______________________________________________

              _______________________________________________

              _______________________________________________

              _______________________________________________

  How to find you:

              Name
              _______________________________________
              Address
              _______________________________________
              Zip
              _______________________________________
              Phone
              _______________________________________


ΓòÉΓòÉΓòÉ 12. Figures ΓòÉΓòÉΓòÉ

  1. Distributed Application Graph

  2. MakeDCE flow diagram

  3. idlgen data and control flow

  4. Client/Server component overview in MakeDCE environment

  5. Splitting a stand-alone application into Client and Server roles


ΓòÉΓòÉΓòÉ 12.1. Distributed Application Graph ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid2 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid1 ΓòÉΓòÉΓòÉ

An edge in the graph represents a collection of operations that can use RPC.
It is named after the DCE Interface describing these operations. The edge
arrowhead represents the direction of an RPC; directed from node B to node A
specifies that interface I2 is imported by node B (source of edge) and exported
by node A (target of edge). A single application node can import and export
multiple interfaces.


ΓòÉΓòÉΓòÉ 12.2. MakeDCE flow diagram ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid4 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid3 ΓòÉΓòÉΓòÉ


C files (.c and .h items in the top box) are sources for developing IDL files
(using idlgen). The stubs generated from them by the idl compiler, together
with glue code generated by gluegen, and the original C files are used to make
up the client and server applications.

Numbered items in these figures play a role in DCE application development with
MakeDCE.

  1. A collection of C sources and their .h files is given 1.

  2. For any subset of relevant C sources 2, the idlgen tool is activated (3).
     It takes as input the C sources and an IDL file.

     Note:  Each IDL file denotes a server interface by defining the set of
     operations it exports.  There may be several different interfaces to the
     same server, to the same set of C sources, or to various (overlapping)
     subsets of the given C sources. idlgen always operates on an IDL file and
     its associated C sources. Yet, for flexibility, idlgen can accept an IDL
     file with any subset of C sources whenever you want to progress in small
     steps, gradually building up the final IDL file. idlgen also takes C files
     alone as input, generating an IDL file for them without the IDL header
     attributes.

     Another flexibility advantage is to use old IDL files to lend internal
     information to newly generated IDL files when both IDL files share some C
     sources. idlgen does not support this possibility at this time. Multiple
     IDL input files could mean one main IDL input file, while other files
     would play the role of examples (see Number of Input IDL Files).

  3. The IDL file (.idl) comes from four possible sources:

    o An initial skeleton IDL file 4 is generated by uuidgen [uuidgen is a DCE
      tool that generates Unique Universal IDs.  When activated as uuidgen -i,
      it generates an IDL skeleton file, containing a uuid in the proper place.
      ] 5
    o A existing IDL file 6 is fed into idlgen
    o An erroneous IDL file is corrected by the user and fed again into idlgen
      7
    o An existing IDL file (either complete or still in development 8) to be
      used as an example for the IDL file in development.

  4. The basic idlgen step 3 also takes user input and corrections9, which are
     applied to the IDL file until a good or legal IDL file is generated (10).

  5. The good IDL file is fed into the idl compiler11, where good means that
     there is nothing else idlgen can do about it, although the idl compiler
     may still detect more errors. In cases where you made no final decision in
     the idlgen step3, the IDL file does not pass the idl compilation step11,
     which generates error and warning messages12.

  6. A successful idl compilation generates stubs 14 and19.

  7. gluegen generates the glue code, 15 and 20, which starts the server and
     wraps the client, so that client and server bind at runtime to resolve the
     RPC services required. gluegen uses an APF file 13 as input for the
     glue-code generation.

  8. From the files generated by the idl compiler, some 14 are needed to be
     compiled and linked 16 with the glue code15 and some of the sources 17 are
     needed to create the server program 18.

  9. Similarly to the server, another set of IDL-generated files19 with some
     glue code 20 and a portion of the C sources 21 are compiled and linked 22
     to generate the client program 23.


ΓòÉΓòÉΓòÉ 12.3. idlgen data and control flow ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid6 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid5 ΓòÉΓòÉΓòÉ

idlgen Components and processing steps in reading input, matching idl and C
sources, and producing resulting IDL file.


ΓòÉΓòÉΓòÉ 12.4. Client/Server component overview in MakeDCE environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid8 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid7 ΓòÉΓòÉΓòÉ

Note the parallel roles between the gluegen process, and the stubs generated by
the idl compiler.


ΓòÉΓòÉΓòÉ 12.5. Splitting a stand-alone application into Client and Server roles ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid10 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> fid9 ΓòÉΓòÉΓòÉ

The components of each application node (Client and Server) are as follows:

 o Glue-code and glue-stub are generated by gluegen from an APF file. Separate
   pairs of glue-code and glue-stub files are generated for each application -
   one for the Client and one for the Server. The glue-codes include the main()
   entry-points of the Client and Server programs.

 o The glue-library is linked with each program and implements the API used in
   the glue-code. Application code can also use the API of the Glue library.

 o Application code in the Client is the Main part of the original application,
   which performs an RPC to the Server.

 o Application code in the Server is the Utility part of the original
   application, which implements the RPC performed by the Client.

 o Server-stub is a code generated by the idl compiler (part of DCE) for the
   Server. The code is generated from an IDL file that represents the interface
   between the Client and the Server.

 o Client-stub is a code generated by the idl compiler for the Client.

 o DCE RTL is the DCE runtime library, which supports the DCE execution
   environment of DCE applications. This layer uses other lower-level
   communication support layers in the operating systems of the respective
   platforms on which the application nodes run.


ΓòÉΓòÉΓòÉ 13. Glossary ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.1. A ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.1.1. ACF file ΓòÉΓòÉΓòÉ

ACF file

An optional definition file complementary to the IDL file, which provides
additional specifications for the idl compiler when generating stubs.


ΓòÉΓòÉΓòÉ 13.1.2. Application Profile ΓòÉΓòÉΓòÉ

Application Profile

gluegen configures DCE applications using Application Profiles that are a
combination of one or more interface profiles plus additional global
parameters.


ΓòÉΓòÉΓòÉ 13.1.3. APF ΓòÉΓòÉΓòÉ

APF

Application Profile Language. Formal statements used for specifying application
profiles.


ΓòÉΓòÉΓòÉ 13.2. B ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.2.1. Binding ΓòÉΓòÉΓòÉ

Binding

The operation that connects a Client and a Server for the purpose of making an
RPC. To bind, a Server has to make its network location known to the Client so
that a connection over the communication network can be established. Binding is
performed at the level of interfaces and can use many kinds of DCE services. To
bind, a Client needs to have at least an interface UUID and versions (and can
include an object UUID), as well as a way to obtain the Server machine and port
addresses.

 port      A machine-wide unique resource used for data communications between
           separate applications on separate machines (or the same machine).
 host      A network-wide resource identifying a specific machine or domain. In
           DCE, machines are also organized in cells, but each machine is
           uniquely identified. On Internet, a machine is uniquely identified
           by a four-field number and its compatible string of names. An
           example is harod.haifa.ibm.com, which is a symbolic name of the
           unique address 9.148.5.128.
 protocol  An agreed-upon method of communication between two endpoints on a
           network. DCE supports two protocols:  TCP/IP and UDP/IP. The former
           is connection-based, and the latter is datagram-based.


ΓòÉΓòÉΓòÉ 13.2.2. Binding Handle ΓòÉΓòÉΓòÉ

Binding Handle

A DCE internal data structure that identifies the resources allocated for
performing RPC between Client and Server. The binding handle has its
appropriate form in the Client and in the Server. It can be partially bound,
which means that some of the information to establish binding is present, but
RPCs cannot be performed yet. To fully bind, a handle can require a significant
number of interactions with the DCE API. There are four kinds of binding
handles:

 Auto Handle A binding handle used by the DCE/RPC run-time that is completely
           transparent at the RPC level (that is, the RPC function prototype
           does not include a handle parameter). Whenever a Client performs
           RPC, the handle is initialized automatically based solely on
           information in the IDL file.
 Customized Handle The most general form of a handle, which allows an
           application to maintain its own structure representing its notion of
           a handle.
 Explicit Handle The general form of a binding handle, which the application
           has to initialize and explicitly pass to the RPC run-time through a
           parameter to the operation.
 Implicit Handle A binding handle similar to the Auto Handle in that it is also
           completely transparent at the RPC level, but the application has to
           bind the handle. This is done through a naming convention that
           assures that the correct implicit handle is initialized and bound by
           the application for a given interface (defined in an IDL file).


ΓòÉΓòÉΓòÉ 13.3. C ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.3.1. Client ΓòÉΓòÉΓòÉ

Client

The portion of a DCE application that performs RPC calls. This is a program
which may be engaged in all possible kinds of activities, some of which involve
calls through RPC to a remote Server.


ΓòÉΓòÉΓòÉ 13.4. D ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.4.1. DCE Cell ΓòÉΓòÉΓòÉ

DCE Cell

An organization of hosts in a local area network to work as a single namespace
cell. A directory service for the cell is used to resolve binding request for
Clients on the cell to Servers on the cell.


ΓòÉΓòÉΓòÉ 13.4.2. DCE Run-Time Library ΓòÉΓòÉΓòÉ

DCE Run-Time Library

The collection of procedures and functions that implement the DCE API through
which applications can gain access to all DCE services, perform RPC, and use
threads.


ΓòÉΓòÉΓòÉ 13.5. E ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.5.1. EPV ΓòÉΓòÉΓòÉ

EPV

Entry-Point Vector. A mapping between IDL operations and actual procedure entry
points in IDL manager code. A manager can have more than one EPV per interface,
thus differentiating different versions. When an RPC is received, this vector
is used to select the actual service routine. By default, the idl compiler
generates the EPV automatically in the stubs.


ΓòÉΓòÉΓòÉ 13.5.2. Entry-point mapper ΓòÉΓòÉΓòÉ

Entry-point mapper

Another functional name for the RPCD tool. An application can refer to an
entry-point mapper on its own host as a local entry-point mapper and on remote
machines as remote entry-point mappers.


ΓòÉΓòÉΓòÉ 13.5.3. export ΓòÉΓòÉΓòÉ

export

A flag word contained in a meta comment indicating that the symbols following
it are to be exported.


ΓòÉΓòÉΓòÉ 13.6. I ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.6.1. idl compiler ΓòÉΓòÉΓòÉ

idl compiler

A DCE tool that compiles IDL files (and possibly also ACF files) into stubs and
possibly additional support code.


ΓòÉΓòÉΓòÉ 13.6.2. IDL file ΓòÉΓòÉΓòÉ

IDL file

Interface Definition Language file that defines the interface between Server
and Client. This file contains definitions of RPC operation prototypes, as well
as the semantics of parameter marshalling, RPC behavior, and the unique
identification of this set of operations. IDL files are compiled by the idl
compiler into stubs.


ΓòÉΓòÉΓòÉ 13.6.3. IDLGEN ΓòÉΓòÉΓòÉ

IDLGEN

An environmental variable that can be used for holding idlgen command switches.


ΓòÉΓòÉΓòÉ 13.6.4. IDL version ΓòÉΓòÉΓòÉ

IDL version

A pair of numbers, termed major and minor, constituting the version numbers,
part of the header of an IDL file, which, together with the interface UUID in
the IDL file, differentiates and identifies an interface for binding.


ΓòÉΓòÉΓòÉ 13.6.5. Interface Profile ΓòÉΓòÉΓòÉ

Interface Profile

A group of parameters that affect the initialization process and binding method
that an application node uses with respect to a given interface; one of the set
of parameters used by gluegen.


ΓòÉΓòÉΓòÉ 13.7. M ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.7.1. Manager ΓòÉΓòÉΓòÉ

Manager

The implementation of operations defined in an IDL file. Sometimes, these are
organized in a single file called manager.c. Sometimes the implementation can
span several files collectively, termed the manager of an interface.


ΓòÉΓòÉΓòÉ 13.7.2. Marshalling ΓòÉΓòÉΓòÉ

Marshalling

The activity of encoding parameter structures, contents, and presentation into
a byte stream that can be sent using a packet switching communication media, so
that it can be recreated at the receiving end. Marshalling takes care of
differences between machine architectures, operating systems, languages, and
compilers.


ΓòÉΓòÉΓòÉ 13.7.3. Meta comment ΓòÉΓòÉΓòÉ

Meta comment

Comments that idlgen embeds in the output IDL file. There are three kinds of
Meta comment contents:

 o Disclaimer identifying idlgen as the IDL file generator.

 o List of export and noexport symbols identified from the C source file.

 o Flagging certain C source forms that are incompatible with IDL files (at the
   present time this applies only to enum tags).


ΓòÉΓòÉΓòÉ 13.7.4. MK_DEFAULT ΓòÉΓòÉΓòÉ

MK_DEFAULT

An idlgen special keyword inserted in IDL output files by idlgen when
generating IDL attributes.  This keyword is removed on subsequent idlgen passes
on the IDL file.


ΓòÉΓòÉΓòÉ 13.7.5. MK_ERROR ΓòÉΓòÉΓòÉ

MK_ERROR

An idlgen special keyword inserted in IDL output files by idlgen to flag
incompatibilities between IDL file declarations and the corresponding C source
declarations. This keyword remains even after subsequent idlgen passes until
the user makes corrections to the C source file.


ΓòÉΓòÉΓòÉ 13.8. N ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.8.1. Name Services ΓòÉΓòÉΓòÉ

Name Services

DCE Name services consist of the RPCD port mapper and the more general
directory services, which can span a local cell or a global worldwide directory
of service names.


ΓòÉΓòÉΓòÉ 13.8.2. noexport ΓòÉΓòÉΓòÉ

noexport

Flag word contained in a meta comment indicating that the symbols following it
are not to be exported.


ΓòÉΓòÉΓòÉ 13.9. R ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.9.1. RPC ΓòÉΓòÉΓòÉ

RPC

Remote Procedure Call. A communication paradigm used mostly in connection with
Client/Server models. Each RPC is performed by a Client program and is serviced
by a Server program. In the application code, the call to an RPC and the
service entry point look exactly like any other local procedure call and its
return in the application. An RPC call involves sending (marshalling) input
parameters to the server invoking a remote service that unmarshalls these
parameters, and placing the calling party in wait state until completion of the
remote service. Output parameters are then marshalled back to the caller so
that it can continue running. The servicing party awaits further calls for
service.


ΓòÉΓòÉΓòÉ 13.9.2. RPCD ΓòÉΓòÉΓòÉ

RPCD

A DCE tool (a daemon) that operates one per host and maintains a mapping table
between interfaces and entry-points (ports) of Servers. Each Server can
register all its exported interfaces in the RPCD daemon, associated with object
UUIDs if so desired, and can also register the interface with the ports
allocated to these objects and interfaces. A Client can then request the daemon
to resolve a particular interface to a corresponding port on the machine.


ΓòÉΓòÉΓòÉ 13.9.3. RPC stubs ΓòÉΓòÉΓòÉ

RPC stubs

A piece of code that the idl compiler generates from a given IDL file. There
are a Client stub and a Server stub. The Client stub takes care of performing
the call out from the client, and the Server stub takes care of the
complementary activity on the Server side. Stubs have to be compiled and linked
with the appropriate Server and Client programs.


ΓòÉΓòÉΓòÉ 13.10. S ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.10.1. Security Services ΓòÉΓòÉΓòÉ

Security Services

A DCE feature that limits the permission of Clients to bind with Servers,
unless specific security permissions are obtained. Security services are
functional during Server registration and handle binding.


ΓòÉΓòÉΓòÉ 13.10.2. Server ΓòÉΓòÉΓòÉ

Server

A portion of a DCE application that services RPC calls. This is a program that
can be engaged in a number of activities and that is capable of listening for
incoming RPC calls and servicing them when received.


ΓòÉΓòÉΓòÉ 13.10.3. String Binding ΓòÉΓòÉΓòÉ

String Binding

The simplest method of binding a Client to a Server. Specifies the actual
machine and port of the Server in the form of a string. Such strings can come
from a command line, a file, and so on.


ΓòÉΓòÉΓòÉ 13.11. T ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.11.1. tbd(...) ΓòÉΓòÉΓòÉ

tbd(...)

A flag contained in a meta comment indicating that idlgen has determined that
the given symbol is for export or noexport (the value is given in the
parentheses). This decision must be confirmed by the user.


ΓòÉΓòÉΓòÉ 13.11.2. Threads ΓòÉΓòÉΓòÉ

Threads

A DCE support which, at the application level (unlike the operating-system
level), permits the concurrent execution of several independent execution
paths. All threads of the same program share the same code and static program
memory segment but have distinctive stacks. Support of the DCE threads comes as
a library of routines. Threads are used in DCE to allow Servers to service more
than one request concurrently.


ΓòÉΓòÉΓòÉ 13.12. U ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.12.1. UUID ΓòÉΓòÉΓòÉ

UUID

Universal Unique IDentifier. Used to identify DCE objects in a universally
ensured unique string of 128 bits. UUIDs are generated by the DCE uuidgen tool.
UUIDs have a hexadecimal string representation composed of 5 fields separated
by hyphens, such as 006EE100-21AF-1BFA-8B16-10005AA8B716. The two types of
UUIDs are the following:

 Interface UUID A UUID used in the header of IDL files to uniquely identify the
                interface when binding a Client and a Server for the operations
                in the IDL file.
 Object UUID    A UUID used in DCE binding when a specific server or object is
                requested among the numerous possible Servers implementing a
                given interface (identified by its own UUID and IDL file).


ΓòÉΓòÉΓòÉ 13.12.2. uuidgen ΓòÉΓòÉΓòÉ

uuidgen

A DCE tool that generates UUIDs. Activating this tool with the -i switch
generates an IDL skeleton file where the contents of an interface can be filled
in.  It has its own UUID.