═══ 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: (+972)4-296-282 VNET: SHANI at HAIFASC3 email: shani@vnet.ibm.com ═══ 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 . 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 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 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 #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 #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 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 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 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 and so on. ::= | | | ::= interface [ like] { [ ; ] ... } ::= application { [ ; ] ... } ::= protseq = | bindtype = | handle = | host = | ep = | eptype = | idl = "" | obj = | nse = ::= finput = | foutput = | nthreads = | import [ { [ ; ] ... } ] | export [ { [ ; ] ... } ] ::= ncadg_ip_udp | ncaca_ip_tcp ::= implicit | explicit | auto ::= string | lepm | repm | ns ::= | | ::= ... ::= null | stdin | | "" ::= null | stdout | stderr | | "" ::= shared | unique ::= legal IDL file name ::= legal C identifier ::= DCE uuid value ::= ... ::= "... " ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ::= 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: (+972)4-296114 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 ═══ ═══ fid2 ═══ ═══ 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 ═══ ═══ fid4 ═══ ═══ 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 ═══ ═══ fid6 ═══ ═══ 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 ═══ ═══ fid8 ═══ ═══ 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 ═══ ═══ fid10 ═══ ═══ 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.