omniORB on OpenVMS platforms
============================

This file contains information on building omniORB on OpenVMS (Alpha and
and VAX) platforms.

Changes in 3.0.0 prerelease
---------------------------

New requirements
................

At least OpenVMS version 7.1 is now required.  OpenVMS VAX and Compaq C++ 5.6
are still supported but Compaq C++ 6.2 is recommended (available only on Alpha).

Note that if you need to use Compaq C++ 5.6 you will need to apply the
dec_cxx_5_6.patch located in the [patches] directory.  A good port of patch for
OpenVMS resides at: ftp.sidhe.org/VMSPerl_Community/non-perl_utils.

Anyone wishing to port to OpenVMS 6.x is encouraged to try.  See the file,
readme.openvms_v6.

Python for OpenVMS must be installed prior to building the distribution. The
minimum version is 1.5.2-V007b.

The following python logical names are used:

	Logical name	Definition
	---------------	-------------------------------------------------
	python_include	pyvms_disk:[python.python-1_5_2.include]
	python_olb	pyvms_disk:[python.python-1_5_2.vms.o_'platform']

Note that release builds will utilize object libraries built with python
configured for noDEBUG and THREADS (python_olb:*_d0t.olb) and vice versa (debug
builds require python_olb:*_ddt.olb).

DEC C must be installed.  This distibution has been tested with:

	DEC C V5.7-004 on OpenVMS Alpha V7.1-2
	DEC C V5.6-003 on OpenVMS VAX V7.1

Other versions of DEC/Compaq C may be possible, but note that VAX C will not
work.

