%% -*- mode: LaTeX -*-
%%
%% Copyright (c) 1997, 1998, 1999 The University of Utah and the Computer
%% Systems Laboratory at the University of Utah (CSL).
%%
%% This file is part of Flick, the Flexible IDL Compiler Kit.
%%
%% Flick is free software; you can redistribute it and/or modify it under the
%% terms of the GNU General Public License as published by the Free Software
%% Foundation; either version 2 of the License, or (at your option) any later
%% version.
%%
%% Flick is distributed in the hope that it will be useful, but WITHOUT ANY
%% WARRANTY; without even the implied warranty of MERCHANTABILITY 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 along with
%% Flick; see the file COPYING.  If not, write to the Free Software Foundation,
%% 59 Temple Place #330, Boston, MA 02111, USA.
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The IIOP runtime is a \emph{very minimal} ORB-like system, implementing only
the functions that are required to implement basic client/server communication.
The current runtime should be sufficient, however, to allow Flick-generated
stubs to communicate with any other implementation of IIOP, including programs
running on top of other ORBs.
%
The following sections describe how to use Flick's IIOP runtime.  A complete
application based on the IIOP runtime is described in Section~\ref{sec:The
CORBA Phonebook in C}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Server Command Line Options}
\label{subsec:Server Command Line Options}

When an IIOP server starts, the Flick-generated \cfunction{main} function calls
\cfunction{CORBA_ORB_init} to initialize the IIOP runtime and start the ORB\@.
Flick's runtime searches for and processes the following command line
arguments:

\begin{optionlist}
  \item[-ORBipaddr~\optionarg{ipaddress}]
  %
  (Optional.)  Specify the network interface for the server.  This option is
  useful if your machine has multiple network interfaces.  If unspecified, the
  server will use the host's primary network interface.

  \item[-ORBid~\optionarg{name}]
  %
  (Optional.)  Use \optionarg{name} as the server's ORB identifier; see Section
  14.26.1 of the CORBA~2.0 specification.  This option is generally not used.
  The default ORB identifier is ``FlickORB-{}-''.
  %
  % Old text, apparently no longer true, removed for Flick 1.1 release ---
  %
  % if you specify a different name, then client programs will need to take
  % special steps in order to create object references (because
  % \cfunction{CORBA_ORB_string_to_object} won't be able to create object
  % references by itself).  See Section~\ref{subsec:Creating Object References}
  % below for details.

  \item[-OAport~\optionarg{portnumber}]
  %
  (Required.)  Specify the port that the server will use.  There is no default
  value; the port number must be explicitly given on the command line.

  \item[-OAid~\optionarg{name}]
  %
  (Optional.)  Use \optionarg{name} as the server's BOA (Basic Object Adapter)
  identifier; see Section~14.26.2 of the CORBA~2.0 specification.  Like
  \option{-ORBid}, this option is rarely used.  The default BOA identifier is
  ``FlickBOA-{}-''.
  %
  % Old text, apparently no longer true, removed for Flick 1.1 release ---
  %
  % and if you specify a different value, then client programs will need to
  % take special steps in order to create object references.
\end{optionlist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Creating Object Implementations}
\label{subsec:Creating Object Implementations}

After initializing the ORB and the BOA (done for you by the Flick-generated
\cfunction{main} function), a server must create one or more object
implementations (object instances) that will be available to service client
requests.  These implementations are created by a function called
\cfunction{register_objects} which you must write as part of your server's
application code.  The prototype for this function is:

\begin{verbatim}
   void register_objects(CORBA_ORB, CORBA_BOA, int argc, char **argv,
                         CORBA_Environment *);
\end{verbatim}

\noindent The \cfunction{main} function generated by Flick will call your
version of \cfunction{register_objects} in order to initialize your server's
objects.  In general, your \cfunction{register_objects} function should parse
the given command line in order to create its objects.  Your function should
call \cfunction{CORBA_BOA_create} to create each of its object
instances:\footnote{Flick's version of \cfunction{CORBA_BOA_create} differs
slightly from what is specified by Section~8.2 of the CORBA~2.0
specification.  This will eventually be fixed, probably by updating the runtime
to conform to the newer Portable Object Adapter (POA) specification.}

\begin{verbatim}
   CORBA_Object CORBA_BOA_create(CORBA_BOA boa,
                                 CORBA_ReferenceData *obj_key,
                                 const char *obj_type, FLICK_SERVER obj_impl,
                                 CORBA_Environment *ev);
\end{verbatim}

