File: polyorb_ug.texi

package info (click to toggle)
polyorb 2.6.0~20090423-10
links: PTS
area: main
in suites: squeeze
size: 25,004 kB
ctags: 240
sloc: ada: 236,464; makefile: 2,281; sh: 1,373; cpp: 957; java: 500; ansic: 198; python: 191; perl: 23; exp: 6
file content (6637 lines) | stat: -rw-r--r-- 238,391 bytes
\input texinfo @c -*-texinfo-*-

@c %**start of header

@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c
@c                                Style Guide
@c
@c  1. Always put a @noindent on the line before the first paragraph
@c     after any of these commands:
@c
@c          @chapter
@c          @section
@c          @subsection
@c          @subsubsection
@c          @subsubsubsection
@c
@c          @end smallexample
@c          @end itemize
@c          @end enumerate
@c
@c  2. DO NOT use @example. Use @smallexample instead.
@c     a) DO NOT use highlighting commands (@b{}, @i{}) inside an @smallexample
@c        context.  These can interfere with the readability of the texi
@c        source file.  Instead, use one of the following annotated
@c        @smallexample commands, and preprocess the texi file with the
@c        gentexifile tool (which generates appropriate highlighting):
@c        @smallexample @c ada
@c        @smallexample @c adanocomment
@c        @smallexample @c projectfile
@c     b) The "@c ada" markup will result in boldface for reserved words
@c        and italics for comments
@c     c) The "@c adanocomment" markup will result only in boldface for
@c        reserved words (comments are left alone)
@c     d) The "@c projectfile" markup is like "@c ada" except that the set
@c        of reserved words include the new reserved words for project files
@c
@c  3. Each @chapter, @section, @subsection, @subsubsection, etc.
@c     command must be preceded by two empty lines
@c
@c  4. The @item command should be on a line of its own if it is in an
@c     @itemize or @enumerate command.
@c
@c  5. DO NOT put trailing spaces at the end of a line.  Such spaces will
@c     cause the document build to fail.
@c
@c  6. DO NOT use @cartouche for examples that are longer than around 10 lines.
@c     This command inhibits page breaks, so long examples in a @cartouche can
@c     lead to large, ugly patches of empty space on a page.
@c
@c  7. To add an entry to the bibliography, you must:
@c     * add it to polyorb_ug.bib
@c     This will generate the correct polyorb_ug_ref.texi file
@c     You may then cite the correct reference.
@c
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

@c $Id: polyorb_ug.texi 135863 2009-01-20 15:58:45Z hugues $

@include svn.texi

@setfilename polyorb_ug.info
@settitle PolyORB User's Guide

@set COPYRIGHT Copyright @copyright{} 2003-2008, Free Software Foundation
@set AUTHORS1 Robert Duff, J@'er@^ome Hugues, Laurent Pautet,
@set AUTHORS2 Thomas Quinot, Samuel Tardieu

@setchapternewpage odd
@syncodeindex fn cp

@c %**end of header

@copying
PolyORB is free software; you can redistribute it and/or modify it
under terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later
version. PolyORB is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHAN- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.  You should have received a
copy of the GNU General Public License distributed with PolyORB; see
file COPYING. If not, write to the Free Software Foundation, 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.
@end copying

@titlepage

@title PolyORB User's Guide
@include polyorb_version.texi
@subtitle Version @value{POLYORB_VERSION}
@svndate $Date: 2009-01-20 16:58:45 +0100 (Tue, 20 Jan 2009) $ 
@subtitle @value{SVNDate}
@author @value{AUTHORS1}
@author @value{AUTHORS2}

@page
@vskip 0pt plus 1filll

@value{COPYRIGHT}

@insertcopying
@end titlepage

@ifinfo
@ifhtml
@node Top, About This Guide,,
@top PolyORB User's Guide
@end ifhtml
@ifnothtml
@node Top, About This Guide, (dir), (dir)
@top PolyORB User's Guide
@end ifnothtml

PolyORB User's Guide

@include polyorb_version.texi
Version @value{POLYORB_VERSION}

$Date: 2009-01-20 16:58:45 +0100 (Tue, 20 Jan 2009) $

@value{AUTHORS1}
@value{AUTHORS2}

@value{COPYRIGHT}

@noindent
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being ``PolyORB User's Guide'', and with no
Back-Cover Texts.  A copy of the license is included in the section
entitled ``GNU Free Documentation License''.

@menu
* About This Guide::
* Introduction to PolyORB::
* Installation::
* Overview of PolyORB personalities::
* Building an application with PolyORB::
* Tasking model in PolyORB::
* CORBA::
* RT-CORBA::
* DSA::
* MOMA::
* AWS::
* GIOP::
* SOAP::
* Tools::
* Performance considerations::
* Conformance to standards::
* References::
* GNU Free Documentation License::
* Index::

@detailmenu
 --- The Detailed Node Listing ---

About This Guide

* What This Guide Contains::
* Conventions::

Introduction to PolyORB

* Introduction to distributed systems::
* Distribution models and middleware standards::
* The PolyORB generic middleware::

Installation

* Supported Platforms::
* Build requirements::
* Build instructions::
* Additional instructions for cross platforms::
* Building the documentation and PolyORB's examples::
* Build Options::
* Compiler Tools and Run-Time libraries Options::
* Platform notes::

Overview of PolyORB personalities

* Application personalities::

* CORBAoverview::
* DSAoverview::
* MOMAoverview::
* AWSoverview::

* Protocol personalities::

* GIOPoverview::
* SOAPoverview::

Configuration

* Compile-time configuration::
* Run-time configuration::
* Setting up protocol personalities::
* Activating debugging traces::
* Tracing exceptions::
* polyorb.gpr::
* polyorb-config::

Tasking model in PolyORB

* PolyORB Tasking runtimes::
* PolyORB ORB Tasking policies::
* PolyORB ORB Controller policies::
* PolyORB Tasking configuration::

CORBA

* What you should know before Reading this section::
* Installing CORBA application personality::
* Usage of idlac::
* Resolving names in a CORBA application::
* Building a CORBA application with PolyORB::
* Configuring a CORBA application::
* PolyORB specific APIs::
* Implementation Notes::

RT-CORBA

* What you should know before Reading this section2::
* Installing RT-CORBA::
* Configuring RT-CORBA::
* RTCORBA.PriorityMapping::
* RTCosScheduling Service::

DSA

* Introduction to the Ada DSA::
* Partition Communication Subsystem::
* Most Features in One Example::
* A small example of a DSA application::
* Building a DSA application with PolyORB::
* Running a DSA application::

MOMA

* What you should know before Reading this section4::
* Installing MOMA application personality::
* Package hierarchy::

GIOP

* Installing GIOP protocol personality::
* GIOP Instances::
* Configuring the GIOP personality::
* Code sets::

SOAP

* Installing SOAP protocol personality::
* Configuring the SOAP personality::

Tools

* po_catref::
* po_names::

Conformance to standards

* CORBA standards conformance::
* RT-CORBA standards conformance::
* CORBA-GIOP standards conformance::
* SOAP standards conformance::

@end detailmenu
@end menu

@end ifinfo

@c -------------------------------------------------------------------

@contents

@c -------------------------------------------------------------------
@node About This Guide
@unnumbered About This Guide
@c -------------------------------------------------------------------

@noindent
This guide describes the use of PolyORB, a middleware that enables
the construction of distributed Ada applications.

It describes the features of the middleware and related APIs and
tools, and details how to use them to build Ada applications.

@menu
* What This Guide Contains::
* Conventions::
@end menu

@c -------------------------------------------------------------------
@node What This Guide Contains
@unnumberedsec What This Guide Contains
@c -------------------------------------------------------------------

@noindent
This guide contains the following chapters:
@itemize @bullet

@item @ref{Introduction to PolyORB} provides a brief description of
middleware and PolyORB's architecture.

@item @ref{Installation} details how to configure and install PolyORB
on your system.

@item @ref{Overview of PolyORB personalities} enumerates the different
personalities, or distribution mechanisms, PolyORB provides.

@item @ref{Building an application with PolyORB} presents the
different steps to build a distributed application using PolyORB.

@item @ref{Tasking model in PolyORB} details the use of tasking
constructs within PolyORB.

@item @ref{CORBA} describes PolyORB's implementation of OMG's CORBA.

@item @ref{RT-CORBA} describes PolyORB's implementation of RT-CORBA,
the real-time extensions of OMG's CORBA.

@item @ref{DSA} describes PolyORB's implementation of the Ada
Distributed Systems Annex.

@item @ref{MOMA} describes PolyORB's implementation of MOMA, the
Message Oriented Middleware for Ada.

@item @ref{AWS} describes the integration of the Ada Web Server (AWS)
framework into PolyORB.

@item @ref{GIOP} describes PolyORB's implementation of GIOP, the
protocol defined as part of CORBA.

@item @ref{SOAP} describes PolyORB's implementation of SOAP.

@item @ref{Tools} describes PolyORB's tools.

@item @ref{Conformance to standards} discusses the conformance of the
PolyORB's personalities to the CORBA and SOAP standards.

@item @ref{References} provides a list of useful references to
complete this documentation.

@item
@ref{GNU Free Documentation License} contains the text of the license
under which this document is being distributed.
@end itemize

@c -------------------------------------------------------------------
@node Conventions
@unnumberedsec Conventions
@cindex Conventions
@cindex Typographical conventions
@c -------------------------------------------------------------------

@noindent
Following are examples of the typographical and graphic conventions used
in this guide:

@itemize @bullet
@item
@code{Functions}, @code{utility program names}, @code{standard names},
and @code{classes}.

@item
@samp{Option flags}

@item
@file{File Names}, @file{button names}, and @file{field names}.

@item
@var{Variables}.

@item
@emph{Emphasis}.

@item
[optional information or parameters]

@item
Examples are described by text
@smallexample
and then shown this way.
@end smallexample
@end itemize

@noindent
Commands that are entered by the user are preceded in this manual by
the characters @w{``@code{$ }''} (dollar sign followed by space). If
your system uses this sequence as a prompt, then the commands will
appear exactly as you see them in the manual. If your system uses some
other prompt, then the command will appear with the @code{$} replaced
by whatever prompt you are using.

Full file names are shown with the ``@code{/}'' character
as the directory separator; e.g., @file{parent-dir/subdir/myfile.adb}.
If you are using GNAT on a Windows platform, please note that
the ``@code{\}'' character should be used instead.

@c -------------------------------------------------------------------
@node Introduction to PolyORB
@chapter Introduction to PolyORB
@cindex PolyORB
@c -------------------------------------------------------------------

@menu
* Introduction to distributed systems::
* Distribution models and middleware standards::
* The PolyORB generic middleware::
@end menu

@c -------------------------------------------------------------------
@node Introduction to distributed systems
@section Introduction to distributed systems
@c -------------------------------------------------------------------

A distributed system architecture comprises a network of computers and the
software components that execute on those computers. Such architectures are
commonly used to improve the performance, reliability, and reusability of
complex applications. Typically, there is no shared address space
available to remotely-located components (that is to say, components running
on different nodes of the network), and therefore these components must
communicate using some form of message-passing.


@menu
* Using OS Network Services::
* Using a Middleware Environment::
* Using a Distributed Language::
@end menu

@node Using OS Network Services, Using a Middleware Environment, Introduction to distributed systems, Introduction to distributed systems
@subsection Using OS Network Services

There are several programming techniques for developing distributed
applications. These applications have traditionally been developed
using network programming interfaces such as sockets. Programmers have
to perform explicit calls to operating system services, a task that
can be tedious and error-prone. This includes initializing socket
connections and determining peer location, marshalling and unmarshalling
data structures, sending and receiving messages, debugging and testing
several programs at the same time, and porting the application to
several platforms to uncover subtle differences between various
network interfaces.

Of course, this communication code can be encapsulated in wrappers to reduce
its complexity, but it is clear that most of it can be automatically
generated. Message passing diverts developer's attention from the
application domain. The query and reply scenario is a classical scheme
in distributed applications; using message passing for such a scheme
can be compared to using a ``goto'' mechanism in a non-distributed
application.  This is considered unacceptable methodology in modern software
engineering. A more robust design is be to use a
structured approach based on procedure calls.

In some respects, network programming can be compared to the
multi-threading programming issue. The user can decide to split his code
into several pieces and to multiplex the thread executions himself, using a
table-driven model. The scheduling code ends up embedded into the user
code. This solution is error-prone and fragile in regard to any future
modification. Relying on an implementation of threads such as provided in
POSIX is a better solution. Relying on language primitives that support
concurrency, such as Ada tasks, is best.

@node Using a Middleware Environment, Using a Distributed Language, Using OS Network Services, Introduction to distributed systems
@subsection Using a Middleware Environment

A middleware environment is intended to provide high level abstractions
in order to easily develop user applications.  Environments like CORBA
or Distributed Computing Environment (DCE) provide a framework to
develop client/server applications based on the Remote Procedure Call model
(RPC). The RPC model is inspired by the query and reply
scheme. In rough analogy to a regular procedure call, arguments are pushed
onto a stream, along with some data specifying the remote procedure to
be executed. The stream is transmitted over the network to the
server. The server decodes the stream, performs the regular subprogram call
locally, and then puts the output parameters into another stream, along with the
exception (if any) raised by the subprogram execution. The server then
sends this stream back to the caller. The caller decodes the stream and raises
the exception locally if needed.

CORBA provides the same enhancements to the remote procedure model that
object-oriented languages provide to classical procedural languages.  These
enhancements include encapsulation, inheritance, type checking, and
exceptions. These features are offered through an Interface Definition
Language (IDL).

The middleware communication framework provides all the machinery to
perform, somewhat transparently, remote procedure calls or remote object
method invocations. For instance, each CORBA interface communicates
through an Object Request Broker (ORB). A communication subsystem such
as an ORB is intended to allow applications to use objects without being
aware of their underlying message-passing implementation. In addition. the user
may also require a number of more complex services to develop his
distributed application. Some of these services are indispensable, for example
a location service that allows clients to reference remote services via
higher level names, instead of a traditional scheme for addressing remote
services that use Internet host addresses and communication port
numbers. Other services provide domain-independent interfaces that are
frequently used by distributed applications.

If we return to the multi-threaded programming comparison, the
middleware solution is close to what a POSIX library or a language like
Esterel@footnote{@t{Esterel} is an imperative synchronous language
designed for the specification and the development of reactive systems.}
would provide for developing concurrent applications. A middleware
framework like DCE is close to a POSIX library in terms of abstraction
levels. Functionalities are very low-level and very complex. CORBA is
closer to Esterel in terms of development process.  The control part of
the application can be specified in a description language. The
developer then has to fill in automatically generated source code templates
(stubs and skeletons) to build the computational part of the application. The
distribution is a pre-compilation process and the distributed boundaries
are always explicit. Using CORBA, the distributed part is written in IDL
and the core of the application is written in a host language such as C++.

@node Using a Distributed Language,  , Using a Middleware Environment, Introduction to distributed systems
@subsection Using a Distributed Language

Rather than defining a new language like the CORBA IDL, an alternative is
to extend an existing programming language with distributed
features. The distributed object paradigm provides a more
object-oriented approach to programming distributed systems. The notion
of a distributed object is an extension to the abstract data type that
allows the services provided in the type interface to be called
independently of where the actual service is executed. When combined
with object-oriented features such as inheritance and polymorphism,
distributed objects offer a more dynamic and structured computational
environment for distributed applications.

The Distributed Systems Annex (DSA) of Ada defines several
extensions that allow the user to write a distributed system entirely in
Ada.  The types of distributed objects, the services they provide, and
the bodies of the remote methods to be executed are all defined in conventional
Ada packages. The Ada model is analogous to the Java/RMI model.
In both languages, the IDL is replaced by well-defined language constructs.
Therefore, the language supports both remote procedure
calls and remote object method invocations transparently, and the semantics
of distribution are consistent with the rest of the language.

A program written in such a language is intended to communicate with a
program written in the same language, but this apparent restriction has
several useful consequences. The language can provide more powerful
features because it is not constrained by the common features available
in all host languages. In Ada, the user will define a specification of
remote services and implement them exactly as he would for ordinary,
non-distributed services. His Ada environment will compile them to
produce a stub file (on the caller side) and a skeleton file that
automatically includes the body of the services (on the receiver
side). Creating objects, obtaining or registering object references or
adapting the object skeleton to the user object implementation are made
transparent because the language environment has a full control over the
development process.

Comparing with multi-threaded programming once again, the language
extension solution is equivalent to the solution adopted for tasking
facilities in Ada.  Writing a distributed application is as simple as
writing a concurrent application: there is no binding consideration and
no code to wrap.  The language and its run-time system take care of
most issues that would divert the programmer's attention from the
application domain.

@c -------------------------------------------------------------------
@node Distribution models and middleware standards
@section Distribution models and middleware standards
@c -------------------------------------------------------------------

@noindent
Middleware provides a framework that hides the complex issues of
distribution, and offers the programmer high-level abstractions that
allow easy and transparent construction of distributed applications.
A number of different standards exist for creating object-oriented
distributed applications. These standards define two subsystems that
enable interaction between application partitions:

@itemize @bullet
@item the API seen by the developer's applicative objects;

@item the protocol used by the middleware environment to interact with
other nodes in the distributed application.


@end itemize


@noindent
Middleware implementations also offer programming guidelines and
development tools to ease the construction of large heterogeneous
distributed systems. Many issues typical to distributed programming
may still arise: application architectural choice, configuration or
deployment. Since there is no ``one size fits all'' architecture,
choosing the adequate distribution middleware in its most appropriate
configuration is a key design point that dramatically impacts the
design and performance of an application.

Consequently, applications need to rapidly tailor middleware to the
specific distribution model they require. A distribution model is
defined by the combination of distribution mechanisms made available
to the application. Common examples of such mechanisms are Remote
Procedure Call (RPC), Distributed Objects or Message Passing. A
distribution infrastructure or middleware refers to software that
supports one distribution model (or several), e.g.: OMG CORBA, Java
Remote Method Invocation (RMI), the Distributed Systems Annex of Ada,
Java Message Service (MOM).

@c -------------------------------------------------------------------
@node The PolyORB generic middleware
@section The PolyORB generic middleware
@c -------------------------------------------------------------------

@noindent
Typical middleware implementations for one platform support only one
set of such interfaces, predefined configuration capabilities and
cannot interoperate with other platforms. In addition to traditional
middleware implementations, PolyORB provides an original architecture
to enable support for multiple interoperating distribution models in a
uniform canvas.

PolyORB is a polymorphic, reusable infrastructure for building or
prototyping new middleware adapted to specific application needs. It
provides a set of components on top of which various instances can be
elaborated. These instances (or personalities) are views on PolyORB
facilities that are compliant to existing standards, either at the API
level (application personality) or at the protocol level (protocol
personality). These personalities are mutually exclusive views of the
same architecture.

The decoupling of application and protocol personalities, and the
support for multiple simultaneous personalities within the same
running middleware, are key features required for the construction of
interoperable distributed applications. This allows PolyORB to
communicate with middleware that implements different distribution
standards: PolyORB provides middleware-to-middleware interoperability
(M2M).

PolyORB's modularity allows for easy extension and replacement of its
core and personality components, in order to meet specific requirements.
In this way, standard or application-specific personalities can be
created in a streamlined process, from early stage prototyping to
full-featured implementation. The PolyORB architecture also allows
the automatic, just-in-time creation of proxies between incompatible
environments.

