API PRO CMMS
API PRO 8 Installation Guide
By API Maintenance Systems A/S
API Maintenance Systems A/S
Roskildevej 342 B, st.
DK-2630 Taastrup
Denmark
Tel. +45 4348 9900
Fax. +45 4348 9901
E-mail: support@apipro.com
WEB:
www.apipro.com
Product Version: API PRO 8
Language: English
Manual Revision: 27th April 2014
Copyright  2016 by API Maintenance Systems A/S. All rights reserved
Registered trademarks and trademarks are the property of their respective companies
Table of Contents
USING THE INSTALLATION GUIDE .................................................................................................... 6
CHOICE OF INSTALLATION .................................................................................................................. 7
Overview .......................................................................................................................................... 7
SINGLE USER ............................................................................................................................................. 8
Before the installation ...................................................................................................................... 8
Assistance during installation .......................................................................................................... 8
Passwords and user rights ............................................................................................................... 8
Installation ....................................................................................................................................... 8
PROGRESS OPENEDGE DATABASE ON WINDOWS 2003 SERVER .............................................11
Before the installation .....................................................................................................................11
Assistance during installation .........................................................................................................11
Passwords and user rights ..............................................................................................................11
Installation ......................................................................................................................................11
ORACLE DATABASE ...............................................................................................................................13
Before the installation .....................................................................................................................13
Assistance during installation .........................................................................................................13
Passwords and user rights ..............................................................................................................13
Installation ......................................................................................................................................13
SQL SERVER DATABASE .......................................................................................................................15
Before the installation .....................................................................................................................15
Assistance during installation .........................................................................................................15
Passwords and user rights ..............................................................................................................15
Installation ......................................................................................................................................15
SECTION A – PREPARATION OF V7 DATABASE BEFORE UPGRADING ..................................17
Preparation of database before upgrading to API PRO 8 ..............................................................17
STEP 1: DUMP OF DATA FROM EXISTING VERSION .....................................................................................18
STEP 2: CHECKING THE DUMPED DATA USING API PRO 8 PROGRAM .........................................................19
STEP 3: REPAIRING THE DUMPED DATA ......................................................................................................22
General notes regarding upgrade ...................................................................................................27
Program: DIAGNOSIS procedures .................................................................................................27
SECTION B - INSTALLING THE PROGRESS OPENEDGE SERVER SOFTWARE .....................29
SECTION C - INSTALLING THE API PRO DATABASE ....................................................................45
SECTION D - CONFIGURATION OF THE API PRO DATABASE ...................................................54
SECTION E - INSTALLING THE API PRO CLIENT SOFTWARE...................................................70
Modifying APIPRO.PF file .............................................................................................................73
APPSERVER Enabled or disabled ..................................................................................................75
Modifying DLC values ....................................................................................................................75
Configuration for Asian languages .................................................................................................76
Installation of the latest Service Pack .............................................................................................77
SECTION F - CONFIGURING THE API PRO CLIENTS ....................................................................79
Environment ....................................................................................................................................81
SECTION G - COMPILING THE API PRO SYSTEM ..........................................................................84
Possible warnings and errors .........................................................................................................90
SECTION H - ADVANCED DATABASE CONFIGURATION .............................................................91
BACKGROUND WRITERS .............................................................................................................................91
ADMINSERVICE FOR OPENEDGE (WINDOWS 2000/2003)...........................................................................91
SECTION I - MS SQL SERVER INSTALLATION ................................................................................93
PREPARE SQL SERVER ...............................................................................................................................93
MS SQL 2008 EXPRESS – MANAGEMENT STUDIO .....................................................................................94
General............................................................................................................................................94
Options ............................................................................................................................................94
Build API PRO schema ...................................................................................................................97
Client ODBC Configuration............................................................................................................99
SECTION J - ORACLE SERVER INSTALLATION ...........................................................................103
Codepage ......................................................................................................................................103
Choose or Create Tablespace .......................................................................................................103
Create User ...................................................................................................................................103
Create API PRO schema ...............................................................................................................104
Connection from Client to Oracle Database Server .....................................................................104
SECTION K - LOADING DATA ............................................................................................................106
LOADING DATA INTO API PRO 8 PROGRESS DATABASE ..........................................................................106
Start API PRO 8 ............................................................................................................................108
SECTION L – APPSERVER....................................................................................................................109
APPLICATION SERVER CONFIGURATION...................................................................................................109
CONFIGURE CLIENT TO CONNECT TO APPSERVER ....................................................................................117
AppServer-Name ...........................................................................................................................118
CONFIGURE API PRO CLIENT NOT TO CONNECT TO APPSERVER ............................................................119
SECTION M – LICENSE AND MODULE ACCESS CODES .............................................................121
LICENSE ...................................................................................................................................................121
MODULE ACCESS CODES...........................................................................................................................122
WHEN THE EVALUATION SYSTEM HAS EXPIRED .......................................................................................123
REPLACING EVALUATION SYSTEM LICENSE CODES WITH OFFICIAL LICENSE CODES .................................125
SECTION N – DUMP AND LOAD DATA .............................................................................................127
DUMP OF DATA.........................................................................................................................................127
LOAD OF DATA .........................................................................................................................................128
SECTION O – PROGRESS LICENCING INFORMATION ...............................................................130
GENERAL INFORMATION ..........................................................................................................................130
Progress OpenEdge Software Components ..................................................................................130
SECTION P – ARCHITECTURE ...........................................................................................................131
CLIENT-SERVER ARCHITECTURE..............................................................................................................131
DIFFERENCE BETWEEN DATABASE SERVER AND FILE SERVER ................................................................132
SECTION Q - OPENEDGE DATABASE ADMINISTRATION TASKS............................................135
ON-LINE BACKUP .....................................................................................................................................135
Backup on Windows 2000/2003 using a Progress OpenEdge database .......................................135
Restore ..........................................................................................................................................136
Unable to open copy database…. ..................................................................................................136
Making a backup automatically every night .................................................................................137
EXPAND AN OPENEDGE DATABASE ..........................................................................................................138
REMOVE USER (MULTI USER PROGRESS OPENEDGE DATABASE ONLY) ...............................................139
SECTION R - SERVER SETUP AND SERVER TOOLS.....................................................................141
PERMISSION FOR END-USER ON THE FILESERVER ......................................................................................141
FILE PERMISSIONS ....................................................................................................................................143
EVENT VIEWER SETUP ..............................................................................................................................143
Managing Progress Events on NT ................................................................................................144
SECTION S - INSTALLATION ON CITRIX ........................................................................................146
INSTALLATION OF API PRO IN A CITRIX ENVIRONMENT ..........................................................................146
INSTALLATION OF API PRO .....................................................................................................................146
Using the installation guide
PLEASE NOTE: This document is a draft version of what will be the Installation guide
for API PRO 8
This installation guide will advise you on how to install the API PRO 8 Computerized
Maintenance Management System.
This guide contains first some general information. Then there is a chapter for each of the
supported types of installation. In the end, there are several Section chapters. References are
made to these Sections from the chapters which describe the supported types of installation.
Please read the general chapters and the relevant part of this installation guide for your type
of installation carefully, before you start the installation. When you start the actual
installation, you can use the installation guide as a step by step description of how to install
the API PRO system.
All names are trademarks or registered trademarks of their respective companies.
Availability on Many Platforms
API PRO is available on many different platforms and databases. This installation guide
contains the installation instructions for the most common multi-user system platforms with
Windows Clients and a Windows 2003/2008 server with a Progress OpenEdge, Oracle and
MS SQL database.
For all other platforms, please consult your local API PRO representative.
Hardware and Software Requirements API PRO 8
Please read our HW/SW requirements for more information.
Upgrade path from previous API PRO versions
With the API PRO 8 installation package, it is possible to upgrade from API PRO Open.7 to
API PRO 8. If you have an older version, you must first upgrade to version 7 before you can
upgrade to API PRO 8.
Architecture of an API PRO Installation
Because of the flexibility of the API PRO system and the availability on many different
platforms, there are many possible architecture designs for an API PRO system.
‘Section P Architecture’ describes some of the most common architectures.
Choice of Installation
Overview
The installation of API PRO can be combined in many ways, depending on platforms and
databases. In this installation guide, we will only describe some of them. Because of the high
number combination possibilities we have split the installation up in many Sections,
containing a part of the installation.
From each installation type, we will refer to these chapters.
Installation types
This installation guide supports the following installation types.
Single user
Installation of a system with a Progress OpenEdge database on a Windows 2003 server
Installation of a system with an Oracle database
Installation of a system with a SQL\Server database
Select the proper type of installation and follow the installation instructions in the
corresponding chapter.
Single User
Before the installation
There are no special requirements before the installation
Assistance during installation
There is no special assistance needed for making a single-user installation.
Passwords and user rights
In order to make a single-user installation you need the local administrator password for the
computer where the installation is made
Installation
Dump data from v7, v7SP01- v7SP06 system
If you are upgrading a version 7, v7SP01- v7SP06 API PRO system, you must first dump the
data from your current version and make a copy of various configuration files.
Please read ‘Section A – Preparation of V7 database before upgrading’ for more information
on dump data from v7, v7SP01- v7SP06.
Install the client software.
Install the database
The next step is to install the database.
Please read the ‘Section C Installing the API PRO database’ for more information.
Install the client software
Please read the ‘Section E Installing the API PRO client software’ for more information.
Configure the client
Now you must configure the client that means installing short cuts, various components, etc.
Please read ‘Section F Configuring the API PRO clients’ for more information.
Compile the system
The next step is to compile the system.
Please read ‘Section G Compiling the API PRO system’ for more information.
Load data from v7, v7SP01- v7SP06 system
If upgrading from v7, v7SP01- v7SP06, you must load the data that has been dumped from
the v7, v7SP01- v7SP06 system.
Please read ‘Section K Loading data’ for more information.
Configuration for Crystal Reports in Single-user Mode
If the user wishes to use Crystal Reports on a single user installation, then the API PRO
installation needs to be reconfigured.
No user should be logged on the database while proceeding with this configuration.
In order to be able to run Crystal Reports, the installation must be configured such that an
ODBC connection to the database is possible.
For this purpose, a service name needs to be started. You must start a command-prompt and
execute the following command:
proserve <<APIPRO DB directory>>\API3 -N TCP -S 2550 -H localhost
N.B You may also select another service port, but then you must remember to make this
change consistent all through this documentation.
The 'proserve' command is reset every time the computer is restarted. Therefore it is
recommended that a .CMD file, containing this command, is created. The .CMD file should
be put in the startup tasks so that the database is restarted every time the computer starts.
This command will ask Progress to start the database. If the task is successful, the following
response will appear in the command-prompt:
OpenEdge Release 10.2B2B as of Thu Aug 18 02:07:21 EDT 2005
13:20:33 BROKER
This broker will terminate when session ends.
13:20:33 BROKER 0: Multi-user session begin.
13:20:34 BROKER 0: Begin Physical Redo Phase at 64 .
13:20:35 BROKER 0: Physical Redo Phase Completed at blk 135 off 2850 upd 27.
13:20:35 BROKER 0: Started for 2550 using TCP, pid 268.
This confirms that the database is started, which makes the existing shortcuts to API PRO
invalid.
N.B The command promon <<APIPRO DB directory>> enables you to check specific
features regarding the database.
In order for the shortcuts to work, you need to correct the APIPRO.pf located in the
APIPRO\WORK-directory. The five first lines in the file must be the following.
-db api3
# Database
-ld api3
# Logical Name
-N TCP
# Protocol
-H localhost
# Host
-S 2550
# Service
The same correction should be applied in the AUTOCOMP.pf located in the
APIPRO\WORK-directory. The rest of the files should remain unchanged.
Now you should test the APIPRO shortcut to verify that you are able to log onto the
database. If the test is successful, then you are ready to run your reports.
N.B Remember to setup an ODBC connection before using Crystal Reports on the APIPRO
database (Please read API PRO Installation add-ons document).
Progress OpenEdge database
on Windows 2003 server
Before the installation
There are no special requirements before the installation
Assistance during installation
During the installation, you will need assistance from the network administrator. He must
provide the following information:
-
Location for installation of the database and server software
-
Location for installation of the client software
-
IP address (host name) of the database server
-
Administrator passwords for database server and file server
Passwords and user rights
In order to make a multi-user installation with a Progress OpenEdge database on Windows
2000/2003 server, you need the following user rights:
You need the local administrator password for the database server
You need full access rights to the file server where the client software will be located.
Installation
Dump data from v7, v7SP01- v7SP06 system
If you are upgrading a version v7, v7SP01- v7SP06 API PRO system, you must first dump
the data from your current version and make a copy of various configuration files.
Please read the ‘Section A – Preparation of V7 database before upgrading’ - depending on
the upgrade situation- for more information.
Install the Progress OpenEdge server software
Now the Progress OpenEdge server software must be installed.
Please read the chapter ‘Section B Installing the Progress OpenEdge Server software’ for
more information.
Install the database
The next step is to install the database.
Please read the ‘Section C Installing the API PRO database’ for more information.
Configure the API PRO Database
After installation of the database, the databases must be configured. This means defining how
to start and stop the database, start-up parameters must be configured, etc.
Please read the chapter ‘Section D Configuration of the API PRO database’ for more
information.
Install the client software
The next step is to install the client software.
Please read the ‘Section E Installing the API PRO client software’ for more information.
Install the application server (optional)
The next step is to install the application server.
Please read the ‘Section L AppServer’ for more information.
Configure the client
Now you must configure the client that means installing short cuts, various components, etc.
Please read ‘Section F Configuring the API PRO clients’ for more information.
Compile the system
The next step is to compile the system.
Please read ‘Section G Compiling the API PRO system’ for more information.
Load data from v7, v7SP01- v7SP06 system
If upgrading from v7, v7SP01- v7SP06 you must load the data that has been dumped from
the v7, v7SP01- v7SP06 API PRO system.
Please read ‘Section K Loading data’ for more information.
Oracle Database
Before the installation
Before the API PRO installation is started, the Oracle database must be up and running. On
each work station that will be used for API PRO, the Oracle client software must be installed
and the Oracle Net connection must be configured.
Assistance during installation
During the installation, you will need assistance from the network administrator. He must
provide the following information:
-
Location for installation of the client software
-
Administrator passwords for the file server
During the installation, you will need assistance from the Oracle database administrator
(DBA). He must provide the following assistance:
Create a table space on the Oracle database
Build the API PRO schema
Provide user ID and password accordingly
Passwords and user rights
In order to make an installation with an Oracle database you need the following user rights:
You need full access rights to the file server where the client software will be located.
You will need a user ID and password for the API PRO schema on the Oracle database
Installation
Dump data from v7, v7SP01- v7SP06 system
If you are upgrading a version v7, v7SP01- v7SP06 API PRO system, you must first dump
the data from your current version and make a copy of various configuration file.
Please read the ‘Section A – Preparation of V7 database before upgrading’ for more
information.
Install the Oracle database
Now you must install the Oracle database
Please read the ‘Section J Oracle Server installation’ for more information.
Install the client software
The next step is to install the client software.
Please read the ‘Section E Installing the API PRO client software’ for more information.
Configure the client
Now you must configure the client that means installing short cuts, various components, etc.
Please read ‘Section F Configuring the API PRO clients’ for more information.
Compile the system
The next step is to compile the system.
Please read ‘Section G Compiling the API PRO system’ for more information.
Load data into the system
Finally, you must load data into the database.
If you are upgrading from v7, v7SP01- v7SP06 system, then please read ‘Section K Loading
data’ for more information.
SQL Server Database
Before the installation
Before the API PRO installation is started, the SQL Server database must be up and running.
On each work station that will be used for API PRO, the ODBC data source connection must
be configured.
Assistance during installation
During the installation, you will need assistance from the network administrator. He must
provide the following information:
-
Location for installation of the client software
-
IP address of the database server
-
Administrator passwords for database server and file server
During the installation, you will need assistance from the SQL Server database administrator
(DBA). He must provide the following assistance:
Create a database on the SQL Server database
Build the API PRO schema
Provide user ID and password accordingly
Passwords and user rights
In order to make an installation with an SQL Server database you need the following user
rights:
You need full access rights to the file server where the client software will be located.
You will need a user ID and password for the API PRO schema on the SQL Server database
Installation
Dump data from V7, v7SP01- v7SP06 system
If you are upgrading a version V7, v7SP01- v7SP06 API PRO system, you must first dump
the data from your current version and make a copy of various configuration file.
Please read the ‘Section A – Preparation of V7 database before upgrading’ for more
information.
Install the MS SQL Server database
Now you must install the SQL Server database
Please read the ‘Section I MS SQL Server installation’ for more information.
Install the client software
The next step is to install the client software.
Please read the ‘Section E Installing the API PRO client software’ for more information.
Configure the client
Now you must configure the client that means installing short cuts, various components, etc.
Please read ‘Section F Configuring the API PRO clients’ for more information.
Compile the system
The next step is to compile the system.
Please read ‘Section G Compiling the API PRO system’ for more information.
Load data into the system
Finally, you must load data into the database.
If you are upgrading from a version V7, v7SP01- v7SP06 system, then please read ‘Section
K Loading data’ for more information.
Section A – Preparation of V7
database before upgrading
Ensure all users are logged out of the system. Ensure no users can log in
again.
Make a backup of your V7 system
Make a backup of the system, both programs and data on the file server and
the database.
It must be emphasized the users are not allowed to be logged on API PRO
during these steps. This will prevent inconsistent data.
Preparation of database before upgrading to API PRO 8
This description covers all aspects during upgrade from previous version of API PRO to
newest version API PRO 8.
If current version is before version API PRO Open.7 then the version should be updated to at
least API PRO Open.7 before continuing with this description.
Important:
All upgrade procedures must be performed through the direct API PRO
database connection!
No application server allowed!
Upgrade_Preparation fix-package should be installed on your current system
before data dump.
The section described 4 main steps of preparation the data base for the upgrade to API PRO
8:
1.
Dump data from existing version
2.
Check the dumped data using API PRO 8 program.
Run the upgrade tool belonging to the version which is being upgraded to (in this
case – API PRO 8). This tool will go through the dumped D-files and create a test
report showing which data is invalid and not ready for import into a new version.
3.
Repair of the dumped data.
In step 3 errors mentioned in the report, created in step 2, are repaired in the existing
version of API PRO. After this is done, repeat step 1 and step2.
4.
When the error reports and diagnostic reports are all empty, the data can be loaded
into the database for the new API PRO version. Refer to Section K – Loading
Data for more information.
When the data dump is done, please keep the created file called “api-dump.log”. This file
should later be compared with the import control file for the updated version.
The package that belongs to this description should first be installed in the existing
environment. After the xcoded files are installed they should be compiled using the compile
file: update.lst contained in the package.
Important:
Between each run of fix tool on larger databases (more than 1 GB) it is
recommended that you shut down current API PRO start a new API PRO
session.
Step 1: Dump of Data from Existing Version
From the existing database, run as external the following procedure. With 'Run external
procedure', you must call the program FIX-DB\DUMP-API.R.
The following window will appear, here you should press OK.
After pressing OK button you should enter a directory where the files should be dumped.
This directory should already exist on a drive, where there is enough space for all data.
The default directory is ..\dump. This means that the data will be dumped in the directory
APIPRO7\DUMP.
During the dump of the data, the status will be displayed. The time needed for the dump of
the data is dependent on the size of the database, the connection between the client and the
server and the general performance of the database server. It will take between several
minutes for a small database to several hours for large databases.
When the dump of the data is finished, you will be notified with the following message:
Dump documents
If your Document storage is configured to store documents in the database, you should check
this option. The program then will dump the binary data of the stored documents. Otherwise,
when your documents are stored on the external drive, this option should be switched off.
The program creates a separate DOCUMENTS directory, where the binary files will be
placed, in the dump folder and a separate log file for dumping the documents:
..\DOCUMENTS\_service\ ds_file_DUMP.log .
You should not remove the API PRO Open.7 version. However, if you upgrade your
Progress OpenEdge software, you should uninstall the existing Progress OpenEdge software,
both on the database server and on the clients.
Step 2: Checking the dumped data using API PRO
8 program
When the data dump has finished, then you are able to continue to the next step in your
upgrade
A main procedure can be used to check that the dumped D-files contain only valid data. It’s
important that the data being loaded into the new upgraded system is all valid. This step helps
you to provide this security, so please follow these instructions carefully.
The main program that checks the dumped D-files is named “fix-db/fix-@#$.r.”
This procedure creates a log file, and dependent what is written in this log file a number of
correction and/or diagnosis procedures can be used.
Program: fix-db/fix-@#$.r
After Ok button is pressed, you get the following message:
On the next step you need to specify directory with your dumped data and the directory,
where this data should be copied.
This functionality detects the dumped data which might cause errors during import due to the
restrictions special for a particular platform or have suspicious values. These are:
TEXT values exceeding the maximum length specified in the field format (Oracle and MS
SQL Server restriction)
DATE values with the year are less than 1753 (MS SQL Server restriction).
DATE values with the year greater than 2100 (suspicious date).
The problems found are logged in 2 files:
invdata-d.log and replace-d.log
both placed in ../copy directory indicated by the user. File invdata-d.log reports on the
following:
-
Illegal job type
-
Invalid length
-
Date not valid
Example of the log-file invdata-d.log:
‘Illegal job type’ warning is a special case of the invalid length and was decided to be
reported separately as one of the key problems of transferring data.
The above mentioned functionality is limited to reporting and does not perform an automatic
correction of d-files. For doing that you must execute one of the other utilities (see below).
Below an edited example how the contents in the log-file “replace-d.log” could be:
Important:
The contents of these 2 reports MUST NOT indicate any problems!!!
If the remark column is not “OK”, then you should take action and choose a
utility which corrects the wrong data.
After you have corrected the reported errors then you MUST start all over with
the dump data procedure (Step 1 and Step2).
Only when both of these reports are 100% correct, you can continue with the
next steps.
Step 3: Repairing the dumped data
Use the existing version for this step.
Important:
Remember to shut down current API PRO and start a new API PRO session
before each run of fix tool.
Program: fix-db/fixjobt.r
In previous versions of API PRO, the job type stored on the database was 3 characters.
In the new versions of API PRO the job type is only stored as 1 character. In order to convert
old format to new format, this utility is used.
It’s based upon a text file which you make manually, where the from- and to- values is taken
from the log file created by fix-db/fix-@#$.r.
Arguments for the program are as follows:
<correction-file>, <code-page>
Code page should be entered according to the actual settings, ex 1252, ISO8859-1,UTF-8 etc.
Example:
The format of the manual created correction file is this:
<from-value>|<to-value>.
Example:
CMU|U
CMP|C
PM|P
INS|I
CBM|B
OTH|O
Each occurrence of <from-value> in a job type field will be replaced with <to-value>.
Program: fix-db/fixyear.r
This utility corrects date fields in API PRO database based on a file with correction
instructions provided by the user. It’s based upon a text file which you make manually, where
the from - and to- values is taken from the log file created by fix-db/fix-@#$.r.
Arguments for the program are as follows:
<correction-file>, <code-page>
Code page should be entered according to the actual input file format (1252, ISO88591,UTF-8 etc.) But in this case when we have the numeric data (of date type) it can have any
code-page.
The format of the manual created correction file is this:
<from-value>|<to-value>.
Examples:
1700|2000
3001|2001
9999|1999
1003|2003
200|2000
Each occurrence of <from-value> in all date fields will be replaced with <to-value>.
Program: fix-db/fix-crlf.r
This utility searches for incorrect presence of Carriage return, Newline, Tab, Escape,
Backspace or Form feed.
These illegal representations of control character are typically introduced to the system via
use of CTRL-C / CTRL-V.
There are no arguments for this program, which is called as RUN External like this:
After pressing OK you will have this question:
After pressing OK this message box is showing the update progress:
When the procedure is ended, this message box shows up:
Edited example of the resulting log-file:
Program: fix-db/fixchar.r
It is recommended always to activate the procedure fix-crlf.r BEFORE this
utility.
This utility searches for and deletes all ‘control characters’ such as Carriage Return <CR> in
all characters fields.
It can be called with different arguments, depending on what should be fixed.
At first the key values should be checked and if there are any warning messages in the log
file placed in the Temp-directory and named “fixchar.log”, then all key values should be
changed manually in the API PRO system. After that all others values could be verified with
argument “No”.
Call this utility as external procedure like below:
Argument ‘yes’ means that it will fix all KEY values.
After program is run then examine the log file “fixchar.log” placed in the Temp-directory.
If everything is OK then it looks like this:
If there is warnings in the log file such as:
“Warning!!! Can't change key value because such key already exists”.
…then you should manually change all key values with warnings in API PRO.
Argument ‘no’ means that it will fix ALL values.
When pressing OK then a message box like this is shown so progress can be viewed:
When finished this message box shows up:
Example of the log file as it should be with no errors in the database:
General notes regarding upgrade
Fields with extents are processed. For this reason the analysis and correction procedure fixchar.r can take some time dependent of which argument you have selected.
As a decision about each field with invalid length should be made separately for each case,
fix of long texts is not included in fix-char.r.
Description fields, which have a format of 2000 characters, such as Note or Description, are
not analyzed in fix-char.r.
These fields are handled in fix-db/fix-crlf.r
In general when importing it is VERY important to check the log and error files after import!
Log files: *.log will normally be places in directory importing from (except fix-@#$ where it
is saved in output directory)
Error files *.e are places in same directory as *.d files. One will exist for each d file imported
and non-zero size indicates program encountered a problem during import / fix.
If you see any *.e files with size > 0 bytes, then go back to system where you dumped data
from and correct the problems and dump data again.
Notice if data are very corrupt you might need special tools for correcting your old database
before you can update to newer version.
This is why it is important to do test updates to see you current data are OK!
When your installation is ready for upgrading to API PRO 8, then the normal installation
procedure for API PRO 8 should be followed. Please read the API PRO 8 Installation Guide
regarding this.
After loading the data to API PRO 8 you ought to dump the data and compare the dump-data
log file with the log file you made initially based upon the database from where you started
the migration. These two log file should show the same number of records for each table in
the directory.
Program: DIAGNOSIS procedures
A couple of diagnosis procedures are also available. These procedures just checks the
database, they don’t repair and update the data.
Program: fix-db/diagtxln.r
This utility searches the API PRO database for text values of character fields that exceed the
maximum length specified in the field format. The resulting report diagtxln.log is placed in
the system temporary directory.
Example of the log-file:
In order to see illegal job type values, search for ‘Job_type’ in the file.
Program: fix-db/diagyear.r
This utility searches the database for values of date fields out of the interval 1753 - 2100.
The resulting report diagyear.log is placed in the system temporary directory.
Section B - Installing the
Progress OpenEdge Server
software
API PRO 8 runs with Progress OpenEdge v. 10.2B server software. This chapter will
describe how to install this software.
If an older Progress version has been installed on the database server, then it should be
uninstalled before installing 10.2B. Before you uninstall the Progress software, you must
disable the ‘AdminService for Progress’. Please read the chapter ‘AdminService for
Progress’ in ‘Section H - Advanced database configuration’ for more details.
In order to install the Progress server software, you should place the API PRO DVD in the
database server client machine.
The following screen will appear. Here you shall select the “Install Progress server” option.
Hint: If the tool does not start up automatically, then you can execute the program
progress\setup.exe on the API PRO DVD.
The Progress OpenEdge installation tool will now ask for the serial numbers and the control
numbers for the different Progress OpenEdge client products. You have received these
numbers on paper together with the API PRO DVD.
The products that should be installed here are the following:

