Cache' Server Kit
October 22, 2009
Please read the 'License' file before proceeding. The EsiObjects Public License (EOPL) license is based on the Mozilla Public License (MPL). The 'License Explained' file describes the license.
The Cache' Server kit consists of a ZIP archive containing the following files:
1.Cache_ESI.dat – This file contains all the EsiObjects globals and routines. They reside in the VES namespace.
2.Cache_USER.dat - This file is the repository for all libraries created by you. It is the dataset logged into. On a new installation it is empty. All routines and globals in the VES namespace (stored in the ESI dataset) are mapped through translation.
3.The readme_cache files contain the installation and setup information.
4.License file contains the actual EOPL license.
5.License Explained file contains a short description of what the License means.
The kit is approximately 104 megabytes in size.
This release contains the following enhancements and changes: GT.M specific changes only.
This set of release notes documents installation of the runtime support for EsiObjects on a Cache' database server. We strongly recommend that you have the current version of the EsiObjects client software installed.
The runtime support consists of two Cache' databases. As of this release, Cache' database servers for EsiObjects are supported on Windows Vista and XP.
EsiObjects must run on a Cache's 2009 systems or newer for Windows Vista and XP.
Disk space required: 65 MB for the Cache' runtime support databases.
DOWNLOADING THE KIT
You may access this kit through SourceForge, http://esiobjects.sourceforge.net. The kit consists of a zip archive file named eo_server_cache_4_2_1_0_rc3.zip. Unzip this archive to extract two Cache' database files: Cache_ESI.dat and Cache_USER.dat.
NEW AND UPGRADE INSTALLATIONS
For a new EsiObjects installation, Cache' must be configured for the two new databases included in the kit. Detailed instructions are in the sections "Setting up the Databases" and "Configuring Cache". An upgrade installation of EsiObjects uses only one of the two databases from the kit; see the section "Upgrading a Cache' Server" for details.
SETTING UP THE DATABASES
Before you configure Cache', you need to bring in the new EsiObjects runtime support databases. They will be installed manually from the kit instead of being added from within Cache'. This step requires two new directories:
1. Create two subdirectories named "ESI" and "ESIUSER" under Cache's system manager directory, typically C:\Cachesys\MGR.
2.Copy the Cache_ESI.dat file unzipped from the kit into the new "ESI" directory and rename it cache.dat.
3.Copy the Cache_USER.dat file unzipped from the kit into the new "ESIUSER" directory and rename it cache.dat.
Before you can access the EsiObjects runtime support database, you must make sure that Cache' is properly configured. You must also register the two new databases with Cache' and configure a Namespace for each of them. This requires the following steps:
1.Make sure that Cache' has been started.
2.Open the Cache' System Management Portal.
3.In the Cache' System Management Portal window, click on the 'Configuration' link and then the 'Memory and Startup' link. Click on the Manually button. Change the 'Memory Allocated for Routine Cache' field to 32 if it is not already that value or greater. If changed, click on the Save button. Note: If you changed this setting you must restart Cache' after the installation is complete.
4.Return to the Home page and select the 'Configurations' link and then the “Local Databases” link. Both of the databases you copied into your new Cache' directories must be registered with Cache':
(a)Click on the 'Create New Database' link to bring up the Database wizard. Enter "ESI" as the name of your database and the directory path you created for the ESI database. Click on the Next button and take all the defaults. Click on the Finish button to create the database entry.
(b)Repeat steps (4a) to register the application database in the ESIUSER directory. Name the database ESIUSER.
5.Return to the Configuration page and click on the 'Namespaces' link. Namespaces must be created for both of the databases you copied into your new Cache' directories:
(a)Click on the 'Create New Namespace' link. Enter 'ESI' as the namespace name and select the ESI database you just created. Uncheck the 'Create a default CSP application for this namespace' field. Press "Finish" to exit.
(b)Repeat steps (5a) to add the application namespace and associate it with the matching ESIUSER database. The ESIUSER namespace requires special global and routine mappings, which are set up in the next steps.
(c) Return to the 'Namespaces' page. Click on the 'Global Mapping' link for the ESIUSER namespace. Click on the 'New Global Mapping' button. Select the database ESI location. Enter in the global name "VESO*" (with an upper case letter o before the star). Click on 'OK' to file the mapping.
(d) Return to the 'Namespaces' page. Click on the 'Routine Mapping' link for the ESIUSER namespace. Click on the 'New Routine Mapping' button. Enter in the routine name "VESO*" (with an upper case letter o before the star). Leave type to 'All'. Select the database ESI location. Click on 'OK' to file the mapping. Next, enter in the routine name "VESo*" (with an lower case letter o before the star). Leave type to 'All'. Select the database ESI location. Click on 'OK' to file the mapping.
6.You may now restart Cache'.
UPGRADING A CACHE' SERVER
To upgrade an existing Cache' server to a newer version of EsiObjects, only one of the two Cache' databases from the kit is used. The Cache_ESI.dat database should replace the existing database in the "ESI" namespace.
There are two ways to accomplish this:
1.If you can, the simplest way is to simply shut down the Cache' instance and then remove the old database in the ESI subdirectory of the Cache' system manager directory. Then move the new database into the ESI subdirectory. Make sure that the new database file is renamed cache.dat. Restart Cache'.
2.Or, go to the Home page of the System Management Portal and select the Databases link under the Operations column. Then, dismount the ESI database and then remove the old database in the ESI subdirectory of the Cache' system manager directory. Then move the new database into the ESI subdirectory. Make sure that the new database file is renamed cache.dat. Finally, remount the database.
To install the EsiObjects IDE, go to https://sourceforge.net/projects/esiobjects/files/ and choose the esiobjects-client/18.104.22.168 directory. Download the eo_client_kit_4_2_0_0.kit file. Extract it into a working directory. Execute the Setup.exe file. This wizard will install the client IDE.
If you want to make sure you have the latest client, you can download it from the SourceForge SVN.
The latest updates for the Cache server side is stored at:
The client IDE is stored at:
STARTING THE SERVER
The EsiObjects server must have the TCP listener running. There are two ways to start the listener:
To start the server manually, perform the following steps:
1.Start up a Cache' Programmer window and enter the ESIUSER namespace. You may do this with the command:
> zn "ESIUSER"
2.Start the server with a command of the following form:
> Job START^VESOTCSV(port)
The job parameter 'port' is the TCP port on which the server will listen for remote access requests. This parameter is mandatory. It is recommended that you use port 9000 if it is not otherwise reserved on your server machine. The server will run in background mode.
Alternatively, you may start the server with a "Do" command, in which case the server will run in the foreground until terminated with ^C. This is typically used for testing purposes
To have the listener come up automatically at Cache' boot time, you may use the %ZSTART utility provided by Cache'. Simply access the %SYS namespace and modify the %ZSTART.int routine. Add the following and save it.
At this point, multiple EsiObjects clients may now connect to sessions on the port you specified.
Remember that a Cache' license server must be configured and running, or else connection attempts may hang.
Report all errors in SourceForge, http://esiobjects.sourceforge.net. Follow the link "If you need to report a problem with EsiObjects please click here." This way a problem description will reach the appropriate people. When describing the problem, precede it with a scenario, that is, the state that EsiObjects is in when the error occurred. That way, we can quickly recreate that state to reproduce the problem.