\noindent The first argument should be the \ctype{CORBA_BOA} that was passed to
your \cfunction{register_objects} function.  The second argument is a pointer
to an octet sequence that names the new object instance.  This name must be
unique across all object instances.  As is usual, the sequence is described by
a C structure containing three fields: \cidentifier{_buffer},
\cidentifier{_length}, and \cidentifier{_maximum}.  The third argument is a
string that identifies the type (class) of the object; this string may be in
any format you choose.  (Flick does not parse the object type string; Flick
uses the string only when creating and parsing object references.)  The fourth
argument to \cfunction{CORBA_BOA_create} is a pointer to the Flick-generated
dispatch function for the object interface; as far as Flick's IIOP runtime is
concerned, this is what determines the object's class.  The name of the server
dispatch function is usually the name of the interface concatenated with the
suffix ``\cfunction{_server}''.  The fifth and final argument is a pointer to a
\ctype{CORBA_Environment}; your \cfunction{register_objects} function should
check the environment after each call to \cfunction{CORBA_BOA_create} to see if
an error has occurred.

It is useful for your \cfunction{register_objects} function to create any
additional data structures that your server will need in order to represent its
objects.  For instance, the phonebook application in Section~\ref{sec:The CORBA
Phonebook in C} creates a list of structures to represent its phonebooks; each
structure is keyed by a \ctype{CORBA_ReferenceData} and contains the data for a
single phonebook object.  The server work functions later use
\cfunction{CORBA_BOA_get_id} to locate the data for a phonebook object, mapping
from a CORBA object reference to the object's \ctype{CORBA_ReferenceData}, and
then using that name to locate the phonebook object's data.

Your \cfunction{register_objects} function should raise an exception if it is
unable to initialize your server's objects.  If no exception is raised, then
the Flick-generated \cfunction{main} server function will begin to process
requests on the registered objects.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Creating Object References}
\label{subsec:Creating Object References}

A client can create an object reference with the following function:

\begin{verbatim}
   CORBA_Object CORBA_ORB_string_to_object(CORBA_ORB orb, CORBA_char *name,
                                           CORBA_Environment *ev);
\end{verbatim}

The name can be either a stringified Interoperable Object Reference (IOR) or a
URL-style name of the form
``\option{iiop:1.0//\emph{hostname}:\emph{port}/\emph{objecttype}/\emph{objectname}}''.\footnote{The
idea for URL-style object references was adopted from SunSoft's reference IIOP
implementation, which is available at
\urlftp{ftp://ftp.omg.org/pub/interop/iiop.tar.Z}.  Flick's URL-style
references differ from those supported by the SunSoft IIOP implementation in
that Flick's references include the object type.}  The latter form is generally
preferred because it is easier to type.  Whenever a Flick-based server creates
an object instance, the server prints both the IOR and URL-style name of the
new object.

Alternately, a client can create an object reference by going through the
following steps:

\begin{enumerate}
  \item Initialize an ORB, using \cfunction{CORBA_ORB_init}.

  \item Create a BOA, using \cfunction{CORBA_ORB_BOA_init}.

  \item Create the object reference by calling \cfunction{CORBA_BOA_create}
  with the appropriate \ctype{CORBA_ReferenceData} (key) value.
\end{enumerate}

This procedure will find the corresponding object instance within the given ORB
and create an appropriate object reference.  Of course,
\cfunction{CORBA_ORB_string_to_object} is generally simpler for clients to use.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Using Object References}
\label{subsec:Using Object References}

Once a client has obtained an object reference, it may use the reference to
invoke operations on the object as defined by the object's IDL interface.
Flick's IIOP runtime provides these additional functions for manipulating
object references:

{\footnotesize
\begin{list}{}{}
  \item%
    {\cprototype{CORBA_char *CORBA_ORB_object_to_string(CORBA_ORB, CORBA_Object, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Create and return a stringified Interoperable Object Reference (IOR).

  \item%
    {\cprototype{CORBA_char *CORBA_ORB_object_to_readable_string(CORBA_ORB, CORBA_Object, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Create and return a human-readable, URL-style stringified object reference.
  (This is not a standard CORBA function.)

  \item%
    {\cprototype{CORBA_Object CORBA_ORB_string_to_object(CORBA_ORB, CORBA_char *, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Create and return an object reference from a stringified object reference
  (IOR or URL).

  \item%
    {\cprototype{CORBA_ReferenceData *CORBA_BOA_get_id(CORBA_BOA, CORBA_Object, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Return the corresponding key for the given object reference.

  \item%
    {\cprototype{CORBA_boolean CORBA_Object_is_nil(CORBA_Object, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Return true if the object reference is nil.

  \item%
    {\cprototype{CORBA_Object CORBA_Object_duplicate(CORBA_Object, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Duplicate an object reference.

  \item%
    {\cprototype{void CORBA_Object_release(CORBA_Object, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Release an object reference.

  \item%
    {\cprototype{CORBA_unsigned_long CORBA_Object_hash(CORBA_Object, CORBA_unsigned_long, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Return a value suitable for use in a hash table.  The value is not guaranteed
  unique, but good enough to implement an efficient hash table with the number
  of buckets indicated by the second argument.

  \item%
    {\cprototype{CORBA_boolean CORBA_Object_is_equivalent(CORBA_Object, CORBA_Object, CORBA_Environment *);}}%
    \hspace{0pt}\\
  Return true if the two object references refer to the same object instance.
\end{list}
}% End `\footnotesize'.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% End of file.

