orb2 for C/C++ User’s Guideorb2 for C/C++ User’s Guide Subject Instructions for developing applications with orb2 for C/C++. Software Supported orb2 for C/C++ 3.8 Revision History

orb2 for C/C++User’s Guide

orb2 Release 3.8

orb2 for C/C++User’s Guide

Subject

Instructions for developing applications with orb2 for C/C++.

Software Supported

orb2 for C/C++ 3.8

Revision History

Release 3.0 September 1996

Release 3.0 March 1997

PDF version January 1998

Release 3.4 March 2001

Rebranded September 2001

Release 3.5 April 2003

Release 3.6 August 2004

Release 3.7 June 2005

Release 3.8 February 2008

2AB, Inc. disclaims the implied warranties of merchantability and fitness for a particular purpose and makes no express warranties except as may be stated in its written agreement with and for its customer. In no event is 2AB, Inc. liable to anyone for any indirect, special or consequential damages.

The information and specifications in this document are subject to change without notice. Consult your 2AB, Inc. marketing representative for product or service availability.

U.S. Government Restricted Rights. The Software Program(s) and Documentation furnished under this Agreement were developed at private expense and are provided with Restricted Rights. Any use, duplication, or disclosure by and for any agency of the U.S. Government shall be subject to the Restricted Rights applicable to commercial computer software under FAR Clause 52.227-19 or DFAR Clause 252.277-7013 or any successor thereof.

Copyright © 1996 - 2008 by 2AB, Inc. All Rights Reserved.

Trademarks

The 2AB logo is a registered trademark of 2AB, Inc. 2AB, eXplorer, iLock, iLock Security Services, jLock, orb2, orbLock, webLock and Xcon are trademarks of 2AB, Inc.

Microsoft, Windows, Windows NT, Windows 2000 and Windows XP are registered trademarks of the Microsoft Corporation.

OMG, Object Management Group, OMG Interface Definition Language (IDL), Unified Modeling Language and UML are trademarks of the Object Management Group. CORBA and IIOP are registered trademarks of the Object Management Group.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

HP-UX is a registered trademarks of the Hewlett-Packard Company.

Apache and Tomcat are trademarks of The Apache Software Foundation.

AIX and Domino are trademarks of the International Business Machines Corporation in the United States or other countries or both.

iPlanet, J2EE, J2SE, Java, JavaScript, JavaServer Pages, JKD, Solaris, Sun and Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

All other brand or product names are trademarks or registered trademarks of their respective companies or organizations.

User’s Guide orb2 for C/C++ 3.8 i

Contents

Contents

Figures

Tables

About This DocumentWhat is orb2 for C/C++?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0-viiWhat does this guide include? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0-viiOMG Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0-viiTechnical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0-viii

Chapter 1 Getting Started1.1 CORBA Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.2 Development Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.3 Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.4 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.5 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.6 Locating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

1.6.1 Stringified Object References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31.6.2 Naming Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31.6.3 Trader Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

1.7 Demonstration Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Chapter 2 Developing a Distributed orb2 Application2.1 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12.2 Compiling IDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22.3 C Code Generated by stubgen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32.4 Developing C Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

2.4.1 Developing C Server Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-42.4.1.1 Developing the C Calculator Server Program . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

2.4.2 Developing C Client Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62.4.2.1 Developing the C Calculator Client Program . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62.4.2.2 Compiling and Running the C Calculator Demo Programs . . . . . . . . . . . . . . 2-9

2.5 C++ Code Generated By stubgen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92.6 Developing C++ Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

2.6.1 Developing C Server Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102.6.1.1 Developing the C++ Calculator Server Program . . . . . . . . . . . . . . . . . . . . . . 2-10

2.6.2 Developing C++ Client Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-122.6.2.1 Developing the C++ Calculator Client Program . . . . . . . . . . . . . . . . . . . . . . . 2-122.6.2.2 Compiling and Running the C++ Calculator Demo Programs. . . . . . . . . . . 2-14

ii orb2 for C/C++ 3.8 User’s Guide

Contents

Chapter 3 Compiling IDL3.1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13.2 Running the stubgen IDL Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.2.1 Overriding the Supplied Preprocessor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Chapter 4 Initializing the ORB4.1 Writing the Initialization Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14.2 ORB Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14.3 Precedence of Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24.4 Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24.5 ORB Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34.6 Deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

4.6.1 Files Removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84.6.1.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84.6.1.2 Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

4.6.2 Deprecated Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-94.6.3 Deprecated Command-line Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10

Chapter 5 DII/DSI5.1 Static Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15.2 Dynamic Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15.3 Invoking Dynamic Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15.4 Receiving Requests Dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15.5 Dynamic Any's . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25.6 Performance Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25.7 Demonstration Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Appendix A C Language Mapping Specification TablesA.1 Summary of Argument/Result Passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Appendix B C++ Language Mapping Specification Tables

Appendix C Alternative Exception Handling in C++C.1 Deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1C.2 Callee Side Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2C.3 Caller Side Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3C.4 Portable Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3C.5 Anonymous Catch Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8C.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8

Appendix D Properties

Index

User’s Guide orb2 for C/C++ 3.8 iii

Contents

iv orb2 for C/C++ 3.8 User’s Guide

Contents

User’s Guide orb2 for C/C++ 3.8 iii

Figures

Figure 2.1 IDL for the Calculator Object (Calc.idl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Figure 2.2 Prototypes Generated for Calculator Operations . . . . . . . . . . . . . . . . . . . . . 2-4Figure 2.3 Code Generated for Calculator interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Figure 2.4 Prototypes Generated for Calculator Operations . . . . . . . . . . . . . . . . . . . . . 2-9

iv orb2 for C/C++ 3.8 User’s Guide

Figures

User’s Guide orb2 for C/C++ 3.8 v

Tables

Table 0.1 OMG Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 0-viiTable A.1 Basic Argument and Result Passing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Table A.2 Client Argument Storage Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2Table B.1 Basic Argument and Result Passing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-1Table B.2 T_var Arguments and Result Passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2Table B.3 Client Argument Storage Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2

vi orb2 for C/C++ 3.8 User’s Guide

Tables

User’s Guide orb2 for C/C++ 3.8 vii

About This Document

What is orb2 for C/C++?The orb2 for C/C++ product provides an Object Request Broker (ORB) that is compliant with the Common Object Request Broker Architecture (CORBA) Specification (Version 2.1) and the IDL/C/C++ Language Mapping Specification. In addition, the product provides an implementation of the CORBA Naming Services that is compliant with the CosNaming Specification.

The orb2 for C/C++ product supports the following features:

• CORBA IDL support• CORBA C/C++ language mapping• Multi-threading• Dynamic Invocation Interface• Dynamic Skeleton Interface• Naming and Trader Services• Simple configuration• Easily embedded

What does this guide include?This guide provides information on configuring and running the orb2 for C/C++ environment. It also provides some elementary documentation for CORBA developers. It does not purport to provide complete documentation of the CORBA specifications. These documents are freely available and should be understood by those that develop systems using this product. These documents are referenced in Section , OMG Documentation, below.

OMG DocumentationTable 0.1 lists documentation provided by the Object Management Group (OMG).

Table 0.1 OMG Documentation

Name Number Version

CORBA/IIOP formal/99-10-07 2.3

C Language Mapping formal/99-08-03 1.0

C++ Language Mapping formal/99-08-04 1.0

CORBA/IIOP formal/2001-09-34 2.5 (Chapter 22)

Naming Service formal/2002-09-02 1.2

About This Document Technical Support

viii orb2 for C/C++ 3.8 User’s Guide

Technical SupportYour feedback is important to us. Please provide input to the 2AB Technical Support Staff.

You can communicate comments to and request help from the Technical Support Staff via the following methods:

Telephone

U.S. or Canada:877.334.9572 (Toll Free)

All Other Countries:+1.205.621.7455

Email

[email protected]

User’s Guide orb2 for C/C++ 3.8 1-1

Chapter 1 Getting Started

This chapter will provide the information required to install, configure and run example systems that utilize orb2 for C/C++.

1.1 CORBA InteroperabilityThe orb2 for C/C++ product supports the OMG’s IIOP protocol. It supports version 1.0 and should interoperate with any ORB product that supports this protocol. This includes the orb2 for Java product.

1.2 Development EnvironmentThe following table describes the supported C/C++ compilers for each supported operating system:

For best results, it is recommended that you use the same compilers as listed here in your development environment.

1.3 Runtime EnvironmentThe Naming Service and eXplorer Console Management Service require the Java Runtime Environment (JRE) 1.4 or higher.

1.4 LicensingIn order to run any of the orb2 for C/C++ utilities or customer-written code, a valid license file containing appropriate license feature(s) must exist. A license file is available from 2AB, and you may receive it via email, download or on a CD-ROM.

OS/Version Compiler/Version

Windows NT4 MS Visual C/C++ v6.0

Windows 2000 MS Visual C/C++ v6.0

Windows XP MS Visual C/C++ v6.0

Linux 2.4 gcc 2.95.3

Solaris 2.7 Sun Workshop Compilers C v4.2 & C++ v4.2

Solaris 2.8 Sun Workshop Compilers C v4.2 & C++ v4.2

HP-UX 11 HP C, Advanced C++

AIX 5.1 Native compiler

VOS Continuum v14.0.2f Native compiler

OpenVMS v7.3 VMSAlpha C/C++ v6.5

Getting Started 1.5 Environment Variables

1-2 orb2 for C/C++ 3.8 User’s Guide

The license file will be named xxxxxx.lic where xxxxxx indicates the enterprise that owns the license. To install the license, copy the file into the lib subdirectory under the directory pointed to by environmental variable ORB2C. This is a binary file, so due care must be exercised when the file is transferred between systems, etc. Verify that only one file with the .lic extension exists in the directory.

The license file may contain one or more license features. The table below describes which license feature must be available to run each program.

Use the display_license program in the $ORB2C/bin directory to view the contents of your license file.

There are no other specific runtime requirements to enable you to develop and run orb2 applications. The applications you produce will be native executables that will run standalone.

1.5 Environment VariablesThere are several environment variables that must be set when using orb2 for C/C++. They are the JRE_HOME, ORB2, ORB2C and PATH variables. The paragraphs below describe the use of each of these variables. When getting started with orb2 for C/C++, it is best to set these variables.

The JRE_HOME and ORB2 environment variables are used by both the Naming Service and the eXplorer Console Management Service.

Several programs and/or scripts that are provided with the orb2 installation require that the ORB2C environment variable be set to the path of the installation directory. In particular, the Trader Service requires that this environment variable is set.

There are no specific requirements that any directories within the orb2 for C/C++ installation be included within a system’s path. If you plan to run orb2 executables from a command-line prompt, it is recommended that the system’s path include the bin subdirectory of the orb2 installation.

1.6 Locating ObjectsA client application that needs to communicate with a distributed object must first obtain an object reference for the target object before it can invoke operations upon that object. This chapter discusses three techniques that can be used to obtain object references for distributed objects. They are getting stringified object references, using a Naming Service and using a Trader Service. There are other techniques that could be used, such as objects providing references for other objects in the same service, but these other techniques will not be discussed in this chapter.

Application Required License Feature

Customer-written program, demo programs orb2 for C/C++ Runtime

Trader, Node Manager and associated clients, etc.orb2 for C/C++ Runtime ororb2 for Java Runtime ororb2 for Eiffel Runtime

Stubgen -lc or stubgen (default langauge) orb2 for C/C++ SDK

Stubgen -lc++ orb2 for C/C++ Runtime

Stubgen -ljava Disabled. Use idlc instead.


1.6.1 Stringified Object References Getting Started

1.6.1 Stringified Object ReferencesA service that creates an object reference may create a textual representation of that object reference that is referred to as a stringified object reference. Once a stringified object reference has been created, it can be communicated to clients through a variety of means. It may be file transferred to another machine, e-mailed or it might even be stored in a well-known place on a file system.

Using an ORB's object_to_string method creates stringified object references.

Example

Clients that want to use stringified object references must have prior knowledge of where the stringified object reference can be obtained (e.g. from a specified file). Once the stringified object reference has been obtained, it can create the object reference with the ORB's string_to_object method. This would be done as follows:

An ior_string may be formatted in corbaloc: or IOR: syntax.

The corbaloc: syntax is much easier for humans to read and is structured "corbaloc::hostname:port/WellKnownName." Hostname and port describe where the service is located, and WellKnownName is one of the strings "orb2_Trader" or "NameService." These are the only values supported in orb2 for C/C++ at this time.

The IOR: syntax is a string of hex characters that represent the Object Reference.

1.6.2 Naming ServiceThe OMG provides a specification for a Naming Service that allows object references to be stored in a hierarchical name tree. Services may store object references using a Naming Service, and client applications may retrieve object reference if they understand the naming scheme used by the service. A complete description on the use of the OMG's Naming Service can be found in the OMG's Naming Service Specification. This document is retrievable as the file "formal/2002-09-02."

The orb2 product provides an implementation of the OMG's Naming Service. This service is built using C/C++ and can be run with a Java 1.3 or higher interpreter. By default, the Naming Service uses TCP/IP port 9999 and stores its persistent data in the naming.db file located in the installation’s lib subdirectory.

Complete information required to configure, run and develop clients that use the Naming Service can be found in the orb2 Core Services Guide.

1.6.3 Trader ServiceThe Trader Service provides the means for a client to retrieve one or more object references that match both a specified service type and some arbitrary set of constraints.

Complete information required to configure, run and develop clients that use the Trader Service can be found in the orb2 Services Guide.

org.omg.CORBA.Object obj = ??? // object reference created in some mannerString ior = orb.object_tostring(obj); // create the stringified object reference

org.omg.CORBA.Object obj = orb.string_to_object(ior_string);

Getting Started 1.7 Demonstration Programs


1.7 Demonstration ProgramsThe orb2 for C/C++ product provides demonstration programs that provide examples of using some aspect of its functionality. These demonstration programs are located in the demos subdirectory of the orb2 for C/C++ installation directory.

Each demonstration program has a Readme file that provides instructions for building and running the demo. For those demonstration programs that have been pre-built, it is only necessary to rebuilt the programs if the source code is changed.


Chapter 2 Developing aDistributed orb2

Application

This chapter will discuss the steps required to build a distributed client-server system using orb2 for C/C++. This will be demonstrated by constructing a Calculator server that performs arithmetic calculations and returns results to client applications. Three versions of this implementation are provided in the demos subdirectory. These three demo systems are identical with the exception of how object references are located. The Simple demo stores the server references in a file, the Trading demo stores the server reference in the Trader Service and the Naming demo stores the server references in the Naming Service.

The principals of building distributed applications that take advantage of the orb2 for C/C++ facilities are also introduced. It uses the code in the demonstration programs to show you how to:

• Describe object interfaces using the Interface Definition Language (IDL).• Compile the IDL using the orb2 for C/C++ IDL compiler to produce stub and

skeleton code.• Develop servant programs that provide the object implementations.• Develop a client application that uses the servant program.• Use different techniques to locate objects.• Compile the C/C++ programs.• Run the distributed application.

2.1 InterfacesYou use IDL to describe the interface for each component in a CORBA environment. The interface describes how a user of the component, the client, communicates with the server component...not how the component is implemented.

The IDL for the calculator, which you can find in the Calc.idl file, is shown in Figure 2.1. It defines a module, Demos, that has one interface, Calculator, and defines one exception, DivideByZero. The Calculator interface defines five methods or operations. They are add, subtract, multiply, divide and kill.

Developing a Distributed orb2 Application 2.2 Compiling IDL


Notice that the divide operation raises the DivideByZero exception if division by zero is attempted. Also notice that the kill operation is marked as being oneway, which means that client applications do not wait for a response.

When you compile this IDL file using the orb2 IDL compiler (stubgen), it produces C or C++ source files that are referred to as stubs and skeletons. Stubs are files used by the client application. Skeletons are files used by the server application.

2.2 Compiling IDLorb2 for C/C++ includes an IDL compiler that produces pure C/C++ code based on the CORBA IDL-to-C/C++ mapping specification. When you execute the orb2 IDL compiler, it generates two sets of C or C++ source files, stub code for clients and skeleton code for the server.

• The stub code creates proxy objects that a client can use to invoke object reference of the interface types defined in the IDL file.

• The skeleton code provides access to objects that support those interfaces.

The orb2 IDL compiler is called stubgen.

A license feature must exist in your license file to run stubgen. Please see Section 1.4, Licensing, for more details.

To compile the IDL file, Calc.idl, and generate C stubs and skeletons, issue the following command:

stubgen -t -lc Calc.idl

This results in the following files:

Calc.ht_Calc.hm_Calc.hm_Calc.cs_Calc.cc_Calc.c

To compile the IDL file, Calc.idl, and generate C++ stubs and skeletons, issue the following command:

stubgen -t –lc++ Calc.idl

This results in the following files:

module Demos {exception DivideByZero { string reason; };interface Calculator {

// Operation declarations:long add(in long op1, in long op2);long subtract(in long op1, in long op2);long multiply(in long op1, in long op2);long divide(in long op1, in long op2, out long res_1)

raises (DivideByZero);

// kill myself:oneway void kill();

};};

Figure 2.1 IDL for the Calculator Object (Calc.idl)


2.3 C Code Generated by stubgen Developing a Distributed orb2 Application

Calc.hppm_Calc.cpps_Calc.cppc_Calc.cppCalcSrv.cpp

By default, all files are generated in the current directory. When you specify the –t command-line argument, the CalcSrv.cpp source file is also generated. You may rename this file and modify it in order to use it as your starting point in developing your server.

Note Do not modify any of the other generated files! This is internal orb2 code.

2.3 C Code Generated by stubgenSince there is no concept of objects in C, the stubgen program simply declares function prototypes for each of the operations described in the IDL. The name of each function is derived so: ModuleName_InterfaceName_Operation. For instance, Demos_Calculator_add is the add operation of the Calculator interface in the Demos module.

//Calc.hCORBA_long Demos_Calculator_add (

Demos_Calculator obj,CORBA_long arg1,CORBA_long arg2,CORBA_Environment *ev );