You may find additional technical literature on PolyORB, including research
papers and implementation notes, on the project websites:
@url{http://libre.adacore.com/polyorb/} and
@url{http://polyorb.objectweb.org/}.

@i{Note: PolyORB is the project formerly known as DROOPI, a Distributed
Reusable Object-Oriented Polymorphic Infrastructure}

@c -------------------------------------------------------------------
@node Installation
@chapter Installation
@c -------------------------------------------------------------------

@menu
* Supported Platforms::
* Build requirements::
* Build instructions::
* Additional instructions for cross platforms::
* Building the documentation and PolyORB's examples::
* Build Options::
* Compiler Tools and Run-Time libraries Options::
* Platform notes::
@end menu

@c -------------------------------------------------------------------
@node Supported Platforms
@section Supported Platforms
@c -------------------------------------------------------------------

@noindent
PolyORB has been compiled and successfully tested on the following
platforms:

@itemize @bullet
@item AIX
@item FreeBSD
@item HP-UX
@item Linux
@item MacOS X
@item Solaris
@item Tru64
@item VxWorks
@item Windows
@end itemize

@noindent
@emph{Note: PolyORB should compile and run on every target for which
GNAT and the @code{GNAT.Sockets} package are available.}

@c -------------------------------------------------------------------
@node Build requirements
@section Build requirements
@c -------------------------------------------------------------------

@noindent
Ada compiler:
@itemize @bullet
@item GNAT Pro 6.0 or later
@item GNAT GPL 2007  or later
@item FSF GCC 4.3 or later
@end itemize

For builds for cross targets, both a native and a cross compiler are
required, as some tools (like an IDL-to-Ada compiler) are meant for
use on the build host.

Optional:

@itemize @bullet
@item (Only for older versions of GNAT, and only if you want to build
  the CORBA application personality): A C++ compiler. The OMG IDL
  specification mandates that IDL source files be preprocessed according
  to standard C++ preprocessing rules. Newer versions of GNAT provide an
  integrated IDL preprocessor. This feature is detected and used
  automatically. However, for older versions of GNAT, PolyORB relies on
  an external preprocessor provided by a suitable C++ compiler. Please
  refer to the documentation of your particular version of GNAT to know
  if it supports this feature.

@item XML/Ada (@url{http://libre.adacore.com/xmlada/}) if you
  want to build the SOAP protocol personality.
@end itemize

@noindent
Note: per construction, the macro @command{configure} used to find
your GNAT compiler looks first for the executable @command{gnatgcc},
then @command{adagcc} and finally @command{gcc} to find out which
Ada compiler to use. You should be very careful with your path and
executables if you have multiple GNAT versions installed. See the
explanation below on the ADA environment variable if you need to
override the default guess.

@c -------------------------------------------------------------------
@node Build instructions
@section Build instructions
@c -------------------------------------------------------------------

@noindent
To compile and install PolyORB, execute:


@smallexample
  $ ./configure [some options]
  $ make
  $ make install
@end smallexample

@noindent
This will install files in standard locations.  If you want to choose
a prefix other than @file{/usr/local}, give configure a
@option{--prefix=whereveryouwant} argument.

NOTE: you must use GNU make (version 3.80 or later) to build PolyORB.

@c -------------------------------------------------------------------
@node Additional instructions for cross platforms
@section Additional instructions for cross platforms
@c -------------------------------------------------------------------

@noindent
The @file{RANLIB} environment variable must be set to the path of the
cross @file{ranlib} prior to running @file{configure} with the
appropriate @code{--target} option.

For example, for VxWorks 5 execute:
@smallexample
  $ export RANLIB=ranlibppc
  $ ./configure --target=powerpc-wrs-vxworks [some options]
  $ make
  $ make install
@end smallexample

Only one PolyORB installation (native or cross) is currently possible
with a given @code{--prefix}. If both a native and a cross
installation are needed on the same machine, distinct prefixes must be
used.

@c -------------------------------------------------------------------
@node Building the documentation and PolyORB's examples
@section Building the documentation and PolyORB's examples
@c -------------------------------------------------------------------

@noindent
PolyORB's documentation and examples are built separately.

To build the examples, run @command{make examples} in the root
directory.  The build process will only build examples that correspond
to the personalities you configured. Note that some examples require the
CORBA COS Naming and IR services to be enabled (using
@command{--enable-corba-services="naming ir"} on the @command{configure}
command line).

Similarly, to build the documentation, run @command{make docs}.

You may install PolyORB's documentation in a standard location using
@command{make install}.

@c -------------------------------------------------------------------
@node Build Options
@section Build Options
@c -------------------------------------------------------------------

@noindent
Available options for the 'configure' script include:

@itemize @bullet

@item  @option{--with-appli-perso="..."}: application personalities to build

      Available personalities: AWS, CORBA, DSA, MOMA

      e.g.   @option{--with-appli-perso="corba moma"} to build both the CORBA
             and MOMA personalities

@item  @option{--with-proto-perso="..."}: protocol personalities to build

      Available personalities: GIOP, SOAP

      e.g.   @option{--with-proto-perso="giop soap"} to build both the GIOP
             and SOAP personalities

@item  @option{--with-idl-compiler="..."}: select default IDL compiler

       Available IDL compilers: iac, idlac

       e.g.  @option{--with-idl-compiler=''iac''} to build iac

@item  @option{--with-corba-services="..."}: CORBA COS services to build

      Available services: event, ir, naming, notification, time

      e.g.  @option{--with-corba-services="event naming"} to build only
      COS Event and COS Naming.

@end itemize

@noindent
By default, only the CORBA and GIOP personalities are built, and no
CORBA Services are built.

@itemize @bullet

@item  @option{--with-openssl}: build SSL support and SSL dependent
features, including the IIOP/SSLIOP personality

@item @option{--help}: list all options available

@item  @option{--enable-shared}: build shared libraries.

@item  @option{--enable-debug}:  enable debugging information generation
and supplementary runtime checks. Note that this option has a significant
space and time cost, and is not recommended for production use.

@end itemize

@c -------------------------------------------------------------------
@node Compiler Tools and Run-Time libraries Options
@section Compiler, Tools and Run-Time libraries Options
@c -------------------------------------------------------------------

@noindent
The following environment variables can be used to override configure's
guess at what compilers to use:

@itemize

@item @code{CC}:  the C compiler
@item @code{ADA}: the Ada compiler (e.g. gcc, gnatgcc or adagcc)
@item @code{CXXCPP}, @code{CXXCPPFLAGS}: the preprocessor used by
the IDL-to-Ada compiler (only when setting up the CORBA application
personality). CORBA specifications require this preprocessor to be
compatible with the preprocessing rules defined in the C++
programming language specifications.

@end itemize

@noindent
For example, if you have two versions of GNAT installed and available
in your @code{PATH}, and configure picks the wrong one, you can
indicate what compiler should be used with the following (assuming
Bourne shell syntax):

@smallexample
  $ ADA=/path/to/good/compiler/gcc ./configure [options]
@end smallexample

PolyORB will be compiled with GNAT build host's configuration,
including run-time library. You may override this setting using
@code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH} environment
variables. See GNAT User's Guide for more details.

You can add specific build options to GNAT using the
@code{EXTRA_GNATMAKE_FLAGS} variable:

@smallexample
  $ EXTRA_GNATMAKE_FLAGS=--RTS=rts-sjlj ./configure [options]
@end smallexample

You can also pass compiler-only flags using the @code{ADAFLAGS} variable.

NOTE: Developers building PolyORB from the version control repository
will need to rebuild the configure script and other files. To do so, run
the support/reconfig script after each update from the repository. In
addition to the requirements above, developers will need autoconf 2.57
or newer, automake 1.6.3 or newer, and libtool 1.5.8 or newer.

@c -------------------------------------------------------------------
@node Platform notes
@section Platform notes
@c -------------------------------------------------------------------

@noindent
Solaris (all versions):

/usr/ucb/tr is not suitable to build PolyORB. Your PATH must
be set to that tr(1) is /usr/bin/tr, /use/xpg4/bin/tr or GNU tr.

@noindent
Solaris 2.8:

/usr/bin/sed and /usr/ucb/sed will silently chop long
lines, and /usr/xpg4/bin/sed will enter an endless loop while
processing PolyORB files. GNU sed is required to configure and build PolyORB.

@noindent
Tru64 5.1A:

The default maximal data segment size may not be sufficient to compile
PolyORB. If a GNAT heap exhausted error message occurs during build,
try raising this limit using:
@smallexample
ulimit -d unlimited
@end smallexample

@noindent
AIX 5.2:

PolyORB must be compiled with the -mminimal-toc compiler switch. This is
taken care of automatically by the PolyORB configure script.

@noindent
HP-UX 11.00:

The version of install(1) from /opt/imake/bin on HP-UX is not suitable
for installing PolyORB. Make sure that /opt/imake/bin is not on the PATH
when building and installing PolyORB.

@c -------------------------------------------------------------------
@node Overview of PolyORB personalities
@chapter Overview of PolyORB personalities
@cindex Personalities
@c -------------------------------------------------------------------

@noindent
A personality is an instantiation of specific PolyORB components. It
provides the mechanisms specified by a distribution model, e.g. an
API, a code generator or a protocol stack.

This section provides a brief overview of existing personalities.

@emph{Note: some of these personalities are available only through
PolyORB's repository.}

@menu
* Application personalities::
* Protocol personalities::
@end menu

@c -------------------------------------------------------------------
@node Application personalities
@section Application personalities
@cindex Application personalities
@c -------------------------------------------------------------------

@noindent
Application personalities constitute the adaptation layer between
application components and middleware. They provide APIs and/or a code
generator to register application entities with PolyORB's core, and
interoperate with the core to allow the exchange of requests with
remote entities.

@menu
* CORBAoverview::
* DSAoverview::
* MOMAoverview::
* AWSoverview::
@end menu

@c -------------------------------------------------------------------
@node CORBAoverview
@subsection CORBA
@cindex CORBA
@cindex RT-CORBA
@cindex CORBA, COS Services
@c -------------------------------------------------------------------

@noindent
CORBA is the OMG specification of a Distributed Object Computing (DOC)
distribution model (@cite{[OMG04]}). It is now a well-known and
well-established specification, used in a wide range of industrial
applications.

PolyORB provides a CORBA-compatible implementation based on a mapping of
the IDL language version 1.2 described in @cite{[OMG01]} and CORBA
core specifications. PolyORB also provides an implementation of
various additional specifications described by the OMG, including
@code{COS Services: COS Naming, Notification, Event, Time}, and
additional specifications: @code{RT-CORBA}, @code{PortableInterceptors},
@code{DynamicAny}.

@c -------------------------------------------------------------------
@node DSAoverview
@subsection Distributed Systems Annex of Ada (DSA)
@cindex DSA, Distributed Systems Annex
@c -------------------------------------------------------------------

@noindent
The Distributed Systems Annex of Ada (DSA) @cite{[ISO06]} is a normative
part of the language specification. It was first introduced in the
``Ada 95'' revision of the language (@cite{[ISO95]}). It describes remote
invocation schemes applied to most language constructs.

@c -------------------------------------------------------------------
@node MOMAoverview
@subsection Message Oriented Middleware for Ada (MOMA)
@cindex MOMA, Message Oriented Middleware for Ada
@c -------------------------------------------------------------------

@noindent
MOMA (Message Oriented Middleware for Ada) provides message passing
mechanisms. It is an Ada adaptation of Sun's Java Message Service
(JMS) @cite{[SUN99]}, a standardized API for common message passing
models.

@c -------------------------------------------------------------------
@node AWSoverview
@subsection Ada Web Server (AWS)
@cindex AWS, Ada Web Server
@c -------------------------------------------------------------------

@noindent
The Web Server personality provides the same API as the Ada Web Server
project (AWS) @cite{[Obr03]}. It allows for the implementation of web
services, web server applications, or classical web pages. AWS-based
servers allow the programmer to directly interact with incoming or
outgoing @code{HTTP} and @code{SOAP} requests.

@c -------------------------------------------------------------------
@node Protocol personalities
@section Protocol personalities
@cindex Protocol personality
@c -------------------------------------------------------------------

@noindent
Protocol personalities handle the mapping of requests
(representing interactions between application entities) onto messages
exchanged through a communication network, according to a specific
protocol.

@menu
* GIOPoverview::
* SOAPoverview::
@end menu

@c -------------------------------------------------------------------
@node GIOPoverview
@subsection GIOP
@cindex GIOP
@c -------------------------------------------------------------------

@noindent
GIOP is the transport layer of the CORBA specifications. GIOP is a
generic protocol. This personality implements GIOP versions from 1.0
to 1.2 along with the CDR representation scheme to map data types
between the neutral core layer and CDR streams. It also provides the
following dedicated instances:

@itemize @bullet
@item IIOP supports synchronous request semantics over TCP/IP,
@cindex IIOP

@item IIOP/SSIOP supports synchronous request semantics using SSL sockets,
@cindex SSLIOP

@item MIOP instantiation of GIOP enables group communication over
IP multicast,
@cindex MIOP

@item DIOP relies on UDP/IP communications to transmit one-way
requests only.
@cindex DIOP

@end itemize

@c -------------------------------------------------------------------
@node SOAPoverview
@subsection SOAP
@cindex SOAP
@c -------------------------------------------------------------------

@noindent
The SOAP protocol @cite{[W3C03]} enables the exchange of structured
and typed information between peers. It is a self-describing XML
document @cite{[W3C03]} that defines both its data and
semantics. Basically, SOAP with @code{HTTP} bindings is used as a
communication protocol for Web Services.

@c -------------------------------------------------------------------
@node Building an application with PolyORB
@chapter Building an application with PolyORB
@cindex Configuration, PolyORB
@c -------------------------------------------------------------------

@menu
* Compile-time configuration::
* Run-time configuration::
* Setting up protocol personalities::
* Activating debugging traces::
* Tracing exceptions::
* polyorb.gpr::
* polyorb-config::
@end menu

@c -------------------------------------------------------------------
@node Compile-time configuration
@section Compile-time configuration
@c -------------------------------------------------------------------

@noindent
The user may configure some elements of a PolyORB application at
compile-time.

@menu
* Tasking runtimes::
* Middleware tasking policies::
* Sample files::
@end menu

@c -------------------------------------------------------------------
@node Tasking runtimes
@subsection Tasking runtimes
@c -------------------------------------------------------------------

@noindent
PolyORB provides several tasking runtimes. The user may select the
most appropriate one, depending on application requirements. The
tasking runtimes determine the constructs PolyORB may use for its
internal synchronizations.

@itemize @bullet
@item @code{No_Tasking}: There is no dependency on the Ada tasking
runtime, middleware is mono-task.

@item @code{Full_Tasking}: Middleware uses Ada tasking constructs,
middleware can be configured for multi-tasking.

@item @code{Ravenscar} : Middleware uses Ada
tasking constructs, with the limitations of the Ravenscar profile
@cite{[DB98]}.  Middleware can be configured for multi-tasking.
@cindex Ravenscar
@end itemize

@noindent
See @ref{Tasking model in PolyORB} for more information on this point.

@c -------------------------------------------------------------------
@node Middleware tasking policies
@subsection Middleware tasking policies
@c -------------------------------------------------------------------

@noindent
PolyORB provides several tasking policies. A tasking policy defines
how tasks are used by the middleware to process incoming requests.

@itemize @bullet
@item @code{No_Tasking}: There is only one task in middleware,
processing all requests.

@item @code{Thread_Per_Session}: One task monitors communication
entities. One task is spawned for each active connection. This task
handles all incoming requests on this connection.

@item @code{Thread_Per_Request}: One task monitors communication
entities. One task is spawned for each incoming request.

@item @code{Thread_Pool}: A set of tasks cooperate to handle all
incoming requests.

@end itemize

@noindent
See @ref{Tasking model in PolyORB} for more information on this point.

@c -------------------------------------------------------------------
@node Sample files
@subsection Sample files
@c -------------------------------------------------------------------

@noindent
PolyORB provides a set of predefined setup packages. You must `with'
one of them in your application node to activate the corresponding
setup.

@itemize @bullet
@item @code{PolyORB.Setup.Client}: a client node, without tasking
enabled, configured to use all protocol personalities built with PolyORB.

@item @code{PolyORB.Setup.Ravenscar_TP_Server}: a server node, with tasking
enabled, configured to use all protocol personalities built with
PolyORB. Middleware tasking runtime follows Ravenscar's profile
restrictions. Middleware tasking policy is @code{Thread_Pool}.

@item @code{PolyORB.Setup.Thread_Per_Request_Server}: a server node,
with tasking enabled, configured to use all protocol personalities
built with PolyORB. Middleware tasking policy is
@code{Thread_Per_Request}.

@item @code{PolyORB.Setup.Thread_Per_Session_Server}: a server node,
with tasking enabled, configured to use all protocol personalities
built with PolyORB. Middleware tasking policy is
@code{Thread_Per_Session}.

@item @code{PolyORB.Setup.Thread_Pool_Server}: a server node,
with tasking enabled, configured to use all protocol personalities
built with PolyORB. Middleware tasking policy is
@code{Thread_Pool}.

@end itemize

@noindent
To use one of these configurations, add a dependency on one of
these packages, for example,
@code{with PolyORB.Setup.Thread_Pool_Server;}. The elaboration of the
application (based on Ada rules) and the initialization of the partition
(based on the application personalities mechanisms) will properly set up
your application.

@c -------------------------------------------------------------------
@node Run-time configuration
@section Run-time configuration
@c -------------------------------------------------------------------


@noindent
The user may configure some elements of a PolyORB application at
run time.

Using the default configurations provided by PolyORB, the parameters
are read in the following order: command line, environment variables,
configuration file. PolyORB will use the first value that matches the
searched parameter.

@menu
* Using a configuration file::
* Using environment variables::
* Using the command line::
* Using a source file::
@end menu

@c -------------------------------------------------------------------
@node Using a configuration file
@subsection Using a configuration file
@cindex @file{polyorb.conf}
@cindex @code{POLYORB_CONF}
@c -------------------------------------------------------------------


@noindent
A configuration file may be used to configure a PolyORB node. A sample
configuration file may be found in @file{src/polyorb.conf}.

The syntax of the configuration file is:
@itemize @bullet
@item empty lines and lines that have a '#' in column 1 are ignored;

@item sections can be started by lines of the form
    @code{[ SECTION-NAME ]};

@item variable assignments can be performed by lines of the form
@code{VARIABLE-NAME = VALUE}.

Any variable assignment is local to a section.

Assignments that occur before the first section declaration are
relative to section [environment].  Section and variable names are
case sensitive.

Furthermore, each time a value starts with @code{"file:"}, the contents
of the file are used instead.
@end itemize

@noindent
Default search path for @file{polyorb.conf} is current
directory. Environment variable @code{POLYORB_CONF} may be used to
set up information on configuration file.

PolyORB's configuration file allows the user to
@enumerate
@item enable/disable the output of debug information
@item set up default reference on naming service
@item select the default protocol personality
@item set up each protocol personality
@end enumerate

@noindent
The configuration file is read once when running a node, during
initialization. Look in the sample configuration file
@file{src/polyorb.conf} to see the available sections and variables.

@c -------------------------------------------------------------------
@node Using environment variables
@subsection Using environment variables
@c -------------------------------------------------------------------

@noindent
A variable @code{Var.Iable} in section @code{[Sec]} can be overridden
by setting environment variable @code{"POLYORB_SEC_VAR_IABLE"}.

@c -------------------------------------------------------------------
@node Using the command line
@subsection Using the command line
@c -------------------------------------------------------------------

@noindent
PolyORB allows to set up configuration variables on the command
line. The syntax is close to the one described in configuration files.
A variable @code{Var.Iable} in section @code{[Sec]} can be overridden
with flag @code{--polyorb-<sec>-<var>-<iable>[=<value>]}.

@c -------------------------------------------------------------------
@node Using a source file
@subsection Using a source file
@c -------------------------------------------------------------------

@noindent
Many embedded systems do not have a filesystem or a shell, so the
previous run-time configuration methods cannot be used on these targets.
On these platforms, a PolyORB node can also be configured using the API of package
@code{PolyORB.Parameters.Static}. An example configuration file may be
found in @file{examples/static/po_static_conf.ads}.

An array of PolyORB parameters of type @code{Static_Parameters_Array} is
first declared containing a list of pairs of Variable and Value strings.
The syntax is close to the one described in configuration files.
A variable @code{Var.Iable} in section @code{[Sec]} is specified
as the pair of strings @code{"[sec]var.iable", "<value>"}.

There is no need to with this @file{po_static_conf.ads} in the application
source code, the only requirement is that the array is exported with the
external name "@code{__polyorbconf_optional}". This allows to modify
PolyORB parameters without recompiling the application, just relinking
it. For example:

@smallexample
  $ gnatmake -c po_static_conf.ads `polyorb-config`
  $ gnatmake -b -l server.adb `polyorb-config` -largs po_static_conf.o
@end smallexample

Note the @code{-l} flag to gnatmake for linking only, and the need to
specify to the linker the object file with the array using @code{-largs}
if no package withs it.

It should be noticed that this static array of parameters is read at
elaboration time only, this API cannot be used to modify the PolyORB
configuration at run-time.

@c -------------------------------------------------------------------
@node Setting up protocol personalities
@section Setting up protocol personalities
@c -------------------------------------------------------------------

@noindent
PolyORB allows the user to activate some of the available protocol
personalities and to set up the preferred protocol. Protocol-specific
parameters are defined in their respective sections.

@menu
* Activating/Deactivating protocol personalities::
* Configuring protocol personality preferences::
@end menu

@c -------------------------------------------------------------------
@node Activating/Deactivating protocol personalities
@subsection Activating/Deactivating protocol personalities
@cindex Protocol personality, activation
@c -------------------------------------------------------------------

@noindent
Protocol activation is controlled by PolyORB's configuration file.

The section @code{[access_points]} controls the initialization of
@emph{access points}. An access point is a node entry point that may
serve incoming requests.

@smallexample
[access_points]
soap=enable
iiop=enable
diop=disable
uipmc=disable
@end smallexample

@noindent
This example activates SOAP and IIOP, but deactivates DIOP and MIOP.

The section @code{[modules]} controls the activation/deactivation of
some modules within PolyORB. It is used to enable @emph{bindings} to
remote entities.

@smallexample
[modules]
binding_data.soap=enable
binding_data.iiop=enable
binding_data.diop=disable
binding_data.uipmc=disable
@end smallexample

@noindent
This example enables the creation of bindings to remote objects using
SOAP or IIOP. Objects cannot be reached using DIOP or UIPMC.

@emph{Note: by default, all configured personalities are activated.}

@c -------------------------------------------------------------------
@node Configuring protocol personality preferences
@subsection Configuring protocol personality preferences
@c -------------------------------------------------------------------

@noindent
The user may affect a @emph{preference} to each protocol
personality. The protocol with the higher preference will be selected
among possible protocols to send a request to a remote node.

See @code{polyorb.binding_data.<protocol>.preference} in
section @code{[protocol]} to set up protocol's preference.

Possible protocols are defined as the protocols available on the
remote node, as advertised in its @emph{object reference}.  @code{IOR}
or @code{corbaloc} references may support multiple protocols;
@code{URI} references support only one protocol.

Each protocol supports a variety of configuration parameters, please
refer to the protocols' sections for more details.

@c -------------------------------------------------------------------
@node Activating debugging traces
@section Activating debugging traces
@cindex Debugging traces
@c -------------------------------------------------------------------

@noindent
To activate the output of debug information, you must first configure
and compile PolyORB with debugging traces activated (which is the default,
unless your build is configured with @command{--enable-debug-policy=ignore}).

To output debugging traces on a selected package, create a
configuration file with a @code{[log]} section and the name of the
packages for which you want debug information:

@smallexample
# Sample configuration file, output debug for PolyORB.A_Package
[log]
polyorb.a_package=debug
@end smallexample

@noindent
Note that some packages may not provide such information. See the sample
configuration file @file{src/polyorb.conf} for the complete list of
packages that provide traces.

@c -------------------------------------------------------------------
@node Tracing exceptions
@section Tracing exceptions
@cindex Exceptions
@c -------------------------------------------------------------------

@noindent
To trace exception propagation in PolyORB's source code, activate debugging
traces for package @code{PolyORB.Exceptions}.

@c -------------------------------------------------------------------
@node polyorb.gpr
@section @command{polyorb.gpr}
@cindex @command{polyorb.gpr}
@c -------------------------------------------------------------------

@noindent
This section describes how to build your program using project files.
An alternative method, using @command{polyorb-config}, is described in the
following section. @command{polyorb-config} is intended primarily for Unix-like
systems. The project-file method will work on all supported systems.

To build your application, create a project file as usual.
Import the @command{polyorb.gpr} project by putting @code{with "polyorb";}
in your project file.

Set the ADA_PROJECT_PATH environment variable to point to the directory
containing @command{polyorb.cfg}, which is @command{<prefix>/lib/gnat}.
If SOAP is being used, ADA_PROJECT_PATH must also be set so we can find
@command{xmlada.gpr}.

If your project file is @command{my_proj.gpr}, you can build it by saying:

@smallexample
  $ gnatmake -P my_proj
@end smallexample

See the GNAT User's Guide and the GNAT Reference Manual for more information
on project files.

@c -------------------------------------------------------------------
@node polyorb-config
@section @command{polyorb-config}
@cindex @command{polyorb-config}
@c -------------------------------------------------------------------

@noindent
@command{polyorb-config} returns path and library information on
PolyORB's installation.  It can be used on the @command{gnatmake}
command line, like this:


@smallexample
  $ gnatmake my_program.adb `polyorb-config`
@end smallexample


@smallexample

@c XXX check consistency with corresponding man page

NAME
       polyorb-config  - script to get information about the installed version
       of PolyORB.

SYNOPSIS
       polyorb-config [--prefix[=DIR]] [--exec-prefix[=DIR]] [--version|-v]
       [--config] [--libs] [--cflags] [--idls] [--help]

DESCRIPTION
       polyorb-config  is  a  tool  that is used to determine the compiler and
       linker flags that should be used to compile and link programs that  use
       PolyORB.

OPTIONS
       polyorb-config accepts the following options:

       --prefix[=DIR]
                Output the directory in which PolyORB architecture-independent
               files are installed, or set this directory to DIR.

       --exec-prefix[=DIR]
                Output the directory in which  PolyORB  architecture-dependent
               files are installed, or set this directory to DIR.

       --version
               Print  the  currently installed version of PolyORB on the stan-
               dard output.

       --config
               Print the configuration of the currently installed  version  of
               PolyORB on the standard output.

       --libs  Print  the  linker  flags  that are necessary to link a PolyORB
               program.

       --cflags
               Print the compiler flags that are necessary to compile a  Poly-
               ORB program.

       --idls
               Output flags to set up path to CORBA's IDL for idlac.

       --with-appli-perso=P,P,P
               Restrict output to only those flags relevant to the listed
               applicative personalities.

       --with-proto-perso=P,P,P
               Restrict output to only those flags relevant to the listed
               protocol personalities.

       --with-corba-services=S,S,S
              Restrict output to only those flags relevant to the listed
              services.

       --help  Print help message.


@end smallexample

@c -------------------------------------------------------------------
@node Tasking model in PolyORB
@chapter Tasking model in PolyORB
@cindex Tasking model
@c -------------------------------------------------------------------

@menu
* PolyORB Tasking runtimes::
* PolyORB ORB Tasking policies::
* PolyORB Tasking configuration::
* PolyORB ORB Controller policies::
* PolyORB ORB Controller configuration::
@end menu

@c -------------------------------------------------------------------
@node PolyORB Tasking runtimes
@section PolyORB Tasking runtimes
@cindex Tasking runtime
@c -------------------------------------------------------------------

@noindent
PolyORB may use any of three different tasking runtimes to manage and
synchronize tasks, if any. Tasking runtime capabilities are defined
in the Ada Reference Manual @cite{[ISO06]}.

The choice of a specific tasking runtime is a compile-time parameter,
@ref{Tasking runtimes} for more details on their configuration.

@c -------------------------------------------------------------------
@subsection Full tasking runtime
@c -------------------------------------------------------------------

@noindent
Full tasking runtime refers to the configuration in which there are
dependencies on the tasking constructs defined in chapter 9 of
@cite{[ISO06]}. It makes use of all capabilities defined in this section
to manage and synchronize tasks.

In this configuration, a PolyORB application must be compiled and
linked with a tasking-capable Ada runtime.

@c -------------------------------------------------------------------
@subsection No tasking runtime
@c -------------------------------------------------------------------

@noindent
No tasking runtime refers to the configuration in which there is no
dependency on tasking constructs. Thus, no tasking is required.

In this configuration, a PolyORB application may be compiled and
linked with a tasking-capable Ada runtime or a no-tasking Ada runtime.

@c -------------------------------------------------------------------
@subsection Ravenscar tasking runtime
@cindex Ravenscar
@c -------------------------------------------------------------------

@noindent
Ravenscar tasking runtime refers to the configuration in which tasking
constructs are compliant with the @emph{Ravenscar tasking restricted
profile}.

In this configuration, a PolyORB application may be compiled and
linked with a tasking-capable Ada runtime or a Ravenscar Ada runtime.

To configure tasking constructs used by PolyORB, one must instantiate
the @code{PolyORB.Setup.Tasking.Ravenscar} generic package shown below
to set up tasks and protected objects used by PolyORB core.

@include polyorb-setup-tasking-ravenscar.ads.texi

@c -------------------------------------------------------------------
@node PolyORB ORB Tasking policies
@section PolyORB ORB Tasking policies
@c -------------------------------------------------------------------

PolyORB ORB Tasking policies control the creation of tasks to
process all middleware internal jobs, e.g. request processing, I/O
monitoring.

@noindent
@i{Note: there is a dependency between ORB Tasking policies, and the
runtime used, as detailed below.}

@c -------------------------------------------------------------------
@subsection No Tasking
@c -------------------------------------------------------------------

Under the No Tasking ORB policy, no tasks are created within the
middleware instance: it uses the environment task to process all
jobs. Note that this policy is not thread safe and is compatible with
the No tasking runtime only.

@c -------------------------------------------------------------------
@subsection Thread Pool
@c -------------------------------------------------------------------

Under the Thread Pool ORB policy, the middleware creates a pool of
threads during initialization of PolyORB. This pool processes all
jobs. The number of tasks in the thread pool can be configured by three
parameters in the @code{[tasking]} configuration section.

@itemize @bullet

@item @code{min_spare_threads} indicates the number of tasks
created at startup.

@item @code{max_spare_threads} is a ceiling. When a remote subprogram
call is completed, its anonymous task is deallocated if the number of
unused tasks already in the pool is greater than the ceiling. If not,
then the task is queued in the pool.

@item @code{max_threads} indicates the maximum number of tasks in the pool.

@end itemize

@xref{PolyORB Tasking configuration}, for more information on how to
configure the number of tasks in the thread pool.

@c -------------------------------------------------------------------
@subsection Thread Per Session
@c -------------------------------------------------------------------

Under the Thread Per Session ORB policy, the middleware creates one
task when a new session (one active connection) is opened. The task
terminates when the session is closed.

@c -------------------------------------------------------------------
@subsection Thread Per Request
@c -------------------------------------------------------------------

Under the Thread Per Request ORB policy, the middleware creates one
task per incoming request. The task terminates when the request is
completed.

@c -------------------------------------------------------------------
@node PolyORB Tasking configuration
@section PolyORB Tasking configuration
@c -------------------------------------------------------------------


@noindent
The following parameters allow the user to set up some of the tasking
parameters.

@c check consistency with polyorb.conf

@smallexample

###############################################################################
# Parameters for tasking
#

[tasking]
# Default storage size for all threads spawned by PolyORB
#storage_size=262144

# Number of threads by Thread Pool tasking policy
#min_spare_threads=4
#max_spare_threads=4
#max_threads=4

@end smallexample

@c -------------------------------------------------------------------
@node PolyORB ORB Controller policies
@section PolyORB ORB Controller policies
@c -------------------------------------------------------------------

The PolyORB ORB Controller policies are responsible for the management
of the global state of the middleware: they assign middleware internal
jobs, or I/Os monitoring to middleware tasks.

ORB Controller policies grant access to middleware internals and
affect one action for each middleware task. They ensure that all
tasks work concurrently in a thread-safe manner.

@c -------------------------------------------------------------------
@subsection No Tasking
@c -------------------------------------------------------------------

The No Tasking ORB Controller policy is dedicated to no-tasking
middleware configurations; the middleware task executes the following
loop: process internal jobs, then monitor I/Os.

@c -------------------------------------------------------------------
@subsection Workers
@c -------------------------------------------------------------------

The Workers ORB Controller policy is a simple controller policy: all
tasks are equal, they may alternatively and randomly process requests
or wait for I/O sources.

@i{Note: this is the default configuration provided by PolyORB sample
setup files, @xref{Sample files}.}

@c -------------------------------------------------------------------
@subsection Half Sync/Half Async
@c -------------------------------------------------------------------

The Half Sync/Half Async ORB Controller policy implements the ``Half
Sync/Half Async'' design pattern: it discriminates between one thread
dedicated to I/O monitoring that queue middleware jobs; another pool
of threads dequeue jobs and process them.

@i{Note: this pattern is well-suited to process computation-intensive
requests.}

@c -------------------------------------------------------------------
@subsection Leader/Followers
@c -------------------------------------------------------------------

The Leader/Followers ORB Controller policy implements the
``Leader/Followers '' design pattern: multiple tasks take turns to
monitor I/O sources and then process requests that occur on the event
sources.

@i{Note: this pattern is adapted to process a lot of light requests.}

@c -------------------------------------------------------------------
@node PolyORB ORB Controller configuration
@section PolyORB ORB Controller configuration
@c -------------------------------------------------------------------


@noindent
The following parameters allow the user to set up parameters for ORB
Controllers.

@c check consistency with polyorb.conf

@smallexample

###############################################################################
# Parameters for ORB Controllers
#

[orb_controller]
# Interval between two polling actions on one monitor
#polyorb.orb_controller.polling_interval=0

# Timeout when polling on one monitor
#polyorb.orb_controller.polling_timeout=0

@end smallexample

@c -------------------------------------------------------------------
@node CORBA
@chapter CORBA
@cindex CORBA
@c -------------------------------------------------------------------

@menu
* What you should know before Reading this section::
* Installing CORBA application personality::
* IDL-to-Ada compiler::
* Resolving names in a CORBA application::
* The CORBA Interface Repository::
* Building a CORBA application with PolyORB::
* Configuring a CORBA application::
* Implementation Notes::
* PolyORB specific APIs::
@end menu


@c -------------------------------------------------------------------
@node What you should know before Reading this section
@section What you should know before Reading this section
@c -------------------------------------------------------------------

@noindent
This section assumes that the reader is familiar with the CORBA
specifications described in @cite{[OMG04]} and the @emph{IDL-to-Ada}
mapping defined in @cite{[OMG01]}.

@c -------------------------------------------------------------------
@node Installing CORBA application personality
@section Installing CORBA application personality
@c -------------------------------------------------------------------

@noindent
Ensure PolyORB has been configured and then compiled with the CORBA
application personality. See @ref{Building an application with PolyORB}
for more details on how to check installed personalities.

To build the CORBA application personality, @pxref{Installation}.

@c -------------------------------------------------------------------
@node IDL-to-Ada compiler
@section IDL-to-Ada compiler
@c -------------------------------------------------------------------

@noindent
PolyORB provides two IDL-to-Ada compilers:

@enumerate
@item @command{idlac} is the legacy PolyORB IDL-to-Ada compiler,
@item @command{iac} is the new, optimized IDL-to-Ada compiler.
@end enumerate

@menu
* Usage of idlac::
* Usage of iac::
* Difference between idlac and iac::
@end menu

@c -------------------------------------------------------------------
@node Usage of idlac
@subsection Usage of @command{idlac}
@cindex @command{idlac}
@c -------------------------------------------------------------------

@noindent
@command{idlac} is PolyORB's IDL-to-Ada compiler.


@smallexample

@c XXX check consistency with corresponding man page

NAME
       idlac - PolyORB's IDL-to-Ada compiler

SYNOPSIS
       idlac [-Edikpqv] [-[no]ir] [-gnatW8] [-o DIR] idl_file [-cppargs ...]

DESCRIPTION
       idlac is an IDL-to-Ada compiler, compliant with version 1.2 of the
       ``Ada Language Mapping Specification'' produced by the OMG.

OPTIONS
       idlac accepts the following options:

       -E      Preprocess only.

       -d      Generate delegation package.

       -i      Generate implementation template.

       -s      Generate server side code.

       -c      Generate client side code.

       -k      Keep temporary files.

       -p      Produce source on standard output.

       -q      Be quiet (default).

       -v      Be verbose.

       -ir     Generate code for interface repository.

       -noir   Don't generate code for interface repository (default).

       -gnatW8
               Use UTF8 character encoding

       -o DIR Specify output directory

       -cppargs ARGS
               Pass ARGS to the C++ preprocessor.

       -I dir  Shortcut for -cppargs -I dir.

EXIT STATUS
       idlac returns one of the following values upon exit:

       0      Successful completion

       1      Usage error

       2      Illegal IDL specification

@end smallexample

@noindent
@command{idlac} creates several files :


@itemize @bullet

@item  @code{myinterface.ads}, @code{myinterface.adb} : these files contain
  the mapping for user defined types (client and server side).

@item @code{myinterface-impl.ads}, @code{myinterface-impl.adb} :
  these files are to be filled in by the user. They contain the
  implementation of the server. They are generated only if the -i flag
  is specified.

@item @code{myinterface.ads}, @code{myinterface.adb} : these files
  contain the client stubs for the interface.

@item @code{myinterface-skel.ads}, @code{myinterface-skel.adb} : these files
  contain the server-side skeletons for the interface.

@item @code{myinterface-helper.ads}, @code{myinterface-helper.adb} : these
  files contain subprograms to marshal data into CORBA Any containers.

@item @code{myinterface-ir_info.ads}, @code{myinterface-ir_info.adb} : these
  files contain code for registering IDL definitions in the CORBA Interface
  Repository. They are generated only if the @code{'-ir'} flag is specified.


@end itemize

@c -------------------------------------------------------------------
@node Usage of iac
@subsection Usage of @command{iac}
@cindex @command{iac}
@c -------------------------------------------------------------------

@noindent
@command{iac} is PolyORB's new IDL-to-Ada compiler. It supports
many command line parameters to control code generation optimizations
such as use of static hashing for deterministic request dispatching,
and optimized GIOP marshalling for CORBA applications.

@smallexample

@c XXX check consistency with corresponding man page

NAME
       iac - PolyORB's IDL-to-Ada compiler

SYNOPSIS
       iac [-Edikpqv] [-[no]ir] [-gnatW8] [-o DIR] idl_file [-cppargs ...]

DESCRIPTION
       iac is an IDL-to-Ada compiler, compliant with version 1.2 of the
       ``Ada Language Mapping Specification'' produced by the OMG.

OPTIONS
       iac accepts the following options:

  -E       Preprocess only
  -k       Keep temporary files
  -p       Produce source on standard output
  -o DIR   Specify output directory (DIR must exist)

  -dm      Generate debug messages when analyzing scopes

  -df      Dump the frontend tree (the IDL tree)

  -cppargs Pass arguments to the C++ preprocessor
  -I <dir> Shortcut -cppargs -I directory. Use this flag
           for the imported entities
  -nocpp   Do not preprocess input

  -<lang>  Generate code for a supported language

   types   Generate a list of all types present in the IDL file
           -p       Print the list generate

   ada     Generate Ada source code
           -i       Generate implementation packages
           -c       Generate code for client side only
           -s       Generate code for server side only
           -d       Generate delegation package (defunct)
           -ir      Generate code for interface repository (defunct)
           -noir    Do not generate code for interface repository (default)
           -hc      Using perfect minimal hash tables in skeletons
                    and minimize CPU time
           -hm      Using perfect minimal hash tables in skeletons
                    and minimize memory space
           -rs      Use the SII/SSI to handle requests
           -rd      Use the DII/DSI to handle requests (default)
           -da      Dump the Ada tree
           -db      Generate only the package bodies
           -ds      Generate only the package specs
           -dw      Output the withed entities
           -dt      Output tree warnings
           -di      Generate code for imported entities

   idl     Dump parsed IDL file
           -b n     Base to output integer literal
                    As a default (zero) use base from input
           -e       Expand IDL Tree
           -df      Dump IDL Tree (may be used in conjunction with -e
                    to dump the expanded IDL tree)
           -di      Output IDL code of imported entities  (may be
                    used in conjunction with -e to output the
                    expanded IDL code)

EXIT STATUS
       iac returns one of the following values upon exit:

       0      Successful completion

       1      Usage error

       2      Illegal IDL specification

@end smallexample

@noindent
@command{iac} creates several files :


@itemize @bullet

@item  @code{myinterface.ads}, @code{myinterface.adb} : these files contain
  the mapping for user defined types (client and server side).

@item @code{myinterface-impl.ads}, @code{myinterface-impl.adb} :
  these files are to be filled in by the user. They contain the
implementation of the server. They are generated only if the -i flag
is specified.

@item @code{myinterface.ads}, @code{myinterface.adb} : these files
  contain the client stubs for the interface.

@item @code{myinterface-skel.ads}, @code{myinterface-skel.adb} : these files
  contain the server-side skeletons for the interface.

@item @code{myinterface-helper.ads}, @code{myinterface-helper.adb} : these
  files contain subprograms to marshal data into CORBA Any containers.

@item @code{myinterface-ir_info.ads}, @code{myinterface-ir_info.adb} : these
  files contain code for registering IDL definitions in the CORBA
Interface Repository. They are generated only if the @code{'-ir'} flag
is specified.

@item @code{myinterface-cdr.ads}, @code{myinterface-cdr.adb} : these
  files contain code for optimized CDR marshalling of GIOP
messages. They are generated only if the @code{'-rs'} flag is
specified.

@end itemize

@c -------------------------------------------------------------------
@node Difference between idlac and iac
@subsection Difference between idlac and iac
@c -------------------------------------------------------------------

@noindent
This section lists the main differences between @command{idlac} and
@command{iac}

@itemize
@item @command{iac} is backward compatible with @command{idlac}, but
lacks the following feature:
@enumerate
@item generation of delegation files.
@end enumerate
@end itemize

@command{iac} implements additional name clash resolution rules.
When the name of an IDL operation clashes with a primitive operation
of Ada.Finalization.Controlled (of which CORBA.Object.Ref is a derived
type), it is prefixed with "IDL_" in generated sources.

@c -------------------------------------------------------------------
@node Resolving names in a CORBA application
@section Resolving names in a CORBA application
@c -------------------------------------------------------------------

@noindent
PolyORB implements the CORBA COS Naming service.

@menu
* po_cos_naming::
* Registering the reference to the COS Naming server::
* Using the COS Naming::
@end menu

@c -------------------------------------------------------------------
@node po_cos_naming
@subsection @command{po_cos_naming}
@cindex @command{po_cos_naming}
@cindex @command{CORBA COS Naming}
@c -------------------------------------------------------------------

@noindent
@command{po_cos_naming} is a standalone server that supports the CORBA
COS Naming specification. When launched, it returns its @code{IOR} and
@code{corbaloc}, which can then be used by other CORBA applications.

If you want @command{po_cos_naming} to return the same @code{IOR} or
@code{corbaloc} at each startup, you must set a default listen port
for the protocol personalities you use. See @ref{Configuring protocol
personality preferences} for more details.

@command{po_cos_naming} can output its @code{IOR} directly to a file
using the @command{-file <filename>} flag.  This, in conjonction with
the @command{'file://'} naming scheme provided by @command{CORBA},
provides a convenient way to store initial references to the Naming
Service.

@smallexample
Usage: po_cos_naming
 -file <filename> : output COS Naming IOR to 'filename'
 -help : print this help
 [PolyORB command line configuration variables]
@end smallexample

@c -------------------------------------------------------------------
@node Registering the reference to the COS Naming server
@subsection Registering the reference to the COS Naming server
@c -------------------------------------------------------------------

@noindent
You have two ways to register the reference to the root context of the
COS Naming server the application will use:

@itemize @bullet
@item Setting up the @code{name_service} entry in the @code{[corba]}
section in your configuration file, @code{name_service} is the
@code{IOR} or @code{corbaloc} of the COS Naming server to use. See
@ref{Using a configuration file} for more details.

@item Registering an initial reference using the @code{-ORBInitRef
NamingService=<IOR>} or @code{-ORBInitRef NamingService=<corbaloc>}
command-line argument. See the CORBA specifications for more details.

@item Registering an initial reference for
@code{NamingService} using the
@code{CORBA.ORB.Register_Initial_Reference} function. See the CORBA
specifications for more details.

@end itemize

@c -------------------------------------------------------------------
@node Using the COS Naming
@subsection Using the COS Naming
@c -------------------------------------------------------------------

@noindent
PolyORB provides a helper package to manipulate the COS Naming in your
applications. See @ref{PolyORB specific APIs} for more details.

@c -------------------------------------------------------------------
@node The CORBA Interface Repository
@section The CORBA Interface Repository
@c -------------------------------------------------------------------

@noindent
PolyORB implements the CORBA Interface Repository.

@menu
* po_ir::
* Using the Interface Repository::
@end menu

@c -------------------------------------------------------------------
@node po_ir
@subsection @command{po_ir}
@cindex @command{po_ir}
@c -------------------------------------------------------------------

@noindent
@command{po_ir} is a standalone server that supports the CORBA
Interface Repository. When launched, it returns its @code{IOR} and
@code{corbaloc}, which can then be used by other CORBA applications.

If you want @command{po_ir} to return the same @code{IOR} or
@code{corbaloc} at each startup, you must set a default listen port
for the protocol personalities you use. See @ref{Configuring protocol
personality preferences} for more details.

@c -------------------------------------------------------------------
@node Using the Interface Repository
@subsection Using the Interface Repository
@c -------------------------------------------------------------------

@noindent
The IDL-to-Ada compiler generates a helper package that allows you to
register all entities defined in your IDL specification in the
Interface Repository.

@c -------------------------------------------------------------------
@node Building a CORBA application with PolyORB
@section Building a CORBA application with PolyORB
@c -------------------------------------------------------------------

@menu
* echo example::
* Other examples::
@end menu

@c -------------------------------------------------------------------
@node echo example
@subsection @code{echo} example
@c -------------------------------------------------------------------


@noindent
We consider building a simple ``Echo'' CORBA server and client. This
application echoes a string. The source code for this example is
located in the @file{examples/corba/echo} directory in the PolyORB
distribution. This applications uses only basic elements of CORBA.

To build this application, you need the following pieces of code:

@enumerate
@item IDL definition of an @code{echo} object
@item Implementation code for the @code{echo} object
@item Code for client and server nodes
@end enumerate

@c -------------------------------------------------------------------
@subsubsection IDL definition of an @code{echo} object
@c -------------------------------------------------------------------

@noindent
This interface defines an @code{echo} object with a unique method
@code{echoString}. Per construction, this method returns its argument.

@include echo.idl.texi

@c -------------------------------------------------------------------
@subsubsection Implementation code for the @code{echo} object
@c -------------------------------------------------------------------

@noindent
Package @code{Echo.Impl} is an implementation of this interface. This
implementation follows the @emph{IDL-to-Ada} mapping.

@include echo-impl.ads.texi
@include echo-impl.adb.texi

@noindent
@i{Note: @code{Echo.Impl} body requires a dependency on
@code{Echo.Skel} to ensure the elaboration of skeleton code and the
correct setup of PolyORB's internals.}

@c -------------------------------------------------------------------
@subsubsection Test code for client and server nodes
@c -------------------------------------------------------------------

@noindent
Client and server code demonstrate how to make a remote invocation on
a CORBA object, and how to set up an object on a server node.

@emph{Note: the dependency on @code{PolyORB.Setup.Client} or
@code{PolyORB.Setup.No_Tasking_Server} enforces compile-time
configuration, @pxref{Sample files}.}

@itemize @bullet
@item Client code tests a simple remote invocation on
an object. It is a no-tasking client. A reference to the object is built
from a stringified reference (or @code{IOR}), which is passed on command
line.

@include client.adb.texi

@item The server code sets up a no-tasking node. The object is registered to
the @code{RootPOA}. Then an @code{IOR} reference is built to enable
interaction with other nodes.

@include server.adb.texi

@end itemize

@c -------------------------------------------------------------------
@subsubsection Compilation and execution
@c -------------------------------------------------------------------

@noindent
To compile this demo,
@enumerate
@item Process the IDL file with @command{idlac} (or @command{iac})
@smallexample
 $ idlac echo.idl
@end smallexample

@item Compile the client node
@smallexample
 $ gnatmake client.adb `polyorb-config`
@end smallexample

@item Compile the server node
@smallexample
 $ gnatmake server.adb `polyorb-config`
@end smallexample

@end enumerate

@noindent
Note the use of backticks (`). This means that
@command{polyorb-config} is first executed, and then the command line
is replaced with the output of the script, setting up library and
include paths and library names.

To run this demo:

@itemize @bullet
@item run @file{server}, the server outputs its IOR, a hexadecimal
string with the IOR: prefix:
@smallexample
$ ./server
Loading configuration from polyorb.conf
No polyorb.conf configuration file.
'IOR:01534f410d00000049444c3[..]'
@end smallexample

@item In another shell, run @file{client}, passing cut-and-pasting the
complete IOR on the command line:
@smallexample
$ ./client 'IOR:01534f410d00000049444c3[..]'
Echoing string: " Hello Ada ! "
I said : Hello Ada !
The object answered : Hello Ada !
@end smallexample
@end itemize

@c -------------------------------------------------------------------
@node Other examples
@subsection Other examples
@c -------------------------------------------------------------------

@noindent
PolyORB provides other examples to test other CORBA features. These
examples are located in the @file{example/corba} directory in the PolyORB
distribution.

@itemize @bullet
@item @file{all_functions} tests CORBA parameter passing modes
(@code{in}, @code{out}, ..);
@item @file{all_types} tests CORBA types;
@item @file{echo} is a simple CORBA demo;
@item @file{random} is a random number generator;
@item @file{send} tests MIOP specific API.
@end itemize

@c -------------------------------------------------------------------
@node Configuring a CORBA application
@section Configuring a CORBA application
@cindex Configuration, CORBA
@c -------------------------------------------------------------------

@menu
* Configuring PolyORB::
* Configuring GIOP protocol stack for PolyORB::
* Configuring Security services for PolyORB::
* Command line arguments::
@end menu

@noindent
To configure a CORBA application, you need to separately configure
PolyORB and the GIOP protocol (or any other protocol personality you
wish to use).

@c -------------------------------------------------------------------
@node Configuring PolyORB
@subsection Configuring PolyORB
@c -------------------------------------------------------------------

@noindent
Please refer to @ref{Building an application with PolyORB} for more
information on PolyORB's configuration.

@c -------------------------------------------------------------------
@node Configuring GIOP protocol stack for PolyORB
@subsection Configuring GIOP protocol stack for PolyORB
@c -------------------------------------------------------------------

@noindent
The GIOP protocol is separated from the CORBA application
personality. See @ref{Configuring the GIOP personality} for more
information on GIOP's configuration.

@c -------------------------------------------------------------------
@node Configuring Security services for PolyORB
@subsection Configuring Security services for PolyORB
@c -------------------------------------------------------------------

@noindent
PolyORB provides support for some elements of the CORBA Security
mechanisms. This sections lists the corresponding configuration
parameters.

@subsubsection Supported mechasnisms

@noindent
PolyORB provides support for the following security mechanisms:

@enumerate
@item SSL/TLS protected transport;

@item GSSUP (user/password) authentication mechanism;

@item identity assertion and backward trust evaluation.
@end enumerate

@subsubsection Compile-time configuration

To enable security support, applications must `with' one of the
predefined setup packages:

@enumerate
@item @code{PolyORB.Setup.Secure_Client} - for client side support only;

@item @code{PolyORB.Setup.Secure_Server} - for both client and server
side support.
@end enumerate

@subsubsection Run-time configuration

@enumerate
@item Capsule configuration

This section details the configuration parameters for capsule
configuration.

@smallexample
[security_manager]
# List of sections for configure client's credentials
#own_credentials=my_credentials
#
# Client requires integrity proteced messages
#integrity_required=true
#
# Client requires confiodentiality protected messages
#confidentiality_required=true
#
# Client requires security association to detect replay (not supported
for now)
#detect_replay_required=true
#
# Client requires security association to detect message sequence
errors (not
# supported for now)
#detect_misordering_required=true
#
# Client requires target authentication
#establish_trust_in_target_required=true
#
# Client requires client authentication (usually not applicable at
all)
#establish_trust_in_client_required=true
#
# (rare useful)
#identity_assertion_required=true
#
# (rare useful)
#delegation_by_client_required=true
@end smallexample

@item Credentials configuration

This section details configuration parameters for defining a program's
credentials. Depending on the mechanisms used for the transport and
authentication layers, the credentials configuration section may define
configuration only for one transport mechanism and/or one
authentication mechanism.

@smallexample
#[my_credentials]
#
# TLS protected transport mechanism used as transport mechanism
#transport_credentials_type=tls
#
# Connection method. Available methods: tls1, ssl3, ssl2
#tls.method=tls1
#
# Certificate file name
#tls.certificate_file=my.crt
#
# Certificate chain file name
#tls.certificate_chain_file=
#
# Private key file name
#tls.private_key_file=my.key
#
# Name of file, at which CA certificates for verification purposes are
#located
#tls.certificate_authority_file=root.crt
#
# Name of directory, at which CA certificates for verification
#purposes are
# located
#tls.certificate_authority_path=
#
# List of available ciphers
#tls.ciphers=ALL
#
# Verify peer certificate
#tls.verify_peer=true
#
# Fail if client don't provide ceritificate (server only)
#tls.verify_fail_if_no_peer_certificate=true
#
# GSSUP (user/password) mechanism as authentication mechanism
#authentication_credentials_type=gssup
#
# User name
#gssup.username=username@@domain
#
# User password
#gssup.password=password
#
# Target name for which user/password pair is applicable
#gssup.target_name=@@domain
@end smallexample

@item POA configuration

This section details configuration parameters for defining security
characteristics of objects managed by POA. The POA's name is used as
the section name.

@smallexample
#[MySecurePOA]
#
# Unprotected invocations is allowed
#unprotected_invocation_allowed=true
#
# Section name for configuration of used protected transport mechanism
#(if any)
#transport_mechanism=tlsiop
#
# Section name for configuration of used authentication mechanism (if
#any)
#authentication_mechanism=my_gssup
#
# Target require client authentication at authentication layer (in
#addition
# to authentication at transport layer)
#authentication_required=true
#
# Name of file for backward trust evalutation rules
#backward_trust_rules_file=file.btr
#
# Section name for configuration of authorization tokens authority
#privilege_authorities=
@end smallexample

@item TLS protected transport mechanism configuration

This section details configuration parameters for the TLS protected
transport mechanism. The section name for mechanism configuration is
defined in the POA configuration.

@smallexample
[tlsiop]
# List of access points
#addresses=127.0.0.1:3456
@end smallexample

@item GSSUP authentication mechanism

This section details configuration parameters for the GSSUP
authentication mechanism. The section name for mechanism configuration
is defined in the POA configuration.

@smallexample
#[my_gssup]
#
# Authentication mechanism
#mechanism=gssup
#
# Target name
#gssup.target_name=@@domain
#
# User name/password mapping file
#gssup.passwd_file=passwd.pwd
@end smallexample
@end enumerate

@c -------------------------------------------------------------------
@node Command line arguments
@subsection Command line arguments
@c -------------------------------------------------------------------

@noindent
The CORBA specifications define a mechanism to pass command line
arguments to your application, using the @code{CORBA::ORB:Init}
method.

For now, PolyORB supports the following list of arguments:

@itemize @bullet
@item @code{InitRef} to pass initial reference.

@end itemize

@c -------------------------------------------------------------------
@node Implementation Notes
@section Implementation Notes
@c -------------------------------------------------------------------

@menu
* Tasking::
* Implementation of CORBA specifications::
* Additions to the CORBA specifications::
* Interface repository::
* Policy Domain Managers::
* Mapping of exceptions::
* Additional information to CORBA_Unknown::
* Internals packages::
@end menu

@noindent
PolyORB strives to support CORBA specifications as closely as
possible. However, on rare occasions, the implementation adapts the
specifications to actually enable its completion. This section
provides information on the various modifications we made.

@c -------------------------------------------------------------------
@node Tasking
@subsection Tasking
@c -------------------------------------------------------------------

@noindent
PolyORB provides support for tasking and no-tasking, using
configuration parameters. Please refer to @ref{Building an
application with PolyORB} for more information on PolyORB's
configuration.

When selecting a tasking-capable runtime, ORB-related functions are
thread safe, following the IDL-to-Ada mapping recommendations.

@c -------------------------------------------------------------------
@node Implementation of CORBA specifications
@subsection Implementation of CORBA specifications
@c -------------------------------------------------------------------

@noindent
In some cases, the CORBA specifications do not describe the
semantics of the interface in sufficient detail. We add an
@code{Implementation Notes} tag to the package specification to
indicate the modifications or enhancements we made to the standard.

In some cases, the IDL-to-Ada mapping specifications and the CORBA
specifications conflict. We add an @code{Implementation Notes} tag to
the package specification to indicate this issue. Whenever possible,
PolyORB follows the CORBA specifications.

@c -------------------------------------------------------------------
@node Additions to the CORBA specifications
@subsection Additions to the CORBA specifications
@c -------------------------------------------------------------------

@noindent
In some cases, the specifications lack features that may be
useful. We add an @code{Implementation Notes} tag to the package
specification to detail the additions we made to the standard.

In addition to the above, PolyORB follows some of the recommendations
derived from the OMG Issues for Ada 2003 Revision Task Force mailing
list (see @url{http://www.omg.org/issues/ada-rtf.html} for more
information).

@c -------------------------------------------------------------------
@node Interface repository
@subsection Interface repository
@c -------------------------------------------------------------------

@noindent
@i{The documentation of the PolyORB's CORBA Interface Repository will
appear in a future revision of PolyORB.}

@c -------------------------------------------------------------------
@node Policy Domain Managers
@subsection Policy Domain Managers
@c -------------------------------------------------------------------

@noindent
You have two ways to register the reference to the CORBA Policy Domain
Manager the application will use:

@itemize @bullet
@item Setting up the @code{policy_domain_manager} entry in the
@code{[corba]} section in your configuration file,
@code{policy_domain_manager} is the @code{IOR} or @code{corbaloc} of
the COS Naming server to use. See @ref{Using a configuration file} for
more details.

@item Registering an initial reference using the @code{-ORB InitRef
PolyORBPolicyDomainManager=<IOR>} or @code{-ORB InitRef
PolyORBPolicyDomainManager=<corbaloc>} command-line argument. See the
CORBA specifications for more details.

@item Registering an initial reference for
@code{PolyORBPolicyDomainManager} using the
@code{CORBA.ORB.Register_Initial_Reference} function. See the CORBA
specifications for more details.

@end itemize

@c -------------------------------------------------------------------
@node Mapping of exceptions
@subsection Mapping of exceptions
@c -------------------------------------------------------------------

@noindent
For each exception defined in the CORBA specifications, PolyORB
provides the @code{Raise_<excp_name>} function, a utility function
that raises the exception @code{<excp_name>}, along with its exception
member. PolyORB also defines the @code{Get_Members} function (as
defined in the IDL-to-Ada mapping) to provide accessors to retrieve
information on the exception.

In addition, for each exception defined in a user-defined IDL
specification, the IDL-to-Ada compiler will generate a
@code{Raise_<excp_name>} function in the Helper package. It is a
utility function that raises the exception @code{<excp_name>}, along
with its exception member.

@c -------------------------------------------------------------------
@node Additional information to CORBA_Unknown
@subsection Additional information to @code{CORBA::Unknown}
@c -------------------------------------------------------------------
@cindex @code{CORBA::Unknown}
@cindex CORBA, Server-side exception

@noindent
When a CORBA application raises an Ada exception that is not part of
the IDL specifications, nor defined by the CORBA specifications, then
this exception is translated into a @code{CORBA::UNKNOWN} exception.

To help debugging CORBA applications, PolyORB supports a specific
service context to the GIOP protocol personality that conveys
exception information. When displaying exception information,
server-side specific exception information is delimited by
@i{``<Invocation Exception Info: ...>''}

Here is an example from the @code{all_types} example provided by
PolyORB.

@smallexample
Exception name: CORBA.UNKNOWN
Message: 4F4D0001M
<Invocation Exception Info: Exception name: CONSTRAINT_ERROR
Message: all_types-impl.adb:315 explicit raise
Call stack traceback locations:
0x84d279c 0x84c1e78 0x84b92c6 0x84b8e9>
Call stack traceback locations:
0x81d0425 0x81d0554 0x81d6d8c 0x81fd02b 0x81fc091 0x82eea12 0x83e4c22 0x807b69a 0xb7a15e3e
@end smallexample

Note that call stack tracebacks can be translated into symbolic form
using the @code{addr2line} utility that comes with GNAT.

@c -------------------------------------------------------------------
@node Internals packages
@subsection Internals packages
@c -------------------------------------------------------------------

@noindent
PolyORB sometimes declares internal types and routines inside CORBA
packages. These entities are gathered into an
@code{Internals} child package. You should not use these functions:
they are not portable, and may be changed in future releases.

@c -------------------------------------------------------------------
@node PolyORB specific APIs
@section PolyORB's specific APIs
@c -------------------------------------------------------------------

@menu
* PolyORB.CORBA_P.CORBALOC::
* PolyORB.CORBA_P.Naming_Tools::
* PolyORB.CORBA_P.Server_Tools::
@end menu

@noindent
PolyORB defines packages to help in the development of CORBA programs.

@itemize @bullet

@item @ref{PolyORB.CORBA_P.CORBALOC}:

This package defines a helper function to build a @code{corbaloc}
stringified reference from a CORBA object reference.

@item @ref{PolyORB.CORBA_P.Naming_Tools}:

This package defines helper functions to ease interaction with CORBA
COS Naming.

@item @ref{PolyORB.CORBA_P.Server_Tools}:

This package defines helper functions to ease set up of a simple CORBA
Server.

@end itemize

@page
@node PolyORB.CORBA_P.CORBALOC
@subsection @code{PolyORB.CORBA_P.CORBALOC}
@cindex @code{PolyORB.CORBA_P.CORBALOC}

@include polyorb-corba_p-corbaloc.ads.texi


@page
@node PolyORB.CORBA_P.Naming_Tools
@subsection @code{PolyORB.CORBA_P.Naming_Tools}
@cindex @code{PolyORB.CORBA_P.Naming_Tools}

@include polyorb-corba_p-naming_tools.ads.texi

@page
@node PolyORB.CORBA_P.Server_Tools
@subsection @code{PolyORB.CORBA_P.Server_Tools}
@cindex @code{PolyORB.CORBA_P.Server_Tools}

@include polyorb-corba_p-server_tools.ads.texi

@c -------------------------------------------------------------------
@node RT-CORBA
@chapter RT-CORBA
@cindex RT-CORBA
@c -------------------------------------------------------------------

@menu
* What you should know before Reading this section2::
* Installing RT-CORBA::
* Configuring RT-CORBA::
* RTCORBA.PriorityMapping::
* RTCosScheduling Service::
@end menu

@c -------------------------------------------------------------------
@node What you should know before Reading this section2
@section What you should know before Reading this section
@c -------------------------------------------------------------------

@noindent
This section assumes that the reader is familiar with the Real-Time
CORBA specifications described in @cite{[OMG02a]} and @cite{[OMG03]}.

@c -------------------------------------------------------------------
@node Installing RT-CORBA
@section Installing RT-CORBA
@c -------------------------------------------------------------------

@noindent
The RT-CORBA library is installed as part of the installation of the
CORBA personality. Note that you may have to select specific run-time
options to enable full compliance with RT-CORBA specifications and
ensure real time behavior.

@c XXX TO BE COMPLETED

@c -------------------------------------------------------------------
@node Configuring RT-CORBA
@section Configuring RT-CORBA
@c -------------------------------------------------------------------

@menu
* PolyORB.RTCORBA_P.Setup::
@end menu

@noindent
This section details how to configure your application to use the
RT-CORBA library.

@c -------------------------------------------------------------------
@node PolyORB.RTCORBA_P.Setup
@subsection @code{PolyORB.RTCORBA_P.Setup}
@cindex @code{PolyORB.RTCORBA_P.Setup}
@c -------------------------------------------------------------------

@noindent
The RT-CORBA specifications mandate that the implementation provide a
mechanism to set up some of its internals.

The package @code{PolyORB.RTCORBA_P.Setup} provides an API to set up
the @code{PriorityMapping} and @code{PriorityTransform} objects.

@include polyorb-rtcorba_p-setup.ads.texi

@c -------------------------------------------------------------------
@node RTCORBA.PriorityMapping
@section @code{RTCORBA.PriorityMapping}
@cindex @code{RTCORBA.PriorityMapping}
@c -------------------------------------------------------------------

@noindent
PolyORB provides different implementations of this specification:

@itemize @bullet

@item @code{RTCORBA.PriorityMapping.Direct} maps CORBA priorities
directly to native priorities. If the CORBA priority is not in
@code{System.Priority'Range}, then the mapping is not possible.

@item @code{RTCORBA.PriorityMapping.Linear} maps each individual
native priority to a contiguous range of CORBA priorities, so that the
complete CORBA priority range is used up for the mapping. See
@file{rtcorba-prioritymapping-linear.adb} for more details.

@end itemize

@c -------------------------------------------------------------------
@node RTCosScheduling Service
@section RTCosScheduling Service
@cindex RTCosScheduling Service
@c -------------------------------------------------------------------

@menu
* Overview::
* ClientScheduler::
* ServerScheduler::
@end menu

@c -------------------------------------------------------------------
@node Overview
@subsection Overview
@c -------------------------------------------------------------------

@noindent
PolyORB provides an implementation of the RTCosScheduling service
defined in @cite{[OMG02a]}.

PolyORB uses some permissions stated in the specifications to allow for
easy configuration of @code{ClientScheduler} and
@code{ServerScheduler}, defined in the following sections.

Additional information on the use of the API may be found in the
RTCosScheduling example in
@file{examples/corba/rtcorba/rtcosscheduling}.

@c -------------------------------------------------------------------
@node ClientScheduler
@subsection @code{RTCosScheduling::ClientScheduler}
@c -------------------------------------------------------------------

@noindent
Client side @i{activities} are defined in a configuration file that can
be loaded using
@file{RTCosScheduling.ClientScheduler.Impl.Load_Configuration_File}

On the client side, the user can set up

@itemize @bullet

@item current task priority, using registered @code{PriorityMapping} object.

@end itemize

@noindent
This file has the following syntax, derived from PolyORB configuration
file syntax:

@smallexample
# Name of the activity
[activity activity1]

# Activity priority, in RTCORBA.Priority'Range
priority=10000

@end smallexample

@noindent
In this example, activity @code{activity1} is defined with priority
@code{10'000}.

@c -------------------------------------------------------------------
@node ServerScheduler
@subsection @code{RTCosScheduling::ServerScheduler}
@c -------------------------------------------------------------------

@noindent
Server side @i{POAs} and @i{objects} are defined in a configuration
file that can be loaded using
@file{RTCosScheduling.ClientScheduler.Impl.Load_Configuration_File}

On the server side, the user can set up

@itemize @bullet

@item object priority, using registered @code{PriorityMapping} object.

@item all RT-CORBA-specific POA configuration parameters.

@end itemize

@noindent
This file has the following syntax, derived from PolyORB configuration
file syntax:

@smallexample
# Name of the object
[object object1]

# Object priority, in RTCORBA.Priority'Range
priority=10000

@end smallexample

@noindent
In this example, object @code{object1} is defined with priority
@code{10'000}.

@smallexample
# Name of the POA
[poa poa1]

# PriorityModelPolicy for POA
priority_model=CLIENT_PROPAGATED
default_priority=0 # not meaningful for CLIENT_PROPAGATED

# Threadpools attached to POA
threadpool_id=1

# Name of the POA
[poa poa2]

# PriorityModelPolicy for POA
priority_model=SERVER_DECLARED
default_priority=40

# Threadpools attached to POA
threadpool_id=2

# Name of the POA
[poa poa3]

# POA with no defined policies

@end smallexample

@noindent
In this example, Two POAs are defined: POA @code{poa1} will use the
@code{CLIENT_PROPAGATED} PriorityModel Policy, default value is not
meaningful for this configuration, @code{poa1} will use the Threadpool
#1; POA @code{poa2} will use the @code{SERVER_DECLARED} PriorityModel
Policy, default server priority is 40, @code{poa2} will use the
Threadpool #2. Note that both policies are optional and can be omitted.

@c -------------------------------------------------------------------
@node DSA
@chapter Ada Distributed Systems Annex (DSA)
@cindex DSA, Distributed Systems Annex
@c -------------------------------------------------------------------

@menu
* Introduction to the Ada DSA::
* Partition Communication Subsystem::
* Most Features in One Example::
* A small example of a DSA application::
* Building a DSA application with PolyORB::
* Running a DSA application::
@end menu

@c -------------------------------------------------------------------
@node Introduction to the Ada DSA
@section Introduction to the Ada DSA
@c -------------------------------------------------------------------

A critical feature of the Distributed Systems Annex (DSA) is that it allows the
user to develop his application the same way whether this application is
going to be executed as several programs on a distributed system, or as a
single program on a non-distributed system. The DSA has been designed
to minimize the source changes needed to convert
an ordinary non-distributed program into a distributed program.

The simplest way to start with DSA is to develop the
application on a non-distributed system. Of course, the design of the
application should take into account the fact that some units are going
to be accessed remotely. In order to write a distributed Ada program,
it is necessary for the user to label by means of categorization pragmas
some of library level compilation units of the application program. The units
that require
categorization are typically those that are called remotely, and those
that provide the types used in remote invocations.

In order to ensure that distributed execution is possible, these units are
restricted to contain only a limited set of Ada constructs.
For instance, if the distributed system has no shared memory,
shared variables must be forbidden. To specify the nature of these restrictions,
the DSA provides several categorization pragmas, each of which excludes some
language constructs from the categorized package.

Of course, the user can develop the non-distributed application with his
usual software engineering environment. It is critical to note that the
user needs no specialized tools to develop his/her distributed
application. For instance, he can debug his application with the usual
debugger. Note that a non-distributed program is not to be confused with
a distributed application composed of only one program. The latter is
built with the help of the configuration tool and includes the
communication library.

Once the non-distributed version of the program is complete, it has to
be configured into separate partitions. This step is surprisingly
simple, compared to that of developing the application itself. The
configuration step consists of mapping sets of compilation units into
individual partitions, and specifying the mapping between partitions and
nodes in the computer network. This mapping is specified and managed by
means of a gnatdist configuration.

The distributed version of the user application should work as is, but
even when a program can be built both as a non-distributed or a
distributed program using the same source code, there may still be
differences in program execution between the distributed and
non-distributed versions. These differences are discussed in subsequent
sections (see @ref{Pragma Asynchronous} and @ref{Pragma
All_Calls_Remote}).

Developing a non-distributed application in order to distribute it
later is the natural approach for a novice. Of course, it is not always
possible to write a distributed application as a non-distributed
application. For instance, a client/server application does not belong
to this category because several instances of the client can be active
at the same time. It is very easy to develop such an application using
PolyORB; we shall describe how to do this in the following sections.

@menu
* Architecture of a Distributed Ada Application::
* Categorization Pragmas::
* Pragma Declared Pure::
* Pragma Remote_Call_Interface::
* Pragma Remote_Types::
* Pragma Shared_Passive::
* More About Categorization Pragmas::
@end menu

@c -------------------------------------------------------------------
@node Architecture of a Distributed Ada Application, Categorization Pragmas, Introduction to the Ada DSA, Introduction to the Ada DSA
@subsection Architecture of a Distributed Ada Application
@c -------------------------------------------------------------------

A distributed system is an interconnection of one or more processing
nodes and zero or more storage nodes. A distributed program comprises
one or more partitions. A partition is an aggregate of library
units. Partitions communicate through shared data or RPCs. A passive
partition has no thread of control. Only a passive partition can be
configured on a storage node. An active partition has zero or more
threads of control and has to be configured on a processing node.

The library unit is the core component of a distributed Ada
application. The user can explicitly assign library units to a
partition. Partitioning is a post-compilation process. The user
identifies interface packages at compile-time. These packages are
categorized using pragmas. Each of these pragmas supports the use of one of
the following classical paradigms:

@itemize @bullet
@item Remote subprograms:
For the programmer, a remote subprogram call is similar to a regular
subprogram call. Run-time binding using access-to-subprogram types can
also be used with remote subprograms. These remote subprograms are
declared in library units categorized as remote call interface
(RCI).

@item Distributed objects:
Special-purpose access types can designate remote
objects. When a primitive dispatching operation is invoked on an object
designated by such a remote access, a remote call is performed transparently
on the partition on which the object resides. The types of these distributed
objects are declared in library units categorized as remote types (RT).

@item Shared objects:
Global data can be shared among active partitions, providing a
repository similar to shared memory, a shared file system or a
database. Entryless protected objects allow safe concurrent access and update
of shared objects. This feature is orthogonal to the notion of distributed
objects, which are only accessed through exported services. These shared
objects are declared in library units categorized as shared passive (SP).

@end itemize

The remotely-called subprograms declared in a library unit categorized
as remote call interface (RCI) or remote types (RT) may be either
statically or dynamically bound. The partition on which a statically
bound remote subprogram is executed can be determined before the
call. This is a static remote subprogram call. In contrast, a remote method or
a dereference of an access to remote subprogram are dynamically bound remote
calls, because the partition on which the remote subprogram is executed
is determined at runtime, by the actuals of the call.

In the following example, Data_1 and Data_2 are shared passive (SP)
library units. Data_1 is configured on a passive partition mapped on a
storage node. Partition_1 and Partition_2 are active partitions. Note
that under some circumstances, a partition, for instance Partition_2,
can be duplicated. To be duplicated, Unit_2 and Unit_3 which are
configured on Partition_2 have to provide only dynamically bound remote
subprograms. Otherwise, a partition calling a remote subprogram on
Unit_2 would not be able to statically determine where to perform the
remote call between the two instances of Unit_2.

@*
@*
@image{xe-arch.fig}
@*

@c -------------------------------------------------------------------
@node Categorization Pragmas, Pragma Declared Pure, Architecture of a Distributed Ada Application, Introduction to the Ada DSA
@subsection Categorization Pragmas
@c -------------------------------------------------------------------

Library units can be categorized according to the role they play in a
distributed program. A categorization pragma is a library unit pragma
that restricts the kinds of declarations that can appear in a library unit
and possibly in its child units, as well as the legal semantic dependences
that the categorized unit can have. There are several categorization
pragmas:

@itemize @bullet
@item Remote_Call_Interface
@item Remote_Types
@item Shared_Passive
@item Pure
@end itemize

The following paragraphs do not present the detailed semantics of these
pragmas (formal details will be found in the Ada Reference Manual).
Their purpose is to give the reader an intuitive overview of
the purpose of these pragmas. If a library unit is not categorized, this
unit is called a normal unit and plays no special role in the distributed
application. Such a unit is duplicated on any partition in which it is
mentioned.

A parenthetical remark: to avoid the need for specific run-time
libraries for the DSA, the notion of remote rendezvous does not exist
in Ada: tasks cannot be invoked directly from one partition
to another. Therefore, declarations of task types and general protected types
with entries are not allowed in categorized Ada library units.


@c -------------------------------------------------------------------
@node Pragma Declared Pure, Pragma Remote_Call_Interface, Categorization Pragmas, Introduction to the Ada DSA
@subsection Pragma Declared Pure
@c -------------------------------------------------------------------

This pragma is not specific to the Distributed Systems Annex. A pure
package can appear in the context of any package, categorized or not.
A pure package is a preelaborable package that
does not contain variable data.
It is particularly useful to define types, constants and
subprograms shared by several categorized packages. In contrast, normal
packages cannot appear in the context of categorized package declarations.
Because a pure package has no state, it can be duplicated on several partitions.

@c -------------------------------------------------------------------
@node Pragma Remote_Call_Interface, Pragma Remote_Types, Pragma Declared Pure, Introduction to the Ada DSA
@subsection Pragma Remote_Call_Interface
@c -------------------------------------------------------------------

@menu
* Overview of Pragma Remote_Call_Interface::
* Regular Remote Subprograms (RCI)::
* Remote Access to Subprograms (RAS)::
* Remote Access to Class Wide Types (RACW)::
* Summary of Pragma Remote_Call_Interface::
@end menu

@c -------------------------------------------------------------------
@node Overview of Pragma Remote_Call_Interface, Regular Remote Subprograms (RCI), Pragma Remote_Call_Interface, Pragma Remote_Call_Interface
@subsubsection Overview of Pragma Remote_Call_Interface
@c -------------------------------------------------------------------

Library units categorized with this pragma declare subprograms that can be
called and executed remotely. An RCI unit acts as a server for remote calls.
There is no memory space shared between server and clients.
A subprogram call that invokes one such
subprogram is a classical RPC operation; it is a
statically bound operation, because the compiler can determine the identity
of the subprogram being called.

Dynamically bound calls are provided through two mechanisms:

@itemize @bullet

@item
The dereference of an access-to-subprogram value, i.e. a value whose type is
a remote access-to-subprogram (RAS).

@item
A dispatching call whose controlling argument is
an access-to-class-wide operand.
The formal is a remote access-to-class-wide (RACW)
type. These remote access types can be declared in RCI
packages as well.

@end itemize

A remote access type (RAS or RACW) can be viewed as a fat pointer, that is
to say a structure with a remote address and a local address (like an URL:
@t{<protocol>}://@-@t{<remote@code{-}machine>}/@-@t{<local@code{-}directory>}). The
remote address must denote the host of the partition on which the entity has
been created; the local address describes the local memory
address within the host.

It is very unlikely that RCI units can be duplicated in the distributed
system. An implementation may allow separate copies of a RCI unit as
long as it ensures that the copies present a consistent state to all clients.
In the general case, preserving consistency is very costly. For this reason, the
implementation may require a RCI unit to be unique in the distributed
system.

@node Regular Remote Subprograms (RCI), Remote Access to Subprograms (RAS), Overview of Pragma Remote_Call_Interface, Pragma Remote_Call_Interface
@subsubsection Regular Remote Subprograms (RCI)

In the following example, a RCIBank offers several remote services:
Balance, Transfer, Deposit and Withdraw. On the caller side, the bank
client uses the stub files of unit RCIBank. On the receiver side,
the bank receiver uses the skeleton files of unit RCIBank including
the body of this package.

@include types.ads.texi
@include rcibank.ads.texi
@include rciclient.adb.texi

@node Remote Access to Subprograms (RAS), Remote Access to Class Wide Types (RACW), Regular Remote Subprograms (RCI), Pragma Remote_Call_Interface
@subsubsection Remote Access to Subprograms (RAS)

In the following example, several mirroring banks offer their services
through the same database. Each bank registers a reference to each of
its services with a central bank. A client of the central bank requests
a service from one of the mirroring banks. To satisfy requests, the RCI
unit RASBank defines Balance_Type, a remote access to subprogram. (Recall
that an access type declared in a remote unit has to be either remote
access to subprogram or remote access to class wide type).

Note that to obtain a remote access to subprogram, the subprogram that
delivers the remote access must be remote itself. Therefore, MirrorBank
is a RCI library unit.

@include rasbank.ads.texi

In the code below, a mirroring bank registers its services to the
central bank.

@include mirrorbank.ads.texi
@include mirrorbank.adb.texi

In the code below, a central bank client asks for a mirroring bank and
calls the Balance service of this bank by dereferencing a remote access
type.

@include bankclient.adb.texi


@node Remote Access to Class Wide Types (RACW), Summary of Pragma Remote_Call_Interface, Remote Access to Subprograms (RAS), Pragma Remote_Call_Interface
@subsubsection Remote Access to Class Wide Types (RACW)

A bank client is now connected to a bank through a terminal. The bank
wants to notify a connected client, by means of a message on its
terminal, when another client transfers a given amount of money to its
account. In the following example, a terminal is designed as a
distributed object. Each bank client will register its terminal object
to the bank server for further use. In the code below, Term_Type is the
root type of the distributed terminal hierarchy.

@include terminal.ads.texi

In the code below, the RCI unit RACWBank defines Term_Access, a remote
access to class wide type. Term_Access becomes a reference to a
distributed object. In the next section, we will see how to derive and
extend Term_Type, how to create a distributed object and how to use a
reference to it.

@include racwbank.ads.texi

@node Summary of Pragma Remote_Call_Interface,  , Remote Access to Class Wide Types (RACW), Pragma Remote_Call_Interface
@subsubsection Summary of Pragma Remote_Call_Interface

Remote call interface units:

@itemize @bullet
@item
Allow subprograms to be called and executed remotely

@item
Allow statically bound remote calls (remote subprogram)

@item
Allow dynamically bound remote calls (remote access types)

@item
Forbid variables and non-remote access types

@item
Prevent specification from depending on normal units

@end itemize


@c -------------------------------------------------------------------
@node Pragma Remote_Types, Pragma Shared_Passive, Pragma Remote_Call_Interface, Introduction to the Ada DSA
@subsection Pragma Remote_Types
@c -------------------------------------------------------------------

@menu
* Overview of Pragma Remote_Types::
* Distributed Object::
* Transmitting Dynamic Structure::
* Summary of Remote Types Units::
@end menu

@node Overview of Pragma Remote_Types, Distributed Object, Pragma Remote_Types, Pragma Remote_Types
@subsubsection Overview of Pragma Remote_Types

Unlike RCI units, library units categorized with this pragma can define
distributed objects and remote methods on them. Both RCI and RT units
can define a remote access type as described above (RACW). A subprogram
defined in a RT unit is not a remote subprogram. Unlike RCI units, a RT
unit can be duplicated on several partitions, in which case all its
entities are distinct. This unit is duplicated on each
partition in which it is defined.

@node Distributed Object, Transmitting Dynamic Structure, Overview of Pragma Remote_Types, Pragma Remote_Types
@subsubsection Distributed Object

If we want to implement the notification feature proposed in the
previous section, we have to derive Term_Type. Such a derivation is
possible in a remote types unit like NewTerminal (see below). Any object
of type New_Term_Type becomes a distributed object and any reference to
such an object becomes a fat pointer or a reference to a distributed
object (see Term_Access declaration in @ref{Remote Access to Class Wide
Types (RACW)}).

@include newterminal.ads.texi

In the code below, a client registers his name and his terminal with
RACWBank. Therefore, when any payer transfers some money to him,
RACWBank is able to notify the client of the transfer of funds.

@include term1client.adb.texi

In the code below, a second client, the payer, registers his terminal
to the bank and executes a transfer to the first client.

@include term2client.adb.texi

In the code below, we describe the general design of Transfer. Classical
operations of Withdraw and Deposit are performed. Then, RACWBank
retrieves the terminal of the payee (if present) and invokes a
dispatching operation by dereferencing a distributed object Term. The
reference is examined at run-time, and the execution of this operation
takes place on the partition on which the distributed object resides.

@include racwbank.adb.texi

@node Transmitting Dynamic Structure, Summary of Remote Types Units, Distributed Object, Pragma Remote_Types
@subsubsection Transmitting Dynamic Structure

@include stringarraystream.ads.texi

Non-remote access types cannot be declared in the public part of a
remote types unit. However, it is possible to define private non-remote
access types as long as the user provides its marshalling procedures,
that is to say the mechanism needed to place a value of the type into a
communication stream.  The code below describes how to transmit a linked
structure.

The package declaration provides a type definition of single-linked
lists of unbounded strings. An implementation of the marshalling
operations could be the following:

@include stringarraystream.adb.texi


@node Summary of Remote Types Units,  , Transmitting Dynamic Structure, Pragma Remote_Types
@subsubsection Summary of Remote Types Units

Remote types units:

@itemize @bullet
@item
Support the definition of distributed objects

@item
Allow dynamically bound remote calls (via remote access types)

@item
Allow non-remote access types (with marshalling subprograms)

@item
Cannot have a specification that depends on normal units

@end itemize

@c -------------------------------------------------------------------
@node Pragma Shared_Passive, More About Categorization Pragmas, Pragma Remote_Types, Introduction to the Ada DSA
@subsection Pragma Shared_Passive
@c -------------------------------------------------------------------

@menu
* Overview of Pragma Shared_Passive::
* Shared and Protected Objects::
* Summary of Pragma Shared_Passive::
@end menu

@node Overview of Pragma Shared_Passive, Shared and Protected Objects, Pragma Shared_Passive, Pragma Shared_Passive
@subsubsection Overview of Pragma Shared_Passive

The entities declared in such a categorized library unit are intended to
be mapped on a virtual shared address space (file, memory,
database). When two partitions use such a library unit, they can
communicate by reading or writing the same variable in the shared
unit. This supports the conventional shared variables paradigm.
Entryless protected objects can be declared in these units, to provide
an atomic access to shared data, thus implementing a simple transaction
mechanism. When the address space is a file or a database, the user can
take advantage of the persistency features provided by these storage
nodes.

@node Shared and Protected Objects, Summary of Pragma Shared_Passive, Overview of Pragma Shared_Passive, Pragma Shared_Passive
@subsubsection Shared and Protected Objects

In the code below, we define two kinds of shared
objects. External_Synchronization requires that the different partitions
updating this data synchronize to avoid conflicting operations on shared
objects. Internal_Synchronization provides a way to get an atomic
operation on shared objects. Note that only entryless protected types are
allowed in a shared passive unit; synchronization must be done with
protected procedures.

@include sharedobjects.ads.texi

@node Summary of Pragma Shared_Passive,, Shared and Protected Objects, Pragma Shared_Passive
@subsubsection Summary of Pragma Shared_Passive

Shared passive units:

@itemize @bullet
@item
Allow direct access to data from different partitions

@item
Provide support for shared (distributed) memory

@item
Support memory protection by means of entryless protected objects

@item
Prevent specification from depending on normal units

@end itemize

@c -------------------------------------------------------------------
@node More About Categorization Pragmas, , Pragma Shared_Passive, Introduction to the Ada DSA
@subsection More About Categorization Pragmas
@c -------------------------------------------------------------------

@menu
* Variables and Non-Remote Access Types::
* RPC Failures::
* Exceptions::
* Pragma Asynchronous::
* Pragma All_Calls_Remote::
* Generic Categorized Units  ::
* Categorization Unit Dependencies::
@end menu

@node Variables and Non-Remote Access Types, RPC Failures, More About Categorization Pragmas, More About Categorization Pragmas
@subsubsection Variables and Non-Remote Access Types

In RT or RCI package declarations, variable declarations are forbidden,
and non-remote access types are allowed as long as their marshalling
subprograms are explicitly provided (see @ref{Transmitting Dynamic
Structure}).

@node RPC Failures, Exceptions, Variables and Non-Remote Access Types, More About Categorization Pragmas
@subsubsection RPC Failures

Calls are executed at most once: they are made exactly one time or they
fail with an exception. When a communication error occurs,
@i{System.RPC.Communication_Error} is raised.

@node Exceptions, Pragma Asynchronous, RPC Failures, More About Categorization Pragmas
@subsubsection Exceptions

Any exception raised in a remote method or subprogram call is propagated
back to the caller. Exception semantics are preserved in the regular
Ada way.

@include internal.ads.texi
@include rempkg2.ads.texi
@include rempkg1.ads.texi

Let us say that RemPkg2, Internal and RemExcMain packages are on the same
partition Partition_1 and that RemPkg1 is on partition Partition_2.

@include rempkg2.adb.texi
@include rempkg1.adb.texi
@include remexcmain.adb.texi

When RemPkg1.Subprogram on Partition_1 raises Internal.Exc, this
exception is propagated back to Partition_2. As Internal.Exc is not
defined on Partition_2, it is not possible to catch this exception
without an exception handler @b{when others}. When this exception is
reraised in RemPkg1.Subprogram, it is propagated back to Partition_1. But
this time, Internal.Exc is visible and can be handled as we would in a
single-partition Ada program. Of course, the exception message is also
preserved.

@c XXXX Schema ??? exceptions

@node Pragma Asynchronous, Pragma All_Calls_Remote, Exceptions, More About Categorization Pragmas
@subsubsection Pragma Asynchronous

By default, a remote call is blocking: the caller waits until the remote
call is complete and the output stream is received.
Just like a normal (nonremote) call, the caller does not proceed
until the call returns.
By contrast, a
remote subprogram labeled with pragma Asynchronous allows statically
and dynamically bound remote calls to it to be executed
asynchronously. A call to an asynchronous procedure doesn't wait for the
completion of the remote call, and lets the caller continue its
execution. The remote procedure must have only @b{in} parameters, and
any exception raised during the execution of the remote procedure is
lost.

When pragma Asynchronous applies to a regular subprogram with @b{in}
parameters, any call to this subprogram will be executed
asynchronously. The following declaration of
AsynchronousRCI.Asynchronous gives an example.

@include asynchronousrci.ads.texi
@include asynchronousrt.ads.texi

A pragma Asynchronous may apply to a remote access-to-subprogram (RAS) type.
An asynchronous RAS can be both asynchronous and synchronous depending
on the designated subprogram. For instance, in the code below, remote
call (1) is asynchronous but remote call (2) is synchronous.

A pragma Asynchronous may apply to a RACW as well. In this case, the
invocation of @b{any} method with @b{in} parameters is @i{always} performed
asynchronously. Remote method invocation (3) is asynchronous but remote
method invocation (4) is synchronous.

@include asynchronousmain.adb.texi

This feature supports the conventional message passing paradigm. The
user must be aware that this paradigm, and asynchronous remote calls in
particular, has several drawbacks:

@itemize @bullet

@item
It violates the normal semantics of calls; the caller proceeds without
awaiting the return. The semantics are more similar to a ``remote goto''
than a remote call

@item
It prevents easy development and debugging in a non-distributed context

@item
It can introduce race conditions

@end itemize

To illustrate the latter, let us take the following example:

@include node2.ads.texi
@include node2.adb.texi
@include node1.ads.texi
@include node1.adb.texi
@include nondeterministic.adb.texi

Let us say that Main is configured on Partition_0, Node1 on Partition_1
and Node2 on Partition_2. If Node1.Send and Node2.Send procedures were
synchronous or if no latency was introduced during network
communication, we would have the following RPC order: Main remotely
calls Node1.Send which remotely calls Node2.Send which sets V to
1. Then, Main remotely calls Node2.Send and sets V to 2.

Now, let us assume that both Send procedures are asynchronous and that
the connection between Partition_1 and Partition_2 is very slow. The
following scenario can very well occur. Main remotely calls Node1.Send
and is unblocked. Immediately after this call, Main remotely calls
Node2.Send and sets V to 2. Once this is done, the remote call to
Node1.Send completes on Partition_1 and it remotely calls Node2.Send
which sets V to 1.

@node Pragma All_Calls_Remote, Generic Categorized Units  , Pragma Asynchronous, More About Categorization Pragmas
@subsubsection Pragma All_Calls_Remote

A pragma All_Calls_Remote in a RCI unit forces remote procedure
calls to be routed through the communication subsystem even for a local
call. This eases the debugging of an application in a non-distributed
situation that is very close to the distributed one, because the communication
subsystem (including marshalling and unmarshalling procedures) can be
exercised on a single node.

In some circumstances, a non-distributed application can behave
differently from an application distributed on only one partition. This
can happen when both All_Calls_Remote and Asynchronous features are used
at the same time (see @ref{Pragma Asynchronous} for an example). Another
circumstance occurs when the marshalling operations raise an
exception. In the following example, when unit ACRRCI is a
All_@-Calls_@-Remote package, the program raises Program_Error. When
unit ACRRCI is no longer a All_Calls_Remote package, then the program
completes silently.

@include acrrt.ads.texi
@include acrrt.adb.texi
@include acrrci.ads.texi
@include acrrci.adb.texi
@include acrmain.adb.texi

@node Generic Categorized Units  , Categorization Unit Dependencies, Pragma All_Calls_Remote, More About Categorization Pragmas
@subsubsection Generic Categorized Units

@include genericrci.ads.texi
@include rciinstantiation.ads.texi
@include normalinstantiation.ads.texi

Generic units may be categorized.  Instances do not automatically
inherit the categorization of their generic units, but they can be
categorized explicitly. If they are not, instances are normal
compilation units. Like any other categorized unit, a categorized
instance must be at the library level, and the restrictions of
categorized units apply on instantiation (in particular on generic
formal parameters).

@node Categorization Unit Dependencies,  , Generic Categorized Units  , More About Categorization Pragmas
@subsubsection Categorization Unit Dependencies

Each categorization pragma has very specific visibility rules. As a
general rule, RCI > RT > SP > Pure, where the comparison indicates
allowed semantic dependencies. This means that a Remote_Types package
can make visible in its specification only Remote_Types, Shared_Passive
and Pure units.

@c -------------------------------------------------------------------
@node Partition Communication Subsystem
@section Partition Communication Subsystem
@c -------------------------------------------------------------------

@menu
* Marshalling and Unmarshalling Operations::
* Incorrect Remote Dispatching::
* Partition Ids::
* Concurrent Remote Calls::
* Consistency and Elaboration::
* Abortion and Termination::
@end menu

@node Marshalling and Unmarshalling Operations, Incorrect Remote Dispatching, Partition Communication Subsystem, Partition Communication Subsystem
@subsection Marshalling and Unmarshalling Operations

The Partition Communication Subsystem (PCS) is the runtime library for
distributed features. It marshals and unmarshals client and server requests
into a data stream suitable for network transmission.

Parameter streams are normally read and written using four attributes:

@itemize @bullet

@item Write: write an element into a stream, valid only for constrained
types

@item Read: read a constrained element from a stream

@item Output: same as Write, but write discriminants or array bounds as well
if needed

@item Input: same as Read, but read discriminants or bounds from
  the stream (the Input attribute denotes a function)
@end itemize

An Ada compiler provides default 'Read and 'Write operations. But it is
up to the implementation of the PCS to provide default 'Read and 'Write
to ensure proper operation between heterogeneous architectures (see
@ref{Heterogeneous System}).

The user can override these operations, except for predefined
types. Overriding with a custom version provides the user with a way
to debug its application (even outside of the Distributed Systems
Annex). On the other hand, remaining with the default implementation
allows the user to take advantage of optimized and portable representations
provided by the PCS.

@include new_integers.ads.texi
@include new_integers.adb.texi

The language forces the user to provide Read and Write operations for
non-remote access types. Transmitting an access value by dumping its
content into a stream makes no sense when the value is going to be transmitted
to another partition (with a different memory space). To transmit non-remote
access types see @ref{Transmitting Dynamic Structure}.

@node Incorrect Remote Dispatching, Partition Ids, Marshalling and Unmarshalling Operations, Partition Communication Subsystem
@subsection Incorrect Remote Dispatching

When a remote subprogram takes a class wide argument, there is a risk of
using an object of a derived type that will not be clean enough to be
transmitted. For example, given a type called Root_Type, if a remote
procedure takes a Root_Type'Class as an argument, the user can call it
with an instance of Derived_Type that is Root_Type enriched with a field
of a task type. This will lead to a non-communicable type to be
transmitted between partitions.

To prevent this, paragraph E.4(18) of the Ada Reference Manual explains that
any actual type used as parameter for a remote call whose formal type is
a class wide type must be declared in the visible part of a Pure or
Remote_Types package. This property also holds for remote functions
returning class wide types. To summarize, the actual type used should
have been eligible for being declared where the root type has been
declared. If a `bad' object is given to a remote subprogram,
@i{Program_Error} will be raised at the point of the call.

@node Partition Ids, Concurrent Remote Calls, Incorrect Remote Dispatching, Partition Communication Subsystem
@subsection Partition Ids

U'Partition_ID identifies the partition where the unit U has been
elaborated. For this purpose, the PCS provides an integer type
Partition_ID to uniquely designate a partition. Note that a Partition_ID
is represented as a universal integer, and has no meaning outside of the
PCS. The RM requires that two partitions of a distributed program have
different Partition_ID's at a given time. A Partition_ID may or may not
be assigned statically (at compile or link time). A Partition_ID may or
may not be related to the physical location of the partition.

Partition_ID's can be used to check whether a RCI package is configured locally.

@include check_pid.adb.texi

@node Concurrent Remote Calls, Consistency and Elaboration, Partition Ids, Partition Communication Subsystem
@subsection Concurrent Remote Calls

It is not defined by the PCS specification whether one or more threads
of control should be available to process incoming messages and to wait
for their completion. But the PCS implementation is required to be
reentrant, thereby allowing concurrent calls on it to service concurrent
remote subprogram calls into the server partition.  This means that at
the implementation level the PCS manages a pool of helper tasks. This
(apart from performance) is invisible to the user.

@node Consistency and Elaboration, Abortion and Termination, Concurrent Remote Calls, Partition Communication Subsystem
@subsection Consistency and Elaboration

A library unit is consistent if the same version of its declaration is
used in all units that reference it. This requirement applies as well to
a unit that is referenced in several partitions of a distributed
program.  If a shared passive or RCI library unit U is included in some
partition P, It is a bounded error to elaborate another partition P1 of
a distributed program that that depends on a different version of U.  As
a result of this error, Program_Error can be raised in one or both
partitions during elaboration.

U'Version yields a string that identifies the version of the unit
declaration and any unit declaration on which it depends. U'Version_Body
yields a string that identifies the version of the unit body. These
attributes are used by the PCS to verify the consistency of an
application.

After elaborating the library units, but prior to invoking the main
subprogram, the PCS checks the RCI unit versions, and then accept any
incoming RPC. To guarantee that it is safe to call receiving stubs, any
incoming RPC is kept pending until the partition completes its
elaboration.

@node Abortion and Termination,  , Consistency and Elaboration, Partition Communication Subsystem
@subsection Abortion and Termination

If a construct containing a remote call is aborted, the remote
subprogram call is cancelled. Whether the execution of the remote
subprogram is immediately aborted as a result of the cancellation is
implementation defined.

An active partition terminates when its environment task terminates. In
other terms, a partition cannot terminate before the Ada program itself
terminates. The standard termination mechanism applies, but can be
extended with extra rules (see @ref{Partition Attribute Termination} for
examples).

@c -------------------------------------------------------------------
@node Most Features in One Example
@section Most Features in One Example
@c -------------------------------------------------------------------

The example shown on the following figure highlights most of the
features of DSA. The system is based on a set of factories and workers
and a storage.  Each entity is a partition itself. A factory hires a
worker from a pool of workers (hire - 1) and assigns a job (query - 2)
to him. The worker performs the job and saves the result (reply - 3) in
a storage common to all the factories.  The worker notifies the factory
of the end of his job (notify - 4).

@*
@*
@image{full-ex.fig}
@*

When a worker has completed his job, the result must be saved in a
common storage. To do this, we define a protected area in SP package
Storage (see following code). An entryless protected object ensures
atomic access to this area.

@include storage.ads.texi

Common is a Remote_Types package that defines most of the remote
services of the above system (see following code). First, we define a
way for the workers to signal the completion of his job. This callback
mechanism is implemented using RAS Notify.

@include common.ads.texi

We define an abstract tagged type Worker which is intended to be the
root type of the whole distributed objects hierarchy. Assign allows a
factory to specify a job to a worker and a way for the worker to signal
its employer the completion of this job. Any_Worker is a remote access
to class wide type (RACW). In other words, it is a reference to a
distributed object of any derived type from Worker class. Note that the
two remote access types (Any_Worker and Notify) are declared as
asynchronous. Therefore, any override of Assign will be executed
asynchronously. To be asynchronous, an object of type Notify has to be a
reference to an asynchronous procedure.

NewWorker is derived from type Worker and Assign is overridden.

@include newworkers.ads.texi

The following code shows how to derive a second generation of workers
NewNewWorker from the first generation NewWorker. As mentioned above,
this RT package can be duplicated on several partitions to produce
several types of workers and also several remote workers.

@include newnewworkers.ads.texi

In the following code, we define a unique place where workers wait for
jobs. WorkerCity is a Remote_Call_Interface package with services to
hire and free workers. Unlike Remote_Types packages,
Remote_Call_Interface packages cannot be duplicated, and are assigned to
one specific partition.

@include workercity.ads.texi

In order to use even more DSA features, Factory is defined as a generic
RCI package (see sample above). Any instantiation defines a new factory
(see sample above). To be RCI, this instantiation has to be categorized
once again.

@include factory.ads.texi
@include newfactory.ads.texi

@c -------------------------------------------------------------------
@node  A small example of a DSA application
@section A small example of a DSA application
@c -------------------------------------------------------------------

In this section we will write a very simple client-server
application using PolyORB DSA. The server will provide a @code{Remote
Call Interface} composed of a single @code{Echo_String} function that
will take a String and return it to the caller.

Here is the code for the server:

@file{server.ads}:
@include dsa_server.ads.texi

@file{server.adb}:
@include dsa_server.adb.texi

And here is the code for the client:

@file{client.adb}:
@include dsa_client.adb.texi

@noindent
For more details about the Distributed Systems Annex,
see the Ada Reference Manual @cite{[ISO06]}.

@c -------------------------------------------------------------------
@node Building a DSA application with PolyORB
@section Building a DSA application with PolyORB
@c -------------------------------------------------------------------

This section describes how to build a complete distributed Ada application
using the PolyORB implementation of the DSA.

@menu
* Introduction to PolyORB/DSA::
* How to Configure a Distributed Application::
* Gnatdist Command Line Options::
* The Configuration Language::
* Partition Runtime Parameters::
* Gnatdist Internals::
* PolyORB PCS Internals::
* Remote Shell Notes::
@end menu

@node Introduction to PolyORB/DSA, How to Configure a Distributed Application, Building a DSA application with PolyORB, Building a DSA application with PolyORB
@subsection Introduction to PolyORB/DSA

A distributed Ada application comprises a number of partitions
which can be executed concurrently on the same machine or, and this is
the interesting part, can be distributed on a network of machines.
The way in which partitions communicate is described in Annex E of the
Ada Reference Manual.

A partition is a set of compilation units that are linked together to
produce an executable binary. A distributed program comprises two or
more communicating partitions.

The Distributed Systems Annex (DSA) does not describe how a distributed
application should be configured. It is up to the user to define what
are the partitions in his program and on which machines they should be
executed.

The tool @t{po_gnatdist} and its configuration language
allows the user to partition his program and to specify the
machines on which the individual partitions are to execute.

@t{po_gnatdist} reads a configuration file (whose syntax is described in
section @ref{The Configuration Language}) and builds several
executables, one for each partition. It also takes care of launching the
different partitions (default) with parameters that can be specific to
each partition.

@node How to Configure a Distributed Application, Gnatdist Command Line Options, Introduction to PolyORB/DSA, Building a DSA application with PolyORB
@subsection How to Configure a Distributed Application

@itemize @bullet

@item
Write a non-distributed Ada application, to get familiar with the PolyORB
environment. Use the categorization pragmas to specify the packages that
can be called remotely.

@item
When this non-distributed application is working, write a configuration
file that maps the user categorized packages onto specific
partitions. This concerns particularly remote call interface and remote
types packages.  Specify the main procedure of the distributed
application (see @ref{Partition Attribute Main}).

@item
Type `po_gnatdist @i{<configuration-file>}'.

@item
Start the distributed application by invoking the start-up shell script
or default Ada program (depending on the Starter option, see @ref{Pragma
Starter}).

@end itemize

@node Gnatdist Command Line Options, The Configuration Language, How to Configure a Distributed Application, Building a DSA application with PolyORB
@subsection Gnatdist Command Line Options

@smallexample

po_gnatdist [switches] configuration-file [list-of-partitions]

@end smallexample

@c We should add some explanations of the gnatdist specific flags
@c -n, -M and on some particular mechanism (a spec without a body).

The switches of @t{po_gnatdist} are, for the time being, exactly the same
as those of gnatmake, with the addition of @t{--PCS}, which allows the
user to override the default selection of distribution runtime library
(PCS). By default @t{po_gnatdist} outputs a configuration
report and the actions performed. The switch -n allows @t{po_gnatdist} to
skip the first stage of recompilation of the non-distributed
application.

The names of all configuration files must have the suffix
@t{.cfg}. There may be several configuration files for the same
distributed application, as the user may want to use different
distributed configurations depending on load and other characteristics
of the computing environment.

If a list of partitions is provided on the command line of the po_gnatdist
command, only these partitions will be built. In the following
configuration example, the user can type :

@smallexample

po_gnatdist @i{<configuration> <partition_2> <partition_3>}

@end smallexample

@node The Configuration Language, Partition Runtime Parameters, Gnatdist Command Line Options, Building a DSA application with PolyORB
@subsection The Configuration Language

The configuration language is @i{Ada-like}. As the capabilities of PolyORB
will evolve, so will this configuration language. Most of the attributes
and pragmas can be overridden at run-time by command line arguments or
environment variables.

@menu
* Language Keywords::
* Pragmas and Representation Clauses::
* Configuration Declaration::
* Partition Declaration::
* Location Declaration::
* Partition Attribute Main::
* Pragma Starter::
* Pragma Boot_Location::
* Partition Attribute Self_Location::
* Partition Attribute Passive::
* Partition Attribute Data_Location::
* Partition Attribute Allow_Light_PCS::
* Pragma Priority::
* Partition Attribute Priority::
* Partition Attribute Host::
* Pragma Import::
* Partition Attribute Directory::
* Partition Attribute Command_Line::
* Partition Attribute Environment_Variables::
* Partition Attribute Termination::
* Partition Attribute Reconnection::
* Channel Declaration::
* Partition and Channel Attribute Filter::
* Pragma Registration_Filter::
* Pragma Version::
* Partition Attribute Task_Pool::
* Partition Attribute ORB_Tasking_Policy::
* A Complete Example::
@end menu

@node Language Keywords, Pragmas and Representation Clauses, The Configuration Language, The Configuration Language
@subsubsection Language Keywords

All the Ada keywords are reserved keywords of the configuration
language. @t{po_gnatdist} generates full Ada code in order to build the
different executables. To avoid naming conflicts between Ada and the
configuration language, all the Ada keywords have been reserved even if
they are not used in the configuration language.

There are three new keywords:

@itemize @bullet

@item @i{configuration} to encapsulate a configuration

@item @i{Partition} that is a predefined type to declare partitions

@item @i{Channel} that is a predefined type to declare channels between
partitions.

@end itemize

@node Pragmas and Representation Clauses, Configuration Declaration, Language Keywords, The Configuration Language
@subsubsection Pragmas and Representation Clauses

It is possible to modify the default behavior of the configuration via
a pragma definition.

@smallexample

PRAGMA ::=
   @b{pragma} PRAGMA_NAME [(PRAGMA_ARGUMENTS)];

@end smallexample

It is also possible to modify the default behavior of all the partitions
(or channels) via an attribute definition clause applied to the
predefined type @b{Partition} (or @b{Channel}).

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} Partition'ATTRIBUTE_NAME @b{use} ATTRIBUTE_ARGUMENTS;
 | @b{for} Channel'ATTRIBUTE_NAME @b{use} ATTRIBUTE_ARGUMENTS;

@end smallexample

It is also possible to modify the default behavior of a given partition
(or channel) via an attribute definition clause applied to the partition
(or channel) itself.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'ATTRIBUTE_NAME @b{use} ATTRIBUTE_ARGUMENTS;

@end smallexample

When an attribute definition clause is applied to a given object of a
predefined type, this overrides any attribute definition of the
predefined type. In the next sections, attributes apply to a given
object rather than to the predefined type.

@node Configuration Declaration, Partition Declaration, Pragmas and Representation Clauses, The Configuration Language
@subsubsection Configuration Declaration

The distribution of one or several Ada programs is described by a single
configuration unit. This configuration unit has a specification part and
an optional body part. A configuration unit is declared as an Ada
procedure would be. The keyword @b{configuration} is reserved for this
purpose.

@smallexample

CONFIGURATION_UNIT ::=
   @b{configuration} IDENTIFIER @b{is}
      DECLARATIVE_PART
   [@b{begin}
      SEQUENCE_OF_STATEMENTS]
   @b{end} [IDENTIFIER];

@end smallexample

@node Partition Declaration, Location Declaration, Configuration Declaration, The Configuration Language
@subsubsection Partition Declaration

In the declarative part, the user declares his partitions and can change
their default behavior. @t{po_gnatdist} provides a predefined type
@b{Partition}. The user can declare a list of partitions and can also
initialize these partitions with an initial list of Ada units.

@smallexample

DECLARATIVE_PART ::= @{DECLARATIVE_ITEM@}

DECLARATIVE_ITEM ::=
   PARTITION_DECLARATION
 | CHANNEL_DECLARATION
 | REPRESENTATION_CLAUSE
 | SUBPROGRAM_DECLARATION
 | PRAGMA

SUBPROGRAM_DECLARATION ::=
   MAIN_PROCEDURE_DECLARATION
 | PROCEDURE_DECLARATION
 | FUNCTION_DECLARATION

PARTITION_DECLARATION ::=
   DEFINING_IDENTIFIER_LIST : Partition
      [:= ENUMERATION_OF_ADA_UNITS];

DEFINING_IDENTIFIER_LIST ::=
   DEFINING_IDENTIFIER @{, DEFINING_IDENTIFIER@}

STATEMENT ::=
   IDENTIFIER := ENUMERATION_OF_ADA_UNITS;

SEQUENCE_OF_STATEMENTS ::=
   STATEMENT @{STATEMENT@}

@end smallexample

Once declared, a partition is an empty list of Ada units. The operator
@b{":="} adds the Ada units list on the right side to the current list
of Ada units that are already mapped to the partition. This is a
non-destructive operation. Whether a unit is a relevant Ada unit or not
is checked later on by the back-end of @t{po_gnatdist}. These assignments
can occur in the declarative part as well as in the body part.

@smallexample

ENUMERATION_OF_ADA_UNITS ::= (@{ADA_UNIT @{, ADA_UNIT@}@});

@end smallexample

@node Location Declaration, Partition Attribute Main, Partition Declaration, The Configuration Language
@subsubsection Location Declaration

There are several kinds of location in the configuration
language. We shall present them in the next subsections, but here is a
short overview of these locations:

@itemize @bullet

@item Boot_Location defines the network locations to use to communicate
with the the boot server during the boot phase

@item Self_Location defines the network locations to use by others
to communicate with the current partition

@item Data_Location defines the data storage location used by the
current partition to map its shared passive units

@end itemize

A location is composed of a support name and a specific data for this
support. For instance, a network location is composed of a protocol name
like @i{tcp} and a protocol data like @i{<machine>:<port>}. A storage
location is composed of a storage support name like @i{dfs} (for
Distributed File System) and a storage support data like a directory
@i{/dfs/glade}.

@smallexample

LOCATION      ::= ([Support_Name =>] STRING_LITERAL,
                   [Support_Data =>] STRING_LITERAL)

LOCATION_LIST ::= (LOCATION [,LOCATION)])

@end smallexample

Note that a location may have an undefined or incomplete support
data. In this case, the support is free to compute a support data. For
instance, ("tcp", "") specifies that the protocol is used but that the
protocol data @i{<machine>:<port>} is to be determined by the protocol
itself.

A location or a list of locations can be can be concatenated into a
single string to be used as a command line option or an environment
variable (see @ref{Partition Runtime Parameters}).

If a partition wants to communicate with another partition once the
location list of the latter is known, the caller will use the first
location of the callee whose protocol is locally available. For
instance, if a callee exports three locations ("N1", "D1"), ("N2", "D2")
and ("N3", "D3"), a caller with protocols N2 and N3 locally available
will try to communicate with the callee using the protocol of name N2
and of specific data D2.

@node Partition Attribute Main, Pragma Starter, Location Declaration, The Configuration Language
@subsubsection Partition Attribute Main

Basically, the distributed system annex (DSA) helps the user in building
a distributed application from a non-distributed application (Of course,
this is not the only possible model offered by DSA). The user can
design, implement and test his application in a non-distributed
environment, and then should be able to switch from the non-distributed
case to a distributed case. As mentioned before, this two-phase design
approach has several advantages.

In a non-distributed case, the user executes only one main executable
possibly with a name corresponding to the main unit name of his
application. With @t{po_gnatdist}, in a distributed case, a main executable
with a name corresponding to the main unit name is responsible for
starting the entire distributed application. Therefore, the user can
start his application the same way he used to do in the non-distributed
case.

For this reason, the configuration language provides a way to declare
the main procedure of the non-distributed application.

@smallexample

MAIN_PROCEDURE_DECLARATION ::=
   @b{procedure} MAIN_PROCEDURE_IDENTIFIER @b{is in} PARTITION_IDENTIFIER;

@end smallexample

In this case, the partition in which the main procedure has been mapped
is called the main partition. It includes in its code a call to this
main procedure. The main partition has an additional specific role,
because the boot server is located on it (see @ref{PolyORB PCS Internals}).

The main procedures for the other partitions have a null body. However,
the user can also modify this behavior by providing an alternate main
procedure. To do this, an alternate main subprogram has to be declared
and assigned to the partition Main attribute.

@smallexample

PROCEDURE_DECLARATION ::=
   @b{procedure} PROCEDURE_IDENTIFIER;

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Main @b{use} PROCEDURE_IDENTIFIER;

@end smallexample

@node Pragma Starter, Pragma Boot_Location, Partition Attribute Main, The Configuration Language
@subsubsection Pragma Starter

As a default, the main executable is a full Ada starter procedure. That
means that it launches all the other partitions from an Ada program. The
pragma Starter allows the user to ask for one starter or another. When
the partition host is not statically defined (see @ref{Partition
Attribute Host}), the starter subprogram will ask for it interactively
when it is executed.

@smallexample

CONVENTION_LITERAL ::= Ada   |
                       Shell |
                       None

PRAGMA ::=
   @b{pragma} Starter ([Convention =>] CONVENTION_LITERAL);

@end smallexample

@itemize @bullet

@item
The default method consists in launching partitions from the main
partition Ada subprogram using a remote shell (see below).

@item
The user may ask for a Shell script that starts the different partitions
one at a time on the appropriate remote machines, using a remote
shell. As the Ada starter, the Shell script starter ask for partition
hosts interactively when a partition host is not already defined. Having
a textual shell script allows the user to edit it and to modify it
easily.

@item
The user may ask for a None starter. In this case, it is up to the user
to launch the different partitions.

@end itemize

@subsubsection Pragma Remote_Shell

When pragma Starter is Ada or Shell, the main partition launches the
other partitions. The remote shell used as a default is determined
during PolyORB configuration and installation. It is either rsh, remsh or
the argument passed to --with-rshcmd=[ARG]. The pragma Remote_Shell
allows the user to override the default.

@smallexample

PRAGMA ::=
   @b{pragma} Remote_Shell
     ([Command =>] STRING_LITERAL,
      [Options =>] STRING_LITERAL);

@end smallexample

The Command parameter indicates the name of the remote shell command
name and the Options parameter corresponds to the additional flags to
pass to the remote shell command.

@node Pragma Boot_Location, Partition Attribute Self_Location, Pragma Starter, The Configuration Language
@subsubsection Pragma Boot_Location

When a partition starts executing, one of the first steps consists in a
connection to the boot server.  This pragma provides one or more
locations in order to get a connection with the boot server.

@smallexample

PRAGMA ::=
   PRAGMA_WITH_NAME_AND_DATA
 | PRAGMA_WITH_LOCATION
 | PRAGMA_WITH_LOCATION_LIST

PRAGMA_WITH_NAME_AND_DATA ::=
   @b{pragma} Boot_Location
     ([Protocol_Name =>] STRING_LITERAL,
      [Protocol_Data =>] STRING_LITERAL);

PRAGMA_WITH_LOCATION ::=
   @b{pragma} Boot_Location ([Location =>] LOCATION);

PRAGMA_WITH_LOCATION_LIST ::=
   @b{pragma} Boot_Location ([Locations =>] LOCATION_LIST);

@end smallexample

This boot server location can be concatenated into a single string to be
used as a command line option or an environment variable (see
@ref{Partition Runtime Parameters}).

@b{Note: pragma Boot_Server is now obsolete. It is recommended to use
pragma Boot_Location. This wording is more consistent with the rest of
the configuration language (see Self_Location @ref{Partition Option
self_location} and Data_Location @ref{Partition Option data_location}).}

@node Partition Attribute Self_Location, Partition Attribute Passive, Pragma Boot_Location, The Configuration Language
@subsubsection Partition Attribute Self_Location

Except for the boot partition on which the boot server is located, a
partition is reachable through a dynamically computed location (for
instance, the partition looks for a free port when the protocol is
tcp). The user may want such a partition to be reachable from a given
location, especially if the user wants to make this partition a boot
mirror. To do so, he can force the partition location with self_location
feature.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Self_Location @b{use} LOCATION;
 | @b{for} PARTITION_IDENTIFIER'Self_Location @b{use} LOCATION_LIST;

@end smallexample

If the attribute definition clause applies to the predefined type
@b{Partition}, the locations have to be incomplete. Otherwise, all the
partitions would be reachable through the same locations, which is
definitively not recommended.

When an attribute self_location definition clause applies to a given
partition, the protocol units needed for this partition are linked in
the executable. By default, when the self_location attribute is not
redefined, the default protocol used by the partition and loaded in its
executable is the @i{tcp} protocol.

@node Partition Attribute Passive, Partition Attribute Data_Location, Partition Attribute Self_Location, The Configuration Language
@subsubsection Partition Attribute Passive

By default, a partition is an active partition. This attribute allows to
define a passive partition. In this case, @t{po_gnatdist} checks that only
shared passive units are mapped on the partition. As this partition
cannot register itself, its location is hard-coded in all the partitions
that depend on its shared passive units.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Passive @b{use} BOOLEAN_LITERAL;

@end smallexample

@node Partition Attribute Data_Location, Partition Attribute Allow_Light_PCS, Partition Attribute Passive, The Configuration Language
@subsubsection Partition Attribute Data_Location

Shared passive units can be mapped on passive or active partitions. In
both cases, it is possible to choose the data storage support and to
configure it with the specific data of a location.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Data_Location @b{use} LOCATION;
 | @b{for} PARTITION_IDENTIFIER'Data_Location @b{use} LOCATION_LIST;

@end smallexample

When an attribute data_location definition clause applies to a given
partition, the data storage support units needed for this partition are
linked in the executable. By default, when the data_location attribute
is not redefined, the default storage support used by the partition and
loaded in its executable is the @i{dfs} support. @i{dfs}, Distributed
File System, is a storage support available as soon as files can be
shared between partitions.

It is not possible to map the different shared passive units of a given
partition on different data storage locations. PolyORB requires all the
shared passive units of a given partition to be mapped on the same
storage support. When the attribute data_location applied to a partition
is a list of locations, all the storage support units needed for this
partition are linked in the executable. By default, only the first one
is activated. The user can choose to change the activated support by
another one specified in the location list. This can be done using the
partition option data_location (see @ref{Partition Option
data_location}).

As passive partitions cannot be activated, it is not possible to provide
a location list as a data_location attribute. It is not possible to
change dynamically its location either.

@node  Partition Attribute Allow_Light_PCS, Pragma Priority, Partition Attribute Data_Location, The Configuration Language
@subsubsection Partition Attribute Allow_Light_PCS

On some circumstances, @t{po_gnatdist} can detect that a partition does not need
the full PCS functionalities. This occurs in particular when the
partition does use any task, any RCI unit or any RACW object. Therefore,
the partition does not receive any message that is not a reply to a
previous request. In this case, the PCS does not drag in the tasking
library and a light PCS is linked in the partition executable.
This specific configuration is automatically determined by
@t{po_gnatdist} with the ALI file information.

This optimization can be inappropriate especially when the user wants to
use the "Distributed Shared Memory" storage support which runs Li and
Hudak's algorithm. In this case, messages are exchanged without being
replies to previously sent requests and the normal PCS should be linked
instead of the light one. Note also that @t{po_gnatdist} cannot know for sure
that the DSM storage support assigned at configuration time is used at
run-time. The user can configure this optimization with the following
attribute.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Allow_Light_PCS @b{use} BOOLEAN_LITERAL;

@end smallexample

@node Pragma Priority, Partition Attribute Priority, Partition Attribute Allow_Light_PCS, The Configuration Language
@subsubsection Pragma Priority

It might be necessary for real-time applications to get control over the
priority at which a remote procedure call is executed. By default,
the PCS sends the priority of the client to the server which sets the
priority of an anonymous task to this value. The pragma Priority allows
to decide which priority policy should apply in the distributed
application.

@smallexample

PRIORITY_POLICY_LITERAL ::= Server_Declared
                          | Client_Propagated

PRAGMA ::=
   @b{pragma} Priority ([Policy =>] PRIORITY_POLICY_LITERAL);

@end smallexample

@itemize @bullet

@item
The default policy Client_Propagated consists in propagating the client
priority to the server.

@item
The policy Server_Declared consists in executing the remote procedure
call at a priority specific to the partition. This priority can be
set using the partition attribute Priority.

@end itemize

@node Partition Attribute Priority, Partition Attribute Host, Pragma Priority, The Configuration Language
@subsubsection Partition Attribute Priority

This attribute allows to set the priority at which level a remote
procedure call is executed on a server when the priority policy is
Server_Declared. By default, the default priority of the anonymous task
is the default task priority.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Priority @b{use} INTEGER_LITERAL;

@end smallexample


@node Partition Attribute Host, Pragma Import, Partition Attribute Priority, The Configuration Language
@subsubsection Partition Attribute Host

Logical nodes (or partitions) can be mapped onto physical nodes. The
host-name can be either a static or dynamic value. In case of a static
value, the expression is a string literal. In case of a dynamic value,
the representation clause argument is a function that accepts a string
as parameter and that returns a string value. When the function is
called, the partition name is passed as parameter and the host-name is
returned.

@smallexample

FUNCTION_DECLARATION ::=
   @b{function} FUNCTION_IDENTIFIER
     (PARAMETER_IDENTIFIER : [@b{in}] String)
      @b{return} String;

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Host @b{use} STRING_LITERAL;
 | @b{for} PARTITION_IDENTIFIER'Host @b{use} FUNCTION_IDENTIFIER;

@end smallexample

The signature of the function must be the following : it takes a
string parameter which corresponds to a partition name. It returns
a string parameter which corresponds to the host-name. The function
that returns the host-name can be an Ada function (default) or a shell
script. A pragma Import is used to import a function defined in Ada or
in Shell (see @ref{Pragma Import}).

This function is called on the main partition by the PCS to launch
a given partition on a given logical node. In case of load balancing,
the function can return the most appropriate among a set of hosts.

@node Pragma Import, Partition Attribute Directory, Partition Attribute Host, The Configuration Language
@subsubsection Pragma Import

Two kinds of subprograms are allowed in the configuration
language. A main procedure is used as a partition Main attribute and a
function is used as a partition Host attribute.

@smallexample

SUBPROGRAM_DECLARATION ::=
     @b{procedure} MAIN_PROCEDURE_IDENTIFIER @b{is} @b{in} PARTITION_NAME;
   | @b{procedure} PROCEDURE_IDENTIFIER;
   | @b{function} FUNCTION_IDENTIFIER
        (PARAMETER_IDENTIFIER : [@b{in}] String)
         @b{return} String;

@end smallexample

The function can be an Ada function (default) or a shell script. To
import a shell script, the pragma Import must be used:

@smallexample

PRAGMA ::=
   @b{pragma} Import
      ([Entity        =>] FUNCTION_IDENTIFIER,
       [Convention    =>] CONVENTION_LITERAL,
       [External_Name =>] STRING_LITERAL);

@b{pragma} Import (Best_Node, Shell, "best-node");
@end smallexample

In this case, the PCS invokes the shell script with the partition
name as a command line argument. The shell script is supposed to return
the partition host-name (see @ref{Partition Attribute Host}).

@node Partition Attribute Directory, Partition Attribute Command_Line, Pragma Import, The Configuration Language
@subsubsection Partition Attribute Directory

Directory allows the user to specify in which directory the partition
executable is stored. This can be useful in heterogeneous systems when
the user wants to store executables for the same target in a given
directory. Specifying the directory is also useful if the partition
executable is not directly visible from the user environment. For
instance, when a remote command like @b{rsh} is invoked, the executable
directory has to be present in the user path. If the Directory
attribute has been specified, the executable full name is used.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Directory @b{use} STRING_LITERAL;

@end smallexample

@node Partition Attribute Command_Line, Partition Attribute Environment_Variables, Partition Attribute Directory, The Configuration Language
@subsubsection Partition Attribute Command_Line

The user may want to pass arguments on the command line of a
partition. However, when a partition is launched automatically by the
main partition, the partition command line includes only PolyORB
arguments. To add arguments on the command line, the user can take
advantage of the following attribute.

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Command_Line @b{use} STRING_LITERAL;

@end smallexample

@node Partition Attribute Environment_Variables, Partition Attribute Termination, Partition Attribute Command_Line, The Configuration Language
@subsubsection Partition Attribute Environment_Variables

The attribute Environment_Variables allows the user to specify a list of
environment variables that should be passed from the main partition
to slave partitions when using a generated (shell or Ada) launcher.

This attribute can be applied to all partitions by defining it for the
predefined type @b{Partition}, or to a specific partition. Note that in
the latter case, the list does not replace the default one but instead
complements it (i.e. variables specified for @b{Partition} are passed
in addition to the partition specific ones).

@smallexample

STRING_LITERAL_LIST ::=
   STRING_LITERAL
   | STRING_LITERAL@b{,} STRING_LITERAL_LIST

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Environment_Variables @b{use (}STRING_LITERAL_LIST@b{);}

@end smallexample

@node Partition Attribute Termination, Partition Attribute Reconnection, Partition Attribute Environment_Variables, The Configuration Language
@subsubsection Partition Attribute Termination

The Ada Reference Manual does not provide any specific rule to handle
global termination of a distributed application (see @ref{Abortion and
Termination}).

In PolyORB/DSA, by default, a set of partitions terminates when each partition
can terminate and when no message remains to be delivered. A distributed
algorithm that checks for this global condition is activated
periodically by the main boot server.

@smallexample

TERMINATION_LITERAL ::= Global_Termination |
                         Local_Termination  |
                         Deferred_Termination

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Termination @b{use} TERMINATION_LITERAL;

@end smallexample

@itemize @bullet

@item When a partition is configured with the global termination policy,
it terminates as soon as the main boot server sends a signal to do
so. The main boot server checks periodically whether the application can
terminate. When all partitions are ready to terminate, the main boot
server sends to each partition a termination request. The global
termination policy is the default policy.

@item The deferred termination policy is very similar to the global
termination. The only difference is that when a partition with a
deferred termination policy receives a termination request, it just
ignores it. This policy allows a partition to run forever without
preventing a set of partitions from terminating. This policy is not yet
implemented.

@item When a partition is configured with the local termination policy,
it terminates as soon as the classical Ada termination is detected by
the partition. It means that this partition does not wait for the
termination request of the main boot server.

@end itemize

@c GARLIC-specific
@c In any case, when the boot partition dies (and when no alternate boot
@c partition can elected, see @ref{The GARLIC PCS}), all the
@c partitions die, whatever their termination policy might be. Note first,
@c that a partition cannot execute without a boot partition. Second, when
@c the user wants to kill his non-distributed application, he kills the
@c main program. Enforcing the mechanism described above ensures that
@c killing the main partition automatically kills all the partitions, that
@c is to say the whole distributed application.

@node Partition Attribute Reconnection, Pragma Version, Partition Attribute Termination, The Configuration Language
@subsubsection Partition Attribute Reconnection

When no RCI package is configured on a partition, such a partition can
be launched several times without any problem. When one or more RCI
packages are configured on a partition, such a partition cannot be
launched more than once. If this partition were to be launched
repeatedly, it would not be possible to decide which partition instance
should execute a remote procedure call.

When a partition crashes or is stopped, one may want to restart this
partition and possibly restore its state - with Shared_Passive packages,
for instance. In such a situation, the partition is already known to
other partitions and possibly marked as a dead partition. Several
policies can be selected:


@smallexample

RECONNECTION_LITERAL ::= Reject_On_Restart  |
                          Fail_Until_Restart |
                          Block_Until_Restart

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Reconnection @b{use} RECONNECTION_LITERAL;

@end smallexample

@itemize @bullet

@item When this partition is configured with the Reject_On_Restart
reconnection policy, the dead partition is kept dead and any attempt to
restart it fails. Any remote call to a subprogram located on this
partition results in a Communication_Error exception. The
Reject_On_Restart policy is the default policy.

@item When this partition is configured with the Fail_Until_Restart
reconnection policy, the dead partition can be restarted. Any remote
call to a subprogram located on this partition results in an exception
Communication_Error as long as this partition has not been restarted. As
soon as the partition is restarted, remote calls to this partition are
executed normally.

@item When this partition is configured with the Block_Until_Restart
reconnection policy, the dead partition partition can be restarted. Any
remote call to a subprogram located on this partition is suspended until
the partition is restarted. As soon as the partition is restarted,
remote calls to this partition are executed normally. The suspended
remote procedure calls to this partition are resumed.


@end itemize

@c @node Channel Declaration, Partition and Channel Attribute Filter, Partition Attribute Reconnection, The Configuration Language
@c @subsubsection Channel Declaration

@c @node Partition and Channel Attribute Filter, Pragma Registration_Filter, Channel Declaration, The Configuration Language
@c @subsubsection Partition and Channel Attribute Filter

@c GARLIC specific

@node Pragma Version, Partition Attribute Task_Pool, Partition Attribute Reconnection, The Configuration Language
@subsubsection Pragma Version

A library unit is consistent if the same version of its declaration is
used throughout (see @ref{Consistency and Elaboration}). It can be
useful to deactivate these checks, especially when the user wants to be
able to update a server without updating a client.

@smallexample

PRAGMA ::=
   @b{pragma} Version ([Check =>] BOOLEAN_LITERAL);

@end smallexample

@node Partition Attribute Task_Pool, Partition Attribute ORB_Tasking_Policy, Pragma Version, The Configuration Language
@subsubsection Partition Attribute Task_Pool

When multiple remote subprogram calls occur on the same partition, they
are handled by several anonymous tasks. These tasks can be allocated
dynamically or re-used from a pool of (preallocated) tasks. When a
remote subprogram call is completed, the anonymous task can be
deallocated or queued in a pool in order to be re-used for further
remote subprogram calls. The number of tasks in the anonymous tasks pool
can be configured by means of three independent parameters.

@itemize @bullet

@item The task pool minimum size indicates the number of anonymous tasks
preallocated and always available in the PCS. Preallocating
anonymous tasks can be useful in real-time systems to prevent task
dynamic allocation.

@item The task pool high size is a ceiling. When a remote subprogram
call is completed, its anonymous task is deallocated if the number of
tasks already in the pool is greater than the ceiling. If not, then the
task is queued in the pool.

@item The task pool maximum size indicates the maximum number of anonymous
tasks in the PCS. In other words, it provides a way to limit the
number of remote calls in the PCS. When a RPC request is received, if
the number of active remote calls is greater than the task pool maximum
size, then the request is kept pending until an anonymous task completes
its own remote call and becomes available.

@end itemize

@smallexample

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'Task_Pool @b{use} TASK_POOL_SIZE_ARRAY;

TASK_POOL_SIZE_ARRAY ::=
  (NATURAL_LITERAL,  @i{--  Task Pool Minimum Size}
   NATURAL_LITERAL,  @i{--  Task Pool High Size}
   NATURAL_LITERAL); @i{--  Task Pool Maximum Size}

@end smallexample

In order to have only one active remote call at a  time, the task pool
configuration is declared as follows:

@smallexample

@b{for} Partition'Task_Pool @b{use} (0, 0, 1);

@end smallexample

@node Partition Attribute ORB_Tasking_Policy, A Complete Example, Partition Attribute Task_Pool, The Configuration Language
@subsubsection Partition Attribute ORB_Tasking_Policy

By default, the Thread_Pool ORB tasking policy is used for all partitions.
This attribute allows selection of an alternate policy among those
provided by PolyORB (see @ref{PolyORB ORB Tasking policies}) for
each partition.

@smallexample
ORB_TASKING_POLICY_LITERAL ::= Thread_Pool        |
                               Thread_Per_Session |
                               Thread_Per_Request

REPRESENTATION_CLAUSE ::=
   @b{for} PARTITION_IDENTIFIER'ORB_Tasking_Policy @b{use} ORB_TASKING_POLICY_LITERAL;

@end smallexample

@i{Note: @ref{Partition Attribute Task_Pool} has no effect when another policy
than Thread_Pool is activated.}

@node A Complete Example,  , Partition Attribute ORB_Tasking_Policy, The Configuration Language
@subsubsection A Complete Example

Almost every keyword and construct defined in the configuration language
has been used in the following sample configuration file.

@include myconfig.cfg.texi

@enumerate

@item @b{Line 01}
Typically, after having created the following configuration file the user
types:

@smallexample

po_gnatdist myconfig.cfg

@end smallexample

If the user wants to build only some partitions then he will list the
partitions to build on the @t{po_gnatdist} command line as follows:

@smallexample

po_gnatdist myconfig.cfg partition_2 partition_3

@end smallexample

The name of the file prefix must be the same as the name of the
configuration unit, in this example @t{myconfig.cfg}. The file suffix
must be @t{cfg}. For a given distributed application the user can have
as many different configuration files as desired.

@item @b{Line 04}
Partition 1 contains no RCI package. However, it will contain the main
procedure of the distributed application, called @i{Master_Procedure} in
this example. If the line @i{procedure Master_Procedure is in
Partition_1;} was missing, Partition 1 would be completely empty. This is
forbidden, because a partition has to contain at least one library unit.

@t{po_gnatdist} produces an executable with the name of @i{Master_Procedure}
which will start the various partitions on their host machines in the
background. The main partition is launched in foreground. Note that by
killing this main procedure the whole distributed application is terminated.

@item @b{Line 08}
Specify the host on which to run partition 2.

@item @b{Line 12}
Use the value returned by a program to figure out at execution time the
name of the host on which partition 3 should execute.  For instance,
execute the shell script @t{best-node} which takes the partition name as
parameter and returns a string giving the name of the machine on which
partition_3 should be launched.

@item @b{Line 14}
Partition 4 contains one RCI package RCI_B5 No host is specified for
this partition. The startup script will ask for it interactively when it
is executed.

@item @b{Line 16}
Specify the directory in which the executable of partition partition_1
will be stored.

@item @b{Line 17}
Specify the directory in which all the partition executables will be
stored (except partition_1, see @ref{Pragmas and Representation
Clauses}). Default is the current directory.

@item @b{Line 20}
Specify the partition main subprogram to use in a given partition.

@item @b{Line 22}
Specify a reconnection policy in case of a crash of Partition_3. Any attempt to
reconnect to Partition_3 when this partition is dead will be
blocked until Partition_3 restarts. By default, any restart is
rejected (Reject_On_Restart). Another policy is to raise
Communication_Error on any reconnection attempt until Partition_3 has
been restarted.

@item @b{Line 23}
Specify additional arguments to pass on the command line when a given
partition is launched.

@item @b{Line 24}
Specify a termination mechanism for partition_4. The default is to
compute a global distributed termination. When Local_Termination is
specified a partition terminates as soon as local termination is
detected (standard Ada termination).

@item @b{Line 26}
Specify the kind of startup method the user wants. There are 3
possibilities: Shell, Ada and None. Specifying @i{Shell} builds a shell
script. All the partitions will be launched from a shell script.  If
@i{Ada} is chosen, then the main Ada procedure itself is used to launch
the various partitions. If method @i{None} is chosen, then no launch
method is used and the user must start each partition manually.

If no starter is given, then an Ada starter will be used.

In this example, Partition_2, Partitions_3 and Partition_4 will be
started from Partition_1 (ie from the Ada procedure Master_Procedure).

@item @b{Line 30}
Specify the use of a particular boot server.

@item @b{Line 32}
It is a bounded error to elaborate a partition of a distributed
program that contains a compilation unit that depends on a different
version of the declaration of an RCI library unit than the one included in
the partition to which the RCI library unit was assigned. When the
pragma Version is set to False, no consistency check is performed.

@item @b{Line 335}
Declare two channels. Other channels between partitions remain
unknown.

@item @b{Line 37}
Use transparent compression / decompression for the arguments and
results of any remote calls on channel @i{Channel_1}, i.e. between
@i{Partition_1} and @i{Partition_4}.

@item @b{Line 38}
Use filter @i{My_Own_Filter} on any declared channel ie @i{Channel_1}
amd @i{Channel_2}. As @i{Channel_1} filter attribute is already
assigned, this applies only to @i{Channel_2}. This filter must be
implemented in a package @i{System.Garlic.Filters.My_Own_Filter}.

@item @b{Line 39}
For all data exchanged between partitions, use the filter @i{ZIP}. (I.e.
for both arriving remote calls as well as for calls made by a
partition.)

@item @b{Line 41}
@i{Some_Filter} will be used to exchange a filter's parameters between
two partitions. @i{Some_Filter} itself must be an algorithm that doesn't
need its own parameters to be filtered again. This filter must be
implemented in a package @i{System.Garlic.Filters.Some_Filter}.

@item @b{Line 43}
The configuration body is optional. The user may have fully described
his configuration in the declaration part.

@item @b{Line 44}
Partition 2 contains two RCI packages RCI_B2 and RCI_B4 and a normal
package. A normal package is not categorized.

@item @b{Line 45}
Partition 3 contains one RCI package RCI_B3

@end enumerate

@node Partition Runtime Parameters, Gnatdist Internals, The Configuration Language, Building a DSA application with PolyORB
@subsection Partition Runtime Parameters

@noindent
You can adjust some parameters of your DSA applications using the PolyORB
configuration file, @file{polyorb.conf}. The parameters relevant to the
Ada Distributed Systems Annex are specified in the @code{[dsa]} section.

See @ref{Run-time configuration} for complete documentation of PolyORB's
runtime configuration facilities.

@table @code
@item name_service = [IOR/corbaloc]
You can set this parameter instead of the environment variable
@code{POLYORB_DSA_NAME_SERVICE}.
Though if you use a Starter, ensure that this parameter is set for
all the partitions, as this is not done automatically as for the
@code{POLYORB_DSA_NAME_SERVICE} environment variable.

@item max_failed_requests = [integer]
Each partition will attempt a given number of requests to the
name server before failing. This allows some time for every
partition to register in the name server.

@item delay_between_failed_requests = [duration in milliseconds]
As above, only this specifies the delay between requests.

@item termination_initiator = [true/false]
Is this partition a termination initiator.

@item termination_policy = [global_termination/deferred_termination/local_termination]
The termination policy for this partition.

@item tm_time_between_waves = [duration in milliseconds]
The delay between termination waves.

@item tm_time_before_start = [duration in milliseconds]
The delay before the termination manager starts sending waves.

@item detach = [true/false]
If true, the partition will be detached.

@item rsh_options = [string]
Options passed to the rsh command when using the module
polyorb.dsa_p-remote_launch

@item rsh_command = [string]
Which command should the module polyorb.dsa_p-remote_launch
use to spawn remote programs.
@end table

@node Gnatdist Internals, PolyORB PCS Internals, Partition Runtime Parameters, Building a DSA application with PolyORB
@subsection Gnatdist Internals

Here is what goes on in @t{po_gnatdist} when building a distributed application:

@itemize @bullet
@item
Each compilation unit in the program is compiled into an object module
(as for non distributed applications). This is achieved by calling
gnatmake on the sources of the various partitions.

@item
Stubs and skeletons are compiled into object modules (these are pieces of
code that allow a partition running on machine A to communicate with a
partition running on machine B). Several timestamp checks are performed
to avoid useless code recompilation and stub generation.

@item
@t{po_gnatdist} performs a number of consistency checks. For instance it checks
that all packages marked as remote call interface (RCI) and shared
passive (SP) are mapped onto partitions. It also checks that a RCI or SP
package is mapped onto only one partition.

@item
Finally, the executables for each partition in the program are
created. The code to launch partitions is embedded in the main partition
except if another option has been specified (see @ref{Pragma
Starter}). In this case, a shell script (or nothing) is generated to
start the partitions on the appropriate machines. This is specially
useful when one wants to write client / server applications where the
number of instances of the partition is unknown.

@end itemize

All Gnatdist intermediate files (object files, etc) are stored under a
common directory named "dsa". The user may remove this whole directory and
its content when he does not intend to rebuild his distributed
applications.

@node PolyORB PCS Internals, Remote Shell Notes, Gnatdist Internals, Building a DSA application with PolyORB
@subsection PolyORB PCS Internals

This section provides notes on the PolyORB implementation of the DSA PCS.
Some of these features are not configurable by the user.

@menu
* Application startup
* Heterogeneous System::
* Allocating Partition Ids::
* Executing Concurrent Remote Calls::
* Priority Inheritance::
* Remote Call Abortion::
* User Filter Implementation::
@end menu

@node Application Startup, Heterogeneous System, PolyORB PCS Internals, PolyORB PCS Internals
@subsubsection Application Startup

A name server needs to be started prior to starting any application
partition. Once the name server is started, its location must be passed
to all partitions as the @t{name_service} runtime parameter. When using
an Ada starter, it is sufficient to pass the name server location to the
starter, and it will be propagated automatically to all partitions.

Upon elaboration, each partition registers its RCI packages with the
name server. Once this is done, remote calls to RCI subprograms can proceed.
Partitions cache the replies from the name server so that during the
course of normal execution, inter-partition calls only involve the caller
and callee partitions (not the name server).

RCI units can then act as ``clearinghouses'' for other partitions to exchange
RACWs and set up dynamic communication paths.

@node Heterogeneous System, Allocating Partition Ids, Application Startup, PolyORB PCS Internals
@subsubsection Heterogeneous System

The GNAT environment provides default stream attributes, except for non-remote
access types (see @ref{Transmitting Dynamic Structure} and
@ref{Marshalling and Unmarshalling Operations}). The implementation of
the default attributes of predefined types can be found in
@i{System.Stream_Attributes} (s-stratt.adb).

The PolyORB PCS provides alternative data representations by default to
ensure portability of the data stream across partitions executing on
heterogeneous architectures. Users may override these representation aspects
by configuring the protocol personality of their choice.

@node Allocating Partition Ids, Executing Concurrent Remote Calls, Heterogeneous System, PolyORB PCS Internals
@subsubsection Allocating Partition Ids

The Partition_ID is allocated dynamically, at run-time. Each partition
connects to a Partition ID Server which is located on the boot server
and asks for a free Partition_ID. The advantage of this approach is that
it supports easily client / server solution (client partitions may be
duplicated, they will obtain different Partition Ids). There is no need
to recompile or relink all the partitions when a new partition is added
to the system. The Partition_ID is not tied in any way to a specific
protocol or to a specific location.

@node Executing Concurrent Remote Calls, Priority Inheritance, Allocating Partition Ids, PolyORB PCS Internals
@subsubsection Executing Concurrent Remote Calls

When multiple remote subprogram calls occur on the same partition, they
are handled by several anonymous tasks. The number of tasks in the
anonymous tasks pool can be configured by three figures (see
@ref{Partition Attribute Task_Pool}). Therefore, the user may have to
synchronize global data in the Remote_Call_Interface or Remote_Types
unit to preserve concurrent access on data. If the user want to suppress
the multiple requests features, he can force the configuration of the
anonymous tasks pool to (0 | 1, 0 | 1, 1). That means that there will be
at most one anonymous task running at a time.

@node Priority Inheritance, Remote Call Abortion, Executing Concurrent Remote Calls, PolyORB PCS Internals
@subsubsection Priority Inheritance

@c Is this implemented in PolyORB/DSA???

It is compiler-dependent whether the caller priority is preserved during
a remote procedure call. In fact, it can be unsafe to rely on
priorities, because two partitions may have different priority ranges
and policies. Nevertheless, PolyORB preserves the caller priority. This
priority is marshaled and unmarshaled during the remote procedure call
and the priority of the anonymous task on the server is set to the
caller priority.

This default policy can be modified by using pragma Priority
@ref{Pragma Priority} and partition attribute
Priority @ref{Partition Attribute Priority}.

@node Remote Call Abortion, , Priority Inheritance, PolyORB PCS Internals
@subsubsection Remote Call Abortion

@c Is this implemented in PolyORB/DSA???

When a remote procedure call is aborted, PolyORB will abort the calling
task on the caller side. It will also try to abort the remote anonymous
task performing the remote call. This task will be aborted without being
requeued in the anonymous tasks pool.

@c -------------------------------------------------------------------
@node Running a DSA application
@section Running a DSA application
@c -------------------------------------------------------------------

By default @command{po_gnatdist} will use the Ada starter. So if you
have not specified @code{pragma Starter (None);} in the
@command{po_gnatdist} configuration file, you should have a starter in
your build directory, named after your configuration file.  In this case
you just have to run this program.

If you don't want to use the Starter and have specified @code{pragma
Starter (None);} in your configuration file, then you should have, in
your Partition'Directory, one binary for each of your partitions.
You'll have to start each of these programs manually.

In both cases you must specify a name server for your application.
You can use for example the one included in PolyORB:
@file{po_cos_naming}. When running this name server it will output its
IOR URI named @code{POLYORB_CORBA_NAME_SERVICE}.

Just ensure that you set the global environment variable
@code{POLYORB_DSA_NAME_SERVICE} to an IOR URI referencing the
running name server. When using the @file{po_cos_naming} name server
just set @code{POLYORB_DSA_NAME_SERVICE} environment variable to the
first value output for @code{POLYORB_DSA_NAME_SERVICE} before
launching each DSA partition.

Here is a small trace output that demonstrates the setup

@smallexample

polyorb/examples/dsa/echo% ../../../tools/po_cos_naming/po_cos_naming&
polyorb/examples/dsa/echo% POLYORB_CORBA_NAME_SERVICE=''....''

polyorb/examples/dsa/echo% export POLYORB_DSA_NAME_SERVICE=''...''
polyorb/examples/dsa/echo% ./client 
The client has started!
Thus spake my server upon me:Hi!
@end smallexample

@c -------------------------------------------------------------------
@node MOMA
@chapter MOMA
@cindex MOMA, Message Oriented Middleware for Ada
@c -------------------------------------------------------------------

@menu
* What you should know before Reading this section4::
* Installing MOMA application personality::
* Package hierarchy::
@end menu

@c -------------------------------------------------------------------
@node What you should know before Reading this section4
@section What you should know before Reading this section
@c -------------------------------------------------------------------

@noindent
This section assumes that the reader is familiar with the JMS
specifications described in @cite{[SUN99]}. MOMA is a thick adaptation
of the JMS specification to the Ada programming language, preserving
most of the JMS concepts.

@c -------------------------------------------------------------------
@node Installing MOMA application personality
@section Installing MOMA application personality
@c -------------------------------------------------------------------

@noindent
Ensure PolyORB has been configured and then compiled with the MOMA
application personality. See @ref{Building an application with PolyORB}
for more details on how to check installed personalities.

To build the MOMA application personality, @pxref{Installation}.

@c -------------------------------------------------------------------
@node Package hierarchy
@section Package hierarchy
@c -------------------------------------------------------------------

@noindent
Packages installed in @file{$INSTALL_DIR/include/polyorb/moma} hold
the MOMA API. MOMA is built around two distinct sets of packages:

@enumerate
@item @file{MOMA.*} hold the public MOMA library, all the constructs
the user may use.

@item @file{POLYORB.MOMA_P.*} hold the private MOMA library, these
packages shall not be used when building your application.

@end enumerate

@c -------------------------------------------------------------------
@node AWS
@chapter Ada Web Server (AWS)
@cindex AWS, Ada Web Server
@c -------------------------------------------------------------------

@noindent
@i{The documentation of this personality will appear in a future
revision of PolyORB.}

@c -------------------------------------------------------------------
@node GIOP
@chapter GIOP
@cindex GIOP
@c -------------------------------------------------------------------

@menu
* Installing GIOP protocol personality::
* GIOP Instances::
* Configuring the GIOP personality::
* Code sets::
@end menu

@c -------------------------------------------------------------------
@node Installing GIOP protocol personality
@section Installing GIOP protocol personality
@c -------------------------------------------------------------------

@noindent
Ensure PolyORB has been configured and then compiled with the GIOP
protocol personality. See @ref{Building an application with PolyORB}
for more details on how to check installed personalities.

To enable configuration of the GIOP protocol personality,
@pxref{Installation}.

@c -------------------------------------------------------------------
@node GIOP Instances
@section GIOP Instances
@c -------------------------------------------------------------------

@noindent
GIOP is a generic protocol that can be instantiated for multiple
transport stacks. PolyORB provides three different instances.

@menu
* IIOP::
* SSLIOP::
* DIOP::
* MIOP::
@end menu

@c -------------------------------------------------------------------
@node IIOP
@subsection IIOP
@cindex IIOP
@c -------------------------------------------------------------------

@noindent
Internet Inter-ORB Protocol (IIOP) is the default protocol defined by
the CORBA specifications. It is a TCP/IP, IPv4, based protocol that
supports the full semantics of CORBA requests.

@c -------------------------------------------------------------------
@node SSLIOP
@subsection SSLIOP
@cindex SSLIOP
@c -------------------------------------------------------------------

@noindent
The SSLIOP protocol provides transport layer security for transmitted
requests.  Its provides encryption of GIOP requests.

To build the SSLIOP, it is required to activate SSL-related features
when building PolyORB. See @option{--with-openssl} in @ref{Installation} for more details.

Enabling security is completely transparent to a preexisting
application, it is also possible to phase in secure communications by
allowing incoming requests which are unsecured.

@c -------------------------------------------------------------------
@node DIOP
@subsection DIOP
@cindex DIOP
@c -------------------------------------------------------------------

@noindent
Datagram Inter-ORB Protocol (DIOP) is a specialization of GIOP for the
UDP/IP protocol stack. It supports only asynchronous (@code{oneway})
requests.

This protocol is specific to PolyORB. DIOP 1.0 is a mapping of GIOP on
top of UDP/IP. DIOP 1.0 uses GIOP 1.2 message format.

@c -------------------------------------------------------------------
@node MIOP
@subsection MIOP
@cindex MIOP
@c -------------------------------------------------------------------

@noindent
Unreliable Multicast Inter-ORB Protocol (MIOP) @cite{[OMG02b]} is a
specialization of GIOP for IP/multicast protocol stack. It supports
only asynchronous (@code{oneway}) requests.

@c -------------------------------------------------------------------
@node Configuring the GIOP personality
@section Configuring the GIOP personality
@cindex Configuration, GIOP
@c -------------------------------------------------------------------

@noindent
The GIOP personality is configured using a configuration
file. See @ref{Using a configuration file} for more details.

Here is a summary of available parameters for each instance of GIOP.

@menu
* Common configuration parameters::
* IIOP Configuration Parameters::
* SSLIOP Configuration Parameters::
* DIOP Configuration Parameters::
* MIOP Configuration Parameters::
@end menu

@c -------------------------------------------------------------------
@node Common configuration parameters
@subsection Common configuration parameters
@cindex GIOP
@c -------------------------------------------------------------------

@noindent
This section details configuration parameters common to all GIOP
instances.

@smallexample
###############################################################################
# GIOP parameters
#

[giop]

###############################################################
# Native code sets
#
# Available char data code sets:
#   16#00010001#   ISO 8859-1:1987; Latin Alphabet No. 1
#   16#05010001#   X/Open UTF-8; UCS Transformation Format 8 (UTF-8)
#
# Available wchar data code sets:
#   16#00010100#   ISO/IEC 10646-1:1993; UCS-2, Level 1
#   16#00010109#   ISO/IEC 10646-1:1993;
#                                UTF-16, UCS Transformation Format 16-bit form
#
#giop.native_char_code_set=16#00010001#
#giop.native_wchar_code_set=16#00010100#
#
# The following parameters force the inclusion of fallback code sets
# as supported conversion code sets. This is required to enable
# interoperability with ORBs whose code sets negotiation support is
# broken. See PolyORB's Users Guide for additional information.
#
#giop.add_char_fallback_code_set=false
#giop.add_wchar_fallback_code_set=false
@end smallexample

@c -------------------------------------------------------------------
@node IIOP Configuration Parameters
@subsection IIOP Configuration Parameters
@c -------------------------------------------------------------------

@c check consistency with polyorb.conf

@smallexample

###############################################################################
# IIOP parameters
#

[iiop]

###############################################################
# IIOP Global Settings

# Preference level for IIOP
#polyorb.binding_data.iiop.preference=0

# IIOP's default address
#polyorb.protocols.iiop.default_addr=127.0.0.1

# IIOP's default port
#polyorb.protocols.iiop.default_port=2809

# IIOP's alternate addresses
#polyorb.protocols.iiop.alternate_listen_addresses=127.0.0.1:2810 127.0.0.1:2820

# Default GIOP/IIOP Version
#polyorb.protocols.iiop.giop.default_version.major=1
#polyorb.protocols.iiop.giop.default_version.minor=2

###############################################################
# IIOP 1.2 specific parameters

# Set to True to enable IIOP 1.2
#polyorb.protocols.iiop.giop.1.2.enable=true

# Set to True to send a locate message prior to the request
#polyorb.protocols.iiop.giop.1.2.locate_then_request=true

# Maximum message size before fragmenting request
#polyorb.protocols.iiop.giop.1.2.max_message_size=1000

###############################################################
# IIOP 1.1 specific parameters

# Set to True to enable IIOP 1.1
#polyorb.protocols.iiop.giop.1.1.enable=true

# Set to True to send a locate message prior to the request
#polyorb.protocols.iiop.giop.1.1.locate_then_request=true

# Maximum message size before fragmenting request
#polyorb.protocols.iiop.giop.1.1.max_message_size=1000

###############################################################
# IIOP 1.0 specific parameters

# Set to True to enable IIOP 1.0
#polyorb.protocols.iiop.giop.1.0.enable=true

# Set to True to send a locate message prior to the request
#polyorb.protocols.iiop.giop.1.0.locate_then_request=true
@end smallexample

@c -------------------------------------------------------------------
@node SSLIOP Configuration Parameters
@subsection SSLIOP Configuration Parameters
@c -------------------------------------------------------------------

@menu
* Ciphers name::
* SSLIOP Parameters::
@end menu

@c -------------------------------------------------------------------
@node Ciphers name
@subsubsection Ciphers name
@c -------------------------------------------------------------------

PolyORB's SSLIOP uses the OpenSSL library to support all ciphers
recommended by CORBA 3.0.3. The OpenSSL library uses specific names for
ciphers. The table below contains CORBA-recommended cipher names and
their OpenSSL equivalents:

@multitable @columnfractions .6 .4
@item CORBA recommended ciphers               @tab OpenSSL equivalent
@item TLS_RSA_WITH_RC4_128_MD5                @tab RC4-MD5
@item SSL_RSA_WITH_RC4_128_MD5                @tab RC4-MD5
@item TLS_DHE_DSS_WITH_DES_CBC_SHA            @tab EDH-DSS-CBC-SHA
@item SSL_DHE_DSS_WITH_DES_CBC_SHA            @tab EDH-DSS-CBC-SHA
@item TLS_RSA_EXPORT_WITH_RC4_40_MD5          @tab EXP-RC4-MD5
@item SSL_RSA_EXPORT_WITH_RC4_40_MD5          @tab EXP-RC4-MD5
@item TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA   @tab EXP-EDH-DSS-DES-CBC-SHA
@item SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA   @tab EXP-EDH-DSS-DES-CBC-SHA
@end multitable

@c -------------------------------------------------------------------
@node SSLIOP Parameters
@subsubsection SSLIOP Parameters
@c -------------------------------------------------------------------

@c check consistency with polyorb.conf

@smallexample
###############################################################################
# SSLIOP parameters
#

[ssliop]

###############################################################
# SSLIOP Global Settings

# SSLIOP's default port
#polyorb.protocols.ssliop.default_port=2810
# If no SSLIOP default address is provide, PolyORB reuses IIOP's
# address

# Private Key file name
#polyorb.protocols.ssliop.privatekeyfile=privkey.pem

# Certificate file name
#polyorb.protocols.ssliop.certificatefile=cert.pem

# Trusted CA certificates file
#polyorb.protocols.ssliop.cafile=cacert.pem

# Trusted CA certificates path
#polyorb.protocols.ssliop.capath=demoCA/certs

# Disable unprotected invocations
#polyorb.protocols.ssliop.disable_unprotected_invocations=true

###############################################################
# Peer certificate verification mode

# Verify peer certificate
#polyorb.protocols.ssliop.verify=false

# Fail if client did not return certificate. (server side option)
#polyorb.protocols.ssliop.verify_fail_if_no_peer_cert=false

# Request client certificate only once. (server side option)
#polyorb.protocols.ssliop.verify_client_once=false
@end smallexample

@c -------------------------------------------------------------------
@node DIOP Configuration Parameters
@subsection DIOP Configuration Parameters
@c -------------------------------------------------------------------

@c check consistency with polyorb.conf

@smallexample
###############################################################
# DIOP Global Settings

# Preference level for DIOP
#polyorb.binding_data.diop.preference=0

# DIOP's default address
#polyorb.protocols.diop.default_addr=127.0.0.1

# DIOP's default port
#polyorb.protocols.diop.default_port=12345

# Default GIOP/DIOP Version
#polyorb.protocols.diop.giop.default_version.major=1
#polyorb.protocols.diop.giop.default_version.minor=2

###############################################################
# DIOP 1.2 specific parameters

# Set to True to enable DIOP 1.2
#polyorb.protocols.diop.giop.1.2.enable=true

# Maximum message size
#polyorb.protocols.diop.giop.1.2.max_message_size=1000

###############################################################
# DIOP 1.1 specific parameters

# Set to True to enable DIOP 1.1
#polyorb.protocols.diop.giop.1.1.enable=true

# Maximum message size
#polyorb.protocols.diop.giop.1.1.max_message_size=1000

###############################################################
# DIOP 1.0 specific parameters

# Set to True to enable DIOP 1.0
#polyorb.protocols.diop.giop.1.0.enable=true
@end smallexample

@c -------------------------------------------------------------------
@node MIOP Configuration Parameters
@subsection MIOP Configuration Parameters
@c -------------------------------------------------------------------

@c check consistency with polyorb.conf

@smallexample
###############################################################################
# MIOP parameters
#

[miop]

###############################################################
# MIOP Global Settings

# Preference level for MIOP
#polyorb.binding_data.uipmc.preference=0

# Maximum message size
#polyorb.miop.max_message_size=6000

# Time To Leave parameter
#polyorb.miop.ttl=15

# Multicast address to use
# These two parameters must be set explicitly, no default value is provided.
# If either parameter is unset, the MIOP access point is disabled.
#polyorb.miop.multicast_addr=<group-ip-address>
#polyorb.miop.multicast_port=<port-number>

# Set to True to enable MIOP
#polyorb.protocols.miop.giop.1.2.enable=false

# Maximum message size
#polyorb.protocols.miop.giop.1.2.max_message_size=1000
@end smallexample

@c -------------------------------------------------------------------
@node Code sets
@section Code sets
@cindex Code sets, GIOP
@c -------------------------------------------------------------------

@noindent
This sections details the various steps required to add support
for new character code sets to PolyORB's GIOP personality. Please
refer to the CORBA specifications (@cite{[OMG04]}), par. 13.10 for more
details on this topic.

@menu
* Supported code sets::
* Incompatibility in code set support::
* Adding support for new code sets::
* Character data Converter::
* Converters factories::
* Registering new code sets::
@end menu


@c -------------------------------------------------------------------
@node Supported code sets
@subsection Supported code sets
@c -------------------------------------------------------------------

@noindent
PolyORB supports the following list of code sets:

@enumerate
@item Available char data code sets:
@enumerate
@item 16#00010001#   ISO 8859-1:1987; Latin Alphabet No. 1
@item 16#05010001#   X/Open UTF-8; UCS Transformation Format 8 (UTF-8)
@end enumerate
@item Available wchar data code sets:
@enumerate
@item 16#00010100#   ISO/IEC 10646-1:1993; UCS-2, Level 1
@item 16#00010109#   ISO/IEC 10646-1:1993; UTF-16, UCS Transformation Format 16-bit form
@end enumerate
@end enumerate

@c -------------------------------------------------------------------
@node Incompatibility in code set support
@subsection Incompatibility in code set support
@c -------------------------------------------------------------------

@noindent
Some ORBs report incompatiblity in code sets because fallback
converters are not explicitly present in the reference.
To work around this issue, you may use the following parameters:

@smallexample
[giop]
giop.add_char_fallback_code_set=true
giop.add_wchar_fallback_code_set=true
@end smallexample

@c -------------------------------------------------------------------
@node Adding support for new code sets
@subsection Adding support for new code sets
@c -------------------------------------------------------------------

PolyORB allows users to extend the set of supported native character
code sets. Adding support for new character code set consists of the
following steps:

@enumerate
@item Developing sets of Converters - special objects that do
marshalling/unmarshalling operations of character data. At least two
Converters are required: for direct marshalling character data in
native code set and for marshalling/unmarshalling character data in
fallback character code set (UTF-8 for char data and UTF-16 for wchar
data). Additional Converters may be developed for marshalling character
data in conversion code set.

@item Developing converter factory subprogram for each Converter.

@item Registering native code set, its native and fallback converters
and optional conversion char sets and its converters.
@end enumerate

@c -------------------------------------------------------------------
@node Character data Converter
@subsection Character data Converter
@c -------------------------------------------------------------------

Character data converters do direct marshalling/unmarshalling of
character data (char or wchar - depending on @code{Converter})
into/from PolyORB's buffer. This allows to minimize the speed penalty on
character data marshalling.

Character data Converters for char data have the following API (from
@file{PolyORB.GIOP_P.Code_Sets.Converters} package:

@smallexample
   type Converter is abstract tagged private;

   procedure Marshall
     (C      : Converter;
      Buffer : access Buffers.Buffer_Type;
      Data   : Types.Char;
      Error  : in out Errors.Error_Container)
      is abstract;

   procedure Marshall
     (C      : Converter;
      Buffer : access Buffers.Buffer_Type;
      Data   : Types.String;
      Error  : in out Errors.Error_Container)
      is abstract;

   procedure Unmarshall
     (C      : Converter;
      Buffer : access Buffers.Buffer_Type;
      Data   :    out Types.Char;
      Error  : in out Errors.Error_Container)
      is abstract;

   procedure Unmarshall
     (C      : Converter;
      Buffer : access Buffers.Buffer_Type;
      Data   :    out Types.String;
      Error  : in out Errors.Error_Container)
      is abstract;
@end smallexample

The Marshall subprograms do marshalling of one character or string of
characters into the buffer. The Unmarshall subprograms do unmarshalling
of one character or string of characters from the buffer.

@i{Note: Depending on the item size of the data (char/wchar) and GIOP
version, marshalling/unmarshalling algorithms may vary. In some
situations marshalling of string is not equivalent to marshalling its
length and marshalling one by one each character. Please refere to GIOP
specifications for more details.}

If marshalling/unmarshalling fails, subprograms must set the Error
parameter to the corresponding error, usually @code{Data_Conversion_E}.

@i{Note: We recommend to always use the Data_Conversion_E error code
with Minor status 1.}

All @code{Converters} (native, fallback and conversion) have similar
APIs.  Wchar data converters differ only in parameter type.

@c -------------------------------------------------------------------
@node Converters factories
@subsection Converters factories
@c -------------------------------------------------------------------

To create new converters, PolyORB uses special factory subprograms
with the following profile:

@smallexample
   function Factory return Converter_Access;
@end smallexample

or

@smallexample
   function Factory return Wide_Converter_Access;
@end smallexample

This function must allocate a new @code{Converter} and initialize its state.

@c -------------------------------------------------------------------
@node Registering new code sets
@subsection Registering new code sets
@c -------------------------------------------------------------------

Registering new native character data code sets begins from
registering new native character data code sets and its native and
fallback @code{Converters}. This is done using
@code{Register_Native_Code_Set}:

@smallexample
   procedure Register_Native_Code_Set
     (Code_Set : Code_Set_Id;
      Native   : Converter_Factory;
      Fallback : Converter_Factory);
@end smallexample

or

@smallexample
   procedure Register_Native_Code_Set
     (Code_Set : Code_Set_Id;
      Native   : Wide_Converter_Factory;
      Fallback : Wide_Converter_Factory);
@end smallexample

If you have additional conversion code sets Converters you may
register it by calling Register_Conversion_Code_Set subprogram:

@smallexample
   procedure Register_Conversion_Code_Set
     (Native     : Code_Set_Id;
      Conversion : Code_Set_Id;
      Factory    : Converter_Factory);
@end smallexample

or

@smallexample
   procedure Register_Conversion_Code_Set
     (Native     : Code_Set_Id;
      Conversion : Code_Set_Id;
      Factory    : Wide_Converter_Factory);
@end smallexample

Note: because of incompatibility in the support of code sets
negotiation in some ORB's it is recommend to recognize two boolean
PolyORB's parameters:

@smallexample
[giop]
giop.add_char_fallback_code_set=false
giop.add_wchar_fallback_code_set=false
@end smallexample

and also register a fallback Converter as conversion Converter if the
corresponding parameter is set to True.

Finally, define your preferred native character data code sets by
parameters (only integer code sets codes now supported):

@smallexample
[giop]
giop.native_char_code_set=16#00010001#
giop.native_wchar_code_set=16#00010100#
@end smallexample

@c -------------------------------------------------------------------
@node SOAP
@chapter SOAP
@cindex SOAP
@c -------------------------------------------------------------------

@menu
* Installing SOAP protocol personality::
* Configuring the SOAP personality::
@end menu

@c -------------------------------------------------------------------
@node Installing SOAP protocol personality
@section Installing SOAP protocol personality
@c -------------------------------------------------------------------

@noindent
Ensure PolyORB has been configured and then compiled with the SOAP
protocol personality. See @ref{Building an application with PolyORB}
for more details on how to check installed personalities.

To enable configuration of the SOAP application personality,
@pxref{Installation}.

@c -------------------------------------------------------------------
@node Configuring the SOAP personality
@section Configuring the SOAP personality
@c -------------------------------------------------------------------

@noindent
The SOAP personality is configured using a configuration
file. See @ref{Using a configuration file} for more details.

Here is a summary of available parameters for each instance of SOAP.

@smallexample
###############################################################################
# SOAP parameters
#

[soap]

###############################################################
# SOAP Global Settings

# Preference level for SOAP
#polyorb.binding_data.soap.preference=0

# SOAP's default address
#polyorb.protocols.soap.default_addr=127.0.0.1

# SOAP's default port
#polyorb.protocols.soap.default_port=8080
@end smallexample

@c -------------------------------------------------------------------
@node Tools
@chapter Tools
@c -------------------------------------------------------------------

@menu
* po_catref::
* po_dumpir::
* po_names::
@end menu

@c -------------------------------------------------------------------
@node po_catref
@section @command{po_catref}
@cindex @command{po_catref}
@c -------------------------------------------------------------------

@noindent
@command{po_catref} is a utility for viewing the components of a
stringified reference (CORBA IOR, corbaloc or URI). The reference's
components include references to access an object through multiple
protocols (e.g. CORBA IIOP, SOAP) and configuration parameters
associated with a reference (e.g. GIOP Service Contexts).

@smallexample
Usage:
       po_catref <stringified reference>
@end smallexample

@noindent
@i{Note: @command{po_catref} can only process protocols PolyORB has
been configured with.}

@c -------------------------------------------------------------------
@node po_dumpir
@section @command{po_dumpir}
@cindex @command{po_dumpir}
@c -------------------------------------------------------------------

@noindent
@command{po_dumpir} is a utility for viewing the content of an
instance of the CORBA Interface Repository.

@smallexample
Usage:
       po_dumpir <stringified reference>
@end smallexample

@noindent
@i{Note: @command{po_dumpir} will be compiled and installed only if
the CORBA personality and the @file{ir} service is compiled. Please
see @ref{Building an application with PolyORB} for more details on how
to set up PolyORB.}

@c -------------------------------------------------------------------
@node po_names
@section @command{po_names}
@cindex @command{po_names}
@c -------------------------------------------------------------------

@noindent
@command{po_names} is a stand-alone name server. It has an interface
similar to CORBA COS Naming, without dragging in any dependencies on
CORBA mechanisms. This name server is to be used when the CORBA
application personality is not required, e.g. with the DSA or MOMA
application personalities.

@c -------------------------------------------------------------------
@node Performance considerations
@appendix Performance considerations
@c -------------------------------------------------------------------

@noindent
This section discusses performance when using PolyORB. Many elements
can be configured, @xref{Building an application with PolyORB}.
By carefully selecting them, you can increase the
throughput of your application.

We review some parameters that can impact performance.

@itemize @bullet
@item @b{Build options}:
@itemize @bullet
@item For production use, you should not build PolyORB with debug
activated.
@end itemize

@item @b{Tasking policies}:
@itemize @bullet
@item You should carefully select the tasking policy to reduce
dynamic ressource allocation (tasks, entry points,
etc.). @xref{Tasking model in PolyORB}.
@end itemize

@item @b{Transport parameters}:
@itemize @bullet
@item Setting @code{tcp.nodelay} to false will disable Nagle buffering.
@end itemize

@item @b{GIOP parameters}:
@itemize @bullet
@item Setting
@code{polyorb.protocols.iiop.giop.1.X.locate_then_request}, where
@code{X} is the GIOP version in use, to false will disable
@code{Locate_Message}, reducing the number of requests exchanged,

@item Increasing
@code{polyorb.protocols.iiop.giop.1.X.max_message_size}, where
@code{X} is the GIOP version in use, will reduce GIOP fragmentation,
reducing middleware processing.
@end itemize
@end itemize

@c -------------------------------------------------------------------
@node Conformance to standards
@appendix Conformance to standards
@c -------------------------------------------------------------------

@menu
* CORBA standards conformance::
* RT-CORBA standards conformance::
* CSIv2 standards conformance::
* CORBA-GIOP standards conformance::
* SOAP standards conformance::
@end menu

@c -------------------------------------------------------------------
@node CORBA standards conformance
@section CORBA standards conformance
@c -------------------------------------------------------------------

@noindent
The OMG defines a CORBA-compliant ORB as an implementation of the CORBA
specifications that supports CORBA Core and one mapping of CORBA's IDL.

Here is a summary of PolyORB's conformance issues with the latest CORBA
specifications (revision 3.0, formal/02-06-01)

@menu
* CORBA IDL-to-Ada mapping::
* CORBA Core::
* CORBA Interoperability::
* CORBA Interworking::
* CORBA Quality Of Service::
* CORBA COS Services::
* CORBA Specialized services::
@end menu

@c -------------------------------------------------------------------
@node CORBA IDL-to-Ada mapping
@subsection CORBA IDL-to-Ada mapping
@cindex CORBA IDL-to-Ada mapping
@c -------------------------------------------------------------------

@noindent
PolyORB supports the IDL-to-Ada specification @cite{[OMG01]}, with the
following limitations in both the CORBA API and the IDL-to-Ada compiler
@code{idlac}:

@itemize @bullet
@item no support for abstract interfaces, object-by-value, context data;
@item no support for CORBA Components;
@item implemented API may present some divergences with current mapping.
@end itemize

@i{Note: generated code is constrained by the limitations of the Ada
compiler used. Please refer to its documentation for more
information.}

Conforming to documentation requirements from section 4.11 of the
IDL-to-Ada specification @cite{[OMG01]}, note that PolyORB's
implementation of CORBA is @i{tasking-safe}. The use of the CORBA
personality on typical GNAT runtimes is @i{task-blocking}, unless
specified in platform notes.

@c -------------------------------------------------------------------
@node CORBA Core
@subsection CORBA Core
@c -------------------------------------------------------------------

@noindent
This set encompasses chapters 1-11. Chapters 3 to 11 are normative.

@itemize @bullet
@item Chapter 3 describes OMG IDL syntax and semantics. See @ref{CORBA
IDL-to-Ada mapping} for a description of non-implemented features;

@item Chapter 4 describes the ORB Interface.

@noindent
PolyORB partially supports this chapter.

@c XXX TO BE EXPANDED, note there are some differences between ORB Core and
@c IDL-to-Ada mapping !}

@item Chapter 5 describes Value Type Semantics.

@noindent
PolyORB does not support this chapter.

@item Chapter 6 describes Abstract Interface Semantics.

@noindent
PolyORB does not support this chapter.

@item Chapter 7 describes Dynamic Invocation Interface (DII)

@noindent
PolyORB supports only the following methods: @code{Create_Request},
@code{Invoke} and @code{Delete}.

@item Chapter 8 describes Dynamic Skeleton Interface (DSI)

@noindent
PolyORB partially supports this chapter: this interface is fully
implemented except for context data.

@item Chapter 9 describes Dynamic Management of Any Values

@noindent
PolyORB partially supports this chapter: this interface is fully
implemented except for object references and value types.

@item Chapter 10 describes The Interface Repository

@noindent
PolyORB supports this chapter, except for the @code{ExtValueDef}
interface, and all CORBA CCM related interfaces.

@item Chapter 11 describes The Portable Object Adapter

@noindent
PolyORB supports this chapter with the following limitations:
@itemize @bullet
@item the @code{USE_SERVANT_MANAGER} policy is partially supported: the
@code{ServantLocator} object is not implemented;
@item support for @code{SINGLE_THREAD} policy is incomplete, reentrant
calls may not work;
@item @code{Wait_For_Completion} and @code{Etherealize_Objects} are
not taken into account in @code{PortableServer.POAManager};
@item @code{PortableServer.POAManagerFactory} API is not implemented.
@end itemize

@end itemize

@c -------------------------------------------------------------------
@node CORBA Interoperability
@subsection CORBA Interoperability
@c -------------------------------------------------------------------

@noindent
This set encompasses chapters 12-16.

@itemize @bullet

@item See @ref{CORBA-GIOP standards conformance} for more information
on this point.

@end itemize

@c -------------------------------------------------------------------
@node CORBA Interworking
@subsection CORBA Interworking
@c -------------------------------------------------------------------

@noindent
This set encompasses chapters 17-21.

@itemize @bullet

@item Chapters 17 to 20 describe interoperability with Microsoft's
COM/DCOM.

@noindent
PolyORB provides no support for these chapters.


@item Chapter 21 describes @code{PortableInterceptor}.

@noindent
PolyORB provides partial support for this chapter.


@end itemize


@c -------------------------------------------------------------------
@node CORBA Quality Of Service
@subsection CORBA Quality Of Service
@c -------------------------------------------------------------------

@noindent
This set encompasses chapters 22-24.


@itemize @bullet

@item Chapter 22 describes CORBA Messaging

@item Chapter 23 describes Fault Tolerant CORBA

@item Chapter 24 describes Secure Interoperability.

@end itemize

@noindent
PolyORB provides no support for these chapters.

@c -------------------------------------------------------------------
@node CORBA COS Services
@subsection CORBA COS Services
@cindex CORBA, COS Services
@c -------------------------------------------------------------------

@noindent
COS Services are specifications of high level services that are
optional extensions to the CORBA specification. They provide helper
packages to build distributed applications.  PolyORB implement the
following COS Services:

@c XXX should indicate version for each COS

@itemize @bullet
@item COS Event and TypedEvent;
@item COS Naming;
@item COS Notification;
@item COS Time;
@end itemize

@c -------------------------------------------------------------------
@node CORBA Specialized services
@subsection CORBA Specialized services
@cindex CORBA, Specialized services
@c -------------------------------------------------------------------

@noindent
PolyORB supports the following specialized services:

@itemize @bullet
@item Unreliable Multicast (MIOP), proposed 1.0 specification @cite{[OMG02b]}.
@cindex MIOP

@item RT-CORBA extensions, see @ref{RT-CORBA} for more information
on this point.

@item CORBA security extensions, see @cite{[OMG]} for more information
on this point.

@end itemize

@c -------------------------------------------------------------------
@node RT-CORBA standards conformance
@section RT-CORBA standards conformance
@c -------------------------------------------------------------------

@noindent
RT-CORBA specifications rely on the CORBA application
personality; the same issues and implementations notes apply.

In addition, here is a list of issues with the implementation of
RT-CORBA static @cite{[OMG02a]} and dynamic scheduling @cite{[OMG03]}
specifications.

@itemize @bullet
@item RT-CORBA static and dynamic scheduling (Chapter 2)

Chapter 2 is common to these two specifications. It describes
key mechanisms of RT-CORBA that are common to both specifications.

PolyORB partially implements this chapter from section 2.1 up to
section 2.10. PolyORB does not provide support for all
connection-related policies.

See implementation notes in the different package specifications for
more details.

@item RT-CORBA static scheduling (Chapter 3)

PolyORB supports this chapter.

@item RT-CORBA dynamic scheduling (Chapter 3)

PolyORB does not support this chapter.

@end itemize

@c -------------------------------------------------------------------
@node CSIv2 standards conformance
@section CSIv2 standards conformance
@c -------------------------------------------------------------------

@noindent
PolyORB supports IIOP/SSL.

@c -------------------------------------------------------------------
@node CORBA-GIOP standards conformance
@section CORBA/GIOP standards conformance
@c -------------------------------------------------------------------

@noindent
GIOP supports part of the CORBA Interoperability specification, from
chapters 12 to 16 of CORBA specifications.

Chapter 12 defines general concepts about ORB interoperability. It
defines an @emph{interoperbility-compliant ORB} as an ORB that supports:

@itemize @bullet
@item API that supports the construction of request-level inter-ORB
bridges, Dynamic Invocation Interface, Dynamic Skeleton Interface and
the object identity operations described in the Interface
Repository. See @ref{CORBA standards conformance} for more details.

@item IIOP protocol as defined in chapter 15.
@end itemize

@noindent
Support for other components is optional.

@itemize @bullet

@item Chapter 13 describes the ORB Interoperability Architecture.

PolyORB fully supports this chapter.

@item Chapter 14 describes how to build Inter-ORB Bridges.

PolyORB fully supports this chapter.

@item Chapter 15 describes the General Inter-ORB Protocol (GIOP).

PolyORB supports GIOP version 1.0 to 1.2, the CDR representation scheme.
Support for IOR and @code{corbaloc} addressing mechanisms is supported
in the CORBA personality, see @ref{CORBA} for more details.

PolyORB does not support the optional IIOP IOR Profile Components,
Bi-directional GIOP. PolyORB also does not support fragmentation
in GIOP 1.1.

@item Chapter 16 describes the DCE ESIOP protocol.

PolyORB does not support this optional chapter.

@end itemize

@c XXX SSLIOP

@c -------------------------------------------------------------------
@node SOAP standards conformance
@section SOAP standards conformance
@c -------------------------------------------------------------------

@noindent
@i{The documentation of the SOAP standards conformance of PolyORB will
appear in a future revision of PolyORB.}


@c -------------------------------------------------------------------
@node References
@appendix References
@c -------------------------------------------------------------------

@enumerate

@include polyorb_ug_ref.texi

@end enumerate

@c -------------------------------------------------------------------
@node Index
@unnumbered Index
@c -------------------------------------------------------------------

@printindex cp

@bye