OpenEdge WorkGroup RDBMS or

OpenEdge Enterprise RDBMS

OpenEdge Application Server Enterprise

NameServer Load Balancer
Depending on the database you are going to work with you should choose among the
following products:

OE DataServer for ODBC

OpenEdge DataServer for Oracle

OpenEdge DataServer for MS SQL Server
When you continue, you must enter the type of installation and the destination. The
destination should be a place where users cannot get to the data directly. Therefore we
suggest entering the destination as the C:\APISERVER\DLCWIN directory, somewhere on
the database server, e.g. C:\APISERVER\DLCWIN.
The working directory is where the log files for server tools are saved – for example
C:\APISERVER\DLCWORK
Next screen is choice for the Administration server
C:\APISERVER\DLCMGMT is the administration software
C:\APISERVER\DLCMGMTWORK is working directory for the administration software
To make sure that everything is installed, you must select “complete installation”.
It is important that you check the OpenEdge Explorer check box!
The Microsoft .NET should be checked too – if not installed already.
The Microsoft .NET Framework will make this dialog appear:
Select the program group where you want to install the shortcut for Progress OpenEdge. It is
recommended to select the default “OpenEdge”.
If you want to allow JDBC or ODBC SQL access to the databases you need to install SQL
Server Engine!
You must select a language and a default language for the Progress OpenEdge software. We
recommend that you install English - International as default language. If you for
example select “German” as the default language, all unexpected Progress error messages
will be in the select default languages. This might be convenient for the users, but it will be
impossible for the API PRO support department to help when these kind of error messages
appear.
This will not influence the language of the API PRO system itself.
We recommend that you also select the local language. If you want to have other languages
installed, you can select them from the list. Please be advised that each language needs 7
to 10 Mb each, on the hard disk.
E.g. In Germany default language would be “English – international” and additional
language “German”.
Progress needs to know what the default setting shall be for the character set, date and the
number format. These settings should be set in progress.ini (situated in
..\APIPRO\DLCSRV\BIN) and in Startup.pf (situated in ..\APIPRO\DLCSRV).
IMPORTANT: The “Character set, Collation, and Case” MUST be modified to
“UTF-8 Basic Basic”.
Number format: Remember to check and choose according to the user and/or region
preference. Very often the number format is (period,comma) instead of (comma,period).
If the WEB Service question – depending on type of installation – appears then change the
suggested defaults.
Port number should be changed from :80 to :8080 which normally is default for Tomcat and
‘Disable Authentication’ should be enabled/checked.
It is possible in Progress OpenEdge version 10.2B to set permissions for starting “Admin
server”
If you do not select any of them, everyone with permission to log in to the server can start
“Admin server” and administrate the databases.
The installation program will now ask you to confirm the installing product.
The progress installation tool will now start to copy files to your hard disk.
Questions can occur during this process – answer what’s appropriate in the situation
(typically answer No)
Press “finish”
Restart machine after the installation is complete. It is recommended not to proceed with
the installation of other components before restart.
Modify DLC and PATH parameters.
It is important to modify those 2 parameters.
Start – Control panel – System – Advanced – Environment Variables.
Create a DLC parameter in the “User variable” box. This parameter shall inform where the
Progress SERVER software is installed.
WARNING: Don’t confuse the Progress SERVER software with the Progress Client
software. This is normally NOT the same location.
Example:
DLC = C:\APISERVER\DLCWIN\
The box “System variable” already contains a PATH parameter. You shall ADD information
to this parameter informing where the Progress SERVER software is installed INCLUDING
the ..\bin directory.
WARNING: Don’t confuse the Progress SERVER software with the Progress Client
software. This is normally NOT the same location.
Example:
PATH=J:\UTIL;%SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System
32\Wbem;C:\Program Files\ATI Technologies\ATI Control Panel;c:\nt;c:\util;
C:\APISERVER\DLCWIN\; C:\APISERVER\DLCWIN\bin
Installation of Progress OpenEdge Service Pack
After installation of Progress it is recommended to install latest Service Pack. Start the API
PRO DVD and select the “Install Progress OpenEdge service pack” option.
Please observe that the Progress OpenEdge database server will be unavailable during this
process.
Before installing it is advised that you check you current patch level. The Patch level can be
seen in the text file …\dlcsrv\version.
If you don’t want to use the menu system on the API PRO DVD, you can as an alternative
install the Service Pack with the following command. In the “Start”, “Run” program, you
must enter: <DVD-drive>:\Progress_SP\setup.exe:
The installation tool will guide you through the installation process:
If the AdminServer service is running you will get the following screen:
Choose yes to continue with the installation.
If the following window appears, click Next. After the Installation Wizard is closed, launch
Task Manager and stop all processes, related to the Progress.
Now you can run Progress Service Pack installation again.
Questions can occur during install of the service pack
Press OK.
Answer Yes or No as appropriate.
After finishing the installation of the service pack , “AdminService for OpenEdge 10.2B”
must be restarted from “Start – Control Panel – Administrative Tools – Services”.
Return to ‘Choice of installation’
Section C - Installing the API
PRO Database
On the API PRO DVD, you will find five different databases:
Initial database
This is an API PRO database without data, but with a menu
system, configuration parameters, etc. This database should be
installed as the ‘live database’ when new installations are made.
Demo database
This is an API PRO database with some test data and examples.
We recommend that customers install a demo database besides
the live database for test and demo purposes.
Empty database
This is an API PRO database without data, without a menu
system and without configuration parameters. This database
should be installed when upgrades of previous versions are
made.
Large Initial
database
This is an API PRO database without data, but with a menu
system, configuration parameters, etc. This database should be
installed as the ‘live database’ when new installations are made.
Large database should be used, when its size exceeds 2Gb.
Large Empty
database
This is an API PRO database without data, without a menu
system and without configuration parameters. This database
should be installed when upgrades of previous versions are
made. Large database should be used, when its size exceeds
2Gb.
All five data bases are available in an UTF-8 ICU UCA version (default basic international
version) and can be found in the following directories on the API PRO DVD:
\PRO-DB\PROGRESS\INITIAL.ICU
\PRO-DB\PROGRESS\DEMO.ICU
\PRO-DB\PROGRESS\EMPTY.ICU
\PRO-DB\Progress\LargeInitial.icu
PRO-DB\Progress\LargeEmpty.icu
The database consists of the files API3.B1, API3.D1, API3.ST and API3.DB.
For single-user systems the databases must be copied to APIPRO8\DB\LIVE and
APISERVER\DB\TEST.
Note: For a single-user system it is important that you place the databases in these
directories. Otherwise the system cannot be started up after finishing the installation
procedure.
For multi-user systems the databases should be placed to the working directory of the
Progress OpenEdge server, which you specified during the installation of the Progress
OpenEdge server software (see Section B - Installing the Progress OpenEdge Server
software). Following our example, the database files should be placed to
C:\APISERVER\DLCWORK directory. You can simply copy the API PRO databases from
the API PRO DVD.
Note: The location of the database will be dependent on your existing backup routines. Please
be aware that you cannot simply copy the API PRO database onto a tape, you will have to
set-up a backup routine for this. Please read Section Q for more information.
The following steps are very important not to forget, since API PRO 8 is based on specific
collations (sortings) for each country.
First you need to examine which collation code is needed for your country. Example: If
the customer is Danish, use the code ICU-da. Write down this code, since it will be used
many times during the installation.
Code page
Collation
Description
UTF-8
BASIC
BASIC = BINARY (Default for APITRANS)
UTF-8
ICU-UCA
Default Unicode Collation Algorithm (Default
linguistic collation for all API3 databases)
UTF-8
ICU-ar
Arabic
UTF-8
ICU-be
Belarusian
UTF-8
ICU-bg
Bulgarian
UTF-8
ICU-ca
Catalan
UTF-8
ICU-cs
Czech
UTF-8
ICU-da
Danish
UTF-8
ICU-de__PHONEBOOK
German phonebook
UTF-8
ICU-el
Greek
UTF-8
ICU-en_BE
English_Belgium
UTF-8
ICU-eo
Esperanto
UTF-8
ICU-es
Spanish
UTF-8
ICUes__TRADITIONAL
Spanish traditional
UTF-8
ICU-et
Estonian
UTF-8
ICU-fa
Persian
UTF-8
ICU-fi
Finnish
UTF-8
ICU-fr
French
UTF-8
ICU-gu
Gujarati
UTF-8
ICU-he
Hebrew
UTF-8
ICU-hi
Hindi
UTF-8
ICU-hi__DIRECT
Hindi direct
UTF-8
ICU-hr
Croatian
UTF-8
ICU-hu
Hungarian
UTF-8
ICU-is
Icelandic
UTF-8
ICU-ja
Japanese
UTF-8
ICU-ja__HQ
Japanese Hiragana Quaternary
UTF-8
ICU-kn
Kannada
UTF-8
ICU-ko
Korean
UTF-8
ICU-lt
Lithuanian
UTF-8
ICU-lv
Latvian
UTF-8
ICU-mk
Macedonian
UTF-8
ICU-mr
Marathi
UTF-8
ICU-mt
Maltese
UTF-8
ICU-nb
Norwegian Bokmål
UTF-8
ICU-nn
Norwegian Nynorsk
UTF-8
ICU-pl
Polish
UTF-8
ICU-ro
Romanian
UTF-8
ICU-ru
Russian
UTF-8
ICU-sh
Serbo-Croatian
UTF-8
ICU-sk
Slovak
UTF-8
ICU-sl
Slovenian
UTF-8
ICU-sq
Albanian
UTF-8
ICU-sr
Serbian
UTF-8
ICU-sv
Swedish
UTF-8
ICU-ta
Tamil
UTF-8
ICU-te
Telugu
UTF-8
ICU-th
Thai
UTF-8
ICU-tr
Turkish
UTF-8
ICU-uk
Ukrainian
UTF-8
ICU-vi
Vietnamese
UTF-8
ICU-zh
Chinese
UTF-8
ICU-zh__PINYIN
Chinese Pinyin
UTF-8
ICU-zh_HK
Chinese Hong Kong
UTF-8
ICU-zh_MO
Chinese Macau
UTF-8
ICU-zh_TW
Chinese Taiwan
IMPORTANT:
If your country is not on the list (for instance Italy which does not have special
local characters) you will normally select 'ICU-UCA' (which is the default for
API PRO 8).
In the following example we show the following scenario:
Customer is Danish. We therefore select ICU-da. Customer is making an update from an old
API PRO system. Therefore we have in this case made a copy of the empty ICU-UCA
database.
We need to change OpenEdge 10.2B Data Administration shortcut:
Start – all programs – Open edge - Data Administration - Right mouse click – properties.
Add -rx to Target line. This allows you to load collations into databases. Don’t forget to save
this modification.
Now double click OpenEdge 10.2B – Data Administration shortcut:
Connect to your copy of the database. E.g. Database is copied to the server using the
location:
C:\APISERVER\DLCWORK
After having connected to the database do we need to select the “admin”, “load data and
definitions” and “data definitions (.df file)”
Now do we need to load the correct df file in order to obtain the right collation. Look in the
location where the Progress OpenEdge server software is installed and find the right df file.
C:\APISERVER\DLCWIN\prolang\utf\ICU-da.df
We get a dialog-box which seems to be an error. This is not an error in our case. Just press
“OK”.
We get a dialog-box which seems to be a warning. This is not a problem in our case. Just
press “OK”.
Wait until you get the message “Load completed” and press “OK”.
Verify collation by selecting 'Utilities' – 'Information'
Close Data Administration program.
NB: REMEMBER to remove the –rx again.
Last step is to run Proenv. Start – all programs – Open edge - Proenv .
You get a proenv command prompt. Change to directory where your API PRO database is
located. In our example use the commands
CD C:\APISERVER\DLCWORK (Open database location directory)
Proutil api3 –C idxbuild all (To rebuild all indexes in database with new collation)
Enter ‘Exit’ to close Proenv command prompt.
Return to ‘Choice of installation’
Section D - Configuration of
the API PRO Database
When you have copied the database files to the database server, you must configure the tool
that is used for starting up and shutting down the database server. This can be done with the
OpenEdge Explorer (MMC). This tool can be found as a short cut in the various Progress
OpenEdge tools after installation of the Progress OpenEdge server software.
1. Start OpenEdge Explorer tool
You should login to the database server machine as ‘Administrator’ and start the OpenEdge
Explorer tool. On the first login you will be asked to enter login and password. This is the
default credentials which should be changed after first login.
Default login: admin
Default password: admin
When the OpenEdge Explorer is started, it looks as follows:
Change password and make sure you remember what it is! Then click Submit.
Click OK to have the web server restart.
When the server is running again you will get following screen:
Enter admin and the password you have assigned, and following screen is displayed:
The password should be changed back to “admin”.
Change the password on admin
Select the button in the left upper corner “ADMIN”
Change the password back to “admin” and save.
Select ”Resources”
2. Define Database
Expand the server tree (in this case server name is apiserver) and click Database
Now click “Add Resource”:
Enter the basic settings for the database:
First of all, you should define the Display name of your database and the path to the database
directory.
Then you should set the ‘Database Broker Type’ to 4GL. Then you should define the
‘Service name or port number’. The client installation supports the following values:
Live database
port: 2550 Display name: Open7Live
Test database
port: 2560 Display name: Open7Test
Click Submit and the 'pin' to pin this database.
Now click Configuration. On the following page click ‘Edit’ and set the database to
autostart. Save changes.
Then click the configuration.open7live.defaultconfiguration and click Edit.
Blocks in database buffers: We recommend >= 10.000 (Depends on available memory
and database size).
Lock table entries:
We recommend >= 81.920 (Sum off all records being part of
transactions)
Max users:
This is sum of direct 4GL connections, AppServer connections
and ODBC connections, so set it to 2-3 times the number of
licensed API PRO Open.7 users if running with AppServer.
Max servers:
A good starting point is maximum users divided by 5 + 2.
(Please observe that you can reserve servers for 4GL
connections and ODBC connections)
Asynchronous page writers: 1 per CPU core in the server.
Other arguments:
Leave this empty for 10.2B, Windows event level will be
configured later
Scroll down to see more options:
Collation table (-cpcoll):
ICU-UCA ← collation selected earlier for databse
Server code page (-cpinternal)
utf-8
Log code page (-cplog):
utf-8
Windows Event Level
'None' (To avoid writing of database events to Microsoft
event viewer.)
REMEMBER to modify the “International”. Here you need to set the database
locale specific settings.
Important:

Collation should match the collation defined for the database (ICUxxxx)

Case table should match the case table used for the database (Almost
always BASIC)

Conversion map should stay at default

Server code page should match code page of database (Always UTF-8)

Log code page should match code page of database (Always UTF-8)
Scroll up and click Save.
Then scroll to the button and Click the
servergroup.open7live.defaultconfiguration.defaultservergroup
Click Edit.
Configure reporting interval, how often will license usages information be logged.
Configure number of servers for 4gl access, number of clients per server (depends on server
and number of users) and minimum clients per server (how quick it should start new server
processes)
Click Save.
3. OpenEdge ODBC connection
IF you want to make custom reports with direct database connections from Crystal Reports or
be able to access the API PRO 8 data from Excel you must set-up an ODBC interface.
Click Create.
Name new server ODBC and click Save and click Edit.
Enter port, IP version and Client type and clients per server and click Save
- You must set the ‘Client type’ to SQL only
- The service name or port number MUST have another name/number to avoid conflicts.
(Live database 2551 and test database 2561)
It can be a good idea to reserve a number of servers for servicing ODBC connections.
For further details read API PRO Installation add-ons- “ODBC”.
4. Start database
Click
until you are back on:
Click Control
Click Start Database.
When database is running the screen switches to:
If you close the pinned screen you will see the green dot in left panel indicating the resource
(database) is running.
5. Configure demo and test database
Repeat step 3 to 6 for the test database.
Return to ‘Choice of installation’
Section E - Installing the API
PRO Client Software
In order to install the API PRO client software, you should place the API PRO DVD in one
of the client machines or on the machine where you want to make a single-user installation.
Observe that to be able to run the Form Design Module .Net V1.1 or newer has to be
installed. This needs to be installed before installation of the API PRO client.
Note: The client software should always be installed on one of the client machines and not
directly on the database server. Refer to the Section P – Architecture to find out what
packages should be applied to the architecture you are using for API PRO.
The following screen will appear:
If you choose ‘Install API PRO Server Image’, the following screen will appear (if the tool
does not start up automatically, then you can execute the program
\APIPRO\UnCompress.EXE in the root directory on the API PRO DVD):
Define the path, where the program should unpack the API PRO8 Client Software and define
which database version you are going to use. This selection depends on database server,
configured for API PRO:
The client software can be installed on the database server itself, a dedicated file server or on
the client machine itself. If the client software is installed on the client machines itself, then
this must be done on each single client machine. Otherwise you will have to make this
installation only once on the file server.
We strongly advise you to install the software in a directory called \APICLIENT\APIPRO8.
Click ‘Unpack image’. The program will start copying files of the API PRO 8 Client
software to your client machine. Wait until the following message appears and click OK:
OpenEdge Database Server
If you have selected OpenEdge Database Server, API PRO will set connection to the
database automatically. Now you can continue reading the part ‘Selecting the language’.
Oracle database
If you have selected an Oracle database, then you must enter the ‘Oracle connection string’.
MS SQL Server database
If you have selected a MS SQL Server database, then you must enter a userid, a password
and the ODBC data source name for the MS SQL Server database:
Modifying APIPRO.PF file
When the installation of the client software is finished you do not have to restart the
computer.
REMEMBER to modify the ..\APIPRO8\WORK\APIPRO.PF file.
Depending on the Server platform 'enable' and 'configure' the chosen platform section
following the example below:
-
OpenEdge Database
-db C:\APISERVER\DB\LIVE\api3
-ld api3
-N TCP
-H 192.168.7.10 (Server IP)
-S 2550
-
MS SQL Server
-db apipro -RO
-ld apipro
-db ODBCDSN -ld api3
-dt MSS
-U USERID
-P PASSWORD
-Dsrv TXN_ISOLATION,1
-
Oracle
-db apipro -RO -ld apipro
-db api3
-dt ORACLE
-U API/API@ORCL
-c 255
The -cpcoll must be modified to reflect your collation in the database. E.g. Database is
configured with Danish collation it must be set to: –cpcoll ICU-da
APPSERVER Enabled or disabled
The files Apipro.ini and Apipro.pf should be modified.
APPSERVER Enabled
APPSERVER Disabled
Apipro.ini:
Apipro.ini:
AppServer-Name=apipro8LiveAS
;AppServer-Name=apipro8LiveAS
AppServer-Host=localhost
;AppServer-Host=localhost
AppServer-Port=5162
;AppServer-Port=5162
Apipro.pf
Apipro.pf
#-db api3
-db api3
#-ld api3
-ld api3
#-N TCP
-N TCP
#-H 192.168.7.10 (Server IP)
-H 192.168.7.10 (Server IP)
#-S 2550
-S 2550
Modifying DLC values
At this stage you should modify DLC and PROBUILD values everywhere in your API PRO
8 client environment.
Edit file ..\APIPRO8\WORK\APIPRO.INI. In the [Startup] section uncomment DLC variable
and enter the same value, which was set in the User Environmental Variables. For the
PROBUILD variable define path of your DLC, appended with PROBUILD directory. This
variable will refer to the OEBUILD directory in your OpenEdge installation. Here is the
example of APIPRO.INI with modified variables:
DLC and PROBUILD variables should be changed in the AOUTOCOMP.INI file
(..\APIPRO8\WORK\autocomp.ini).
Configuration for Asian languages
For Asian languages, such as Chinese, you need a few extra settings to ensure the characters
are displayed correctly.
Note: We recommend that if you change any of the settings mentioned here, you make the
same settings in all PF and INI files that are in use – for “live” database client, for demo
database client, and for the compiler (AUTOCOMP.PF/.INI).
The SCRIPT=ANSI setting (in APIPRO.INI file)
This is a setting for the font definitions in the .INI file. It affects how much space is allocated
for displaying our programs (the way Progress draws up the windows on the screen). If your
API PRO windows look strange - are the wrong size or are stretched in one direction – then
you should try this setting. If you have a Chinese or Japanese version of MS Windows
installed, you will probably need this setting.
The setting is normally not needed on western European versions of MS Windows. In fact, it
seems to have no effect at all.
In your .ini file, go to the [Startup] section. Look for DefaultFont and DefaultFixedFont.
Add the text “script=ansi” at the end of each of these definitions. This will tell Progress to
base its calculations on the sizes of English fonts.
It is also possible to put this setting on each individual font in the [Fonts] section, but it
should not be necessary to do so.
Example of INI file (Startup section only):
[Startup]
V6Display=no
DLC=C:\APISERVER\DLCWIN
PROBUILD= C:\APISERVER\DLCWIN\PROBUILD
DefaultFont=MS Sans Serif, size 10, script=ansi
DefaultFixedFont=Courier New, size=10, script=ansi
Use-3D-Size=No
Keep3DFillInBorder=No
PROPATH=.,..\CUSTOM,..\XCODE
UseSourceEditor=no
EndMsgTitle="API PRO Open.7"
EndMsgText=Windows is closing. Is this OK?
useClipChildren=yes
ButtonImageBorderMode=2
For information only: A quote from the Progress documentation:
Specifying scripts
For each font you specify in the progress.ini file’s [Startup] section or [fonts] section, or in
the Windows registry, you can specify a script, which corresponds to a code page. The syntax
for specifying a script is:
script=script-name
“script-name” is the name of the script. Use one of the following values: ansi, default,
symbol, shiftjis, hangeul, gb2312, chinesebig5, oem, johab, hebrew, arabic, greek, turkish,
vietnamese, thai, easteurope, russian, or baltic.
Do not enclose the value in quotes.
An example of a font specification that specifies a script is:
font0=Courier New, size=8, script=russian
For more information on specifying scripts, see your Windows documentation.
The –ulayout setting
(primary for Chinese)
This setting is for the .PF file. It determines how many bytes of data it is possible to store for
one English letter in the original texts. You will always need this setting for Asian languages.
A value of 4 should be enough for Chinese letters. If you want, you can set a larger value, up
to 9. The value of –ulayout will affect the size of the compiled programs (.r files). The larger
value you use, the more space your compiled programs will take up.
It is very important to set this value in the .PF file for the compiler (AUTOCOMP.PF). It is
the compiler that generates the .r files, so it is the compiler that needs to have this setting.
Installation of the latest Service Pack
After installation of the client software, you should install the latest API PRO Service Pack.
The latest Service Pack is available on the API PRO installation DVD. Select the “Install API
PRO Service Pack” - or select the directory \APIPRO_SP on the API PRO DVD.
The Service Pack is a ZIP file that must be unzipped in the APIPRO8 directory of your
Client installation.
Return to ‘Choice of installation’
Section F - Configuring the
API PRO Clients
For API PRO 8 could run on the client machine the Baseline components should be installed.
The necessary programs are located in APICLIENT\APIPRO8\SETUP\APIPROBaseLine.
Baseline is a package with the required tools for client. This package includes the connection
parameters for the application server as a part of the setup, thus you will be asked to enter
values for application server connection. What Baseline package should be installed depends
on the chosen API PRO architecture (Section P – Architecture).
Baseline
The package includes only main tools for running API PRO 8:

OpenEdge and CodeJock

OpenEdge ODBC Driver

BeauGauge

Crystal Report

Graphical Navigator

CodeJock 16.2.4
Note that this package doesn’t include API PRO 8 interface.
Baseline-Client, Baseline-Server and Baseline-Client-on-Server packages include the main
tools from the Baseline package and the API PRO 8 interface.
WARNING: In case you install on Citrix/Terminal refer to ‘Section S – Installation
on Citrix’ for more information.
Run as administrator API PRO BaseLine Installation (baseline.exe) located in your API
PRO\SETUP\APIPROBaseLine directory.
Installation of Baseline package
Installation of Baseline-Client-on-Server package
When the dialog disappears the “API PRO BaseLine” is installed.
You also need "Microsoft Visual C++ 2005", and "Microsoft .NET Framework 3.5" (or later)
for the baseline to run as expected.
At client boot, the “Client initiator” will ask the AppServer for any new changes and through
this handshake ensure the image of the application stored locally is fully up to date.
The Client Initiator downloading files from the AppServer
Environment
In order CSM to work properly, ini and pf files should be setup
Client.ini
WORK/apipro.ini will be used as a default for CSM/client.ini, but if (and only if!) some
changes should be made for the CSM-clients only, this file should be used.
…
[Startup]
;DLC=
NoSplash=YES
…
[API PRO]
AppServer-Name=<name>
AppServer-Host=<dns> or <ip>
AppServer-Port=<port>
…
[API PRO Open.7]
CodeJockVersion=15.2.1
Section Startup: Remove DLC (controlled outside), set NoSplash (faster login).
Section API PRO: AppServer settings
Section API PRO Open.7: CodeJockVersion (optional)
Note: In .ini files “;” treats the rest of the line as a remark/comment.
Client.pf
WORK/client.pf will be used as a default for CSM/client.pf, but if (and only if!) some
changes should be made for the CSM-clients only, this file should be used.
…
-lng GBP
# Language
-mc
# Compression
-p csm/client.p
# Startup Program
…
Note: In .pf files “#” treats the rest of the line as a remark/comment.
Batch.ini
Batch processing uses CSM/batch.ini:
…
[Startup]
DLC=<dlc>
PROPATH=.,..\CUSTOM,..\XCODE
…
Section Startup: set-up DLC.
Batch.pf
Batch processing uses CSM/batch.pf:
C:\APIPRO\APIPRO6\api3
# Database
…
-b
# Batch mode
-p csm/server.p
# Startup Program
…
Compile.ini
Batch compile (only) processing uses the set-up from CSM/compile.ini:
…
[Startup]
DLC=<dlc>
PROPATH=.,..\CUSTOM,..\XCODE
…
Compile.pf
Batch compile (only) processing uses the set-up from CSM/compile.pf:
C:\APIPRO\APIPRO6\api3
…
-b
# Batch mode
# Database
-rx
# Enable compile of xcode
-p csm/compile.p
# Startup Program for compile
…
If this file is missing CSM/batch.pf will be used instead REQUIRING a full-progress license
for the compile to work. Using the progress option –rx and the special compile program
csm/compile.p allows a run-time license to do the compile.
AppServer
Files monitored by CSM need to be documented. This is done by making a “Recompile &
deploy” build using the “Client Server Management” tool.
All programs will be compiled and will together with the other files (help-files, crystal report
setups) be recorded so future changes to the AppServer WORK/-area will be found and
optional forwarded to the clients at next login.
MSI-package
If WIX-tools are installed a new tailored MSI-package can be made from the “Client Server
Management” tool using the “Initiator”-tab.
This will include the ini and pf from step 1 and 2 above and the title of the package (used for
shortcuts).
For specific purposes such as CSM or Previews (thumbnails) in maints Microsoft Visual C++
redistributable package is also needed. It can be installed by running
SETUP\Preview\vcredist_x86.exe
Return to ‘Choice of installation’
Section G - Compiling the API
PRO system
Before you can use the API PRO system, you must compile the system. This will take
between 7 minutes and a few hours, dependent on the performance of the client and the
bandwidth between the client and the server.
We suggest that you use a powerful client machine for the compilation. Together with the
client software, a compilation tool has been installed.
Check whether the following .PF files have the correct connection with you database:
..APIPRO8\WORK\AUTOCOMP.PF
..\APIPRO8\WORK\APIPRO.PF
..\APIPRO8\WORK\AS-LIVE.PF
..\APIPRO8\WORK\CLIENT.PF
..\APIPRO8\CSM\BATCH.PF
..\APIPRO8\CSM\COMPILE.PF
Now check whether all .INI files have correct DLC and RPOBUILD values. They should
coincide with those modified in the Environment variables.
At least, check all following .CMD files, whether the path to prowin32.exe is correct:
..\APIPRO8\SETUP\COMPILE.CMD
..\APIPRO8\SETUP\APIPRO.CMD
..\APIPRO8\WORK\CLIENT.CMD
To select what languages should be available in APIPRO8 system, edit
..\APIPRO8\WORK\AUTOCOMP.LNG file.
If your database is not running currently, you should start database server, using OpenEdge
Explorer.
So now you are ready to compile your system. The tool is located in the APIPRO8\SETUP
directory.
When you execute this tool, the whole API PRO system will be compiled.
Before the actual compilation is started, you may get the following warning. It can be
ignored.
During the compilation, the status will be displayed:
Compile log file can be found in work directory
(..APICLIENT\APIPRO8\WORK\COMPILE.LOG) and contains information like:
Compile start
: 03/04/2014 17:32
Compile file
: compprog.lst
Session info:
GUI MS-WINXP
Screen reoslution
195,14 characters
: 768 by 1366 pixels = 32 by
Session code Page
: UTF-8
Stream code Page
: UTF-8
Numeric format
decimal point ','
Date format
:
, = thousand delimiter ' '
: dmy
Compile options
:
Languages
: GBP,CST:GBP
Save Into Directory
: .
Custom Save Into
: .
Xcode Directory
: .
Target database
: PROGRESS
Show warnings
: Yes
Show translation warnings
: No
Show messages
: Yes
**: Compiler error, ++: Compiler message, !!: Compiler
warning, --: Translation warning
Databases:
api3 -db C:\APISERVER\DLCWORK\api3,-fc 8192
- Code page
: UTF-8
- Collation
: ICU-UCA
APITRANS: ..\XCODE\apitrans
CSTTRANS: <NOT CONNECTED>
PROPATH:
.
..\CUSTOM
..\XCODE
C:\APISERVER\DLCWIN\gui
C:\APISERVER\DLCWIN\gui\adecomm.pl
C:\APISERVER\DLCWIN\gui\adecomp.pl
C:\APISERVER\DLCWIN\gui\adedesk.pl
C:\APISERVER\DLCWIN\gui\adedict.pl
C:\APISERVER\DLCWIN\gui\adeedit.pl
Now compiling apipro.w
03/04/2014 13:59:20
...
Now compiling workord/workloda.p
03/04/2014 14:03:50
Compile finish
03/04/2014 17:41
Total files:
2800
Successfully compiled:
2800
NOT compiled (errors):
0
Possible warnings and errors
When starting the compilation of your API PRO 8, you may encounter some problems,
which are caused by the wrong configuration of key files.
‘The –l parameter requires a numeric argument. (11996)”
Cause: Wrong configuration of AUTOCOMP.PF file.
Resolution: The connection to the database should be uncommented in AUTOCOMP.PF
file. –lg parameter, which stands for the logical name of the database, should be commented
or temporarily removed from the file.
‘Cannot find or open file M\APISERVER\DB\LIVE\api3.db, errno=2 (43)’
Cause: The database is placed into a wrong directory, which doesn’t coincide with the
working directory, specified during the installation of Progress OpenEdge server software.
Resolution: Move the database files into the correct directory. Run PROENV to execute the
following program:
prostrct REPAIR C:\APISERVER\DLCWORK\api3
Return to ‘Choice of installation’
Section H - Advanced
database configuration
Background writers
If you have an enterprise database, you can tune the performance by changing the
‘Background writers’. Please contact your API PRO representative for more information.
AdminService for OpenEdge (Windows 2000/2003)
When Progress OpenEdge is installed on the database server, then an ‘AdminService for
Open Edge’ will be installed as well. You can configure this AdminService through ‘Control
panel’, ‘Administrative tools’, ‘Services’.
You can configure this service by double clicking on it.
The ‘Startup type’ should be ‘Automatic’ and the service should be started.
Note: If you want to uninstall the Progress OpenEdge software, this ‘AdminService’ may
cause problems. It may be necessary to set the ‘Startup type’ to ‘Manual’ or ‘Disabled’ and to
reboot the machine before you can uninstall the Progress OpenEdge Software.
Return to ‘Choice of installation’
Section I - MS SQL Server
installation
Prepare SQL server
Create database and user on the SQL server. It is recommended to use the same name for the
database and the user, e.g. apidb. When configuring the ODBC connection, use the same
name for the data source, e.g. apidb.
The directory starting with “\PRO-DB\MSS” – at writing moment MSS2005 and MSS2008 on the API PRO DVD contains a sql script for creating the API PRO schema on the SQL
Server database.
The schema holder and the corresponding sql script (APIPRO-SQL-UTF-CI-AI.SQL) have
support for Case Insensitive and Accent Insensitive MS SQL databases. The codepage used
on the MS SQL server side must support storage of UTF-8 based characters. Characters will
be converted from UTF-8 (Client side/OpenEdge) to UCS-2 (Server side/MS SQL Server).
In short the installation is done as follows:
On the MS SQL server.
Logon to the MS SQL Server with adequate rights.
Create a ‘new’ database on the server.
Create a new login and make the new database the default for this login and assign all but
deny rights to the login.
On the server or from a client.
Logon with the new login – check that the default database is correct.
Load and run \PRO-DB\MSS2008\APIPRO-SQL-UTF-CI-AI.SQL
( The Scriptfile APIPRO-SQL-UTF-CI-AI.SQL is the same for SQL 2005 and for SQL2008)
On the client – ODBC configuration.
Under the System DNS create a new ‘data source’ alias.
Choose the driver that is delivered by Progress/OpenEdge.
In the following pages is included a ‘simple’ walk through of the set-up above. The walk
through is based on a set-up with Windows MS SQL 2008 Express running on XP.
MS SQL 2008 Express – Management Studio
Create a database.
General
Specify name of database. Use a name that has a reference to API PRO. Could be for
example apipro or open7 as used below.
Options
Specify the collation table to be used. The one chosen below – Latin1_General_100_CI_AI –
should have a good fit with icu_uca. If you intent to use a local collation, then please verify
that an OpenEdge collation similar to the ‘local’ collation exist/is available. The collation in
the schema holder and the client set-up (pf files) must match the chosen collation on MS
SQL.
Then create a login.
Give the user the same as the database (or one that reflects the database) to make it easy to
remember. Use ‘SQL Server authentication and set default database to the ‘API PRO’
database (APIDB).
Give the user access to the database and assign all rights except: db_denydatareader and
db_denydatawriter.
Build API PRO schema
Invoke the SQL Server query analyser and log on with user id and password (e.g.
APIDB/APIDB). Select the empty API PRO database (e.g. APIDB). Open the script for
building the API PRO schema. It is located on the API PRO DVD: \PRODB\MSS2008\APIPRO-SQL-UTF-CI-AI.SQL. If installing on MS SQL 2005 server the look
in \PRO-DB\MSS2005 for the script.
In MS SQL 2008 Express – select the database and load the script (New Query tool bar) and
then ‘Execute’ to create the API PRO database.
A number of lines with “Warning! The maximum key ….”, “Msg 208, Level 16 ….” And
“Msg 156, Level 15 …” will be reported during the execution of the script. These can be
ignore if they are similar to the ones in the 3 screen shots below:
The last one ‘Msg 156 …’ is indicating that script is finished.
Client ODBC Configuration
On windows 64 bit you need to run the 32 bit version directly:
%WINDIR%\syswow64\odbcad32.exe
Select the OpenEdge ODBC driver.
Click [Test Connection ] to verify connection to SQL server is available.
In API PRO Open.7 for users who use MS SQL on the back end a special tool for hiding
connection parameters in schema holder was developed. This procedure should be followed
for each connection data which is used/available via the schema holder.
Run DB-CONNECTION.CMD in SETUP folder.
Enter the path to schema holder used for your API PRO. Then click “Connect” button - if any
connection data is present in the schema holder it will be displayed. Enter connection
parameters to the form and delete them from .pf file.
When entering connection parameters for the first time (or changing password), the password
confirmation is required. After it’s done click “OK” button.
In order to load the data for creating an initial Oracle or a MS SQL Server database check the
last chapter of "Section K - Loading data".
Return to ‘Choice of installation’
Section J - Oracle Server
installation
This section describes what has to be done in order to get API PRO to run against an Oracle
Database.
Note: In order to install API PRO with an Oracle database, some basic knowledge of Oracle
and Oracle’s database administration tools is needed.
Codepage
API PRO Open.7 uses the codepage utf-8. Therefore both the Oracle instance and the Oracle
client should be configured to AL32UTF8.
Choose or Create Tablespace
First you must create a tablespace for API PRO or choose an already created tablespace. If a
tablespace is created especially for API PRO it is normally named APIPRO.
To create a tablespace the graphical database administration interface, Oracle Enterprise
Manager, can be used.
Otherwise, the following SQL statement will create a tablespace from SQL*Plus or SQLPlus
Worksheet.
Logon as user SYSTEM or another account with DBA rights.
SQL> CREATE TABLESPACE APIPRO DATAFILE ‘FILENAME’ SIZE 500M;
You can use this size for a newly installed API PRO system. If you are migrating from an
API PRO system that uses a Progress OpenEdge database, the size of the Oracle database
should be estimated as 2-3 times the size of the Progress OpenEdge database-file.
Create User
Create a user on the Oracle database with access to tablespace APIPRO. For V5 of API PRO
the user should be named APIPRO. The password is normally set to APIPRO.
To create a user the graphical database administration interface, Oracle Enterprise Manager,
can be used.
Otherwise, the following SQL statement will create a user from SQL*Plus or SQLPlus
Worksheet.
Logon as user SYSTEM or another account with DBA rights.
SQL>
CREATE USER APIPRO IDENTIFIED BY APIPRO
DEFAULT TABLESPACE APIPRO
TEMPORARY TABLESPACE TEMP
QUOTA UNLIMITED ON APIPRO
QUOTA UNLIMITED ON TEMP;
SQL>
GRANT CONNECT, RESOURCE TO APIPRO;
Create API PRO schema
The directory “\PRO-DB\ORACLE10” on the API PRO DVD contains APIPRO-ORACLE10G-UTF.SQL script for creating the API PRO schema on the Oracle database.
Connect to Oracle with SQL*Plus or SQLPlus Worksheet as user APIPRO. Then use the
following statement to run a script that creates tables, indexes and sequences for API PRO on
the Oracle database:
SQL>
START ‘<DVD-DRIVE>:\PRO-DB\oracle10\APIPRO-ORACLE10G-UTF.sql’
Other Oracle Parameters
Also please check that the following parameters is set to at least the following:
open_cursors = 500
Open_cursors is set in the INIT{sid}.ORA file or by windows based tools. Oracle has to be
restarted, before the changes of open_cursors takes effect.
Connection from Client to Oracle Database Server
Oracle client software must be installed on the PCs that are used as API PRO client
machines. Please observe that API PRO uses the codepage utf-8 when communicating with
Oracle. The Oracle Net alias (Net8 for Oracle 8) configured with Oracle Net Configuration
Assistant must entered when installing the API PRO client.
In API PRO 8 for users who use Oracle on the back end a special tool for hiding connection
parameters in schema holder was developed. This procedure should be followed for each
connection data which is used/available via the schema holder.
Run DB-CONNECTION.CMD in SETUP folder.
Enter the path to schema holder used for your API PRO. Then click “Connect” button - if any
connection data is present in the schema holder it will be displayed. Enter connection
parameters to the form and delete them from .pf file.
When entering connection parameters for the first time (or changing password), the password
confirmation is required. After it’s done click “OK” button.
In order to load the data for creating an initial Oracle or a MS SQL Server database check the
last chapter of "Section K - Loading data".
Return to ‘Choice of installation’
Section K - Loading data
This section describes what has to be done in order to load data that has been dumped from
Open.7 system or initial data into the API PRO 8 system.
If upgrading from previous version make sure to read the document ‘API PRO Upgrade to
8.pdf’ before starting the upgrade! This can be found on the DVD in \APIPRO\UPDATE
directory. The same information can be found in the Section A – Preparation of v7 database
before upgrading.
To migrate the dumped Open.7 data into API PRO 8 database, run
READOPEN7DATA.CMD file, located in ..\APIPRO8\SETUP directory.
To load API PRO 8 dumped or initial data to API PRO 8 database, use LOAD.CMD file.
Please also notice that a direct database connection is needed during the load
process.
Loading data into API PRO 8 Progress Database
Run ..\APIPRO8\SETUP\ READOPEN7DATA.CMD or LOAD.CMD, depending on what
data should be loaded into an empty DB. Define the path to your database dump directory.
Calibration/Control prefix and Number of digits fields define the naming pattern of
Calibration/Control keys. Define prefix and number of digits or leave the default values.
After the OK button is pressed, you will receive the message:
Press OK again to start loading data.
Loading of the Open.7 data should be executed without errors. At the end the following
message will appear:
If your Document storage for Open.7 was configured to store documents in the database, you
should load them after the start of API PRO 8.
Execute Progress procedure using the Run external program with the following parameters:
Start API PRO 8
Now you can start up the API PRO 8 system.
The first time you start up the system, there will be executed several correction and
initialization programs. These initialization programs may also take some time to execute.
You may have to enter new API PRO license codes.
After initial login please continue with the load and initialization of change log as
described in this chapter.
Return to ‘Choice of installation’
Section L – AppServer
API PRO 8 supports the Progress OpenEdge Application Server. The AppServer can be
installed on the same server as the database server, but it can also be installed on a dedicated
server. We will in this chapter assume it is installed on the database server. In this case is the
Progress server software already installed and therefore we only need to configure the
AppServer.
In case you don’t want to configure AppServer to run on the same server as the OpenEdge
database or if you are using MS SQL or Oracle you need to install the Progress server
software first.
Application Server Configuration
Start OpenEdge Explorer. Click on AppServer, ‘Add Resource’ and select ‘New’
Add Open7LiveAS Service. (You can use any name, but the API PRO default is
Open7LiveAS)
Enter the name of your AppServer.
Save
When saving the system will give you a warning that the port number 3090 is already in use
clik ok.
Broker properties
Click ‘Edit’ button. Select a port number not in use. Don’t use the default 3090, but start
with 3098 or another number not in use. The port number information is not used by API
PRO, but each AppServer must have unique port number
In this example the port is set to 3092.
Set Auto start to yes.
Set the “broker logging level” to “ERROR ONLY”
If using NT authentication and “special user” is used to connect to the SQL database, the
parameter for OWNER INFORMATION should be used. (The user should be local
administrator)
Agent properties
Select the 2 tab “AGENT”
In this example the installation of API PRO has put the working directory is in
”D:\APICLIENT\APIPRO8\WORK”
“Server startup parameters”: -pf D:\APICLIENT\APIPRO8\WORK\AS-LIVE.PF
(see later in document how to configure content of ‘as-live.pf’)
“Propath”: working directory and xcode to propath before current entries.
Example: D:\APICLIENT\APIPRO8\WORK;
D:\APICLIENT\APIPRO8\XCODE;@{WinChar Startup\PROPATH};@{WorkPath}
“Logging Settings”: Change Server logging level to 'Error Only'.
“Pool Range” configuration:
Initial:
0
Minimum:
0
Maximum: Number of user (license) + 20%
The initial and minimum values must be set to “0” because if the app-server service tries to
start before the database is started, the DB will not be found and user will get an error.
Maximum: The maximum value should be as the number of users in the license code plus
10-20% extra from that amount.
Those percent is added in order to make sure that users who are timed-out will not prevent
others from being able to log-in.
SSL configuration
This is only needed if you want to use SSL encrypted connections between client and
AppServer.
This is not described in this manual, so enabling of this feature will require API PRO
consultancy.
Messaging configuration
This is only needed if you want to integrate the API PRO AppServer with Soniq.
This is not described in this manual, so enabling of this feature will require API PRO
consultancy.
After the configurable parameters are set, press Save button.
Content of AS-LIVE.PF file
This file (as-live.pf) is in our case located in D:\APICLIENT\APIPRO8\WORK. Please
enter the correct path to database if using in memory connection and the correct –cpcoll
parameter.
If you use database on another server you need to enter the remote network parameters: –N,–
H and –S to connect to database.
AppServer Start
Now we are ready to start the AppServer. Click on your application server in the explorer
tree section to open the AppServer main page. Now click on ‘Broker Control’ shortcut and
press ‘Start AppServer’ button.
If status has not changed to “Active” within 4-5 seconds you can press the refresh button:
Configure client to connect to AppServer
To configure API PRO connection to AppServer you might need to modify
APIPRO7\WORK\APIPRO.INI.
In the [API PRO] section focus on the 3 lines with AppServer-Name, AppServer-Host and
AppServer-Port
URL connection from client to AppServer is also supported. This is used to enter all
AppServer connection on single line and/or connect to AppServer via the AIA (AppServer
Internet Adapter)
URL type can be either
AppServer:://
Direct connection from client machine to Name server/AppServer
machine
OR
HTTP://
Connection to AIA that marchals the connection to Name
server/AppServer using the AppServer protocol
Sample records to API PRO.ini file:
AppServer-URL=AppServer://apid03:5162/apipro8Live
AppServerURL=http://apid03:8080/aia/Aia?AppService=apipro8Live
AppServer-Name
The AppServer-Name can be found in properties for the AppServer under AppServer Name
List. If you follow our default the name is APILive (This name is case sensitive)
AppServer-Host
AppServer-Host: Is the IP-number of the server running OpenEdge NameServer, (NS1 is
defined by default).
This will be the same IP-number as the server used for running the databases, if everything is
installed on a single server.
AppServer-Port
AppServer-Port: The service number is normally 5162 for the OpenEdge NameServer.
NS1 is the default NameServer instance created when installing OpenEdge 10.2B
Select properties for this name server. Notice the port number; default is 5162.This is the port
you need to enter in the apipro.ini file.
Configure API PRO client NOT to connect to
AppServer
IMPORTANT: If you don’t want to utilize the AppServer, functionality then modify the
file: APIPRO8\WORK\APIPRO.INI and disable the 3 configuration lines for AppServerName, AppServer-Host and AppServer-Port by entering a semicolon, ( ; ), in front of the
lines like the following sample:
;AppServer-Name=Open7LiveAS
;AppServer-Host=localhost
;AppServer-Port=5162
Section M – License and
Module access codes
License
In some cases, it is necessary to enter new licence codes in the API PRO system:
When you have installed an evaluation system and the licence codes have expired. In this
case you cannot work with API PRO until you enter new license code. On the logon you will
receive the following warning:
Press Ok button and restart the API PRO. This time you will receive another message:
If you want to proceed with importing new license codes, press Ok button. The window
appeared is a list of all modules with the access codes, supported by your license.
When you have installed an evaluation system and you have received new official licence
codes without an expiry date. In this case, you can still enter the system.
In both cases you must have received new API PRO license codes in a file from your local
API PRO distributor.
Module access codes
The “module access codes” defines which API PRO modules you currently have access to
and whether it is a limited access or an evaluation license expiring at a certain date. “Module
access codes” are provided by your local API PRO representative, depending on which
modules you have bought and which ones you are currently evaluating.
To make changes in the “module access code” you must logon as “supervisor” or you will
not be able to select the function in the menu bar. You find “module access codes” under
“system” in the menu bar.
The access codes can be distributed on paper or as a file. When the codes are distributed on
paper, they shell be entered manually by selecting the <New+> button, when they are
distributed on a file, they can be imported by selecting the <IMPORT> button.
<New+>
When your use the <New+> button you can write the new access codes in the Enter new
code box and the new module access codes will be added to the list. The existing data will
NOT be deleted, but edited in case you edit on an already existing module.
<IMPORT>
When you use the <IMPORT> you will be prompted for a location of the license file. For
new installations the license file (extension LIC) will be found in the \APIPRO7\WORK
directory. Otherwise use the file browser or enter the correct path and filename manually.
When the file name is entered, choose “OK” button.
You will be prompted for verification of the license file before the “access codes” will be
added to the existent file. The existing data will NOT be deleted, but edited in case you edit
on already existing module.
When the new license codes are added to the list, choose “OK”.
The new module will be accessible on the next logon.
When the evaluation system has expired
If you start up your system, then the following message will appear:
You should click the <OK> button and you must start the API PRO system once again from
you desktop and the following window will appear:
In the first field you must enter the name of your company, for example ‘API Maintenance
Systems A/S’. In the second field, you must enter the licence code that you have received
from your local API PRO distributor. If you have a normal system, then this is typically a
code of 3 characters and 3 digits, for example DKK004. If you have an evaluation system, it
is typically a code starting with an E- and then a number of digits, for example E-4038. Be
aware, this licence code is case sensitive!
If you press the <OK> button, the following screen will appear:
Here you can import the licence codes from the file that you have received by pressing the
<Import> button.
The license codes (LIC file) will normally be installed in the \APIPRO7\WORK directory.
The system will ask you whether you have imported the correct licence codes.
Press Ok and exit the Module access codes program.
If you have received the codes on paper, you must enter them manually in this program.
When all licence codes have been entered, the <OK> button must be pressed. You will now
get the login screen and you can enter the API PRO system.
Replacing evaluation system license codes with
official license codes
In this case, you should log-in as SUPERVISOR and run the program ‘Module access codes’
under the ‘System’ menu. In this program you should delete the access codes for the Basic
System Module.
Then you press the <OK> button and the following message will appear:
From here, you must follow the same steps as when your evaluation system has expired.
Section N – Dump and Load
data
This Section explains how the API PRO data dump and load tools are used.
The dump program DUMP-API creates a set of .D files in a directory. A .D file for each
table in database is created. The .D files are plain text files which have one line for each row
in the table. When dumping data, a snapshot of the database is taken. Due to inconsistency
problems normally all users should be logged out of API PRO. If DUMP-API is used for
backing up the database, all users must log out.
The load program LOAD fills up an empty database with data. The data must be a set of .D
files created with DUMP-API. The .D files must be located in a directory. LOAD populates
the API PRO tables with the data found in the entered directory.
DUMP-API and LOAD used in connection is a simple tool for making an exact copy of a
database. This can be useful in support issues.
Dump of data
Logon to API PRO. Select the Run External option from the Basic menu.
Enter in the program: FIX-DB/DUMP-API.R
*Note – The dump format will be Numeric (american) and the Date –format will be DMY
Enter the destination directory for the dump.
You will be told when it is finished.
Load of data
The command file \APIPRO7\SETUP\LOAD.CMD can be used for invoking LOAD-API.
The destination database is referenced in the PF file in LOAD.CMD.
It is not possible to load data into a database with data.
Enter the source directory for the load. I.e. where the set of .D files is located.
When the load is finished you can check the the load directory for .E files. They will contain
errors encountered during the load.
If no errors were found the database is ready for running API PRO.
Section O – Progress
licencing information
General Information
Progress OpenEdge Software Components
Personal database (C)
Single-user database software. This software must also be
installed in order to use the translation tool.
Workgroup Database (S)
on a single-CPU machine.
Database server software for smaller systems (max. 20 users)
Enterprise Database (S)
Database server software for large systems.
Appserver Database (S)
AppServer software.
Query/RESULTS (C)
Results report generator.
The Progress OpenEdge ‘Run-time’ software, including the
Client Networking (C)
The Progress OpenEdge software taking care of the
communication between the client and the server. This software is the Progress OpenEdge
equivalent of Oracle’s SQL*Net.
Oracle Dataserver (C)
Oracle database.
‘Interface’ between the Progress OpenEdge programs and the
(C) This component can be installed with the Progress OpenEdge client software installation
program.
(S) This component can be installed with the Progress OpenEdge server software installation
program.
Section P – Architecture
Because of the flexibility of the API PRO system and the availability on many different
platforms, there are many possible architecture variants for an API PRO system.
This Section describes some of the most common variants.
Client-Server Architecture
API PRO is a client-server system. For many people, the client-server concept is not easy to
understand. We often experience that we are called the day after the installation of the
system, because the system cannot be started. It then appears that the database server has not
started. Therefore it is important to understand that the database server process and the client
process are two separate processes which can be started and stopped independently. The
database process does not stop automatically when the last user has logged out of the system.
During normal operation of the system there is no need to stop the database process. This is
normally only needed when software upgrades are made, when a copy of the database must
be made, etc.
The tables below help to understand how the API PRO components should be installed
depending on the architecture, preferred by you.
Table 1. Configuration with separate machines for Client, Database server and
Application server.
Client
Application Server
Database server
API PRO CSM Baseline
OpenEdge 10.2B
OpenEdge 10.2B
API PRO CSM client
API PRO Image
API PRO Database
Table 2. Configuration with the same machine as Database and Application
server
Client
Database and Application server
API PRO CSM Baseline
OpenEdge 10.2B
API PRO CSM client
API PRO Image
API PRO Database
Table 3. Configuration with the same machine for Client, Application and
Database server
Client, Database and Application server *)
OpenEdge 10.2B
API PRO Image
API PRO Database
API PRO CSM Baseline-Server
API PRO CSM client **)
*) Possible to run with-out AppServer
**) Not needed can run directly on API PRO Image
Difference between Database Server and File
Server
In an API PRO installation, there is normally a database server and file server. In many cases
it is physically the same machine, but this is not necessary. There is often much confusion
about the difference between the database server and the file server.
The database server is the machine where the Progress OpenEdge server software is loaded
and where the API PRO database is located. Besides there is some kind of communication
protocol installed. On this machine the database server process must be started and stopped.
The file server is a machine with a large hard disk. Many PC’s in the network can access this
hard disk. For this reason, it is practical to install the Progress OpenEdge client software and
the API PRO programs on this common hard disk. If there is no file server available (this
appears occasionally in UNIX installations) the client software (Progress OpenEdge client
software and API PRO programs) can be installed on the local hard disks of the client PC’s.
In order to decrease network traffic and improve the performance the client software may
also be installed on the local clients, or a local file server.
Nowadays, Citrix and Windows Terminal Server are more and more common. They reduce
the needed bandwidth between client and server and they make the maintenance of the clients
easier.
Here are some examples of common configurations:
1. Configuration with the same machine as database and
fileserver
2. Configuration with separate database and fileserver
3. Configuration with combined database, file and terminal server
The thin line between the client and the server indicates the limited needed bandwidth.
4. Configuration with separate database server and combined file
server and terminal server.
The thin line between the client and the server indicates the limited needed bandwidth.
Section Q - OpenEdge
database administration tasks
On-line backup
On most server platforms with Progress OpenEdge databases (except for single-user) it is
possible to make an on-line backup of your API PRO database. The advantage of an on-line
backup is that you can continue working with the API PRO system while the backup is made.
To you make an off-line backup, you need to always shut down the database before you
start the backup!
On all API PRO systems with a MS SQL or Oracle database, we suggest that the product
backup procedures are used to make a backup of the API PRO database. We refer to the
product documentation for more information about this.
The on-line backup of the API PRO database can be made with the special Progress
OpenEdge backup tools. For detailed documentation about this tool, we refer to the
‘OpenEdge Data Management - Database Administration’.
Here we will give some hints, which are useful, when you want to make on-line backups of
the database.
Backup on Windows 2000/2003 using a Progress
OpenEdge database
We suggest that you make a small .CMD file, which calls the Progress OpenEdge backup
tool. In our example, the database is situated on the NT server on drive D:\ in the directory
API-DB. The backup-file will be stored in the directory BACKUP on drive D:\. The contents
of this directory will be copied onto a tape every night.
The directory API-DB with the API PRO database should NOT be backed up to
the tape while the database is running. This might damage you database.
API3BACK is the name of the backup file (it has no extensions)
The backup database in “D:\backup\api3back”
which is created by online is the one to
backup….
Example of the file ONLINE.CMD:
d:
cd \API-DB
probkup online API3 D:\BACKUP\API3BACK
When the ONLINE.CMD command is executed, a file with the name API3BACK will be
created in the directory D:\BACKUP. This directory must exits.
The ONLINE.CMD command can be called in many ways, from the Windows Explorer,
with a shortcut, etc. In order to test the backup, we suggest that you call the command from a
DOS box. If any error messages would appear, then they will be easy to read.
It is highly recommended that the backup file is verified by doing the following three steps:
1.
Restore the backup file (see next paragraph)
2.
Truncate the restored database with \APIPRO7\WORK\TRUNCATE.BAT
3.
Connect to the restored database in single user mode
If these three tasks can be accomplished without errors, the online backup was successful.
Restore
In order to restore the backup, you also need to use the Progress OpenEdge tools. We suggest
that you never restore a database directly over the existing database, in order to avoid that
you overwrite your working database with an old backup by accident.
The following RESTORE.CMD file can be used to restore the backup file, which was made
with the ONLINE.CMD file. The filenames of the restored database files will be
API3REST.BI and API3REST.DB.
Example of RESTORE.CMD:
d:
cd \API-DB
prorest API3REST D:\BACKUP\API3BACK
In this example:
API-DB
is the directory where the database will be restored.
APIREST
is a new name for the database
API3BACK is the name of the ‘online‘ backup file of the database
If you now want to replace the original database with the restored database, then you should
make a security copy of all files in D:\API-DB and then rename API3REST.* to API3.*
After renaming the database you will need to run PROSTRCT:
Unable to open copy database….
If the database is created using a copy of api3.db, api3.b1 etc the full path is stored in the
database and you need to repair the structure to make it work.
Run the following command in a Proenv command prompt:
prostrct repair dbname ( where dbname is the name of the database)
Note: There might be many reasons why your backup may not work correct. The only
guarantee you have that your backup procedure works correctly is to restore the backup and
test the database.
Making a backup automatically every night
With the Schedule tool on Windows 2000/2003, it is possible to make automatically an online backup of the API PRO database at a certain time.
Choose the Services icon in the Windows 2000/2003 Control Panel. There is a service called
‘Schedule’. This service should be started. The service should also be set up to start
automatically when the server is rebooted.
From the DOS box, it is possible to submit a job to the scheduler with the following
command:
AT 22:00 /every:m,t,w,th,f,sa,su
DB\ONLINE.CMD
cmd
/c
D:\API-
Now the on-line backup will be executed automatically every evening at 22.00 h.
For more information about the Schedule tool, please read the Windows 2000/2003
documentation.
Hint: You can also use the “Scheduled Task Wizard” function. Select the “add scheduled
task” and follow the wizard. This is a more user-friendly way to set-up a schedule.
Is is recommended to make 5-7 online.cmd file (one for each day). Then if something is
happening there will be 5-7 different backup databases where at least one of them is not
corrupted.
Cmd file
name of backupdatabase
schedule task
Online1.cmd
API3BACK1
AT 22:00 /every:m cmd /c C:\APIDB\ONLINE1.CMD
Online2.cmd
API3BACK2
AT 22:00 /every:t cmd /c C:\APIDB\ONLINE2.CMD
Online3.cmd
API3BACK3
AT 22:00 /every:w cmd /c C:\APIDB\ONLINE3.CMD
Online4.cmd
API3BACK4
AT 22:00 /every:th cmd /c C:\APIDB\ONLINE4.CMD
Online5.cmd
API3BACK5
AT 22:00 /every:f cmd /c D:\APIDB\ONLINE5.CMD
Online6.cmd
API3BACK6
AT 22:00 /every:sa cmd /c D:\APIDB\ONLINE6.CMD
Online7.cmd
API3BACK7
AT 22:00 /every:su cmd /c D:\APIDB\ONLINE7.CMD
Note: Please remember that the online backup file should also be backed up to tape or
copied to another server.
Expand an OpenEdge database
A standard Progress workgroup database has a maximum size of 2 GB. When the customer
gets the error "SYSTEM ERROR: Attempted to exceed maximum size on
file . (9452)", then it will be necessary to expand the database
Option 1:
The database is a “standard” database (d1,b1 and db)
Make probkup (with the original api3.st – NOT the new api3.st).
Install the modified api3.st file in the directory where the database is located.
This is how the api3.st file could look like for a database with 4 extents of 1 GB and one
variable extent of up to 2 GB:
#
b api3.b1
#
d "Schema Area":6,32 api3.d1 f 1048576
d "Schema Area":6,32 api3.d2 f 1048576
d "Schema Area":6,32 api3.d3 f 1048576
d "Schema Area":6,32 api3.d4 f 1048576
d "Schema Area":6,32 api3.d5
Now move the original database (the files api3.b1, api3.d1, api3.db and api3.lg) to a different
directory.
Make prorest. This will force the database to get the new big size.
Option 2:
Database is located on c:\apidb\live\api3.
Open Proenv command and go to c:\apidb\live\
Create the following file with name add.st
# a fixed length data file of 2GB
d "Schema Area":6,32 . f 1048576
d "Schema Area":6,32 . f 1048576
d "Schema Area":6,32 . f 1048576
d "Schema Area":6,32 . f 1048576
# a variable length data file with a maximum size of 2GB
d "Schema Area":6,32 .
Execute following commands from Proenv command:
prostrct add api3 add.st
proutil api3 -C truncate
prostrct list api3 api3.st
If you want to restore a database on another directory than where
the probkup was done:
REMEMBER to install api3.st in the directory where the restore of the backup is to be
done!!!!
REMEMBER to modify the path names in the api3.st file to reflect the new directory.
Remove user (multi user PROGRESS OpenEdge
database ONLY)
Following command will list current users of database and offer possibility to shut down.
PROSHUT <db> -N TCP -H <server> -S <port/service string>
Sample:
\\nt3\dlcnt\bin\proshut api3 -N TCP -H nt3 -S work04
OpenEdge Release 10.2B01 as of Tue May 9 05:28:51 EDT 2006
usr
pid
time of login
user id
tty
Limbo?
7 2732 Thu Jul 20 10:58:54 2006 biw
no
8 3344 Thu Jul 20 10:58:56 2006 wdog
no
9 3772 Thu Jul 20 10:58:58 2006 apw
26 2280 Thu Jul 20 11:01:25 2006 an
1 Disconnect a User
2 Unconditional Shutdown
x Exit
Enter choice>
no
allan4
no
Section R - Server setup and
server tools
Permission for end-user on the fileserver
Note there are file permissions, folder permissions and share permissions
Following tables are all related to Windows 2000/2003 folder permissions.
Runtime user without compile or change of terminology:
Folder
Permission
\APIPRO8\DLCWIN + subdirectories
Read & Execute
\APIPRO8\WORK
Full
\APIPRO8\WORK subdirectories
Read
Tempdir
Full
If user wants to compile or change terminology:
Folder
Permission
\APIPRO8\DLCWIN + subdirectories
Read & Execute
\APIPRO8\WORK + subdirectories
Full
\APIPRO8\XCODE
Modify
\APIPRO8\XCODE subdirectories
Read
\APIPRO8\CUSTOM
Modify
\APIPRO8\CUSTOM subdirectories
Read
Tempdir
Full
If user wants to install API PRO service packs, fixes or customizations:
Folder
Permission
\APIPRO8\DLCWIN + subdirectories
Read & Execute
\APIPRO8\WORK + subdirectories
Full
\APIPRO8\XCODE
Modify
\APIPRO8\XCODE subdirectories
Modify
\APIPRO8\CUSTOM
Modify
\APIPRO8\CUSTOM subdirectories
Modify
\APIPRO8\SETUP
Modify
\APIPRO8\SOURCE
Modify
\APIPRO8\
Modify
Tempdir
Full
If user wants to install API PRO clients:
Folder
Permission
\APIPRO8\SETUP
Read
If user wants to install Progress OpenEdge patches:
Folder
Permission
\APIPRO7\DLCWIN + subdirectories
Modify
If user wants to install/uninstall the API PRO client file structure:
Folder
Permission
\APIPRO8 + subdirectories
Full
File permissions
File permissions include Full Control, Modify, Read & Execute, Read, and Write. Each of
these permissions consists of a logical group of special permissions. The following table lists
each file permissions and specifies which special permissions are associated with that
permission.
Special Permissions
Full Control
Modify
Read & Execute
Read
Write
Traverse Folder/Execute File
x
x
X
List Folder/Read Data
x
x
X
x
Read Attributes
x
x
X
x
Read Extended Attributes
x
x
X
x
Create Files/Write Data
x
x
x
Create Folders/Append Data
x
x
x
Write Attributes
x
x
x
Write Extended Attributes
x
x
x
Delete Subfolders and Files
x
Delete
x
x
Read Permissions
x
x
X
x
x
Change Permissions
x
Take Ownership
x
Synchronize
x
x
X
x
x
Event viewer setup
We have discovered that many has problems on the server and workstations with the
databases, because the event viewer is not configured correctly.
The Default event view has log size is "Overwrite events older than 7 days"...
The Event view should have option set "overwrite events as needed" instead
It is also possible to set parameter in startup or in environment settings:
Managing Progress Events on NT
You can define the level of event logging that you want your Progress OpenEdge application
to support by using the Event Level Environment Variable (EVTLEVEL), or the Event Level
startup parameter (-evtlevel). Use the ProControl utility to supply the Event Level as a startup
parameter or environment variable.
none:
No Progress OpenEdge events are written to the event log.
brief:
Progress OpenEdge messages defined as Error and Warning messages
are written to the event log.
normal:
Progress OpenEdge messages defined as Error and Warning messages are
written to the event log. In addition, any Progress OpenEdge message that is normally written
to the log file (.lg) is also written to the Event Log. This is the default.
full:
Every message generated by Progress OpenEdge is written to the Event
Log. Any Progress OpenEdge messages generated using the Message Statement are also
written to the log file.
When using environment:
Make sure the variable is set to all small letters and that EVTLEVEL is all caps. This will
ensure that Windows recognise the setting.
Examples
Startup parameter:
Environments
-evtlevel brief # Only errors and warnings written to event log
EVTLEVEL brief
Section S - Installation on
Citrix
Installation of API PRO in a Citrix environment
To perform this type of installation, API PRO and Citrix knowledge is a recommended
prerequisite.
API PRO have been installed and tested in a Citrix Metaframe 1.8 for windows 2000
environment. In this environment API PRO can be launched through the intranet or an
extranet by use of the ‘normal’ ICA client or through the internet via an internet browser – by
use of the Nfuse product from Citrix - with automatically download of a minimal WEB ICA
client (approx. 300 Kb).
It is also possible to use the API PRO barcode reader solution when running with a normal
ICA client setup.
This note takes the minimal approach to installation of API Pro in a Citrix environment. So it
will not cover access through an internet browser by use of Nfuse, because this is more a
question about installation and configuration of Citrix that a question of installing API PRO.
Actually the installation described below will be directly reusable when running through an
internet browser.
Installation of API PRO
Additional information about the steps below can be found in the API PRO “Installation
guide”. The following chapters should be read before starting the API PRO/Citrix
installation:
1. Progress OpenEdge client
2. API PRO software
3. Configuration of ini and pf files.
4. Client setup
So to get up and running, follow the steps below:
Step 1. Install Progress OpenEdge software.
Set Citrix in install mode.
Start a command prompt and type:
CHANGE USER /INSTALL
Then install Progress OpenEdge and apply the latest recommended Progress OpenEdge patch
– remember to stop any Progress OpenEdge service before applying the patch.
If this Citrix server is not going to be used as Database server or AppServer then only install
OpenEdge client licenses.
If it is going to use for both running client and AppServer and/or Database server then install
all OpenEdge licenses.
After installing Progress OpenEdge toggle Citrix back into execute mode.
Start a command prompt and type:
CHANGE USER /EXECUTE
Step 2. Install API PRO ‘image’.
Transfer the API PRO ‘image’ to the Citrix server by following the instructions in the
Section E - Installing the API PRO Client Software. The only difference in the installation
procedure is that the installation should be carried-out directly on the Citrix server – not from
a client, as stated in the documentation.
Step 3. Install API PRO on the client.
The client in this case is the Citrix server. So change to install mode by typing:
CHANGE USER /INSTALL
in a command prompt. After changing to install mode install the components that is needed
to run API PRO on the Citrix server. This is very similar to the “Client setup” described in
Section F - Configuring the API PRO Clients – except for the fact – that there is no need to
run the NETSETUP to install Progress OpenEdge – because at this point - Progress
OpenEdge is already installed on the Citrix server.
(Also note that NetSetup is not supported with Citrix)
After installing/configuring the needed component – please remember to leave out Netsetup
(Progress):
API PRO Client setup
Service/host
Change back to execution mode by typing:
CHANGE USER /EXECUTE
at a command prompt.
Step 4. Configure Windows/Citrix environment.
A few adjustments to the Windows/Citrix environment is needed to handle more than one
API PRO client on the same machine. Each API PRO client must have its own temporary
directory to be able to run. This can be done in several ways. The solution described below
makes use of a drive substitution to give each user a separate temporary directory.
Make a ‘root’ for the temporary directory. Could be:
MD
{drive}:\TEMPTRIX
Apply the following to the start of the common login file on the server
(%SYSTEMROOT%\SYSTEM32\USRLOGON.CMD) – substitute {drive} with the actually
drive letter:
If exist {drive}:\temptrix\%USERNAME% goto endtemp
MD {drive}:\temptrix\%USERNAME%
:endtemp
subst x: {drive}:\temptrix\%USERNAME%
In order to reflect the new location of the users temporary directory the –T parameter should
be changed to:
-T X:\
in the following pf files:
Apipro.pf
Rb.pf
Autocomp.pf
The windows environment variable DSLOGDIR is set to “C:\TEMP” by the client
installation. This should be changed to “X:\”.
All that is needed now is to make a Published Application in the Citrix environment to get
access to API PRO. So create a Published application with the following arguments:
MetaFrame tools - Published Application Manager
Name: APIPRO
Choose application type: Explicit
Command line and working directory:
{drive}:\APIPRO7\dlcwin\bin\prowin32.exe -pf apipro.pf ininame apipro.ini
{drive}:\APIPRO7\work
Set: "Maximize application at start up" check box
Sound and Video support can be disabled and resolution could be 800x600 with 256 colors.
After creation of the published application – logon with one of the users that you have
allowed access to API PRO.
Step 5. Configure support for BarCode reader.
In order to enable support for a locally connected Barcode reader you must redirect your
local com port to be available in from inside your Citrix environment.
You could check the Citrix documentation and/or the support pages on www.Citrix.com on
how to set up access to a local com port can be found. The document:
CTX637252 How to Synchronize a PDA (Palm) Device over a RAS ICA Connection.
Other entries of interest could be:
CTX384590 Troubleshooting COM Port Redirection Issues in Citrix in WinFrame,
MetaFrame, and MetaFrame XP
In general you must use the:
NET USE COMx: \\CLIENT\COMy:
To redirect your local port to a port in the Citrix environment. Afterwards you must off cause
reconfigure API PRO to reflect the new com port. So if you redirect your local com1 to com3
on the Citrix sever (actually the Citrix client session) you must change for example the
barcode reader com1 to com3 – because this is the way it is seen from inside your Citrix
client session.
Additional notes.
As always the involved companies support pages on the internet is interesting. For example
the following Progress Knowledge base entries:
19842 Tuning Progress on MetaFrame/WinFrame and Terminal Server.
18341 MetaFrame and Terminal Server Installation Notes
will give you some hints on what to do to increase performance.