CORBA_long Demos_Calculator_subtract (Demos_Calculator obj,CORBA_long arg1,CORBA_long arg2,CORBA_Environment *ev );

CORBA_long Demos_Calculator_multiply (Demos_Calculator obj,CORBA_long arg1,CORBA_long arg2,CORBA_Environment *ev );

CORBA_long Demos_Calculator_divide (Demos_Calculator obj,CORBA_long arg1,CORBA_long arg2,CORBA_long* arg3,CORBA_Environment *ev );

void Demos_Calculator_kill (Demos_Calculator obj,CORBA_Environment *ev );

CORBA_long S_Demos_Calculator_add (Demos_Calculator _obj,CORBA_long arg1,CORBA_long arg2,CORBA_Environment* ev

Developing a Distributed orb2 Application 2.4 Developing C Programs


As shown in Calc.h, function prototypes are provided for each of the operations declared in the Calc.idl IDL file. Notice that both client and server prototypes are generated. Other methods are also declared, but that is not important for this demonstration.

2.4 Developing C Programs

2.4.1 Developing C Server ProgramsFor each server object, a servant must exist that implements the operations of the CORBA object. The servant provides the implementation of the operations described for the CORBA object interface.

You write the functions that implement each operation. The function prototypes are already declared in Calc.h, however, you must ensure that the functions you write match the prototypes. If you used the –t command-line argument to stubgen, then a source file was generated to provide you a starting point.

2.4.1.1 Developing the C Calculator Server ProgramThe Server.c file contains the server startup code (in the main method) and the Calculator_Imp class that inherits from the skeleton class. This section describes the significant code in the example.

1. Begin the main program.

2. Initializes an instance of the ORB.

);CORBA_long S_Demos_Calculator_subtract (

Demos_Calculator _obj,CORBA_long arg1,CORBA_long arg2,CORBA_Environment* ev

);CORBA_long S_Demos_Calculator_multiply (

Demos_Calculator _obj,CORBA_long arg1,CORBA_long arg2,CORBA_Environment* ev

);CORBA_long S_Demos_Calculator_divide (

Demos_Calculator _obj,CORBA_long arg1,CORBA_long arg2,CORBA_long* arg3,CORBA_Environment* ev

);void S_Demos_Calculator_kill (

Demos_Calculator _obj,CORBA_Environment* ev

);EXTERN DAIS_ImplementationDef DAIS_Demos_Calculator_impl;EXTERN DAIS_InterfaceDef DAIS_Demos_Calculator_intf;

Figure 2.2 Prototypes Generated for Calculator Operations

/* initialize the orb */CORBA_ORB_init( &argc, argv, "ORB2", &ev);


2.4.1 Developing C Server Programs Developing a Distributed orb2 Application

The CORBA_ORB_init() function is a static member function. It initializes the ORB and returns an ORB instance.

The first parameter of CORBA_ORB_init() is a pointer to argc, the count of command-line arguments.

The second parameter is the pointer to the list of command-line arguments to the program.

The third parameter is the name of the ORB, in this case ORB2. This distinguishes orb2 from any other ORB.

The argc and argv parameters will be modified by CORBA_ORB_init so that any command-line arguments that were understood by orb2 will be removed. The arguments which remain will be in the sequence as supplied at the command line and are available for the application to use in any conventional manner.

3. Create an object and save the reference in a global variable (obj).

4. Save the object reference so that client applications can locate the component. The Simple demonstration saves the reference in a file as follows:

5. The Trading demonstration must first locate the object reference for the Trader Service and register the object reference with the Trader Service.

6. The Naming demonstration must first locate the object reference for the Naming Service and register the object reference with the Naming Service.

The first step is to locate the object reference for the Naming Service. This is achieved by calling resolve_initial_references as shown:

/* create an Object */obj = CORBA_BOA_create(DAIS_boa, id, DAIS_Demos_Calculator_intf,DAIS_Demos_Calculator_impl, &ev);

/* create an Interoperable Object Reference (IOR) from theimplementation object */ior = CORBA_ORB_object_to_string(DAIS_orb,obj,&ev);

/* put IOR into a file so the client can access it */server_ior = fopen("server.ior","w");fprintf(server_ior,"%s",ior);

/* cleanup */fclose(server_ior);CORBA_free(ior);

/* put the Calculator object reference into the Trader */Trading_export(DAIS_trader, obj, "Calculator", "/", "", &ev );

naming_obj = CORBA_ORB_resolve_initial_references(orb, "NameService", &ev);

switch (ev._major){case CORBA_NO_EXCEPTION :

printf("Got NameService initial reference!\n");printf(" NameService IOR: %s\n",

CORBA_ORB_object_to_string(orb, naming_obj, &ev) );break;

default :

Developing a Distributed orb2 Application 2.4.2 Developing C Client Programs


This example contains a printf() call (on success) that should be removed in a production implementation. This can only work if the orb.properties file contains an IOR for the Naming Service as shown here:

com.twoab.orb2.initial_ref=NameService=IOR:000000000000002B49444C3A6F6D672E6F7267...

Register the Calculator Service with the Naming Service.

7. The ORB listens for requests. The DAIS_schedule function waits for requests; the function returns only after ORB.shutdown is called.

8. The Calculator implementation code implements the operations specified in the Calculator interface with the Calculator_Impl class inheriting from the Calculator_sk class generated by the orb2 IDL compiler.

The generated CalcSrv.cpp source file implements a method for each of the operations, along with a comment to show where your implementation code needs to be placed.

2.4.2 Developing C Client ProgramsDeveloping client applications is simply a matter of obtaining an object reference for some distributed component and then using that object reference to invoke remote operations.

The manner in which one locates an object reference depends on the manner in which the server programs make them available. The Simple, Trading and Naming demonstration programs illustrate three common methods of making the object reference of a service available to a client application. They are:

• Write stringified copies of the object reference to a file.• Use the Trader Service.• Use the Naming Service.

2.4.2.1 Developing the C Calculator Client ProgramThe demonstration Calculator clients (Simple, Naming and Trading) run as command-line applications. The client application accepts command-line parameters for the arithmetic calculation to be performed and passes these parameters to the Calculator server. When the Calculator server returns the result, the client application displays the result on the console window.

A CORBA client application performs these basic steps:

• Initializes the orb2 ORB.• Obtains the object reference for the object on which it wants to invoke

operations.• Invokes the operations and processes the results.• Releases the object reference and shuts down the ORB.

printf("Got exception while resolving initial references: %s\n",

CORBA_exception_id(&ev) );CORBA_exception_free(&ev);break;

}

// put the Calculator object reference into the Naming ServiceCosNaming_NamingContext_bind (naming_obj, “Demos”, calc_obj, ev);


2.4.2 Developing C Client Programs Developing a Distributed orb2 Application

The following are excerpts from the client code for the Calculator console. Refer to the Client.c files in the demos/c/simple, demos/c/trading and demos/c/naming directories for the complete program.


The CORBA_ORB_init() function is a static member function. It initializes the ORB and returns an ORB instance.



The third parameter is the name of the ORB, in this case, ORB2. This distinguishes orb2 from any other orb.


2. You can use several techniques to locate object references, the Simple demonstration obtains the object reference from a file.

