The

6 files changed, 856 insertions, 0 deletions

diff --git a/TAO/docs/BUILDING b/TAO/docs/BUILDING
new file mode 100644
index 00000000000..d37985de743
--- /dev/null
+++ b/TAO/docs/BUILDING
@@ -0,0 +1,122 @@
+@(#)BUILDING	1.2 95/09/13
+
+[ THIS HAS NOT YET BEEN UPDATED for the new source tree ... ]
+
+
+HOW TO BUILD AND TEST THIS SOFTWARE
+-----------------------------------
+This software uses uses an autoconfiguration script to provide portability
+to a wide variety of UNIX-like platforms, since not all platforms adhere
+closely to such standards as X/Open UNIX.  On Microsoft operating systems,
+you will need to create one or more compiler-specific project files (for
+the library, and each program using it) based on the Makefile included
+with the distribution, and with a "getopt()" implementation from somewhere
+other than this software distribution.
+
+These directions assume that your source directory is the same as your
+build directory.  For some suggestions about configuring trees when this
+is not the appropriate source tree layout (e.g. one source tree shared
+among multiple build directories, with different OS/CPU/compiler platforms
+used in each build directory), see the file "IMPLEMENTATION".
+
+On UNIX, or UNIX-like systems, type the following commands to your shell
+(here assumed to have a prompt of "% ").  Your output should look something
+like this; your performance will differ, reflecting varying CPU speeds and
+same-host TCP overheads:
+
+	% ./configure
+	creating cache ./config.cache
+	... you'll see lots of other output
+	% make check
+	CC -g -DDEBUG   -c  cdr.cc
+	...
+	testing non-polling server with oneway and null calls
+	20 call non-polling loop timings:
+	oneway hello avg time	= 0.130ms,	7692 calls/second
+	null call avg time	= 0.525ms,	1904 calls/second
+
+	testing with 'cube' calls, stub + DII, IOR strings
+	cube average call time	= 1.031ms, 	969 calls/second
+	1000 calls, 0 errors
+
+	testing request forwarding with 'cube' calls, stub + DII
+	cube average call time	= 1.032ms, 	968 calls/second
+	1000 calls, 0 errors
+
+	testing transmission of primitive data types
+	test1_clnt:  100 loops, 3100 tests (0 errors)
+
+	testing echo of primitive data values
+	echo_clnt:  15 tests (0 errors)
+
+	%
+
+With some older versions of "make", you may need to modify the Makefile
+to get the build to work correctly.  Current versions of GNU make are a
+simple fix, should you encounter this problem, and have other advantages.
+
+If you forget the separate "configure" step above, there is a chance
+that the code will compile and run yet be incorrect.  For example, the
+native byte order might be configured wrongly, and you wouldn't be
+able to tell.  You can run "configure" again at any time, if you want
+to be sure that the software had been configured correctly.  (You may
+want to "make distclean" just in case, to make sure configurations do
+not get inappropriately cached or intermixed.)
+
+You can issue a "configure -help" command to get a summary of the many
+options the configure script accepts.
+
+After you have gotten the software to compile and pass the single-machine
+sanity test of "make check", you may want to try inter-machine testing
+using these programs.  (Several teams have done this to verify that their
+independent IIOP implementations interoperate with this code.)  Read the
+"TESTS" file for further information about how to do such testing using
+the command line interface to these test programs.
+
+
+COMPILER AND OPERATING SYSTEM PLATFORMS
+---------------------------------------
+This software has been compiled using these C++ compilers:
+
+    - SunSoft SPARCworks (for SPARC) 3.0.1 (C++ 4.0.1)
+    - SunSoft PROcompiler (for x86 and PowerPC) 3.0.1 (C++ 4.0.1)
+    - Borland C++ (BC++) 4.5
+    - GNU C++ (G++) 2.6.3 and 2.7.0
+    - Microsoft Visual C++ (VC++) 2.0/2.1 (for x86)
+
+Compilers not listed above often have problems such as poor support for
+standard C++ class nesting or templates, preventing their use with this
+source code.  If you get lots of compiler errors, this may well be the
+root cause of your problem.  Consider switching to a newer compiler; GNU
+C++ is free, and recent versions work well with this code.  (You may need
+to use the GNU C++ library too; "configure" may require it.)
+
+This software, or a slightly earlier version of it, has been tested on these
+OS platforms; not all compiler/hardware/OS combinations were tested:
+
+    - Solaris 2.4 and later; SPARC, Intel, PowerPC platforms.
+    - SunOS 4.1, on SPARC
+    - Linux (1.1.47 and later) on 486 hardware.
+    - NEXTSTEP 3.2 on 486 hardware. (1)
+    - Windows NT Workstation 3.5 on 486 hardware. (2)
+    - HP/UX 9.01 on HP9000/7xx (PA RISC)
+    - HP/UX 8.00 on HP9000/3xx (m68k CPU)
+    - OSF/1 v3.0 on DEC Alpha
+    - Ultrix 4.2 on DECstation
+    - SINIX 5.42 on Siemens/Nixdorf RM400
+
+    (1) NEXTSTEP normally includes an "old" compiler, GCC version 2.5.8, which
+    has a number of serious bugs in its C++ support.  To use this on NeXT
+    systems, you will need a more recent comiler, such as GCC 2.6.3 or 2.7.0.
+
+    (2) On Windows NT, standard "getopt" command line parsing is not part
+    of the operating system's standard libraries.  To use the included test
+    programs, you will need to provide getopt, perhaps the GNU getopt.  FTP
+    sites from which the GNU getopt is available include prep.ai.mit.edu and
+    (a mirror) ftp.uu.net; it's part of the GNU C library and other GNU
+    distributions.
+
+This code hasn't recently been tested on Windows 3.1, but it should be easy
+to make it work there again.  If you make this code run on other operating
+systems, such as OS/2 or MacOS, please consider sending your changes to the
+contact point (above) so that your changes can be part of later versions.
diff --git a/TAO/docs/DIFFERENCES b/TAO/docs/DIFFERENCES
new file mode 100644
index 00000000000..0a8dd343d4d
--- /dev/null
+++ b/TAO/docs/DIFFERENCES
@@ -0,0 +1,360 @@
+@(#)DIFFERENCES	1.1 95/09/13
+
+[ NOTE that the CORBA 2.0 specifications have now been published, but are
+not yet sufficiently available that this document can usefully just list
+any differences between that specification and this software.  As a rule,
+there are no differences between this software and CORBA 2.0 in areas
+where CORBA 2.0 has specified an interface. ]
+
+
+This document summarizes known differences between what is implemented in
+this software and currently available OMG specifications.  As a rule, these
+establish compatibility with revised specifications that are currently being
+prepared for publication. However, in some cases the differences resolve
+problems that are currently being addressed by ORB taskforces.  When those
+revised CORBA specifications are published, this document will be updated to
+reflect any remaining differences from them.
+
+The reason for those changes is that different specifications were adopted
+at the same time and there were in some cases subtle differences which need
+to be resolved.  Minor errata have also been fixed.  None of these changes
+are substantial, with the exception of the TypeCode interpreter API which
+was added to the C++ mapping.
+
+Also, note that the goal of this software is fidelity to the IIOP, so that
+issues relating (in particular) to the C++ language mapping or other OMG
+specifications were judged to be of less importance at this time.
+
+
+DIFFERENCES from IIOP in UNO Spec (95-3-10)
+-------------------------------------------
+Some changes to the original specification (94-9-32) for the IIOP protocol
+were found to be necessary; most related to the subsequently adopted Interface
+Repository (IFR) specification (94-11-7).  Others resulted from correction
+of minor editorial errors, and experience gained as multiple teams implement
+to that specification.
+
+The bulk of those changes have been incorporated into the 95-3-10 document,
+but these few have not.
+
+
+CDR TYPECODE INDIRECTION
+
+An additional constraint on the use of typecode indirection has been
+identified.  Specifically, the typecode to which an indirection points
+be "self-sufficient", and may not point "outside of itself" for any
+further indirections.  For example, always indirections occur within
+encapsulations, so it's OK for the indirection to point anywhere in
+that encapsulation, or at the encoded TCKind enum value immediately
+before the encapsulation's length.  For typecode encapsulations nested
+inside other typecode encapsulations, the indirection may point no
+further than the outermost encapsulation.
+
+Also, when an indirection points to another typecode, the byte order
+of that other typecode must be deduced from the encoded value found
+there.  This is straightforward for encoded TCKind values, all of which
+fit into a single byte:  if the first byte of the word is zero, then
+the encoding is big-endian, else it's little-endian.
+
+Indirecting to another indirection is not allowed, since the byte order
+of the encoded offset can't consistently be deduced.
+
+
+MISCELLANY
+
+The type GIOP::Version is assumed to be identical to IIOP::Version.
+As part of the editorial separation of GIOP from its Internet version
+IIOP, this typedef was accidentally omitted.
+
+This implementation of IIOP supports the OMG-IDL Primitive Data Types as
+defined in Appendix A of 94-9-32, but with TCKind numbers following the new
+tk_exception and tk_alias codes.  (That is, rather than using range 21-25,
+these TCKind values are in the range 23-27.)
+
+These data types are currently the topic of an RFP in process in the OMG,
+and are not currently defined as part of a current OMG specification. 
+Clients and servers using these extended data types are relying on CORBA
+extensions that are not yet standardized; and should be prepared to change.
+
+
+CORBA 2.0/CORE Differences
+--------------------------
+As of this writing, the new CORBA 2.0/CORE document has not yet been made
+available.  This is a modification of the CORBA 1.2 document, with the
+addition of (mandatory) extensions from the UNO (94-9-32) specification:
+notably DSI and some new object reference operations.  This summarizes
+differences between the as-yet-unpublished CORBA 2.0/CORE document and
+the original text in the UNO specification.
+
+
+DYNAMIC SKELETON INTERFACE
+
+Since the new "tk_except" typecodes now include the exception ID (this is
+the repository ID describing the exception's type) the "exception" operation
+used to report an exception through a ServerRequest no longer includes the
+exception ID.
+
+Since the OperationDef entries for attributes are no longer found in the
+interface repositories, the ServerRequest convenience operation to return
+this has been removed.  Application programs (such as bridges) must compare
+the operation name string with the prefixes "_get_" and "_set_" to see if
+any given operation applies to an attribute.  If an operation is one of the
+two for which an OMG-IDL "attribute" declaration is shorthand, then the
+application must search the interface repository for that attribute.
+
+(There are in fact three categories of operations on which an object adapter
+and implementation collaborate to handle:  user defined operations, user
+defined attributes, and operations defined by CORBA such as "is_a" and
+"get_implementation".  Some object adapters, like the BOA, handle this last
+category directly, rather than exposing it to applications.)
+
+The "non_existent" objref operation accidentally used attribute syntax; this
+has been corrected.  All operations on CORBA::Object references now use
+normal operation syntax in their (pseudo) IDL definitions, and are uniformly
+prefixed with underscores as part of their C++ mapping.
+
+
+DIFFERENCES from IDL C++ Mapping (94-9-14)
+------------------------------------------
+There are four basic ways in which the IIOP framework does not comply
+with the OMG's IDL C++ mapping specification, beyond the use of the CORBA2
+module/namespace rather than the CORBA module/namespace.  (CORBA2 is used
+so that this software can be linked with existing ORBs, which should be
+using the CORBA module/namespace already.)
+
+These ways are beyond the portability-derived use of the "class" construct
+(instead of the C++ namespace construct), and the use of CORBA2::Environment
+(rather than C++ exceptions), both of which are accomodated by the mapping:
+
+    (1) This framework does not attempt to be complete.
+    
+	Completeness is not required to implement the Internet IOP,
+	so time was not spent in providing a complete mapping.
+
+    (2) In some cases the API provided is not the one in the mapping.
+	For example CORBA2::Environment is not always passed in all
+	operations.  This was done to promote ease of implementation
+	and coding.
+
+    (3) Implementation details are generally exposed.
+
+	This isn't so much a noncompliance issue (it's not specified
+	that such details must be hidden) as an issue of allowing
+	noncompliant applications.  The effort required to actively
+	prevent use of implementation details by higher level code
+	would be nontrivial, and could slow down IIOP code, so no
+	time was applied to hiding such details.
+
+	(However, note that when the software was modified to use COM,
+	standard C++ techniques were used to hide most such details.)
+
+    (4) The C++ mapping needs completion in some areas.
+
+	Notably, 94-9-14 does not satisfy requirements to provide
+	support for for all data types in an "Any" or exception without
+	needing any precompiled data type support routines.  The
+	TypeCode interpreter addresses this issue.
+
+	Some additional operations were not adopted at the time 94-9-14
+	was defined; both 94-9-32 and 94-11-7 added new ORB interfaces
+	which are not found in the initial C++ mapping document.
+
+With respect to this fourth issue, descriptions of the API extensions
+used is provided later in this file.  The additional CORBA operations
+are not described since their mapping is straightforward if it isn't given
+in those documents.
+
+
+ACCESS TO ALL DATA IN "ANY" AND EXCEPTIONS
+
+The "void *" value in an "Any", and any "CORBA2::Exception *" value, may
+always be passed to the TypeCode interpreter (see next).  This allows access
+to all data held within an "Any" and an Exception.  The "void *" value in an
+Any with an exception TypeCode is of type CORBA2::Exception *".  Due to
+the way CORBA is specified, it is not possible to tell whether an "Any"
+holding an exception denotes a user or standard (system-defined) exception
+except by exhaustive comparison against exception IDs.
+
+Also, _all_ legal OMG-IDL data types may be held in an "Any", and may be
+manipulated using the TypeCode interpreter.  This satisfies a language
+mapping requirement that DII (and DSI) be able to manipulate all OMG-IDL
+data types without requiring compiler generated support for them.
+
+
+TYPECODE INTERPRETER
+
+In any given C/C++ execution environment there is a binary standard for how
+data is represented.  While that standard will differ between execution
+environments, there are a very limited number of ways in which those
+representations differ.  Those differences are encapsulated only in the
+TypeCode interpreter, so that portable applications using the dynamic
+typing infrastructure in the ORB can completely ignore how it's done in
+any particular environment.
+
+The APIs in this software distribution have been suggested for adoption as
+part of the OMG specification suite.  The two APIs are nonstatic member
+functions in the C++ mapping's TypeCode pseudo-object, and are augmented
+by a single new enumeration type.
+
+    unsigned long	size() 
+
+	This returns the size of an instance of the type that is
+	described by the TypeCode.
+	
+	For example, when invoked on the typecode constant CORBA::_tc_Short,
+	the value returned is sizeof(CORBA::Short); and when invoked on the
+	typecode for a structure, it is the size of that structure (including
+	any internal and tail padding needed).  When invoked on a sequence
+	typecode, it returns a value that does not include the size for
+	any embedded buffer.
+    
+    enum traverse_status {TRAVERSE_STOP, TRAVERSE_CONTINUE };
+	
+	This is a data type used in the traverse() member function.
+	It allows data type traversal to be terminated early for
+	non-exceptional conditions, and eliminates the confusion
+	that some similar APIs have created when they use a single
+	boolean value (does TRUE mean to stop, or to continue?).
+
+    traverse_status	traverse (
+			    const void	*value1;
+			    const void	*value2
+			    traverse_status	visit (
+				    TypeCode_ptr	tc,
+				    const void		*visit_value1,
+				    const void		*visit_value2,
+				    void		*visit_context
+				),
+			    void	*context
+			);
+
+	(In the current language mapping, CORBA2::Environment references
+	are passed as the final parameter to the 'traverse' and 'visit'
+	routines for use when reporting exceptions.)
+
+	The pointers "value1" and "value2" point to instances of the
+	data type described by the typecode (or are null pointers).
+
+	For each constituent of that data type (e.g. structure member)
+	the visit() routine is called once.   The constituent's type
+	is described by "tc"; "visit_value1" points to the constituent
+	of that type in "value1" (assuming the traverse routine was
+	not passed a null pointer) and similarly for "visit_value2".
+	The "visit_context" parameter is the context parameter passed
+	to the traverse() routine, and can point to whatever data is
+	needed by the visit() routine.
+
+	Members are traversed in first-to-last order, as defined in the
+	IDL specification for the data type.  So for example, the
+	visit routine for a structure could print out each element
+	on a IO stream passed through the context parameter, perhaps in
+	a neatly formatted form intended for human consumption.
+
+	The visit() function may choose to recursively traverse() each
+	element.  So for example if "tc->kind()" in a visit routine
+	returned CORBA::tk_struct, the contents of that struct would
+	be ignored unless the visit routine invoked traverse() using
+	the typecode and values passed to it.
+
+	If the visit() routine returns TRAVERSE_CONTINUE, succeeding
+	constituents of the data type are visited in turn; if it
+	returns TRAVERSE_STOP, the traverse() routine returns that
+	value to its caller.  Of course, if a visit() routine calls
+	traverse() itself, it may choose to ignore TRAVERSE_STOP.
+
+The traverse() routine is a powerful tool.  It is used in the IIOP code
+itself in several ways; look at such use for tutorial details.  You could
+implement data value comparison and "debug" data dumping as simple exercises
+in the use of these APIs.
+
+The "marshaling interpreter" (marshal.cc) uses it to encode and decode
+values according to the IIOP protocol specification.  The "Any" code
+(any.cc) uses traverse() both to free embedded pointers, and to make "deep"
+copies of any data structure given its TypeCode.
+
+Only that "deep copy" visit routine uses "value2" as anything other than a
+null pointer; it allows efficient construction of "deep copies" without
+needing extra space for temporary values or coroutine stacks.  (A general
+purpose two-value comparison could also use "value2".)  Most uses of the API
+only manipulate a single data value at a time; no realistic need has yet
+been seen for manipulating more than two data values at once.
+
+With respect to the OMG C and C++ mappings, it is clear that this style API
+must be provided for the C mapping, but some people have noted that a
+"purer" object oriented style API could also be provided in C++.  That style
+would use another internal visit routine, performing the requisite "switch"
+over the fixed number of TCKind values, and then make a virtual function
+call to an instance of a C++ class whose private state was the "context" and
+whose member functions matched the arms of the switch.
+
+
+MEMORY ALLOCATION
+
+In order to dynamically manipulate instances of arbitrary data types,
+applications need to be able to allocate and free memory.  The OMG C++
+mapping only says how to do this for data types which have static C++
+interfaces defined, which is clearly inadequate for using constructed
+types with the DII/DSI/Any family of interfaces.
+
+This infrastructure requires the standard "malloc" and "free" primitives to
+be used, and cast to the appropriate type.  Data allocated using malloc
+will normally be sized according to TypeCode::size(), and then be stored
+inside an Any.  When the Any is deleted, if the ORB deallocates the memory
+it always uses "free" (including for any nested pointers, and correctly
+handling cases such as arrays and sequences).
+
+Note that to support implementations where C and C++ language bindings
+share the same ORB infrastructure, this solution is inadequate.  This is
+because the C binding's CORBA_free() interface would have no way to
+determine the type of the data being freed.  Instead, typed allocation
+APIs will need to be used even when using the dynamically typed CORBA
+subsystem ... a TypeCode::malloc() routine would suffice, if it returned
+memory that was internally tagged with that TypeCode.  In such a case,
+the CORBA_free() routine could use that TypeCode to "deep free" data as
+required, and C++ "new" and "delete" operators would need to know about
+the internal tagging for all those data types.  Such tagged allocation
+would need to be used for all data that was to be freed by the ORB.
+
+(Having the C mapping require use of "typed free" routines, instead of the
+CORBA_free interface, is sufficient to eliminate this problem.)
+
+
+PASSING EXCEPTIONS THROUGH THE DII
+
+The C++ mapping's Dynamic Invocation Interface (DII) has key omissions
+in that it doesn't say how to access to user-defined exception values,
+and implicitly requires ORBs either to pass "excess" data on the wire
+or else to consult an interface repository to deal with exceptions or
+(deprecated) "context" strings.
+
+This software changes the DII specification in two ways to support the
+requirement for DII users to be able to see user-defined exceptions, yet
+not to violate the OMG-IDL type model by reporting illegal exceptions:
+
+    * The Object::_create_request() member function, through which DII
+      users provide all the information included in an IDL operation's
+      signature, has an additional parameter.
+
+      That parameter is a sequence of exception typecodes, describing
+      the user-defined exceptions that the operation can return.  (The
+      standard exceptions defined in CORBA may always be returned.)
+      When any other exception is returned, the client's ORB reports that
+      the object's type definition has been violated by the server's ORB.
+
+    * The TypeCode interpreter (see above) may be used to examine all
+      exception values reported through a CORBA::Environment.  A new
+      Exception::id() operation may be used to determine which typecode
+      should be used.
+
+Note that a number of portability and specification problems have been
+identified in the current C++ mapping for DII, e.g. for details of memory
+management.  Later versions of this code may attempt to closely comply
+with an improved mapping for DII, to the extent that the interpretation
+used here differs from that more unambiguous specification.
+
+Since there is no efficient way to distinguish typecodes for user defined
+exceptions from ones for system-defined ("standard") exceptions (comparing
+the exception ID against all the system defined ones is inefficient :-)
+a new enum type "ExceptionType" is defined.  (An analogous type is already
+defined for the C language mapping.)  This is used to report exceptions
+through DII and DSI.
diff --git a/TAO/docs/HISTORY b/TAO/docs/HISTORY
new file mode 100644
index 00000000000..d97a8e35b2e
--- /dev/null
+++ b/TAO/docs/HISTORY
@@ -0,0 +1,44 @@
+@(#)HISTORY	1.1 95/09/13
+
+Mmmmmmmm DD, 1995 -- RELEASE 1.3:
+---------------------------------
+Release 1.3 includes bugfixes, and support for the COM binary interface
+model, both on UNIX and on MS-Windows platforms.  The source tree has
+been considerably restructured, with the goal of enabling addition of
+other components at both the binary and source levels.
+
+
+September 1, 1995 -- RELEASE 1.2:
+---------------------------------
+Release 1.2 includes fixes for problems noted in the recent multivendor
+interoperability testing at Object World, and as reported by other users on
+the Internet.  The most notable of these is that in some cases, when using
+multiple connections to IIOP servers and clients, the connection management
+code previously would get confused about which connection was which.  (One
+consequence of fixing this is that an old test has been removed.)  Also,
+there was no simple way to use Solaris 2.4 threads; see the Makefile for
+details.  A few other minor features were added to facilitate use of this
+code for more than just protocol testing.
+
+
+June 28, 1995 -- RELEASE 1.1:
+-----------------------------
+Release 1.1 includes support for several new platforms.  Particular thanks
+go to the team at APM, which contributed the bulk of the new "autoconf"
+support (substantially enhancing portability), support for DEC Alpha and
+HP 9000 platforms, runtime initialization of the size and alignment table
+used to drive the typecode interpreter, and more; see README.apm for details.
+
+Release 1.1 includes POSIX.1c threading support; on platforms which provide
+POSIX.1c threads, applications will be able to take advantage of them.
+
+Union and indirection support has been added to the TypeCode interpreter,
+and more typecode utility APIs have been implemented.  Various bugfixes and
+cleanup have also been provided.  Unfinished stubs for the COS Naming service
+are included; these rely on C++ exception support.
+
+
+March 21, 1995 -- RELEASE 1.0:
+------------------------------
+The original release ran on a set of UNIX platforms (including Solaris,
+SunOS, Linux, and NEXTSTEP) as well as with 16-bit and 32-bit MS-Windows.
diff --git a/TAO/docs/README.apm b/TAO/docs/README.apm
new file mode 100644
index 00000000000..e46f894bb2c
--- /dev/null
+++ b/TAO/docs/README.apm
@@ -0,0 +1,83 @@
+This document outlines the changes that have been made at APM by the following
+people:
+
+Owen Rees <rtor@ansa.co.uk>
+Guangxing Li <gxl@ansa.co.uk>
+Mike Beasley <mdrb@ansa.co.uk>
+
+Note that the email address <iiop-impl@ansa.co.uk> will reach everyone at APM
+currently interested in this code.
+
+PLATFORMS
+---------
+
+We have got the software to work on the following platforms, with interworking
+between them, compiling with g++ 2.6.3 on all:
+
+ - HP 9000/7xx running HP-UX 9.01
+ - DEC Alpha running OSF1 3.0
+ - Sun 4 running SunOS 4.1.1
+ - HP 9000/3xx running HP-UX 8.00
+ - DECstation running Ultrix 4.2
+
+The port to Alpha (with 64-bit pointers and longs) has necessitated many
+changes; many occurrences of 'long' and 'unsigned long' have been changed to
+'CORBA2::Long' and 'CORBA2::ULong' respectively.
+
+The mixed endianness has revealed some problems which we have fixed.
+
+We define an appropriate type for pointer arithmetic as ptr_arith_t; the exact
+definition depends on the size of a pointer and of the various unsigned
+integral types.
+
+LONG DOUBLE
+-----------
+
+One of the problems that has been fixed is the handling of the 'long double'
+type. CORBA requires this to be 16 bytes long, whereas g++ on many platforms
+implements long double as double, and on Motorola 68000 series hardware
+(e.g. HP9000/300 series and Sun3) long double is 12 bytes.
+
+Unfortunately IEEE floating point is defined such that floating point numbers
+of different lengths have different exponent sizes (unlike the format used on
+IBM and ICL mainframes). This makes conversion between a CORBA long double and
+a double a little tricky. An implementation using bitfields should be
+available soon, but meanwhile:
+
+1)  If native 'long double' is 16 bytes, use it.
+
+2)  Otherwise define CORBA 'long double' as a structure containing an array of
+    16 unsigned chars.
+
+BOOL
+----
+
+We exploit the builtin 'bool' type when available (g++).
+
+USE OF GNU AUTOCONF
+-------------------
+
+The hardware/OS-dependent ifdefs have been rationalised. If you are running on
+any sort of Unix, just run 'configure' and then make/gmake, and it should all
+build. On non-Unix systems noconfig.h will be included instead of config.h.
+
+EXTRA TEST PROGRAM
+------------------
+
+There is an 'echo' client and server, based on 'test1', where values are
+echoed back rather than being cubed, bitwise inverted or whatever.
+
+There is extra code in 'test1_clnt.cc' to output the results of failing tests.
+
+EXTRA DEBUGGING
+---------------
+
+The function 'dmsg_opaque_full' is added. This will dump a given array of
+unsigned chars in hex and as characters.
+
+6 Jun 1995
+
+Mike Beasley, ICL, ANSA project
+c/o APM, Poseidon House, Castle Park, Cambridge CB3 0RD, UK
+Tel: +44 1223 568931  Fax: +44 1223 359779  Email: mdrb@ansa.co.uk
+
diff --git a/TAO/docs/REFERENCES b/TAO/docs/REFERENCES
new file mode 100644
index 00000000000..a44ef31c16e
--- /dev/null
+++ b/TAO/docs/REFERENCES
@@ -0,0 +1,91 @@
+@(#)REFERENCES	1.2 95/11/08
+
+REFERENCES
+==========
+Most of the relevant references here are to OMG documents, however there
+are a few external references of some note:
+
+    *	http://www.uci.agh.edu.pl/research/cs/TOCOOS/COPERNICUS.html
+
+
+OMG REFERENCES
+--------------
+As of this writing, OMG is in the process of publishing new versions of the
+base CORBA specifications, merging specifications as needed into single
+documents and splitting out the C mapping from the CORBA/CORE specification.
+
+This software has made every effort to track both the base documents and the
+agreed corrections and revisions.  Since those documents have not yet been
+published, there will inevitably be areas in which it does not reflect the
+versions yet to be published.  See the "DIFFERENCES" file for information
+about where this software differs from these current base documents:
+
+* CORBA 2.0/Interoperability:  Universal Networked Objects (UNO), OMG
+  TC Document 95-3-10.  This includes the mandatory IIOP and bridging
+  support, as well as the optional DCE-CIOP protocol.
+
+* CORBA 1.2 specification, OMG TC Document 93-12-43.  This is the
+  base document on which the CORBA 2.0 CORE specifications build.
+
+* Universal Networked Objects (UNO), OMG TC Document 94-9-32.  Until
+  the CORBA 2.0/CORE document is published, replacing the CORBA 1.2,
+  initialisation, and IFR specifications, you must use this earlier
+  version of UNO to see (only!) the specification for DSI and several
+  other CORBA CORE extensions (for bridging) adopted by the OMG.
+  [ NOTE: use the IIOP specification in 95-3-10, not the one here;
+  95-3-10 has changes required by the IFR specification, 95-11-7. ]
+
+* Initialisation, OMG TC Document 94-10-24.  This defines the portable
+  APIs for initialising ORBs.
+
+* Interface Repository, OMG TC Document 94-11-7.  This updates the
+  CORBA specifications above and is referenced by the UNO document.
+
+* IDL C++ Language Mapping Specification, OMG TC Document 94-9-14.
+  This defines the mapping of CORBA 1.2, including OMG-IDL, onto C++.
+
+There are a few inconsistencies between these documents, which are in the
+process of being resolved.  The inconsistencies arose because different
+groups worked on different parts of the system, at different times and
+with some different goals.  Contact the various revision committees to
+find out how these differences are being resolved:
+
+    - interop@omg.org ... the interop revision task force (RTF)
+    - cxx_revision@omg.org ... the C++ RTF
+    - orb_revision@omg.org ... the general ORB RTF
+
+Also, note that these ORB specifications correspond to only the lowest levels
+of OMG's Object Management Architecture.  In particular, the "Object Services"
+define object interfaces for naming, events, persistence, relationships,
+lifecycle, externalization, transactions, and concurrency control.  Also,
+"Common Facilities" objects will address such things as compound document
+architecture.  If you intend to develop software based on ORBs, these
+specifications are likely to be of interest.  The OMA is available in
+technical bookstores:
+    
+    Richard Soley (ed.), Object Management Architecture Guide,
+    Second Edition, John Wiley & Sons, New York, 1992.
+
+
+ACQUIRING REFERENCE DOCUMENTS
+-----------------------------
+To acquire those reference documents, use the OMG document server through
+Internet email.  Send a message to "server@omg.org", with content lines
+such as
+
+    send help
+
+to get directions about how to use the server, or 
+
+    send docs/95-3-10.ps
+
+to get a PostScript copy of any particular document.  (OMG specifications
+are available only in PostScript.)
+
+The OMG document server is maintained for use by OMG members, but is also
+available for general Internet access.  Only members will be supported in
+the case of problems.
+
+To find out more about the OMG, send email to "omg@omg.org", or look
+at the Web page at "http://www.omg.org".
+
diff --git a/TAO/docs/TESTS b/TAO/docs/TESTS
new file mode 100644
index 00000000000..97465f288db
--- /dev/null
+++ b/TAO/docs/TESTS
@@ -0,0 +1,156 @@
+@(#)TESTS	1.1 95/09/13
+
+NOTES ON HOW TO TEST THE IIOP ENGINE
+
+Thus far there aren't many standalone tests and little is automated.  This
+file provides brief notes on how to use the tests that do exist, so you
+can verify various functionality.  It supplements the source code and
+a good test-oriented imagination by only a little bit.
+
+The "make test" target in the Makefile is intended to provide reasonably
+good coverage of this implementation.  If you use this code to debug
+some other implementation you may find it useful to know how to get this
+engine code to act differently ... or find out why it's acting the way it
+does act!.
+
+A useful debugging feature is the "-d" flag; each time it's passed, the
+"debug level" is incremented.  So "-ddd" sets the debug level to three,
+generating more output than "-d".  You get message read/write tracing
+with "-d", and at higher levels you can get dumps of more and more data
+in messages.  In a debugger you can assign directly to "debug_level".
+There's currently no point in setting the level to more than ten.
+
+(The "-d" flag, along with other debugging support in the IIOP library,
+is only available if you compile it "-DDEBUG".)
+
+-----------------------
+CLNT, SVR ... this is a real test of the IIOP protocol and uses TCP to
+connect arbitrary processes.  It exercises the TCP code as well as the
+interpretive marshaling of structures as parameters (and return values).
+There is also a simple test to verify that the DII code works for arbitrary
+structures.
+
+The test also prints out the average time used to do the basic calls (not
+using DII).  Note that on modern CPUs, you will see very strong "cache
+effects" for this code -- much of the IIOP engine code is small enough to
+fit into on-chip caches (or a variety of other system caches) and so the
+numbers reported with large loop counts (guaranteeing maximal caching) will
+be much better than you'd see in typical use of this code (where caches are
+filled with other data, at least initially).
+
+* "svr" ... prints an IOR and listens for for requests to it.  The
+  IDL interface supported by the server is "cubit.idl".
+    
+    % svr > obj &			# default, URL-style strings
+    % cat obj
+    iiop:1.0//argon:5555/key0
+    %
+
+    % svr -o foobar > obj &		# ask for IOR strings instead
+    % cat obj
+    IOR:00000000000000010000000000000001000000000000001800010000000000066172676f6e0015b3000000046b657930
+    %
+
+* "clnt -O that_ior" ... makes some simple requests to the server,
+  cubing numbers of different kinds.
+    
+    % clnt -d -O `cat obj`
+    24584: cube octet:  139 --> 179
+    24584: cube short:  -117 --> -28749
+    24584: cube long:  -117 --> -1601613
+    24584: cube struct ...
+    24584: DII cube_struct ... success!!
+    cube average call time	= 8.441ms, 	118 calls/second
+    4 calls, 0 errors
+    %
+
+    % clnt -dd -O `cat obj`
+    24590: send GIOP v1.0 msg, 66 data bytes, my endian, Request
+    24590: recv GIOP v1.0 msg, 13 data bytes, my endian, Reply
+    24590: send GIOP v1.0 msg, 41 data bytes, my endian, Request
+    24590: recv GIOP v1.0 msg, 13 data bytes, my endian, Reply
+    24590: cube octet:  139 --> 179
+    24590: send GIOP v1.0 msg, 42 data bytes, my endian, Request
+    24590: recv GIOP v1.0 msg, 14 data bytes, my endian, Reply
+    24590: cube short:  -117 --> -28749
+    24590: send GIOP v1.0 msg, 44 data bytes, my endian, Request
+    24590: recv GIOP v1.0 msg, 16 data bytes, my endian, Reply
+    24590: cube long:  -117 --> -1601613
+    24590: send GIOP v1.0 msg, 50 data bytes, my endian, Request
+    24590: recv GIOP v1.0 msg, 22 data bytes, my endian, Reply
+    24590: cube struct ...
+    24590: send GIOP v1.0 msg, 50 data bytes, my endian, Request
+    24590: recv GIOP v1.0 msg, 22 data bytes, my endian, Reply
+    24590: DII cube_struct ... success!!
+    cube average call time	= 19.481ms, 	51 calls/second
+    4 calls, 0 errors
+    %
+
+* If you use the URL style objref, it's easy to substitute different
+  keys for the one "svr" prints, causing the server to send standard
+  OBJECT_NOT_EXIST exceptions back to the client.  (This helps to
+  test system exception marshaling, as well as error reporting!)
+
+* Similarly to give host and port names that don't work, to generate
+  client side COMM_FAILURE exceptions.
+
+* The client and server can be on different systems of course.
+  Also, one server can talk to many clients.
+
+* "clnt -O that_ior -n250 -x" ... does the above, 250 times (total
+  of 1000 calls) and asks "svr" to exit when done
+
+* The server can be set up to forward calls to a child process by
+  passing the "-f" flag to it.  The child is forked and assigned an
+  unused port, and then tells the parent its address.  (This kind of
+  facility is part of what's needed to provide BOA-style activation
+  of new processes as required.)
+
+* The server supports a "-t" option, which controls whether the OA
+  is asked to fork a thread to handle each incoming message.  You
+  won't get any benefit from using that without POSIX.1c threads!
+
+-----------------------
+TEST1_SVR, TEST1_CLNT ... this is a more thorough functional test
+than the "cubit" interface above.  Its goal is to test all of the
+IDL primitive types and parameter passing modes, in operations that
+have multiple parameters in request and response message.
+
+* "test1_svr" ... very like "svr" but supports the interfaces defined
+  in the "test1.idl" file.  Or at least, many of them -- as of this
+  writing the test is incomplete.
+
+* "test1_clnt" ... very like "clnt", but doesn't time the calls.
+
+* There are a few problems that these tests unearth on some platforms,
+  e.g. with "float" comparisons on x86 platforms, or when optimization
+  is enabled in some cases.  It appears these are all test bugs rather
+  than implementation bugs, but in any case if you happen to identify
+  fixes for them that'd be appreciated!
+
+* Not all the tests have been written yet ... notably Any, Principal,
+  and wide character strings.
+
+* Since not all platforms support 128 bit floating point directly, you
+  will need to pass the "-l" flag to "test1_clnt" when doing (manual)
+  network testing between machines where one does support it directly
+  (for example, SPARC and PowerPC) and one doesn't (e.g. x86 platforms).
+  Otherwise, there is a loss of numeric precision which will be reported
+  as test failures.
+  
+  (LongDouble values are passed through bridges without any loss of
+  precision, but if software needs to manipulate the values -- e.g.
+  to perform multiplications as this test does -- it must convert
+  them to "double" and lose both precision and range in the process.
+  Code for such conversions is not currently included.)
+
+-----------------------
+ECHO_SVR, ECHO_CLNT ... this is related to an early version of "test1",
+and uses the same on-the-wire call syntax with different call semantics.
+Where "test1" almost always modifies its input value to create output
+values, "echo" sends back the input data unchanged.
+
+Its point is to simplify debugging some classes of marshaling error which
+may turn up, since the "test1" code tries to ensure different patterns are
+sent.  This makes it harder to diagnose bugs turned up by "test1", although
+it performs a more complete overall test.