It is now required that an additional concealed, rooted logical name
(`your-name' in this paragraph) be defined. This logical name must be defined so
that the file that you are now reading resides in your-name:[000000]. In order
to build the entire tree, set default to your-name:[src] and type "make export".
Note that `your-name' is user-selectable.  You might wish to use something that
indicates the omniORB version (e.g., omniORB300root).  This logical name will
need to be available for debugging.  The remainder of this document assumes
that the default device is `your-name:'.

New features
............

The omniORB for OpenVMS developement environment has been largely redesigned
with the goals of making it easier to maintain.

It is no longer necessary to invoke make /macro=(initialize_mms=1) to prepare a
source directory for building.  The makefile system will now invoke a premake
step in order to create the necessary dependency files.

Module dependency files now have the extension `.d', rather than `.mms'.

An autoconfig feature has been added that will automatically determine compiler,
hardware, and operating system version.  The results are written to
[mk]platform.mms.  This feature is enabled by default (autoconfig=1 in
[config]config.mms).  To reconfigure, perform a veryclean build of the entire
directory tree.  Afterwards, the file [mk]dirs.mms should be empty. 

$(TOP) is no longer defined.  It is assumed that [000000] is "top".
$(EXPORT_TREE) and $(IMPORT_TREES) are no longer defined by default.  Thus they
may be defined in other sub-trees such as directories containing contributed
software.

The format of the descrip.mms file has changed.  In addition to removing the
definition of $(TOP), it now defines current as a "_" seperated list of
directory names.

C++ files that need to be compiled should be listed in the MMS macro CXXSRCS
which is a space seperated list.  (CXXSRCS_x, x=0 to 9 are also available due to
VMS draconian limits.)

Macros no longer should be quoted and should appear in a space seperated list. 
However, to pass an actual quote character, the quote should be quadrupled.  For
example,

	DIR_CXXMACROS=tcpSocketVaxRoutines\
		CONFIG_DEFAULT_LOCATION=""""omniCFG:omniORB.cfg""""

Caveats
.......

The premake step now invokes `MMS/macro=dir.mms...'.  This qualifier is somewhat
broken, in that it apparently recognizes only "-" as the continuation character
and ignores .IFDEF statements.  Thus:

	.IFDEF FOO
	BAR=x
	.ELSE
	BAR=y
	.ENDIF

must be rewritten:

	.IFDEF FOO
	FOOBAR=x
	.ELSE
	NOFOOBAR=y
	.ENDIF
	BAR=$(FOOBAR)$(NOFOOBAR)

if it resides in a dir.mms file.

Shareable images are now supported for all platforms.  It is intended that
future versions will be "upwards compatable" (see the OpenVMS LINK manual) but
the mechanism for ensuring this is under development.

Changes in 2.8.0
----------------

To simplify linking, seperate omniORB floating point libraries are no longer
required.

There are additional configuration parameters in [config]config.mms.

Downloading the distribution
----------------------------

Refer to http://www.uk.research.att.com/omniORB/VMSDownload.html for
downloading and unpacking the distribution.


Building the distribution
-------------------------

This distribution requires the use of MMS, although it should be possible to use
the freely available MMK with minor changes (please contact visschb@rjrt.com if
you do this).  It has been tested on Compaq C++ 6.2 for OpenVMS Alpha 7.1-2, and
DEC C++ 5.6 for OpenVMS VAX 7.1.  Some version of TCPIP Services (formerly known
as UCX) is also required.  Has not been tested with other transports such as
multinet.

The MMS files assume the use of the MMS /Skip qualifier.  You should define a
"make" symbol as follows:

	$ make=="mms/skip"

Define a concealed rooted logical so that this file resides in its [000000]
directory.  Set default to the [src] directory.  E.g., supposing that this file
resides in dua0:[omni.omniorb_300]:

	$ define /trans=conc omniORB300root dua0:[omni.omniorb_300.]
	$ set default omniORB300root:[src]

Before starting the build, you should review configuration settings by editing
the file [config]config.mms.

You should now be ready to build. Just type 'make export'.

To build debug versions of the library and/or executables, type:

	$ make/macro=(debug=1)

This will create libraries and executables with a "d" suffix.  For example,
omniORB3d.olb.

Setting up your environment
---------------------------

If your operating system is 6.2 or above, you should add the directory:
myroot:[bin.platform] to the logical name DCL$PATH (where platform is
openvms_{alpha|vax}_(6|7)_{1|2} and myroot:[000000] is the directory containing
the file you are reading).  DCL$PATH should be defined as a search list logical.

If your operating system is 6.1 or below, you should define each of the
executables in that directory as foreign commands.  E.g.:

	$ omniidl2=="mydisk:[myroot.bin.openvms_vax_6_1]omniidl2.exe"

You will also need to define the logical OMNICFG to point to an existing
directory for name service configuration information.  The omniNames server
will use this directory.

You will need to create a file called "omnicfg:omniorb.cfg" to contain the
nameservice IOR as described in the omniORB3 documentation.  The file
should contain:

ORBInitialHost <omninames-host-name>
ORBInitialPort <omninames-port-number>

Once you have created this file, you should startup the omniNames server as a
detached process.  This should be added to your system startup procedure.

Building omniORB3 applications
-----------------------------

Include directories
...................

With OpenVMS 7.1 and above you can use a single logical name (e.g.,
omni_include) to point to the [include] directory.  You can then compile with
/include=("./", "/omni_include") and the compiler should find the others.

With OpenVMS 6.x you may need to define some additional logicals:

	$ define <qualifiers> omniORB3 myroot:[include.omniORB3]
	$ define <qualifiers> omniVms myroot:[include.omniVms]
	$ define <qualifiers> omnithread myroot:[include.omnithread]

To link against the omniORB3 libraries, you should define the following logical
name:

	$ define <qualifiers> omnilib mydisk:[myroot.lib.platform]

With the above definitions in place, you should add
/include=("./","/omni_include")/exceptions to your CXX compiles.

The logical name omnilib is used as a convenience for the cxxlink command line.

To link against the shareable images, you should use the omnilib:omni_share.olb
(or omnilib:omni_shared.olb) library.  To run the resulting executable, you will
need to redefine sys$share.  E.g.,

	$ define sys$share omnilib,sys$library

Alternatively, you can define a logical name for each of the shareable images
contained in omni_shre.olb:

	$ define omnithread_rt omnilib:omnithread_rt.exe
	$ define omniORB3_rt omnilib:omniORB3_rt.exe
	...

You may wish to use or adapt the development environment provided in the DCL 
and MMS files contained in [etc]openvms.zip to accomplish the above.

Floating point support
----------------------

The CORBA standard mandates that an implementation should use the IEEE standard
for floating point types (CORBA::Float and CORBA::Double).  Since native IEEE
floating point is not available on the VAX platform and to provide additional
flexibility for the Alpha platform, these types are proxy types.

The omniORB3 for VMS development environment provides for different floating
point formats by allowing one of:

	make /macro=(D_FLOAT=1)
	make /macro=(G_FLOAT=1)
	make /macro=(IEEE_FLOAT=1)

to explicitly build for D, G, or IEEE floating point support.  The default is
G_Float and D_FLOAT on Alpha and VAX, respectively (consistent with the CXX
default).  You do not need to supply these qualifiers when building the
distribution.

Building the examples
=====================

You are strongly encouraged to try out the examples provided in
[src.examples]. Go into [src.examples] and type 'make all' (where make is
defined as above).

Study the documentations in [doc] (in the omniORB distribution) before
you run any of the example programs.

Documentation
=============

You must read the omniORB3 and the OMNI naming service user guides. Follow
the instructions in the guides to complete the configuration process.

Performance
===========

omniORB is implemented using synchronous socket calls in threads rather than
asynchronous socket calls.  Thus, performance of omniORB relies heavily on the
ability of the O/S to perform I/Os that block only the thread of execution
(rather than the whole process) pending I/O completion.

Alpha
-----

For OpenVMS Alpha platforms, the best way to acheive this behavior is to use
link with /Thread=upcalls.  This requires at least 7.1 of OpenVMS.  Ideally, you
should upgrade (if necessary) to 7.1 or 7.2 and use /Thread=upcalls.  If for
some reason you cannot upgrade the O/S you can use the tcpSocketVaxRoutines.cc
enhancement below.

VAX
---

The OpenVMS VAX platform (effectively) ignores the /Thread=upcalls (at least as
of 7.2).  Therefore you should use the tcpSocketVaxRoutines.cc enhancement
below. However, since this enhancement relies on a DEC CRTL 7.0 feature, it
requires using the backport libraries on versions of VMS prior to 7.1. 
Therefore, upgrading to at least OpenVMS 7.1 is advised.

tcpSocketVaxRoutines.cc
-----------------------

The file [etc]openvms.zip file contains the source file tcpSocketVaxRoutines.cc.
Inclusion of this module into the omniORB object library is controled by the MMS
macro, useTcpSocketVaxRoutines.  This macro is automatically set if the platform
is OpenVMS VAX 7.x.