Brief guide for installation and use of IOPC persistency system

Installation in MS Windows

The first thing we need is to have working installation of Oracle Client. It is available for non-commercial use at http://www.oracle.com. When installing Oracle Client it is necessary to install also the SqlPlus console. Now we need to configure Oracle Client to work with the database server that we want to use to store persistent data. Main part of the process is configuration of tnsnames.ora and sqlnet.ora files. See documentation of Oracle DBMS for further details.
Note: In Oracle DBMS version 10g and later it should be enough to install Oracle Instant Client with SqlPlus ... and configure it.
On most of MS Windows installations it is further necessary to set system variables. Variable PATH should point to the directory with executables of MSVC 6.0 (usually .../Microsoft Visual Studio/VC98/Bin) and to the directory with Oracle's library oci.dll (usually .../Oracle/oci/lib/msvc). Variable INCLUDE should point to the directory of the headers supplied with the MSVC compiler (usually .../Microsoft Visual Studio/VC98/Include).
Now we can start the installation of IOPC persistency library and tools. If we do not want to use compiled version of the library and tools the first step is to compile necessary libraries - Xerces and GC. It is highly recommended to install also STLPort, one of the implementations of STL library. The original STL library from MSVC 6.0 does not work always in the way it should and beyond it the library causes a lot of strange warning messages without any reason when compiling IOPC. The resulting dynamic link library of Xerces should be put into one of directories specified in the PATH system variable.
Further details how to install the mentioned libraries can be found in the zipped file containing source files of the libraries that you can download from this pages. The information can be also found on the internet ( http://xml.apache.org/xerces-c/, ftp://parcftp.xerox.com/pub/gc/gc.html a http://www.stlport.org/).
For all the tools and parts of the library there are ready to use project files for MSVC 6.0 so it should be easy to compile IOPC. The order how to compile it follows: At first we should compile XMLMetadataLoader and XMLMetadataWriter libraries (/iopc/iopc_metadata), then modified version of the OpenC++ (/iopc/iopc_sp/occ.dsw) and then IOPC SP, After it we should IOPC DBSC and IOPC LIB (the order doesn't matter).
Before compiling IOPC LIB it is necessary to set Oracle headers path in the settings of the project (Project - Settings - C/C++ - Preprocessor - Additional include directory) and the path to Oracle libraries (Project - Settings - Link - Input - Additional library path).
No matter whether we compiled IOPC sources or not now we should have working version of IOPC persistent layer and tools.
To make use of IOPC easy it is recommended to add into PATH system variable the path to the directory with compiled version of IOPC (tedy .../iopc/bin/Win32) and into INCLUDE system variable the path to the IOPC LIB header files (.../iopc/iopc_lib/include).

Installation in Linux

Similarly to the installation in Windows, the first requirement is to have working version of Oracle Client. If we don't have it, we have to download and install it - see Installation in Windows for further details.
The system variables are usually correctly set in Linux so in most cases there's no need to change them.
If we don't want or cannot use the compiled version of library and tools, we should start compiling Xerces and GC library. STLPort is not necessary in Linux. See Installation in Windows for details about libraries.
There are prepared Makefile files for compilation of each part of IOPC in directories of the parts. When compiling it is necessary to do it in the same order as described above in section Installation in MS Windows.
To make you of IOPC easy it is recommended to add into PATH system variable the path to the directory with compiled version of IOPC (tedy .../iopc/bin/linux) and into INCLUDE system variable the path to the IOPC LIB header files (.../iopc/iopc_lib/include).

Use of IOPC in MS Windows

Use of the library and the tools in MSVC 6.0 is quite easy.

Each persistent capable class must be inherited from class IopcPersistentObject.
Each source file (*.cpp), which contains (or into which are included by the preprocessor) definitions of persistent capable classes must be processed by IOPC SP. Therefore it is necessary to set MSVC to use IOPC SP as "Custom build step" for these files (the option can be set in file settings in Settings - General - "Always use custom build step", then you should set IOPC SP as "compiler" in "Custom build" tab). Examples how to do it in the right way can be found in examples.zip file. In case of problems setting "Custom build step" see MSVC help. If you have problems using IOPC SP, ask it for help using "-h" switch.
After compiling the user application it is necessary to link it with the IOPC LIB library (iopc_lib.lib).
The next step is to generate XML metadata needed for the application to run. To do it use IOPC SP tool with option "-m". For further information about IOPC SP command line syntax run the program with option "-h". The process of metadata generation and creation of persistent capable classes is described at length in the diploma thesis (but it is available in Czech only by now).
If the user wants he can modify the XML metadata (to change the way of class / attribute mapping to DB tables / columns.
Then it is necessary to generate the script that creates needed DB structures. The IOPC DBSC tool should be used to do it. Information about the tool's command line can be displayed when calling IOPC DBSC using option "-h".
The created script should be executed on desired database. One of the ways how to do it is using SqlPlus console.
Now you can run the user application.

Use of IOPC in Linux

Use of the IOPC tools and library in Linux (using g++) is easier than in MS Windows.

Each persistent capable class must be inherited from class IopcPersistentObject.
Each source file (*.cpp), which contains (or into which are included by the preprocessor) definitions of persistent capable classes must be processed by IOPC SP. Therefore we use IOPC SP instead of compiler in Makefile. The examples of Makefile-s can be found in examples.zip file. In case of problems using IOPC SP, ask it for help using "-h" switch.
Then it is necessary to link the application with the IOPC LIB library (call linker with "-liopc_lib" option).
The following steps are the same as in MS Windows.

The IOPC persistency system was successfully tested on Red Hat Linux version 9.0 (Shrike).

Several notes related to the use of IOPC

The examples of most common use persistency layer interfaces can be found in examples.zip file.
All the functions and classes of the layer, which were developed or modified during IOPC project, are described at length in IOPC documentation (documentation.zip). The functions and classes from original POliTe library are partially described in POLiTe user documentation (POliTeManual.zip).
Important error and warning messages of IOPC persistency tools / library are logged into .err and .wrn files.

Back to the main IOPC project page.