3. In the Trading demonstration, the object reference is obtained from the Trader Service.


/* get the Interoperable Object Reference (IOR) from the file where the server put it */server_ior = fopen("server.ior","r");ior = CORBA_string_alloc(1000);fgets(ior,1000,server_ior);

/* setup an implementation object from the IOR */obj = CORBA_ORB_string_to_object(DAIS_orb, ior, &ev);

/* get the Calculator object reference from the Trader */calc_obj = (Demos_Calculator) Trading_import(DAIS_trader, "Calculator", "/", "", &ev);

Developing a Distributed orb2 Application 2.4.2 Developing C Client Programs


4. In the Naming demonstration, the object reference is obtained from the Naming Service.

5. Perform the requested calculator operations by invoking the methods provided by the object reference returned by the Trader. The servant performs the calculation, and the result is returned to the client. The client prints to the standard output. System and user exceptions that are raised are caught and processed.

6. When processing is complete, the application needs to release the Calculator and Naming object references and shut down the ORB.


switch (ev._major){case CORBA_NO_EXCEPTION :

break;default :

printf("Got exception while resolving initial references: %s\n",


}

/* get the Calculator object reference from the Naming Service */calc_obj = CosNaming_NamingContext_resolve(naming_obj,

&cosNaming_name, &ev);

switch (ev._major){

case CORBA_NO_EXCEPTION :break;

default :printf("Got exception while obtaining Calculator IOR:

%s\n",CORBA_exception_id(&ev) );

CORBA_exception_free(&ev);break;

}

switch(operation) {case 'K':

Demos_Calculator_kill(calc_obj, &ev);break;case '+':sum = Demos_Calculator_add(calc_obj, operand1, operand2,

&ev);fprintf(stdout, "Result: %ld %c %ld = %ld\n", operand1,

operation, operand2, sum);fflush(stdout);

break;.../* See example for remaining implementation code. */}

/* cleanup */ CORBA_Object_release(naming_obj, &ev);CORBA_Object_release(calc_obj, &ev);

CORBA_exception_free(&ev);

DAIS_schedule(); return 0;


2.5 C++ Code Generated By stubgen Developing a Distributed orb2 Application

2.4.2.2 Compiling and Running the C Calculator Demo ProgramsThe Readme files for the Simple, Trading and Naming demonstration programs each provide complete instruction for compiling and running the client and server programs.


2.5 C++ Code Generated By stubgenThe Calc IDL interface is mapped to a C++ interface of the same name (Calc.cpp). As the generated code in Figure 2.3 illustrates, the Calculator interface extends a base class for a CORBA object.

The code generated in the CalculatorOperations.cpp file defines the operations supported by the interface.

The Demos package contains the skeleton code for supporting the Basic Object Adapter (BOA) interface. The classes generated from the application-supplied implementation class support inheritance-based relationships between the object and servant.

struct Demos {

class Calculator :

public virtual CORBA::Object

{

…

}

}

Figure 2.3 Code Generated for Calculator interface

public:

virtual CORBA::Long add (

CORBA::Long,

CORBA::Long COMMA ETYPE) = 0;

virtual CORBA::Long subtract (

CORBA::Long,


virtual CORBA::Long multiply (

CORBA::Long,


virtual CORBA::Long divide (

CORBA::Long,

CORBA::Long,

CORBA::Long& COMMA ETYPE) = 0;

virtual void kill (ETYPE) = 0;

Figure 2.4 Prototypes Generated for Calculator Operations

Developing a Distributed orb2 Application 2.6 Developing C++ Programs


As shown in Calc.hpp, the Calculator class declares a virtual method for each operation described in Calc.idl. Other methods are also declared, but that is not important for this demonstration.

2.6 Developing C++ Programs

2.6.1 Developing C Server ProgramsFor each server object, a servant must exist that implements the operations of the CORBA object. The servant provides the implementation of the operations described for the CORBA object interface.

You write an implementation class to define an implementation in C++. If you used the –t command-line argument to stubgen, then a source file was generated to provide you a starting point.

Instances of the implementation class implement the IDL interfaces. The implementation class must define public methods that correspond to the operations and attributes of the IDL interface supported by the object implementation (as defined by the mapping specification for IDL interfaces). Providing these methods satisfies the abstract methods defined by a specific interface skeleton class.

2.6.1.1 Developing the C++ Calculator Server ProgramThe Server.cpp file contains the server startup code (in the main method) and the Calculator_Imp class that inherits from the skeleton class. This section describes the significant code in the example.

1. Begin the main program.


The CORBA_ORB_init() function is a static member function in the ORB class. It initializes the ORB and returns an ORB instance.





3. Instantiate an instance of the implementation object and save the reference in a global variable (iObject).



2.6.1 Developing C Server Programs Developing a Distributed orb2 Application

4. Save the object reference so that client applications can locate the component. The Simple demonstration saves the reference in a file as follows.

5. The Trading demonstration must first locate the object reference for the Trader Service and register the object reference with the Trader Service.

6. The Naming demonstration must first locate the object reference for the Naming Service and register the object reference with the Naming Service.

The first step is to locate the object reference for the Naming Service. This is achieved by calling resolve_initial_references as shown:

This example contains a printf() call (on success) that should be removed in a production implementation. This can only work if the orb.properties file contains an IOR for the Naming Service as shown here:

com.twoab.orb2.initial_ref=NameService=IOR:000000000000002B49444C3A6F6D672E6F7267...

Register the Calculator Service with the Naming Service.

7. The ORB listens for requests. The orb->schedule function waits for requests; the function returns only after ORB.shutdown is called.

8. The Calculator implementation code implements the operations specified in the Calculator interface with the Calculator_Impl class inheriting from the Calculator_sk class generated by the orb2 IDL compiler.

The generated CalcSrv.cpp source file implements a method for each of the operations, along with a comment to show where your implementation code needs to be placed.

// create an Interoperable Object Reference (IOR) from the implementation objectCORBA::String_var ior = orb->object_to_string(iObject);

// put the IOR into a file so the client can access itofstream out ("server.ior");out << ior << endl;out.close ();

// put the Calculator object reference into the TraderpTrader._EXPORT (iObject,"Calculator","/","");


switch (ev._major){

case CORBA_NO_EXCEPTION :printf("Got NameService initial reference!\n");printf(" NameService IOR: %s\n",

CORBA_ORB_object_to_string(orb, naming_obj, &ev) );break;

default :printf("Got exception while resolving initial

references: %s\n",CORBA_exception_id(&ev) );


}

// put the Calculator object reference into the Naming ServiceCosNaming_NamingContext_bind (naming_obj, “Demos”, calc_obj, ev);

Developing a Distributed orb2 Application 2.6.2 Developing C++ Client Programs


2.6.2 Developing C++ Client ProgramsDeveloping client applications is simply a matter of obtaining an object reference for some distributed component and then using that object reference to invoke remote operations.

The manner in which one locates an object reference depends on the manner in which the server programs make them available.

The Simple, Trading and Naming demonstration programs illustrate three common methods of making the object reference of a service available to client application. They are:

• Write stringified copies of the object reference to a file.• Use the Trader Service.• Use the Naming Service.

2.6.2.1 Developing the C++ Calculator Client ProgramThe demonstration Calculator clients (Simple, Naming and Trading) run as command-line applications. The client application accepts command-line parameters for the arithmetic calculation to be performed and passes these parameters to the Calculator server. When the Calculator server returns the result, the client application displays the result on the console window.

A CORBA client application performs these basic steps:

• Initializes the orb2 ORB.• Obtains the object reference for the object on which it wants to invoke

operations.• Invokes the operations and processes the results.• Releases the object reference and shuts down the ORB.

The following are excerpts from the client code for the Calculator console. Refer to the Client.cpp files in the demos/cpp/simple, demos/cpp/trading and demos/cpp/naming directories for the complete program.


The CORBA::ORB_init() function is a static member function in the ORB class. It initializes the ORB and returns an ORB instance.

The first parameter of CORBA::ORB_init() is a pointer to argc, the count of command-line arguments.The second parameter is the pointer to the list of command-line arguments to the program.


The argc and argv parameters will be modified by CORBA::ORB_init so that any command-line arguments that were understood by orb2 will be removed. The arguments which remain will be in the sequence as supplied at the command line, and are available for the application to use in any conventional manner.

/* initialize the orb */CORBA::ORB_init( argc, argv, "ORB2");


2.6.2 Developing C++ Client Programs Developing a Distributed orb2 Application

2. You can use several techniques to locate object references. The Simple demonstration obtains the object reference from a file.

3. In the Trading demonstration, the object reference is obtained from the Trader Service.

4. In the Naming demonstration, the object reference is obtained from the Naming Service.

// get the Interoperable Object Reference (IOR) from the file wherethe server put itifstream in ("server.ior");char ior[1000];in >> ior;in.close ();

// setup an implementation object from the IORCORBA::Object_var iObject = orb->string_to_object(ior);

// assign the implementation object to a pointer and release the originalpCalc = Demos::Calculator::_narrow (iObject);CORBA::release (iObject);

// get the Calculator object reference from the TraderDAIS_Trader pTrader;CORBA::Object_ptr pObject;

try {

pObject = pTrader.import ("Calculator", "/", "");}catch (CORBA::Exception &ex){

cout << "Exception Occurred: " << ex ._get_id() << endl;}

// assign the implementation object to a pointer and release the originalpCalc = Demos::Calculator::_narrow (pObject);CORBA::release (pObject);


switch (ev._major){


default :printf("Got exception while resolving initial

references: %s\n",CORBA_exception_id(&ev) );


}

/* get the Calculator object reference from the Naming Service */calc_obj = CosNaming_NamingContext_resolve(naming_obj,

&cosNaming_name, &ev);

switch (ev._major){


default :

Developing a Distributed orb2 Application 2.6.2 Developing C++ Client Programs


.

5. Perform the requested calculator operations by invoking the methods provided by the object reference returned by the Trader. The servant performs the calculation and the result is returned to the client. The client prints to the standard output. System and user exceptions that are raised are caught and processed.

6. When processing is complete, the application needs to release the Calculator object reference and shuts down the ORB.

2.6.2.2 Compiling and Running the C++ Calculator Demo ProgramsThe Readme files for the Simple, Trading and Naming demonstration programs each provide complete instruction for compiling and running the client and server programs.

A license feature must exist in your license file to run each demo program. Please see Section 1.4, Licensing, for more details.

printf("Got exception while obtaining Calculator IOR: %s\n",


}

switch(operation) {case 'K':

Demos_Calculator_kill(calc_obj, &ev);break;case '+':

sum = Demos_Calculator_add(calc_obj, operand1, operand2, &ev);

fprintf(stdout, "Result: %ld %c %ld = %ld\n", operand1, operation, operand2, sum);

fflush(stdout);break;.../* See example for remaining implementation code. */

}

/* cleanup */CORBA_Object_release(naming_obj, &ev);CORBA_exception_free(&ev);

DAIS_schedule();return 0;


Chapter 3 Compiling IDL

3.1 IntroductionCORBA-based services implement interfaces that are specified by the Interface Definition Language, which is referred to as IDL. The syntax and semantics of IDL are described completely in the OMG CORBA/IIOP specification.

An IDL compiler is used to interpret the IDL that defines a service and generates stub and skeleton class files that are used by both the service and its client applications. Client applications use the generated stub classes. Services use the generated skeleton classes.

3.2 Running the stubgen IDL CompilerThe orb2 IDL compiler is called stubgen.


Format

stubgen [flags]IDLfile

The [flags] are used to modify the default behavior of the compiler.Flags

-e Use IDL file name and not interface name to generate stub file names.This is the default behavior, the flag is provided simply for backward compatibility.

-l<lang> Language-specific stub and skeleton generation.where <lang> is one of

c c++ com eiffel

Only a subset of these are available, depending on which orb2 product you have installed.

-F<preproc> Overrides the supplied preprocessor. See Section 3.2.1, Overriding the Supplied Preprocessor.

-gx If specified, the compiler adds CORBA standard prefixes to the interface repository identifiers for certain predefined CORBA types. Specifying this option ensures interoperability with other ORBs and is recommended for all new development. However, servers built using this option will not interface correctly to C or C++ clients built with earlier versions of orb2.

-g!x Generate unprefixed identifiers (default).-h Output generated header files in the specified directory.

The default effect is that all header files are generated in the current working directory. This flag permits an alternative directory to be specified.

Compiling IDL 3.2 Running the stubgen IDL Compiler


-m Check mixing of float and integer in expressions. When this flag is set, the CORBA compiler reports an error if an attempt is made to mix integers and floats in a constant expression such as

Const short Value = 4*72/3+2.3;

Otherwise, the compiler truncates as necessary.-n Switch on case sensitivity for identifier names. The default

behavior of the compiler does not differentiate between identifier names on case alone. Therefore, NaMe and name are considered equivalent. This behavior may be modified using the -m flag to be CORBA conformant.

-o Output suppression; semantic check only. Produces no generated code output. However, all the semantic checking is still performed.

-r Suppress relocation code in client stubs.By default each client stub file (c_xxxx.cpp) contains code to enable relocation to be attempted on failure of an invocation. This attempted relocation increases the overhead of the invocation on failure. On some Interfaces such relocation code may not be necessary and this flag can be used to suppress such behavior.

-s Strict CORBA conformance; equivalent to -n -m. Combines the behavior of the -n and -m flags so that both are enforced.

-t Produce prototype server template file.When set, this flag causes the compiler to generate a template file with the name FileSrv.cpp (where File is the name of the original IDL file) which contains templates of all the necessary server implementation routines that developers can use as the basis of their own implementations.

-x Produce extended skeletons.For C++, skeletons are produced for interworking with intra-capsule implementations written in C. Implementations written in C conform to specific signatures for which code must be generated within the skeleton upcall dispatcher.


3.2.1 Overriding the Supplied Preprocessor Compiling IDL

Example The following is an example UNIX command line (assuming $ORB2C is set in your environment)

stubgen -lc++ -I$ORB2C/idl -I/usr/dev/interfaces Intrst.idl

this passes the file Intrst.idl into the CORBA compiler and sets up the paths $ORB2C/idl and /usr/dev/interfaces for #include or #import files. The generated output is for the C++ mapping.

3.2.1 Overriding the Supplied PreprocessorAs part of the IDL compilation process, stubgen passes each IDL file through a preprocessor. As a convenience to the user, each orb2 SDK includes a preprocessor built from sources derived from those in Fraser and Hanson’s lcc. Refer to A Retargetable C Compiler: Design and Implementation, Addison-Wesley, 1995, ISBN 0-8053-1670-1 for full details of lcc. You can, however, arrange to use an alternative preprocessor provided that it

• Accepts -D and -I parameters for macro definitions and includes file directories exactly as stubgen accepts them.

• Reads its input from a named file not identified by any explicit preprocessor flag.

• Writes preprocessed text to standard output.• Accepts C++-style comments as well as C-style comments.

You can then override the supplied preprocessor in one of two ways

• Supply the name of the preferred preprocessor using the -F parameter of stubgen. This name can also include any flags needed to drive the supplied program in the desired manner. To use the Microsoft Visual C++ compiler, you could write

-c <dir> Output generated source files in the specified directory. By default, all source files are generated in the current working directory. This flag specifies an alternative directory.

-I <dir> Allows users to specify additional paths that the compiler searches to locate other .idl files needed for #include or #import. You can use this as often as required to specify multiple directories.

Example

stubgen -I. -I/usr/idl -I$ORB2C/idl test.idl

-D <defines> Allows users to present optional constant definitions to the CORBA compiler.Format

-Dname[=value]

This constant definition is processed by the preprocessor. You can used it to conditionally change the IDL syntax presented to the compiler. The command-line value overrides any equivalent value encountered within the file.

Example

// File.idl#ifdef _do_it // some IDL syntax#endif

Only processed if -D_do_it appears on the command-line.

IDLfile Text file that contains valid IDL syntax with an extension suffix of .idl.

Compiling IDL 3.2.1 Overriding the Supplied Preprocessor


stubgen -F"cl /nologo /E"• Supplied preprocessor is named cpp or cpp.exe and is stored in the orb2 bin

directory. You can replace the supplied preprocessor with a copy of, or a link to, your preferred preprocessor. The copy or link must also be named cpp or cpp.exe.

If your preferred preprocessor does not follow the above conventions, you can code a wrapper script that does and have it called as outlined above.


Chapter 4 Initializingthe ORB

Both client and server applications that utilize CORBA must initialize an ORB within their programs. The parameters that are used to initialize an ORB are obtained from command-line arguments, environment variables and a properties file. A property is a name-value pair that defines the property name and its value. This chapter will describe the command-line parameters and properties that can be used to initialize an orb2 ORB.

4.1 Writing the Initialization Softwareorb2 is initialized in the following manner:




The argc and argv parameters will be modified by CORBA_ORB_init so that any command-line arguments that were understood by orb2 will be removed. The arguments which remain will be in the sequence as supplied at the command line, and are available for the application to use in any conventional manner.

The main thing to remember is that the environment variable ORB2C must be set in order for orb2 to locate the default orb.properties file.

This is the only environment variable that will continue to be used in subsequent releases of orb2 for C/C++. Please see Section 4.6, Deprecation, for important information regarding deprecated options.

4.2 ORB Properties FilesA properties file is a text file that contains one or more name-value pairs each representing a property name and value. Properties are the preferred method for configuring orb2. An ORB properties file would look something like the following:


com.twoab.orb2.trader.hostname=myhostcom.twoab.orb2.trader.port=11001com.twoab.orb2.trader.netid=myhostcom.twoab.orb2.trader.protocol_pref=IIOP TCP UDPcom.twoab.orb2.log_dir_name=d:\orb2_350\logs

Initializing the ORB 4.3 Precedence of Properties


4.3 Precedence of PropertiesSince ORB properties can be obtained from various means, there is a precedence order in obtaining and using the properties. The following is a list of means to obtain properties. It is listed from highest to lowest precedence. If the same property is defined in two places, the place with the higher precedence will determine the property value.

• Command-line arguments.• Properties file (defined by --ORBconfig argument, or defaulted to

$ORB2C/orb.properties).• Environment Variables.• Hardcoded defaults (described below).

4.4 Command-Line ArgumentsWhen a CORBA-based client or server application initializes an ORB, it passes the command-line arguments as a parameter to the initialization method. These command-line arguments are parsed during ORB initialization to determine if any are supported by the ORB’s implementation. Most command-line arguments have equivalent ORB property definitions. The following are command-line arguments that are supported by orb2 for C/C++.

--ORBdebug_level <num>

Sets the detail level of the debug messages that can be produced from orb2. The default is 0 (no debug messages), and any value of 5 or above is very verbose!

--ORBdebug_file <path>

Specifies the path of a file where debug information is to be written. If debugging is activated and this argument is not specified, debug information will be directed to the standard output device (e.g. console).

--ORBconfig

Specifies an alternate properties file.

--ORBid <orb_id>

Specifies a string that will be used to identify this ORB.

--ORBInitRef <reference_info>

Specifies information about services whose object references can be obtained via the resolve_initial_references method. The reference information is in the form of:

name=url

where name is the name of the service that will be specified in resolve_intial_references (e.g. Naming Service), and url is the URL formatted object reference. The orb2 product supports the “ior" URL format as specified by the OMG’s CORBA specification.

This command-line argument may be used multiple times when starting an application.

--ORBport <port_number>

Specifies the port number that will be used to listen for incoming requests for objects created using this ORB.


4.5 ORB Properties Initializing the ORB

--ORBpthread

See property com.twoab.orb2.pthread for details.

--ORBtasks

See property com.twoab.orb2.tasks for details.

Note Please see Section 4.6, Deprecation for important information regarding deprecated options.

4.5 ORB PropertiesWhen an ORB is initialized, it uses configuration information from properties that are passed directly to the CORBA_ORB_init method or properties that are obtained from special configuration files. The following sections describe the configuration properties that are supported by the orb2 for C/C++ product.

The following properties configure orb2 for use with client applications and/or services.

com.twoab.orb2.connect_attempt_delay

Default: 2.

Number of seconds that a server should wait before retrying a failed connection.

com.twoab.orb2.connect_attempts

Default: 2.

Number of times that a server should try to connect in order to return a response to the client.

com.twoab.orb2.connect_timeout

Default: 2.

Number of seconds that a server should wait for a response from the client before determining that the client has “died”.

com.twoab.orb2.console

Default for Windows: Yes. Default for all others: No.

Determines if this process is running in a Windows Console. Used only in Windows.

com.twoab.orb2.debug.file

Default: stdout.

The path and name of the file to which debug messages will be written.

com.twoab.orb2.debug.iiop_msg_buffer_size

Default: 96

Number of bytes of the IIOP message written out in debug messages. Only available for IIOP messages.

com.twoab.orb2.debug.level

Default: 0 (no debug messages)

Sets the level of detail of debug messages. Maximum practical level is 5, which is very verbose!

Initializing the ORB 4.5 ORB Properties


com.twoab.orb2.factory.timeout

Default: 10

Number of seconds that the Factory waits for a server to start.

Number of seconds that the Node Manager waits for its invocations to complete.

com.twoab.orb2.giop.timeout

Default: 5 seconds

Number of seconds after which sending or receiving IIOP connections are timed out if they have not completed.

com.twoab.orb2.host

Default: The system hostname.

The hostname or IP address that the orb2 service can listen on for requests. The orb2 service can listen on only one interface.

This property affects user-built services as well as 2AB-supplied services (such as Trader, etc.)

If you specify a hostname, it must resolve to an IP address that is local on this machine.

If you specify an IP address, it must be an IP address that is local on this machine.

If the hostname is not resolvable, or the IP address is not local, the service will fail to start.

com.twoab.orb2.iiop.socket_size

Default: 65535

Maximum size of each packet; messages larger than this value will be fragmented.

com.twoab.orb2.inactivity_seconds

Default: 0

If set, the process terminates if there is no message activity in this number of seconds.

com.twoab.orb2.initial_ref=name=IOR:xxxx

Default: None

Use this property to make an Object Reference available to the resolve_initial_references() function. It is a name/value pair.

The name is the text that identifies the service (such as NameService).

The value is the stringified IOR that identifies the service.

This will allow an application to call resolve_initial_references for the NameService and obtain the Object Reference for the service.

com.twoab.orb2.language

Default: English

Language to write messages in for internationalization. Valid values: english, jpn_ecu, jpn_sjis.

com.twoab.orb2.license.dir

Default: $ORB2C



Identifies the directory in which a license file may be found.

com.twoab.orb2.master.hostname

Default: none.

Identifies to clients the hostname where the master trader is running.

com.twoab.orb2.master.port

Default: none.

Identifies to clients the port on the host where the master trader is running.

com.twoab.orb2.master.pref

com.twoab.orb2.mps.timeout

Default: 5

Number of seconds that TCP connections are timed out if they have not completed.

com.twoab.orb2.orb_id

Default: ORB2

The ID of this orb, to distinguish from all others.

com.twoab.orb2.port

Default: None

The port number that the orb2 service will listen on for requests.

This property affects user-built services as well as 2AB-supplied services (such as Trader, etc.)

com.twoab.orb2.protocol_pref

Default: IIOP TCP UDP

Preferred protocol that the client or service uses when communicating with other processes.

com.twoab.orb2.pthread

Default: no.

Initializes the ORB to run preemptively using native operating system threads.

All orb2 APIs concerned with threading perform preemptively and may be freely intermixed with any native system calls. The default, if not set, is that the ORB uses non-preemptive threads; that is, the ORB uses native threads and schedules them non-preemptively.

com.twoab.orb2.queuesize

Default: 10000

This is the maximum size that the internal “pending requests” queue can be. Requests are placed in this queue when a service is too busy to service the request immediately.

com.twoab.orb2.tasks

Default: 1.

Sets the ceiling on the total process concurrency. In the pre-emptive case, this allows the developer to limit the number of real threads that are created for

Initializing the ORB 4.5 ORB Properties


server operations to avoid overload. After this limit is exceeded, all new server operation requests are queued until it is possible to make a real thread to support it.

In the non-pre-emptive case, this has a similar function in restricting the number of potentially concurrent threads.

The default is 1; a single thread is available to handle server upcalls.

com.twoab.orb2.trace.file

Default: stdout.

Path and filename that trace data should be written to.

com.twoab.orb2.trace.flags

Default: 0x00000000 (No tracing)

This is a hex value that sets flags to determine what events to produce messages for

com.twoab.orb2.trace.modules

Default: 0x00000000 (No tracing)

This is a hex value that sets flags to determine what modules to produce messages for.

ALL FLAGS (0xffffffff)

CONTENTS (0x00000001) packets, buffers, entries

ENTRIES (0x00000002) changes to table entries

TABLES (0x00000004) changes to tables

QUEUES (0x00000008) queuing and dequeuing

PKTS (0x00000010) packet movements

STATES (0x00000020) changes of state

EVENTS (0x00000040) significant events

PROCS (0x00000080) procedure entries

ERRORS (0x00000100) recoverable errors

LOG (0x00000200) log statistics

VERBOSE (0x00000400) everything else

LOCKING (0x00001000) capsule locking

MEMORY (0x00002000) memory allocation/freeing

RELOC (0x80000000) relocation library

ALL MODULES (0xFFFFFFFF)

BINDER (0x00000001)

BUFFER (0x00000002)

CHANNEL (0x00000004)

INSTRUCT (0x00000008)



com.twoab.orb2.trader.hostname

Default: localhost

Identifies to clients the name of the host where the Trader is running.

com.twoab.orb2.trader.port

Default: 11001

Identifies to clients the port number that the Trader is running.

MPS (0x00000010)

NUCLEUS (0x00000020)

PROTOCOL (0x00000040)

REX (0x00000080)

SCHEDULE (0x00000100)

SESSION (0x00000200)

SYSDEP (0x00000400)

TASK (0x00000800)

THREAD (0x00001000)

ECS (0x00002000)

IDCACHE (0x00004000)

TIMER (0x00008000)

NOTIFY (0x00010000)

IFREFS (0x00020000)

MIFREF (0x00040000)

IRGRAM (0x00080000)

MPSIPC (0x00100000)

MPSUDP (0x00200000)

MPSTCP (0x00400000)

MPSSPX (0x00400000)

MPSIIOP (0x00800000)

GIOP (0x01000000)

GPIN (0x02000000)

GEX (0x04000000)

THREADMEM (0x08000000)

CAPSULE_TRACE (0x10000000)

TRADING (0x20000000)

RELOCATING (0x40000000)

LIBRARIES (0x80000000)

Initializing the ORB 4.6 Deprecation


com.twoab.orb2.trader2.hostname

Default: (none)

Identifies to clients the name of the host where the secondary trader is running.

com.twoab.orb2.trader2.port

Default: (none)

Identifies to clients the port number that the secondary Trader is running.

com.twoab.orb2.trader2.protocol_pref

Default: IIOP TCP UDP

Preferred protocol that the secondary Trader uses when communicating with other processes.

4.6 DeprecationFrom version 3.5 of orb2 for C/C++, the primary method for configuring the ORB will be via a properties file. Accordingly, all environment variables that were in use in previous versions of this product are deprecated and will be deleted in the next release of orb2. The sole exception to this is the environment variable ORB2C, which is required to locate the default orb.properties file.

4.6.1 Files Removed

4.6.1.1 Windows• The DAIS.INI file is no longer required and should be removed. Use a

properties file instead.• The ORB2.INI file is no longer required and should be removed. Use a

properties file instead.• The following executables are deprecated and will no longer be supported after

version 3.5:

4.6.1.2 Unix• The scripts that were built by gen_scripts are no longer required and should

be removed. Use a properties file instead.

ntconf.exe Use a properties file instead.

trclean.exe Client to the trader. Use eXplorer Console Management Service instead.

trclient.exe Client to the trader. Use eXplorer Console Management Service instead.

trexert.exe Client to the trader. Use eXplorer Console Management Service instead.

trman.exe Client to the trader. Use eXplorer Console Management Service instead.

trtest.exe Client to the trader. Use eXplorer Console Management Service instead.

typecl.exe Client to the trader. Use eXplorer Console Management Service instead.


4.6.2 Deprecated Environment Variables Initializing the ORB

• The following Unix executables are deprecated and will no longer be supported after version 3.5:

4.6.2 Deprecated Environment VariablesThis table lists all the environment variables currently supported by orb2 for C/C++ 3.5. These environment variables have been deprecated and will no longer be supported in after versions 3.5.

For reference, the new and old environment variables that work for this release are given. However, you should migrate to properties files at the earliest opportunity.

gen_scripts Use a properties file instead.

trclean Client to the trader. Use eXplorer Console Management Service instead.

trclient Client to the trader. Use eXplorer Console Management Service instead.

trexert Client to the trader. Use eXplorer Console Management Service instead.

trman Client to the trader. Use eXplorer Console Management Service instead.

trtest Client to the trader. Use eXplorer Console Management Service instead.

typecl Client to the trader. Use eXplorer Console Management Service instead.

Environment Variable in 3.5 Env. Variable in Previous Versions

DEBUG_LEVEL DEBUG_LEVEL

DEBUG_FILE DEBUG_FILE

ORB2_DEBUG_DATA DAIS_DEBUG_DATA

ORB2_TRACE_LEVEL DAIS_TRACE_LEVEL

ORB2_TRACE_FILE DAIS_TRACE_FILE

ORB2_LANG DAIS_LANG

ORB2_MSG_CACHE DAIS_MSG_CACHE

DECAY_SECONDS DECAY_SECONDS

PROTOCOL_PREF PROTOCOL_PREF

TEMPLATEDIR TEMPLATEDIR

CAPSULEDIR CAPSULEDIR

ORB2_ERRORACTION DAIS_ERRORACTION

ORB2_EXITACTION DAIS_EXITACTION

ORB2_BUFFER_POOL_SIZE DAIS_BUFFER_POOL_SIZE

ORB2_CONNECT_ATTEMPTS DAIS_CONNECT_ATTEMPTS

Initializing the ORB 4.6.3 Deprecated Command-line Arguments


4.6.3 Deprecated Command-line ArgumentsThis table below lists all the command-line arguments currently supported by orb2 for C/C++ 3.5. All of these command-line arguments have been deprecated.

ORB2_CONNECT_DELAY DAIS_CONNECT_DELAY

ORB2_CONNECT_TIMEOUT DAIS_CONNECT_TIMEOUT

ORB2_REXFRAGSPERTICK DAIS_REXFRAGSPERTICK

ORB2_MPS_TIMEOUT DAIS_MPS_TIMEOUT

MPS_REUSEADDR MPS_REUSEADDR

GIOP_TIMEOUT GIOP_TIMEOUT

IIOP_SOCKET_SIZE IIOP_SOCKET_SIZE

IIOP_SOCKET_BUFFER IIOP_SOCKET_BUFFER

SOCKET_SCAN_PERIOD SOCKET_SCAN_PERIOD

FIFODIR FIFODIR

ORB2_TCP_NETID DAIS_TCP_NETID

ORB2_UDP_NETID DAIS_UDP_NETID

ORB2_LOGDIR DAIS_LOGDIR

VERSION_NUM VERSION_NUM

FACTORY_PERSISTENCE FACTORY_PERSISTENCE

ORB2_FACTORY_TIMEOUT DAIS_FACTORY_TIMEOUT

TRADER_DELETE_STALE TRADER_DELETE_STALE

TRADER_FIRST_CHECKPOINT TRADER_FIRST_CHECKPOINT

TRADER_CHECKPOINT_PERIOD TRADER_CHECKPOINT_PERIOD

ORB2_TRADER_TIMEOUT DAIS_TRADER_TIMEOUT

TRADER_RESTRICTED_UPDATE TRADER_RESTRICTED_UPDATE

TRADER_NAME TRADER_NAME

TRADER_PORT TRADER_PORT

TRADER_PROTOCOL_PREF TRADER_PROTOCOL_PREF

ORB2_TRADER_NETID DAIS_TRADER_NETID

TRADER_IP_NONCE_NAME TRADER_IP_NONCE_NAME

TRADER2_NAME TRADER2_NAME

TRADER2_PORT TRADER2_PORT

TRADER2_PROTOCOL_PREF TRADER2_PROTOCOL_PREF

ORB2_TRADER2_NETID DAIS_TRADER2_NETID

TRADER2_IP_NONCE_NAME TRADER2_IP_NONCE_NAME


4.6.3 Deprecated Command-line Arguments Initializing the ORB

If you use these command-line arguments, you should use the equivalent property in a properties file instead.

ORBreturn

ORBstacksize

ORBrkeys

ORBsecallowed

ORBlocalopt

ORBconsole

ORBqueuesize

ntservice

Initializing the ORB 4.6.3 Deprecated Command-line Arguments


orb2 for C Dynamic Invocation User’s Guide orb2 for C/C++ 3.8 5-1

Chapter 5 DII/DSI

This chapter describes how the Dynamic Invocation Interface (DII) and the Dynamic Skeleton Interface (DSI) allow you to add flexibility to distributed applications. Complete information about how to use Dynamic Interfaces can be found in the OMG's CORBA specification.

5.1 Static RequestsWhen using static request invocations, you use the stub and skeleton classes that are generated by an IDL compiler. Client applications use the stub classes to invoke operation on remote servers. Servers use the skeleton classes to receive the incoming invocations. This is the typical means of building distributed applications with CORBA.

5.2 Dynamic RequestsThere are some applications that may not have knowledge of the services that it might invoke until runtime. That is, when the client application is written and compiled, it is not aware of all the servers that it might need to use. An example of such an application might be a testing tool. Such an application would not have any prior knowledge of the workings of the servers that it might test. It must provide a means of obtaining that information at runtime (e.g. from an operator).

Another type of specialized application would be a server that is not aware of the operations that it must support until runtime. An example of such a server might be a server that does load balancing and redirects operations to servers that are not currently busy.

In the case of the client application described above, it could use the Dynamic Invocation Interface (DII). It would not require pre-compiled stub files. The server described above could use the Dynamic Skeleton Interface (DSI) and would not require pre-compiled skeleton files.

5.3 Invoking Dynamic RequestsThe Dynamic Invocation Interface (DII) allows the dynamic construction of a request, without the need for a pre-compiled stub class. It allows the dynamic construction of an object invocation. The client application must supply information about the operation and the type and value of parameters that are to be passed with the operation. Objects that receive these invocations will have no way of knowing if the operation was invoked statically or dynamically.

5.4 Receiving Requests DynamicallyThe Dynamic Skeleton interface (DSI) provides a way to deliver requests from an ORB to an object implementation that does not have compile-time knowledge of the object it is implementing. The DSI implements all requests on a particular object by having the ORB the same upcall routine, a Dynamic Implementation Routine (DIR). You may use a single DIR as the implementation for many objects with different interfaces.

DII/DSI 5.5 Dynamic Any's

5-2 orb2 for C/C++ 3.8 orb2 for C Dynamic Invocation User’s Guide

5.5 Dynamic Any'sWhen dynamically creating and receiving requests, parameters are inserted/extracted from CORBA Any types. One of the problems of invoking operations upon objects that one has no prior knowledge about is that one probably also does not have any prior knowledge about the data types that may be passed as parameters, especially user defined data types. IDL compilers create classes that define user-defined data types and provide helper classes that support inserting and extracting these data types into and out of CORBA Any types. Without these classes, it becomes necessary to use the CORBA Dynamic Any mechanism to construct these values.

5.6 Performance IssuesOften, people assume that by using the DII and/or DSI interfaces, they might achieve some performance enhancements. They make this assumption based on the fact that they are bypassing code found in stub and skeleton code.Typically, this assumption is false. DII and DSI code must perform the same functionality that the pre-compiled stub and skeleton code, and it may also have the burden of not having prior knowledge of things such as data types.

The DII and DSI interface should be used only for those application that truly have the requirement that they have no prior knowledge of the objects that they may wish to use.

5.7 Demonstration ProgramsDII and DSI usage is illustrated in the demonstration programs in the dynamic subdirectory of the demos directory. In this example, a server offers a simple facility to clients for reversing strings. The revers.idl file describes the implementation for the string reversing functions.

Refer to the files in this directory for a detailed comparison of the static and dynamic demonstration programs.

User’s Guide orb2 for C/C++ 3.8 A-1

Appendix A C LanguageMapping

SpecificationTables

A.1 Summary of Argument/Result PassingTable A.1 summarizes the argument passed by the client to a stub and what is received as a result of that transaction. The CORBA_ prefix is omitted from type names in the table.

Table A.1 Basic Argument and Result Passing

Data Type In Inout Out Return

short short short* short* short

long long long* long* long

unsigned shortunsigned_ short

unsigned_short*

unsigned_short* unsigned_short

unsigned_longunsigned_ long

unsigned_ long*

unsigned_ long* unsigned_ long

float float float* float* float

double double double* double* double

boolean boolean boolean* boolean* boolean

char char char* char* char

octet octet octet* octet* octet

enum enum enum* enum* enum

object reference ptr1

objref_ptr objref_ptr* objref_ptr* objref_ptr

struct, fixed struct* struct* struct** struct*

union, fixed union* union* union* union

union, variable union* union* union** union*

string char* char** char** char*

C Language Mapping Specification Tables A.1 Summary of Argument/Result Passing

A-2 orb2 for C/C++ 3.8 User’s Guide

Notes1 Including pseudo-object references.2 A slice is an array with all the dimensions of the original except thefirst one.

A client is responsible for providing storage for all arguments passed as <in> arguments (Table A.2).

sequence sequence* sequence* sequence* sequence*

array, fixed array array array array slice2

array, variable array array array slice**2 array slice*2

any any* any* any** any*

Table A.2 Client Argument Storage Responsibilities

Type <Inout> Parameter

<Out> Parameter

Return Result

short 1 1 1

long 1 1 1

unsigned short 1 1 1

unsigned long 1 1 1

float 1 1 1

double 1 1 1

boolean 1 1 1

char 1 1 1

octet 1 1 1

enum 1 1 1

object reference ptr 2 2 2

struct, fixed 1 1 1

struct, variable 1 3 3

union, fixed 1 1 1

union, variable 1 3 3

String 4 3 3

Sequence 5 3 3

array, fixed 1 1 6

array, variable 1 6 6

Any 5 3 3

Table A.1 Basic Argument and Result Passing (Continued)


User’s Guide orb2 for C/C++ 3.8 A-3

A.1 Summary of Argument/Result Passing C Language Mapping Specification Tables

Argument passing cases1 The caller allocates all necessary storage, except that which may be

encapsulated and managed within the parameter. For <inout> parameters, the caller provides an initial value. The callee may change that value.For <out> parameters, the caller allocates the storage but need not initialize it. The callee sets the value. Function returns are by value.

2 The caller allocates storage for the object reference.For <inout> parameters, the caller provides an initial value. If the callee wants to reassign the <inout> parameter, it calls CORBA_Object_release on the original input value.To continue to use an object reference, passed in as an <inout>, the caller must duplicate the reference.The client is responsible for the release of all <out> and <return> object references. Release of all object references embedded in other <out> and <return> structures is performed automatically as a result of calling CORBA_free.

3 For <out> parameters, the caller allocates a pointer and passes it, by reference, to the callee. The callee sets the pointer to point to a valid instance of the parameter’s type.For <returns>, the callee returns a similar pointer. The callee is not allowed to return a null pointer in either case. In both cases, the caller is responsible for releasing the returned storage.Following the completion of a request, the caller is not allowed to modify any values in the returned storage. To do so, the caller must first copy the returned instance into a new instance then modify the new instance.

4 For <inout> strings, the caller provides storage for both the input string and the char* pointing to it. The callee may deallocate the input string and reassign the char* to point to new storage to hold the output value.The size of the <out> string is not limited by the size of the in string. The caller is responsible for freeing the storage for the <out>. The callee is not allowed to return a null pointer for an <inout>, <out> or <return> value.

5 For <inout> sequences and Any’s assignments or modifications or modifications of the sequence or Any may cause deallocation of owned storage before any reallocation occurs, depending on the state of the boolean release in the sequence or Any.

6 For <out> parameters, the caller allocates a pointer to an array slice that has all the same dimensions of the original array, except the first, and passes the pointer by reference to the callee. The callee sets the pointer to point to a valid instance of the array. For a <return>, the callee returns a similar pointer. The callee is not allowed to return a null pointer in either case. In both cases, the caller is responsible for releasing the returned storage. Following the completion of a request, the caller is not allowed to modify any values in the returned storage. To do so, the caller must first copy the returned array instance into a new array instance then modify the new instance.

C Language Mapping Specification Tables A.1 Summary of Argument/Result Passing

A-4 orb2 for C/C++ 3.8 User’s Guide

User’s Guide orb2 for C/C++ 3.8 B-1

Appendix B C++ LanguageMapping

SpecificationTables

This appendix contains the OMG IDL C++ Language Mapping Specification Tables:

Table B.1 Basic Argument and Result Passing


short Short Short& Short& Short

long Long Long& Long& Long

unsignedshort

UShort UShort& UShort& UShort

unsignedlong

ULong ULong& ULong& ULong

float Float Float& Float& Float

double Double Double& Double& Double

boolean Boolean Boolean& Boolean& Boolean

char Char Char& Char& Char

octet Octet Octet& Octet& Octet

enum enum enum& enum& enum

objectreferenceptr

objref_ptr objref_ptr& objref_ptr& objref_ptr

struct,fixed

const struct& struct& struct& struct

struct,variable

const struct& struct& struct*& struct*

union,fixed

const union& union& union& union

union,variable

const union& union& union*& union*

string const char* char*& char*& char*

C++ Language Mapping Specification Tables

B-2 orb2 for C/C++ 3.8 User’s Guide

sequence const sequence&

sequence& sequence*& sequence*

array,fixed

const array array array array slice*

array variable const array array array slice*& array slice*

any const any& any& any*& any*

Table B.2 T_var Arguments and Result Passing


objectreferencevar

const objref_var&

objref_var& objref_var& objref_var

struct_var const struct_var&

struct_var& struct_var& struct_var

union_var const union_var&

union_var& union_var& union_var

string_var const string_var&

string_var& string_var& string_var

sequence_var const sequence_var&

sequence_var&

sequence_var&

sequence_var

array_var const array_var&

array_var& array_var& array_var

any_var const any_var&

any_var& any_var& any_var

Table B.3 Client Argument Storage Responsibilities

Type Inout Param

Out Param

Return Result

short 1 1 1

long 1 1 1

unsigned short 1 1 1

unsigned long 1 1 1

float 1 1 1

double 1 1 1

boolean 1 1 1

Table B.1 Basic Argument and Result Passing (Continued)


User’s Guide orb2 for C/C++ 3.8 B-3


Argument Passing Cases

1. A caller allocates all necessary storage, except that encapsulated and managed within the parameter itself.

– For inout parameters, the caller provides the initial value and the callee may change that value.

– For out parameters, the caller allocates the storage but does not need to initialize it. The callee sets the value. Function returns are by value.

2. A caller allocates storage for the object reference.

– For inout parameters, the caller provides an initial value. If the callee wants to reassign the inout parameter, it first calls CORBA::release on the original input value.

– To continue to use an object reference passed in as an inout, the caller must first duplicate the reference.

– The client is responsible for the release of all out and return object references.

– Release of all object references embedded in other structures is performed automatically by the structures themselves.

3. For out parameters, the caller allocates a pointer and passes it, by reference, to the callee.

– The callee sets the pointer to point to a valid instance of the parameter’s type.

– For returns, the callee returns a similar pointer. The callee is not allowed to return a null pointer in either case. In both cases, the caller is responsible for releasing the returned storage.

– After a request completes, the caller is not allowed to modify any values in the returned storage. To do so, the caller must first copy the returned instance into a new instance, then modify the new instance.

char 1 1 1

octet 1 1 1

enum 1 1 1

object reference ptr 2 2 2

struct, fixed 1 1 1

struct, variable 1 3 3

union, fixed 1 1 1

union, variable 1 3 3

string 4 3 3

sequence 5 3 3

array, fixed 1 1 6

array, variable 1 6 6

any 5 3 3

Table B.3 Client Argument Storage Responsibilities (Continued)

Type Inout Param

Out Param

Return Result


B-4 orb2 for C/C++ 3.8 User’s Guide

4. For inout strings, the caller provides storage for both the input string and the char* pointing to it.

– Since the callee may de-allocate the input string and reassign the char* to point to new storage to hold the output value, the caller should allocate the input string using string_alloc().

– The size of the out string is therefore not limited by the size of the in string.

– The caller is responsible for deleting the storage for the out using string_free().

– The callee is not allowed to return a null pointer for an inout, out or return value.

5. For inout sequences and anys, assignment or modification of the sequence, or any, may cause de-allocation of owned storage before any reallocation occurs, depending upon the state of the Boolean release parameter with which the sequence or any was constructed.

6. For out parameters, the caller allocates a pointer to an array slice that has all the same dimensions of the original array except the first and passes the pointer by reference to the callee

– The callee sets the pointer to point to a valid instance of the array.– For returns, the callee returns a similar pointer. The callee is not allowed

to return a null pointer in either case.– In both cases, the caller is responsible for releasing the returned storage.

After a request completes, the caller is not allowed to modify any values in the returned storage. To do so, the caller must first copy the returned array instance into a new array instance, then modify the new instance.

User’s Guide orb2 for C/C++ 3.8 C-1

Appendix C AlternativeException

Handling in C++

C.1 DeprecationAlternative exception handling is deprecated in orb2 for C/C++ v3.5 and is no longer supported. This functionality will be removed with the next major release, v4.0.

In C++, the natural method of signaling and detecting exceptional conditions is the language’s exception mechanism, using the try, catch and throw constructs. The IDL C++ mapping uses this mechanism in server-side application code to signal IDL exception values, and in client-side code to detect them.

However, until recently, not all C++ compilers supported C++ exceptions. For this reason, orb2 also has libraries that provide an alternative mapping to support IDL exceptions. Since all supported C++ compilers now implement the C++ exception mechanism, these libraries are supplied for backward compatibility to existing applications built using C++ compilers without exception support. If you have applications built with the older compilers, you should convert them to use the C++ exception mechanism.

The alternative mapping uses an additional environment reference parameter on each operation, which the called operation must modify to indicate the operation’s success or the IDL exception associated with its failure.

This appendix describes how to use this alternative mechanism directly. Section C.4 contains a set of preprocessor macros that you can use to develop applications that can be compiled to handle exceptions either as C++ exceptions or via the environment parameter. You should use these macros where the normal C++ exception mechanism is not used. If an application is coded to use the environment parameter directly, it should be converted to use the macros as the initial step in converting it to use the C++ exception mechanism.

For example

// IDLinterface Example{ exception InvalidRange{}; void do_shading( in Color hue ) raises (InvalidRange);};

The exception class hierarchy is still maintained based on the base class Exception, and users declare and manipulate these classes through instances of an environment pseudo object, the pseudo IDL

interface environment // PIDL{ attribute Exception exception; void clear();};

Alternative Exception Handling in C++ C.2 Callee Side Usage

C-2 orb2 for C/C++ 3.8 User’s Guide

where the attribute declaration maps into a pair of C++ functions of the form get and set, and both functions map to an overloaded exception call, the C++ class

// C++class Environment{public: void exception(Exception*); exception *exception() const; void clear();};

The set function assumes ownership of the exception pointer and the environment will eventually call delete on this pointer. The exception it points to must be dynamically allocated by the caller.

The get function returns a pointer to the exception, just as an attribute for a variable length struct would, but the pointer refers to memory owned by the environment. After the environment is destroyed, the pointer is no longer valid. The caller must not call delete on the exception pointer returned by the get function. The environment is responsible for de-allocating any exception it holds when it is destroyed. If the environment holds no exception, the get function returns a NULL pointer.

The clear() function causes the environment to delete any exception it is holding. It is not an error to call clear() on an environment holding no exception. Passing a NULL pointer to the set exception function is equivalent to calling clear().

C.2 Callee Side UsageThe exceptions are communicated as attributes of an instance of an environment class, and a reference to an environment class is passed as the first parameter to object implementation functions by the skeleton.

Therefore, given the following IDL

interface Test{ exception Failed{ string reason; }; void launch() raises( Failed );};

the generated abstract class would have the signature

class Test ...{public: virtual void launch(Environment &) = 0;};

An implementation would, therefore, inherit from the skeleton class and the signature for launch() would be

TestImpl::launch( Environment &ev );

where the environment variable is owned by the calling skeleton and is used by the implementation to communicate back exceptions. For example

TestImpl::launch( Environment &ev ){ if ( ignition() ) return; else { static CORBA::Char* reason = "Failed to ignite"; Exception::Failed *ex_ptr = new Exception::Failed; ex_ptr->reason = CORBA::string_alloc( strlen(reason) ); strcpy( ex_ptr->reason, reason );


C.3 Caller Side Usage Alternative Exception Handling in C++

ev.exception( ex_ptr ); return; // Note explicit exit from implementation }}

Unlike the language throw mechanism, the implementer gets help in unwinding the stack back to a point of safety. The code must reflect the implementer’s intentions by exiting the implementation after the exception and return parameters have been initialized. Not only must the exception be initialized, but all out and return values must be set to NULL. This allows automatic and _var types declared by the caller to safely destruct.

C.3 Caller Side UsageApart from the explicit handling of the environment class, the client-side usage is not greatly altered from the try-catch mechanism. The caller must remember to manufacture an instance of an environment, which is passed by reference as the first parameter to all invocations. For example

// Using the Test IDL// C++Environment ev; // default constructorTest_ptr test_objref = // get an object referencetest_objref->launch(ev);// Now simulate the catch blockif ( Exception *ex_ptr = ev.exception() ) // get attribute{ // drill down to explicit exception type if ( SystemException *se = SystemException::_narrow( ex_ptr ) ) { orb_ptr->terminate("System exception"); } if ( Test::Failed *fex_ptr = Test::Failed::_narrow( ex_ptr ) ) { cerr << DAIS_capsule_name << " failed to launch <" << ex_ptr->reason << ">" << endl; }}

Callers may declare environment classes in whatever way is appropriate: as globals, file statics, automatics or dynamically.

C.4 Portable Exception HandlingIn some cases (such as Solaris), both methods of exception handling are supported, allowing you to choose which methods of exception handling to use. For example, in a mixed environment of VMS and Solaris, you would code your applications using CORBA::Environment parameters so that they run on both platforms.

To distinguish between exception environments, orb2 provides two libraries. You should link your application with the appropriate one

• To use native C++ exceptions, link with libdaisp.a

• To use CORBA::Environment, link with libdaisx.a

You can also write your code so that you defer the decision on which exception handling code to use until compile time. To help you to write this type of code, orb2 provides a set of macros that emulate generic exception handling. The macros are expanded at compile time to use one method or the other, depending on the compiler flag.

By defining the constant _CORBA_EH_, you can switch between native C++ exception handling and CORBA::Environment handling at compile time.

Alternative Exception Handling in C++ C.4 Portable Exception Handling


The following pre-defined exception macros are located in orb.hpp. These are grouped into two types. The first set concerns environment type declarations which only have valid expansions for the non-C++ exception case

These may be used in function signatures that need to (optionally) pass environment parameters, such as:

MyInterface::operation( params COMMA ETYPE ENV );

The macros concerned with raising exceptions are

These may be used as follows

voidMyInterface::operation( params COMMA ETYPE ENV ){ // your code if( exception_needed ) { // declare exception DECLARE_EXCEPT( Trader::BadType, ex ); // now raise the exception THROW_EXCEPT( ex ); // we can progress no further RETURN_VOID } else { // continue processing }}

Note the use of the RETURN_VOID macro. In the CORBA::Environment case, you need to either return void or return a value after an exception is raised, but with C++ exceptions nothing can follow a throw. There is no semi-colon after the RETURN_VOID or RETURN_VALUE macro because it is included in the macro.

The following macros are concerned with detecting exceptions. Look in orb.hpp for the expansion details. The macros are described later in this appendix.

START_TRYEND_TRYCHECK_ENV (b)CATCH_LABEL (label)

#ifdef _CORBA_EH_ expands to ...

#ifndef _CORBA_EH_ expands to ...

ETYPE CORBA::Environment&

(nothing)

ENV _ _DAIS_ev (nothing)COMMA , (nothing)DECLARE_ENV CORBA::Environment

& _ _DAIS_ev(nothing)

#ifdef _CORBA_EH_ expands to ...

#ifndef CORBA_EH_ expands to ...

DECLARE_EXCEPT type *b=new type() type b (type,b)THROW_EXCEPT(b) ENV.exception(b) throw bRETHROW_EXCEPT(b) ENV.exception(b) throwRETURN_VALUE(a) return a; (nothing)RETURN_VOID return.; (nothing)


C.4 Portable Exception Handling Alternative Exception Handling in C++

CATCH_ANY (b)CATCH_SYSTEM (b)CATCH_USER (b)CATCH_SPECIFIC (extype, b)CATCH_ANY_ANON ()CATCH_USER_ANON ()CATCH_SYSTEM_ANON ()CATCH_SPECIFIC_ANON (extype)

They are used as follows

some_function(){ DECLARE_ENV; START_TRY { // some code which might raise exceptions } CATCH_SYSTEM(se) { // Handle system exception { END_TRY}

Note ENV must be declared somewhere before CATCH( ex) can expand without compilation errors.

The simulation of exceptions requires that an environment is passed to each call; this environment holds the exception raised by that call. The macros check if an exception is held in the environment and jump to the relevant catch blocks for this try block. This is all done with labels and gotos, so you must conform to standard scoping rules for labels within the program.

Be aware that the macro calls are present in the stub and skeleton code generated by the orb2 CORBA IDL compiler, even if you do not need to use them.

The following example is the VehicleDB client segment rewritten using the macros.

// Client segmentDECLARE_ENV; START_TRY { car_ptr->drive(ENV); CHECK_ENV(label_001); // Not needed}CATCH_LABEL(label_001) // Not neededCATCH_SYSTEM(se){ orb_ptr->terminate( "System exception detected during 'drive'");}CATCH_SPECIFIC(grudge){ switch(grudge->) { // etc ... }}END_TRY

To explain this exampleDECLARE_ENV Holds the exception reported by an operation.

If C++ exceptions are supported, this is a null statement.

START_TRY Equivalent of a try and denotes the start of the guarded block of code.

Alternative Exception Handling in C++ C.4 Portable Exception Handling


Note In environments without C++ exceptions, if a handler is not found prior to the END_TRY macro, the exception is lost. There is no emulation of C++ stack unwinding to find an exception handler.

The following code example shows the changes for the server side

// Server segmentVehicleDBImpl::drive(ETYPE ENV) { static const CORBA::char *qual[4] = {

ENV This extra argument to the drive operation is not declared in the IDL interface description.In environments without C++ exceptions, this parameter is used to allow the operation to return any exception to the caller.If the operation already has arguments, use COMMA ENV to add this argument.If C++ exceptions are supported, this is a null argument.

CHECK_ENV This macro takes a label identifier that should uniquely identify the CATCH_LABEL statement using normal C++ scoping conventions.Checks the environment returned by the statement that could raise an exception. If an exception was reported, it transfers execution directly to the identified label.If C++ exceptions are supported, this is a null statement.You normally add a CHECK_ENV statement after each call that could raise an exception.In the example, it is marked as not needed because the CATCH_LABEL macro is the next statement and the code will naturally "fall through" to the label.

CATCH_LABEL This macro is used as the target for possible exceptions. Its label must be unique within normal C++ scoping conventions.If C++ exceptions are supported, this is a null statement.This is marked as not needed since there is only one CATCH block of macros in the routine.

CATCH_SYSTEM This macro takes a variable name. It creates a variable using the name and uses it to determine whether a system exception has occurred. If it has, the code within the block designated by the '{' and '}' is executed.If C++ exceptions are supported, this is a catch statement matching CORBA::SystemException.

CATCH_SPECIFIC Similar to CATCH_SYSTEM, but for specific user exceptions.There is also CATCH_ANY for general CORBA::Exceptions and CATCH_USER to match any user exception.

END_TRY The logical end of the START_TRY block. You must match the START_TRY and END_TRY macros.


C.4 Portable Exception Handling Alternative Exception Handling in C++

"Car is locked", "Car has no wheels", "Car has no engine", "Car has no fuel" }; switch(condition()) { DECLARE_EXCEPT(VehicleDBImpl::Grudge,ue); ue SELECT p = VehicleDBImpl::Locked; ue SELECT info = CORBA::string_alloc(strlen(qual[0])); strcpy(ue SELECT info, qual[0]); THROW_EXCEPT(ue); }}

To explain the macros

Other macros

ETYPE ENV These macros declare a variable ENV of type ETYPE, which is used to pass any exception back to the caller.These arguments are not declared in the IDL specification.If C++ exceptions are supported, these are null statements.

DECLARE_EXCEPT This macro declares an exception that will be raised by the routine.If this environment supports C++ exceptions, this is equivalent toVehicleDBImpl::Grudge ue;

For environments that do not support C++ exceptions, the equivalent code isVehicleDBImpl::Grudge *ue =

new VehicleDBImpl::Grudge;

The second declaration must allocate some storage for the exception since it is returned to the caller. (At least conceptually, since the client sees the exception after it is un-marshaled on the client machine and the memory is deleted after marshaling within the server skeleton).The difference between the two declarations means that access to fields within the exception must be mapped to hide the possible different implementations.In the first case we use ue.p and in the second ue->p.

SELECT This macro hides the implementation of the exception implementation and allow access to the fields.

THROW_EXCEPT This macro raises the exception and is equivalent to throw.

RETHROW_EXCEPT This maps onto throw, where normal C++ exceptions are supported. It is a NULL statement if not, since the environment will already have the exception saved. The "re-throw" comes about as the environment is returned to the caller.

RETURN_VOIDBREAK_EXCEPTRETURN_VALUE(x)

All NULL statements in C++ exception environments, because the compiler would complain about the statements not being reached. They are needed in environments without C++ exceptions as part of normal flow control.

Alternative Exception Handling in C++ C.5 Anonymous Catch Macros


C.5 Anonymous Catch MacrosIn some cases where an exception can be raised, you want to take some actions that do not depend directly on the exception, such as freeing memory, and then re-throw the exception so it can be handled by the next level exception handler. Normally, you could use the macros already defined, but because you do not use the exception directly, some compilers complain about the unused variable.

For example

CATCH_ANY(ex){ ... // Free some object etc. RETHROW_EXCEPT(); RETURN_VOID}

The Microsoft Visual C++ compiler complains that ex is not used. The normal C++ construct for such catches would be to declare a catch like

catch(exception_type)

that is, just the exception type without the variable.

To accommodate these cases across multiple platforms, there are four macros

CATCH_ANY_ANON()CATCH_USER_ANON()CATCH_SYSTEM_ANON()CATCH_SPECIFIC_ANON(extype)

These plant the appropriate code for an anonymous catch block.

C.6 SummaryIf the C++ environment supports exceptions, the macros map onto the standard C++ constructs and can be used to handle any exception with appropriate catch statements.

In environments that do not support exceptions, the macros can only be used to handle orb2 exceptions returned from calls on interface operations or exceptions from locally defined functions.

You can use the macros to produce platform-independent orb2 code, deferring your implementation until compile time. The implementation is determined by the value of _CORBA_EH_ as specified in the makefile, which should be set for environments that do not raise exceptions. To switch these portability macros at compile time, you can set _CORBA_EH_ as part of the compiler command line as -D_CORBA_EH_. Do not forget to link with orb2 library liborb2x.a or liborbp.a, depending on which one is appropriate.

SWITCH_ON_MINOR(x) This macro is used inside the CATCH_SYSTEM, CATCH_USER or CATCH_ANY blocks if it is known that the exception has a minor value that contains useful information.

DELETE_EXCEPT Used by orb2 internally to delete the memory associated with orb2 exceptions after it has been marshaled.

No C++ exception handling -D_CORBA_EH_ link with liborb2x.a

Use C++ exception handling -D link with liborb2p.a

User’s Guide orb2 for C/C++ 3.8 D-1

Appendix D Properties

This properties provided herein assist you in migrating from earlier versions of orb2 to the current version. Please note that most command-line arguments, and all but one environment variable, have been deprecated. Please see Section 4.6, Deprecation for more information.

Below is a list of all possible properties, available to you in the properties file, that can be set for orb2 for C/C++:

• If an entry exists in the Cmdline-Arg column, the property can be overridden with the specified command-line argument.

• If an entry exists in the Env Var column, the property can be overridden by setting the appropriate environment variable.

• The default value shown applies if nothing is specified in the properties file, command line or environment variables.

com.twoab.orb2.orb_id

Cmdline-arg Env. Var Default Value

ORBid orb2

com.twoab.orb2.port


ORBport 0

com.twoab.orb2.debug.level


ORBdebug_level DEBUG_LEVEL 0

com.twoab.orb2.debug.file


ORBdebug_file DEBUG_FILE

com.twoab.orb2.debug.iiop_msg_buffer_size


ORB2_DEBUG_DATA 96

Properties

D-2 orb2 for C/C++ 3.8 User’s Guide

com.twoab.orb2.trace.modules


ORBtrace_modules 0

com.twoab.orb2.trace.flags


ORBtrace_flags 0

com.twoab.orb2.trace.file


ORBtrace_file ORB2_TRACE_FILE

com.twoab.orb2.tasks


ORBtasks 1

com.twoab.orb2.console


ORBconsole yes - Windowsno - All Others

com.twoab.orb2.queuesize


ORBqueuesize 10000

com.twoab.orb2.language


ORB2_LANG english

com.twoab.orb2.initial_ref


ORBInitRef


Properties

com.twoab.orb2.inactivity_seconds


DECAY_SECONDS 0

com.twoab.orb2.protocol_pref


PROTOCOL_PREF IIOP TCP UDP

com.twoab.orb2.connect_attempts


ORB2_CONNECT_ATTEMPTS 2

com.twoab.orb2.connect_attempt_delay


ORB2_CONNECT_DELAY 2

com.twoab.orb2.connect_timeout


ORB2_CONNECT_TIMEOUT 2

com.twoab.orb2.mps.timeout


ORB2_MPS_TIMEOUT 2000

com.twoab.orb2.giop.timeout


GIOP_TIMEOUT 5

com.twoab.orb2.iiop.socket_size


IIOP_SOCKET_SIZE 65535

Properties


com.twoab.orb2.license.dir


ORBlicense_dir ORB2C $ORB2C

com.twoab.orb2.log_dir_name


ORB2_LOGDIR $ORB2/logfiles

com.twoab.orb2.factory.timeout


ORB2_FACTORY_TIMEOUT 10

com.twoab.orb2.trader.first_checkpoint_time


TRADER_FIRST_CHECKPOINT -1

com.twoab.orb2.trader.checkpoint_period


TRADER_CHECKPOINT_PERIOD 21600

com.twoab.orb2.trader.timeout


ORB2_TRADER_TIMEOUT 10

com.twoab.orb2.trader.restricted_update


TRADER_RESTRICTED_UPDATE

com.twoab.orb2.trader.hostname


TRADER_NAME localhost


Properties

com.twoab.orb2.trader.port


TRADER_PORT 11001

com.twoab.orb2.trader.protocol_pref


TRADER_PROTOCOL_PREF IIOP TCP UDP

com.twoab.orb2.trader.netid


ORB2_TRADER_NETID localhost

com.twoab.orb2.trader.nonce_hostname


TRADER_IP_NONCE_NAME

com.twoab.orb2.trader2.hostname


TRADER2_NAME

com.twoab.orb2.trader2.port


TRADER2_PORT

com.twoab.orb2.trader2.protocol_pref


TRADER2_PROTOCOL_PREF IIOP TCP UDP

com.twoab.orb2.trader2.netid


ORB2_TRADER2_NETID

Properties


com.twoab.orb2.trader2.nonce_hostname


TRADER2_IP_NONCE_NAME

com.twoab.orb2.master.hostname


TRADER2_NAME

com.twoab.orb2.master.port


TRADER2_PORT

com.twoab.orb2.master.protocol_pref


TRADER2_PROTOCOL_PREF IIOP TCP UDP

com.twoab.orb2.master.netid


ORB2_TRADER2_NETID

com.twoab.orb2.master.nonce_hostname


TRADER2_IP_NONCE_NAME

User’s Guide orb2 for C/C++ 3.8 Index-1

Index

Numerics2AB Technical Support 0-viii

Aalternative exception handling in C++ C-1argc parameter 4-1argument passing cases in C++ B-3arguments in C A-1argv parameter 4-1

CC code Generated by stubgen

examplesCalculator 2-3

C Language Mapping Specification TablesClient Argument Storage

Responsibilities A-2C mappings

Basic Argument and Result Passing A-1Client Argument Storage

Responsibilities A-2C++ code Generated by stubgen


C++ Language Mapping Specification TablesBasic Argument and Result Passing B-1Client Argument Storage

Responsibilities B-2T_var Arguments and Result Passing B-2

C++ mappingsBasic Argument and Result Passing B-1Client Argument Storage

Responsibilities B-2T_var Arguments and Result Passing in

C++ B-2Calculator

examplesC code generated by stubgen 2-3C++ code generated by stubgen 2-9files 2-1IDL 2-1

Calculator exampleclient programs

developing in CCalculator example 2-6

developing in C++Calculator example 2-12

server programsdeveloping in C

Calculator example 2-4developing in C++

Calculator example 2-10

callee side usage in C++ C-2caller side usage in C++ C-3client programs

developing in C 2-6developing in C++ 2-12

com.twoab.orb2.connect_attempt_delay 4-3, D-3

com.twoab.orb2.connect_attempts 4-3, D-3com.twoab.orb2.connect_timeout 4-3, D-3com.twoab.orb2.console 4-3, D-2com.twoab.orb2.debug.file 4-3, D-1com.twoab.orb2.debug.iiop_msg_buffer_size

4-3, D-1com.twoab.orb2.debug.level 4-3, D-1com.twoab.orb2.factory.timeout 4-4, D-4com.twoab.orb2.giop.timeout 4-4, D-3com.twoab.orb2.iiop.socket_size 4-4, D-3com.twoab.orb2.inactivity_seconds 4-4, D-3com.twoab.orb2.initial_ref D-2com.twoab.orb2.initial_ref=name=IOR

xxxx 4-4com.twoab.orb2.language 4-4, D-2com.twoab.orb2.license.dir D-4com.twoab.orb2.log_dir_name D-4com.twoab.orb2.master.hostname 4-5, D-6com.twoab.orb2.master.netid D-6com.twoab.orb2.master.nonce_hostname D-6com.twoab.orb2.master.port 4-5, D-6com.twoab.orb2.master.protocol_pref D-6com.twoab.orb2.mps.timeout 4-5, D-3com.twoab.orb2.orb_id 4-5, D-1com.twoab.orb2.port 4-5, D-1com.twoab.orb2.protocol_pref 4-5, D-3com.twoab.orb2.queuesize 4-5, D-2com.twoab.orb2.tasks D-2com.twoab.orb2.trace.file 4-6, D-2com.twoab.orb2.trace.flags D-2com.twoab.orb2.trace.modules 4-6, D-2com.twoab.orb2.trader.checkpoint_period

D-4com.twoab.orb2.trader.first_checkpoint_time

D-4com.twoab.orb2.trader.hostname 4-7, D-4com.twoab.orb2.trader.netid D-5com.twoab.orb2.trader.nonce_hostname D-5com.twoab.orb2.trader.port 4-7, D-5com.twoab.orb2.trader.protocol_pref D-5com.twoab.orb2.trader.restricted_update D-4com.twoab.orb2.trader.timeout D-4com.twoab.orb2.trader2.hostname 4-8, D-5com.twoab.orb2.trader2.netid D-5com.twoab.orb2.trader2.nonce_hostname D-6com.twoab.orb2.trader2.port 4-8, D-5

Index-2 orb2 for C/C++ 3.8 User’s Guide

com.twoab.orb2.trader2.protocol_pref 4-8, D-5

command-line arguments 4-2--ORBdebug_file 4-2--ORBdebug_level 4-2--ORBid 4-2--ORBInitRef 4-2--ORBport 4-2

compiler, stubgen 2-2compiling and running the C Calculator demo

programs 2-9compiling and running the C++ Calculator

demo programs 2-14compiling IDL 2-2, 3-1component concurrency in C A-3concurrency

component A-3configuration properties

com.twoab.orb2.connect_attempt_delay 4-3

com.twoab.orb2.connect_attempts 4-3com.twoab.orb2.connect_timeout 4-3com.twoab.orb2.console 4-3com.twoab.orb2.debug.file 4-3com.twoab.orb2.debug.iiop_msg_buffer_s

ize 4-3com.twoab.orb2.debug.level 4-3com.twoab.orb2.factory.timeout 4-4com.twoab.orb2.giop.timeout 4-4com.twoab.orb2.iiop.socket_size 4-4com.twoab.orb2.inactivity_seconds 4-4com.twoab.orb2.initial_ref=name=IOR

xxxx 4-4com.twoab.orb2.language 4-4com.twoab.orb2.master.hostname 4-5com.twoab.orb2.master.port 4-5com.twoab.orb2.mps.timeout 4-5com.twoab.orb2.orb_id 4-5com.twoab.orb2.port 4-5com.twoab.orb2.protocol_pref 4-5com.twoab.orb2.queuesize 4-5com.twoab.orb2.trace.file 4-6com.twoab.orb2.trace.modules 4-6com.twoab.orb2.trader.hostname 4-7com.twoab.orb2.trader.port 4-7com.twoab.orb2.trader2.hostname 4-8com.twoab.orb2.trader2.port 4-8com.twoab.orb2.trader2.protocol_pref 4-8

CORBA Interoperability 1-1CORBA_ORB_init 4-1

Ddeprecation 4-8

command-line arguments 4-10environment variables 4-9Unix 4-8Windows 4-8

developing

distributed applications 2-1developing C programs 2-4

Calculator examplecompiling and running 2-9

client programs 2-6server programs 2-4

developing C++ programs 2-10Calculator example

compiling and running 2-14client programs 2-12server programs 2-10

distributed applicationsdeveloping 2-1

Dynamic Any's 5-2Dynamic Invocation Interface 5-1Dynamic Requests 5-1

invoking 5-1receiving requests 5-1

Dynamic Skeleton Interface 5-1

Eenvironment variable

JRE_HOME 1-2ORB2 1-2ORB2C 1-2PATH 1-2


exception handling in C++, alternative C-1callee usage C-2caller usage C-3CORBA library C-3library C-3portable C-3pre-defined macros C-4switching at compile time C-3

IIDL

C++ Language Mapping Specification Tables B-1

compileroverriding the supplied preprocessor

3-3running stubgen 3-1stubgen 2-2stubgen options 3-1

compiling 2-2, 3-1interfaces 2-1

initialization software 4-1initializing the ORB 4-1Interface Definition Language. See IDLinterfaces 2-1

IDLCalculator

examples 2-1interoperability 1-1

User’s Guide orb2 for C/C++ 3.8 Index-3

JJRE_HOME 1-2

LLanguage Mapping Specification Tables

Client Argument Storage Responsibilities in C A-2

Client Argument Storage Responsibilities in C++ B-2

T_var Arguments and Result Passing in C++ B-2

Licensing 1-1locating objects

Trader Service 1-3

Mmacros in C++

alternative exception handling C-4anonymous catch C-8

mappingsBasic Argument and Result Passing in C

A-1Basic Argument and Result Passing in

C++ B-1Client Argument Storage

Responsibilities in C A-2Client Argument Storage

Responsibilities in C++ B-2T_var Arguments and Result Passing in

C++ B-2

Oobject_to_string 1-3options for stubgen IDL compiler 3-1ORB properties 4-3ORB properties files 4-1ORB2 1-2ORB2C 1-2--ORBdebug_file 4-2--ORBdebug_level 4-2--ORBid 4-2--ORBInitRef 4-2--ORBport 4-2overriding the supplied preprocessor in

stubgen 3-3

Pparameters

argc 4-1argv 4-1

passing results in C A-1passing results in C++ B-1PATH 1-2portable exception handling in C++ C-3precedence of properties 4-2preprocessor

overriding in stubgen 3-3properties 4-3, 4-4, D-1

configurationcom.twoab.orb2.connect_attempt_de

lay 4-3com.twoab.orb2.connect_attempts

4-3com.twoab.orb2.connect_timeout 4-3com.twoab.orb2.console 4-3com.twoab.orb2.debug.file 4-3com.twoab.orb2.debug.iiop_msg_buf

fer_size 4-3com.twoab.orb2.debug.level 4-3com.twoab.orb2.factory.timeout 4-4com.twoab.orb2.giop.timeout 4-4com.twoab.orb2.iiop.socket_size 4-4com.twoab.orb2.inactivity_seconds

4-4com.twoab.orb2.initial_ref=name=I

ORxxxx 4-4

com.twoab.orb2.language 4-4com.twoab.orb2.master.hostname

4-5com.twoab.orb2.master.port 4-5com.twoab.orb2.mps.timeout 4-5com.twoab.orb2.orb_idt 4-5com.twoab.orb2.port 4-5com.twoab.orb2.protocol_pref 4-5com.twoab.orb2.queuesize 4-5com.twoab.orb2.trace.file 4-6com.twoab.orb2.trace.modules 4-6com.twoab.orb2.trader.hostname 4-7com.twoab.orb2.trader.port 4-7com.twoab.orb2.trader2.hostname

4-8com.twoab.orb2.trader2.port 4-8com.twoab.orb2.trader2.protocol_pre

f 4-8precedence 4-2properties files 4-1

proxy objects 2-2

Rrequests

dynamic 5-1invoking 5-1receiving 5-1

static requests 5-1result passing in C A-1result passing in C++ B-1running the stubgen IDL compiler 3-1

Sserver programs

developing in C 2-4developing in C++ 2-10

skeletons 2-2

Index-4 orb2 for C/C++ 3.8 User’s Guide

definition 2-2Static Requests 5-1string_to_object 1-3Stringified Object References 1-3stubgen

examplesC code generated by stubgen 2-3C++ code generated by stubgen 2-9

stubgen compiler 2-2, 3-1options 3-1overriding the supplied preprocessor 3-3

stubs 2-2definition 2-2

Ttasks

component concurrency A-3technical support 0-viiithreads A-3Trader Service 1-3

UUnix deprecated files & scripts 4-8

WWindows deprecated executables 4-8Windows deprecated files 4-8writing initialization software 4-1

Documents

orb2 for C/C++ User’s Guideorb2 for C/C++ User’s Guide Subject Instructions for developing applications with orb2 for C/C++. Software Supported orb2 for C/C++ 3.8 Revision History