api pro cmms api pro 8 installation guide · using the installation guide please note: this...

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: [email protected]

WEB: www.apipro.com

Product Version: API PRO 8 Language: English

Manual Revision: 27th April 2014

Copyright 2014 by API Maintenance Systems A/S. All rights reserved Registered trademarks and trademarks are the property of their respective companies

mailto:[email protected]

http://www.frontec.se/

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




Installation ............................................................................................................................... 13

SQL SERVER DATABASE ................................................................................................................. 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


There are no special requirements before the 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


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


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.


The next step is to install the client software.


Install the application server (optional)

The next step is to install the application server.

Please read the ‘Section L AppServer’ for more information.




Compile the system



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 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.





- 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


In order to make an installation with an Oracle database you need the following user rights:


You will need a user ID and password for the API PRO schema on the Oracle database

Installation


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.







Compile the system



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 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.





- 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


In order to make an installation with an SQL Server database you need the following user

rights:


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.







Compile the system



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, ISO8859-1,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 fix-

char.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%\System32\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 ICU-

es__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.


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 (ICU-xxxx)

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.


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:

AppServer-Name=apipro8LiveAS

AppServer-Host=localhost

AppServer-Port=5162

Apipro.ini:

;AppServer-Name=apipro8LiveAS

;AppServer-Host=localhost

;AppServer-Port=5162

Apipro.pf

#-db api3

#-ld api3

#-N TCP

#-H 192.168.7.10 (Server IP)

#-S 2550

Apipro.pf

-db api3

-ld api3

-N TCP

-H 192.168.7.10 (Server IP)

-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.


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>


…

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>


…

Compile.pf

Batch compile (only) processing uses the set-up from CSM/compile.pf:

C:\APIPRO\APIPRO6\api3 # Database

…

-b # Batch mode

-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


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 : 768 by 1366 pixels = 32 by

195,14 characters

Session code Page : UTF-8

Stream code Page : UTF-8

Numeric format : , = thousand delimiter ' '

decimal point ','

Date format : 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

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.


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: \PRO-

DB\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".

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-ORACLE-

10G-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-ORACLE-

10G-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".

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.

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

AppServer-

URL=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 AppServer-

Name, 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) Database server software for smaller systems (max. 20 users)

on a single-CPU machine.

Enterprise Database (S) Database server software for large systems.

Appserver Database (S) AppServer software.

Query/RESULTS (C) The Progress OpenEdge ‘Run-time’ software, including the

Results report generator.

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) ‘Interface’ between the Progress OpenEdge programs and the

Oracle database.

(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 on-

line 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 cmd /c D:\API-

DB\ONLINE.CMD

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.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 no

26 2280 Thu Jul 20 11:01:25 2006 an allan4 no

1 Disconnect a User

2 Unconditional Shutdown

x Exit

Enter choice>

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\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\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: -evtlevel brief # Only errors and warnings written to event log

Environments 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.

http://www.citrix.com/

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.

api pro cmms api pro 8 installation guide · using the installation guide please note: this...

Documents