This version of IBM OpenDoc implements level 1.0.4 of OpenDoc (as provided by Apple) across the Windows NT, Windows 95, OS/2, and AIX platforms.
This readme file discusses the functions, prerequisites, and installation instructions for this release. For the latest information and a list of known restrictions, please refer to:
For a description of the things we have changed in this version please refer to:
If you have version 1.0 or earlier of OpenDoc installed on your OS/2 platform, review this file carefully, especially the "Migrating From Prior OS/2 Versions of OpenDoc" and "Installing OpenDoc on OS/2" sections. Following those instructions ensure that your installation is not corrupted.
Also, certain files provided with OS/2, the OS/2 Developer Toolkit, or IBM Visual Age C++ for OS/2 must be updated. These System Object Model (SOM) executables and Presentation Manager (PM) header files are included with this edition of OpenDoc and are applied during installation of this edition of OpenDoc. These files contain the latest available corrective service.
Three packages are provided, organized by operating system environment:
For Windows NT, Windows 95, or OS/2, you need to download the Install Facility files plus one other set of files for a minimum installation. To install the Development Toolkit or the Samples source, you need the Runtime as well.
For AIX, you need to download the Runtime images for a minimum installation.
In order to successfully work with this edition of OpenDoc, you need hardware and software meeting the criteria listed below. Unless otherwise noted, these criteria are required. The prerequisite software must be installed before you install OpenDoc.
Windows | OS/2 | AIX | ||||
NT | 95 | |||||
Hardware | ||||||
Processor (recommended) | Pentium class | Pentium class | Pentium class | Any Power2 or PowerPC | ||
RAM (recommended) | 32 MB | 32 MB | 32 MB | 32 MB | ||
Disk Space Needed | ||||||
during installation | This temporary space can be recovered by deleting the downloaded files after installation completes. | |||||
up to 55 MB | up to 55 MB | up to 25 MB | up to 30 MB | |||
after installation | ||||||
Install | 5 MB | 5 MB | 4 MB | 0 MB | ||
Base | 49 MB | 49 MB | 32 MB | 10 MB | ||
Development Toolkit | 4 MB | 4 MB | 3 MB | 2 MB | ||
Samples | 15 MB | 15 MB | 8 MB | 9 MB | ||
Documentation | 6 MB | 6 MB | 7 MB | 6 MB | ||
Source Code | 11 MB | 11 MB | 8 MB | 6 MB | ||
Software | ||||||
Operating System | Windows NT 3.51 | Windows 95 | OS/2 Warp Connect with
OS/2 Warp FixPak 17 (for OS/2 Warp J, FixPak WX02204) |
AIX 4.1.4 | ||
OS/2 Warp 4.0 | AIX 4.2 | |||||
HTML Browser | HTML 3.0 (tables)-capable browser | |||||
Compiler (if developing parts) | IBM VisualAge C++ for Windows, Version 3.5 or Microsoft Visual C++, Version 4.0 |
IBM VisualAge C++ for OS/2, Version 3.0 |
IBM CSET++ for AIX Compiler, Version 3.1.4 |
IBM OpenDoc, Version 1.2 supports the following functions and more:
The IBM OpenDoc team encourages you to report any problems arising from the execution of the code. Please use the bug report form at:
There are slight differences in the installation procedure depending on your platform. Please see the section below that is specific to your platform.
On Windows NT systems, the user who installs OpenDoc MUST be logged on to a username with System Administrator privileges. If this installation is to support developers who will be building parts, the user who installs OpenDoc must be the same user who installed the compiler, allowing the OpenDoc install facility to correctly set the PATH environment variable.
If you have another version of OpenDoc on your system (or in the partition in which you will be installing this edition if you have a multi-boot system), you will need to remove it prior to installing this version. The following steps are recommended to remove the other version:
Follow the steps below to install OpenDoc on your system:
Use the "File | Save As" menu item from your browser to download each file. If you are using Netscape Navigator, you can use the "Shift-click" method to download the files, that is, hold down the Shift key and click on the file to be downloaded. This causes the file to be downloaded rather than displayed through a viewer.
To remove this edition of OpenDoc, do the following:
The uninstall procedure does not completely remove the changes introduced when OpenDoc was installed. Specifically:
If you have another version of OpenDoc on your system (or in the partition in which you will be installing this edition, if you have a multi-boot system), you will need to remove it prior to installing this version. The IBM OpenDoc team recommends the following steps to remove the other version:
Follow the steps below to install OpenDoc on your system:
Use the "File | Save As" menu item from your browser to download each file. If you are using Netscape Navigator, you can use the "Shift-click" method to download the files, that is, hold down the Shift key and click on the file to be downloaded. This causes the file to be downloaded rather than displayed through a viewer.
To remove this edition of OpenDoc, do the following:
The uninstall procedure does not completely remove the changes introduced when OpenDoc was installed. Specifically:
WARNING: | Installing this edition of OpenDoc includes the application of corrective service to the SOM executables. There is no procedure for removing this corrective service once applied. |
Previously installed products may have set environment variables that need to be unset. Please check the list below for such products:
When you install IBM's Visual Age C++ for OS/2, Version .3.0, it installs other OS/2 products as well. For instance, a version of IBM SOMObjects 2.1 is installed, and a version of the OS/2 Developer's Toolkit is installed.
The installation of IBM Visual Age C++ for OS/2 probably created changes to several important environment variables in your CONFIG.SYS file:
This edition of OpenDoc installs a more current version of parts of the IBM SOMObjects 2.1 runtimes and of the OS/2 include files and lib files from the OS/2 Developer's Toolkit. It will attempt to update or correct the environment variables shown above. In general, after installing OpenDoc, you will no longer need references to %CPPMAIN%\include\OS2 in your make files or in the INCLUDE environment variables. You will no longer need references to %CPPMAIN%\lib\OS2 in your makefile or in the LIB environment variables.
The SOM include files and SOM runtimes are part of the code
installed with this version of OpenDoc. They are more current
than what was shipped in the 3.0 version of the IBM Visual Age C++
for OS/2 product or in its CSDs.
You will need to remove references to any
%CPPMAIN%\*\SOM
directories from your PATH
or LIBPATH
environment variables.
Be careful to observe the above ordering of files.
The installation of IBM SOMObjects 2.1 for OS/2 probably created changes to several important environment variables in your CONFIG.SYS file:
This edition of OpenDoc installs more current versions of parts of the IBM SOMObjects 2.1 runtimes and OS/2 include files and lib files from the OS/2 Developer's Toolkit. It attempts to update or correct the environment variables shown above. In general, after installing OpenDoc, you no longer need references to %SOMBASE%\include\ in your make files or in the INCLUDE environment variables. In addition, you no longer need references to %SOMBASE%\lib\ in your makefile or in the LIB environment variables.
Remove any references to paths that start with the
directory named by %SOMBASE%
from your LIBPATH and
PATH statements before you begin to install this version of OpenDoc.
The installation of an IBM OS/2 Developer Toolkit probably created changes to several important environment variables in your CONFIG.SYS file:
This edition of OpenDoc installs more current versions of parts of the IBM SOMObjects 2.1 runtimes and OS/2 include files and lib files from the OS/2 Developer's Toolkit. It attempts to update or correct the environment variables shown above. In general, after installing OpenDoc, you no longer need references to the include Toolkit directory in your make files or in the INCLUDE environment variables. In addition, you no longer need references to the lib Toolkit directory in your makefile or in the LIB environment variables.
Examine any references to paths that start with the directory named by the Toolkit in your LIBPATH and PATH statements, before you begin to install this version of OpenDoc. You do not need any SOM or OS/2 header or lib information from the Toolkit.
The OpenDoc for OS/2 folder and the Uninstall OpenDoc icon will remain following the uninstall procedure. They can be manually deleted.
If a previous version is installed, do the following:
Alternately, you may uninstall the previous version by following the uninstall instructions provided with that version. We have observed some problems in the behavior of the current version of OpenDoc (such as corruption of the .ir file) due to the incomplete removal of the prior version. The procedure described above does not avoid these problems, but preserves the capability to revert to the prior version easily.
Follow the steps below to install OpenDoc on your system:
Use the "File | Save As" menu item from your browser to download each file. If you are using Netscape Navigator, you can use the "Shift-click" method to download the files, that is, hold down the Shift key and click on the file to be downloaded. This causes the file to be downloaded rather than displayed through a viewer.
To remove this edition of OpenDoc, do the following:
The uninstall procedure removes all of OpenDoc's files, except for files related to parts. These files may be manually deleted.
If you renamed the directories related to the previous version of OpenDoc according to the instructions in the "Disable Any Previous Versions of OpenDoc" section, you may restore the previous version. To do so, do the following:
WARNING: | Installing this edition of OpenDoc includes the application of corrective service to the SOM executables. |
NOTE: | If you have version 1.1 of OpenDoc there is no need to remove it. You may install version 1.2 on top of it. |
Use the "File | Save As" menu item from your browser to download each file. If you are using Netscape Navigator, you can use the "Shift-click" method to download the files, that is, hold down the Shift key and click on the file to be downloaded. This causes the file to be downloaded rather than displayed through a viewer.
Please note that OpenDoc message files are only shipped in the primary code page associated with the lowercase locale name (i.e. xx_YY not Xx_YY). locale name.
To complete the setup of IBM OpenDoc for a particular user, do the following:
Use the "File | Save As" menu item from your browser to download each file. If you are using Netscape Navigator, you can use the "Shift-click" method to download the files, that is, hold down the Shift key and click on the file to be downloaded. This causes the file to be downloaded rather than displayed through a viewer.
Please note that OpenDoc message files are only shipped in the primary code page associated with the lowercase locale name (i.e. xx_YY not Xx_YY). locale name.
To complete the setup of IBM OpenDoc for a particular user, do the following:
To remove this edition of OpenDoc from your AIX 4.1.4 system, do the following:
To remove this edition of OpenDoc from your AIX 4.2 system, do the following:
For either version of AIX, follow these steps to clean up each user's workspace:
This file is created when a user double-clicks on the Install IBM Parts icon. This file remembers certain environment settings which will persist into any subsequent installation of IBM OpenDoc unless the user deletes the file.
Do not delete these directories if they contain files that you wish to keep.
You can access the books for IBM OpenDoc, Version 1.2, by pointing your HTML browser at the doc\en_US\index.htm file under the base OpenDoc directory (that is, the directory specified in the ODBASE environment variable). From this file, you will be able to link to the OpenDoc Programming Guide, OpenDoc Programming Reference, and OpenDoc Problem Determination Guide documents.
To create a new empty document, open the IBM OpenDoc folder and double-click on the OpenDoc icon. Alternately, issue the following command:
docshell
Note: On Windows 95, you must run the odsetenv.bat command file to set the environment properly before launching the docshell command from the command prompt.
The OpenDoc Root Part Selection dialog box displays with a list of part kinds from which you can select the part kind for the root part of the new OpenDoc document. Select one of the available part kinds and click on the OK button. The following part kinds are provided with this edition:
Part Kind Name | Description |
IBM Base Container | A basic container part without any content data of its own. |
Frame List | A synonym for Base Container. |
Link Container | A container part with linking. |
OLE Part (*) |
The part editor that handles embedded OLE objects.
Typically, this part editor is not run as a root part. It is embedded in some other root part to allow an OLE server object to be embedded. |
Scriptable Graph Part (*) | A scriptable container part that demonstrates creation of shapes. |
Shape Part (+) | An irregularly-shaped leaf part. |
Simple Part | A leaf part. |
Text Part (+) | A container part that supports importing and exporting of text. |
Timer (*) | A utility part used by scripting. |
(*) denotes part kinds supported only on Windows NT and Windows 95.
(+) denotes part kinds supported only on Windows NT, Windows 95, and OS/2. |
The following part kinds are provided but are not registered by default. You may register a part by dropping its .odz file onto the Part Editor Install icon in the IBM OpenDoc folder. The .odz files may be found in the pkg directory pointed to by the ODBASE environment variable.
Part Kind Name | Description |
Clock (+) | A running analog clock. |
Dynamic Part (+) | A leaf part that demonstrates dynamic updates, even when the part is not active. |
Graphics Part (+) | A container part that demonstrates creation of shapes. |
Java Part (*) |
A part that allows Java applets or Java Beans to be embedded into
OpenDoc containers.
Before this part is installed and registered, a Java runtime must be installed. |
Page Layout (+) | A container part demonstrating pagination and printing. |
Scriptable Base Container (*) | A container part supporting direct scripting. |
Scriptable Simple Part (*) | A simple leaf part supporting direct scripting. |
Scriptable Simple 1 (*) | An alternate version of Scriptable Simple Part. |
Scriptable Simple 2 (*) | An alternate version of Scriptable Simple Part. |
(*) denotes part kinds supported only on Windows NT and Windows 95.
(+) denotes part kinds supported only on Windows NT, Windows 95, and OS/2. |
You may register additional part kinds if you provide additional part editors. Watch Club OpenDoc for more part editors.
We provide several additional part editors as samples. These part editors may be found in subdirectories underneath the src directory under the directory pointed to by the ODSRC environment variable. These additional part editors are:
Additional Part Kind Name | Description |
Bitmap (*) | A leaf part that displays bitmaps. |
Card Game (*) | A container part for playing poker or blackjack. |
CDPlayer (*) | A leaf part that controls the playing of compact disks. |
ClockPartKind (#) | A leaf part which provides a clock widget. |
Mandelbrot (*) | A leaf part that displays Mandelbrot sets. |
PianoPart (*) | A container part that plays .wav files. |
PushButtonPartKind (#) | A leaf part which provides a push button widget. |
StaffPart (*) | A container part that composes files that may be played using PianoPart part editor. |
TextPartKind (#) | A leaf part which provides a text widget. |
TickerPartKind (#) | A leaf part that scrolls a text banner across the part facet. |
T3GamePart (*) | A container part for playing a 3D Tic-Tac-Toe game. |
(*) denotes part kinds supported only on Windows NT and Windows 95.
(+) denotes part kinds supported only on Windows NT, Windows 95, and OS/2. (#) denotes part kinds supported only on AIX. |
To load an existing document, issue the following command line command:
docshell -f file_name
Where file_name is the name of the OpenDoc document file containing the document you want to load.
On Windows 95, OS/2, and AIX, stationery in the "Stationery" subfolder may be used to create document parts. Open the folder and drag one of the stationery icons to an open document. This action opens the part editor for the type of stationery dropped into the document.
Prior to building the sample parts provided in this edition, please note the following:
Before installing and registering a part enabled for OLE Scripting, be sure to log on with System Administrator privileges.
Run odsomxh.cmd before building any of the sample parts provided with this edition. Failure to run this command could result in the use of incompatible header files.
Run odmkSampleTree to create a writeable copy of the samples source tree. This copy will be placed where the environment variable $ODSRC points.
Run /usr/lpp/som/somxh before building any of the sample parts provided with this edition.
The make files provided with the samples demonstrate how to explicitly specify the path to the proper version of the header files, negating the need to have the SMINCLUDE and INCLUDE environment variables set.
The sample makefiles are all named "makefile" to conform to the "nmake" default makefile name. The OpenDoc sample makefile system, provides recursive subdirectory walking macro which relies on the makefile name being "makefile" in each subdirectory to be traversed. Keep this in mind if you plan to add samples to the existing list of OpenDoc.
If you install the IBM VisualAge C++ for OS/2 compiler or the OS/2 Developer's Toolkit after installing OpenDoc, these environment variables must be manually unset by adding the following lines to the end of your CONFIG.SYS file:
SET SMINCLUDE= SET INCLUDE=
For Windows NT or Windows 95, association of stationery icons with your newly-build part editor must be done manually.
To improve your ability to understand this edition as well as to assist in your debugging, the source code is included with this edition. The bulk of the files are provided, but files necessary to actually build the binaries are excluded. In a typical installation the source code files are in the directory %ODBASE%\SRC. A complete list of source files which exist on your system after successful installation is available in the file %ODBASE%\SRC\SRCFILES.LST.
The license agreement stipulates that you only use the source code for debugging and education. Be wary about exploiting side effects that you discover in the source code, because the IBM OpenDoc team may change the code in future editions.
If you have been using version 1.0 or earlier of OpenDoc on OS/2, you will find that parts compiled for the earlier version will not run on this version, due to changes in interfaces and linkage. You need to obtain recompiled versions of parts before they will work with this version of OpenDoc.
If you have been developing parts on version 1.0 or earlier of OpenDoc on OS/2, you will notice some differences in this release. The interfaces are equivalent, with minor changes to achieve better consistency across different platforms. To better understand the changes, consult the OpenDoc Programming Reference manual available in softcopy with this edition.
You may also notice differences in behavior of some of the part editors. The IBM OpenDoc team has rewritten the BaseContainer part editor to achieve better consistency across platforms. Parts that subclass from BaseContainer may also display these differences.