API PRO CMMS

Client Server
Management

By API Maintenance Systems A/S

 API Maintenance Systems A/S
Sydvestvej 21, 2
DK-2600 Glostrup
Denmark
Tel. +45 4348 9900
Fax. +45 4348 9901
E-mail: support@apipro.com
WEB: www.apipro.com

Product Version: API PRO 9.

Language: English
Manual Revision: 3rd August 2018

Copyright  2018 API Maintenance Systems A/S. All rights reserved

Registered trademarks and trademarks are the property of their respective companies

API PRO -2 - Client Server Management

TABLE OF CONTENTS
OVERVIEW ................................................................................................................................................. 5
INSTALLATION ......................................................................................................................................... 6
1. Create or modify CSM/batch.ini .................................................................................................... 7
2. Create or modify CSM/batch.pf ..................................................................................................... 7
3. Create or modify CSM/compile.ini ................................................................................................ 8
4. Create or modify CSM/compile.pf ................................................................................................. 8
5. File changes in AppServer ............................................................................................................. 9
6. Create CSM/client.ini .................................................................................................................. 10
7. Create CSM/client.pf ................................................................................................................... 11
8. Create client packages (using CSM-initiator) ............................................................................. 12
CSM ADMINISTRATION ........................................................................................................................ 13
Simple .................................................................................................................................................. 14
Advanced ............................................................................................................................................. 16
Initiator ................................................................................................................................................ 18
Editor ................................................................................................................................................... 31
Other options ....................................................................................................................................... 33
Additional configuration...................................................................................................................... 44
INSTALL A CLIENT ................................................................................................................................ 47
Install the BaseLine ............................................................................................................................. 47
Install an API PRO system .................................................................................................................. 49
Command line install ........................................................................................................................... 56
Uninstall an API PRO system .............................................................................................................. 57
BEHIND THE SCENE ............................................................................................................................... 58
Start API PRO at a client: ................................................................................................................... 58
Command line interface....................................................................................................................... 63
Client configuration............................................................................................................................. 69
CSM WORKFLOW ................................................................................................................................... 71
Load ..................................................................................................................................................... 71
Compile ............................................................................................................................................... 72
Deploy ................................................................................................................................................. 74
HOW TO ..................................................................................................................................................... 75
Add/change some files ......................................................................................................................... 75
Add a program ..................................................................................................................................... 76
Delete some files .................................................................................................................................. 77
Fat initiator ......................................................................................................................................... 78
Reject login .......................................................................................................................................... 79
CSM event............................................................................................................................................ 79
Overwrite file-type ............................................................................................................................... 80
Advanced MSI-library ......................................................................................................................... 81
UNC client ........................................................................................................................................... 81
Add an “interface”-database for compile ........................................................................................... 82
Check AppServer continuously for changes ........................................................................................ 83
Load new data-definitions ................................................................................................................... 84
Change BaseLine location ................................................................................................................... 85
Master/slave(s) setup ........................................................................................................................... 86
Protect files .......................................................................................................................................... 87

API PRO -3 - Client Server Management

TRANSLATION ......................................................................................................................................... 89
Add/change translation databases ....................................................................................................... 89
Add/change languages ......................................................................................................................... 91
Add/change translations ...................................................................................................................... 92
FILE-SYSTEMS ......................................................................................................................................... 94
Client file-system ................................................................................................................................. 94
Build file-system .................................................................................................................................. 96
AppServer file-system .......................................................................................................................... 98
DATA BASE ............................................................................................................................................. 103
Build-lock .......................................................................................................................................... 103
Change-lock....................................................................................................................................... 103
KNOWLEDGE BASE .............................................................................................................................. 104
Uninstall the present installed version first ....................................................................................... 104
Initial window not on top ................................................................................................................... 105
Clients always downloads ................................................................................................................. 105
System not compiled with chosen language ....................................................................................... 106
Load fails ........................................................................................................................................... 106
Compile fails ...................................................................................................................................... 107
Build not deployed ............................................................................................................................. 108
Progress error -127 ........................................................................................................................... 110
Progress error 43 .............................................................................................................................. 110
Progress error 477 ............................................................................................................................ 111
Progress error 1006 .......................................................................................................................... 111
Progress error 1403 .......................................................................................................................... 112
Progress error 2886 .......................................................................................................................... 112
Progress error 2888 .......................................................................................................................... 113
Progress error 4025 .......................................................................................................................... 114
Progress error 4454 .......................................................................................................................... 115
Progress error 5622 .......................................................................................................................... 116
Progress error 5898 .......................................................................................................................... 116
Progress error 6087 .......................................................................................................................... 117
Progress error 9331 .......................................................................................................................... 119
Progress error 11274 ........................................................................................................................ 119
Error 0xc0150002 ............................................................................................................................. 120
LIMITATIONS......................................................................................................................................... 121
Package-size ...................................................................................................................................... 121
File-size ............................................................................................................................................. 121
File-name........................................................................................................................................... 121
Editor-size ......................................................................................................................................... 121
ENHANCEMENTS AND RELATED FIX-PACKAGES ..................................................................... 122

API PRO -4 - Client Server Management

 Overview

CSM or Client Server Management handles common tasks for keeping the API PRO
application updated – including:
• Install product updates like fix-packages, custom-packages or new service packs.
• Produce MSI-packages for easy setup of clients.
• Avoid the use of a file-share between the AppServer and clients.
• Ensure the local image of the application is up-to-date.

To do this CSM needs to be configured at the AppServer (running 7.0SP05 or newer).

API PRO -5 - Client Server Management

 Installation

In order for Client Server Management tool to work, some of the setup files need to be
configured on the AppServer. From API PRO 8.00.00 SP00E this can be done using the
Editor of the Client Server Management-program found in the System menu:

The setup files can be edited directly at the AppServer too, and they are all placed in the
CSM/-directory next to XCODE/ and WORK/:

Steps 1 to 5 below deals with the AppServer setup, and steps 6 to 8 helps configure the
setup to be installed on the client machines.

API PRO -6 - Client Server Management

 1. Create or modify CSM/batch.ini
Batch processing uses CSM/batch.ini:
...
[Startup]
;DLC=<dlc>
...

Note: Text after a semicolon (;) in .ini-files is ignored and can be used for comments.

Section Startup:
• Set DLC or inherit value from the system environment.

Tip: Use a System-Environment-Variable to make this value available at the AppServer.

2. Create or modify CSM/batch.pf

Batch processing uses CSM/batch.pf:
-db C:\APISERVER\APITEST9\DB\api3
...
-T C:\temp # Temporary Files
-cpcoll ICU-UCA # Default utf-8 linguistic collation
-inp 64000 # Max statement size
-nocandodomain # Restore CAN-DO() functionality
...
-b # Batch mode
-p csm/server.p # Startup Program
...

Note: Text after a hashtag (#) in .pf-files is ignored and can be used for comments.

• Add option -ld api3 if the name of the database is something different from
api3.
• If option -T is used, then make sure the directory exists.
• Option –cpcoll should match the setup of the database:
Default value is: ICU-UCA.

• Option –inp should be set to no less than 64000 for Progress 10.2B06 and newer.
• Option -nocandodomain should be included for OpenEdge 11.6 and newer.
• If an option like -p has more than one assignment the last one will be used.

Tip: Use a direct database connection if possible as this will allow the AppServer to be
offline while deploying business critical changes to the system.

API PRO -7 - Client Server Management

 3. Create or modify CSM/compile.ini
Batch compile (only) processing uses the setup from CSM/compile.ini:
...
[Startup]
;DLC=<dlc>
PROPATH=.,..\CUSTOM,..\XCODE
...

If this file is missing CSM/batch.ini will be used instead.

Section Startup:
• Set DLC or inherit value from the system environment.
• Ensure PROPATH is correct.

Tip: Use a System-Environment-Variable to make this value available at the AppServer

4. Create or modify CSM/compile.pf

Batch compile (only) processing uses the setup from CSM/compile.pf:
-db C:\APISERVER\APITEST9\DB\api3
...
-T C:\temp # Temporary Files
-cpcoll ICU-UCA # Default utf-8 linguistic collation
-inp 64000 # Max statement size
-nocandodomain # Restore CAN-DO() functionality
...
-b # Batch mode
-rx # Enable compile of xcode
-p csm/compile.p # Startup Program
...

Note: If this file is missing, then CSM/batch.pf will be used. Using this approach
requires a full Progress / OpenEdge license for the system 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 of Xcoded source. The other listed options are
described in the section: Create or modify CSM/batch.pf.

Using nested .pf-files the setup can be inherited from CSM/batch.pf directly:
-pf C:\APISERVER\APITEST9\CSM\batch.pf
-rx # Enable compile of xcode
-p csm/compile.p # Startup Program

API PRO -8 - Client Server Management

 5. File changes in AppServer
Files monitored by CSM need to be documented. This is done by the Recompile & deploy-
option of the Client Server Management-program.

All programs will be compiled and will together with the other files (help-files, crystal
report setups...) be recorded, so future changes to the WORK/-directory of the AppServer
will be found and optionally forwarded to the clients at next login.

Until this step has been successfully completed, clients will get a full client image at every
login.

Important note: If the application cannot be accessed from the AppServer (due to
restrictions or missing packages like CodeJock) the CSM/check.cmd script can be used
just after SETUP/compile.cmd to record the new status of the application.

API PRO -9 - Client Server Management

 6. Create CSM/client.ini
WORK/apipro.ini will be used as a template for CSM/client.ini, but if some
changes should be made for the CSM-clients only, this file should be used.
...
[Startup]
;DLC=
NoSplash=yes
OldBrowseSelectionBar=yes
...
[API PRO]
AppServer-Name=<name>
AppServer-Host=<dns> or <ip>
AppServer-Port=<port>
...
CodeJockVersion=<version>
;LOGIN-USER-ID=supervisor
;HIDE-SAVE-LOGIN=TRUE
...

Tip: It is recommended to use a DNS-entry for the AppServer, as this configuration could
make future changes to the network setup much easier to add.

Sections to update:
Startup:
• Remove DLC
• Set NoSplash=yes
• OldBrowseSelectionBar=yes could be included for OpenEdge 11.5 and
newer.
API PRO:
• Remove LOGIN-USER-ID
• Remove HIDE-SAVE-LOGIN
• Set AppServer settings and CodeJockVersion
By default, client.ini is considered to be a private file, which will not get updates from
the AppServer. However fix A15969 (see: Enhancements and related fix-packages) allows
a shared setup after a few modifications using the Editor:
• Copy CSM/client.ini to WORK/csm/common.ini if this file is missing.
• Copy WORK/client.cmd to CSM/client.cmd if this file is missing.
• Change CSM/client.cmd from:
-ininame client.ini
to:
-ininame csm/common.ini

API PRO -10- Client Server Management

 Now this part of the configuration will be managed by the AppServer. Optional changes to
WORK/csm/common.ini are made using the Editor and the next Check will make a
change-log for the clients.

Note: Any personalization, like the user id for “Remember me” or which CodeJock version
to use, will be overwritten.

7. Create CSM/client.pf
WORK/client.pf will be used as a template for CSM/client.pf, but if some changes
should be made for the CSM-clients this file should be used.
...
-cpcoll ICU-UCA # Default utf-8 linguistic collation
-nocandodomain # Restore CAN-DO() functionality
# -debugalert # Enable ABL stack trace
-mc # Compression
-p csm/client.p # Startup Program
...

Note: Text after a hashtag (#) in .pf-files is ignored and can be used for comments. In the
example shown above –mc is set and -debugalert is NOT set.

By default, client.pf just like client.ini is treaded as a private file which will not
get updates from the AppServer, but fix A15969 (see: Enhancements and related fix-
packages) allows for a shared setup after a few modifications using the Editor:
• Copy CSM/client.pf or WORK/client.pf to WORK/csm/common.pf
if this file is missing.
• Change CSM/client.pf to read from the common setup using a nested-pf:
-pf csm/common.pf

Now this part of the configuration will be managed by the AppServer. Optional changes to
WORK/csm/common.pf are made using the Editor and when done, a Check will make a
change-log for the clients.

Note: If an option like -lng has more than one assignment, then the last one will be used.

This allows for some level of personalization as the client could have control of which
language to use as well as the language option of the Initiator assigns to CSM/client.pf
and not to WORK/csm/common.pf.

API PRO -11- Client Server Management

 8. Create client packages (using CSM-initiator)
Run the Client Server Management-program and produce a ZIP or MSI package for the
clients (See: Initiator).
Alternative the files required can be exported to INIT/ using the Export files (Initiator)
menu-option or by running the CSM/init.cmd script.
The generated folder can be copied to another location where the WiX-Toolset is installed
(as mentioned later in this guide) or loaded into another API PRO system using Load setup-
option.

API PRO -12- Client Server Management

 CSM administration

The Client Server Management-program is found in the System menu:

Here supervisors have access to most of the functionality CSM provides.

The administration is divided into a set of tabs.

API PRO -13- Client Server Management

 Simple
At start-up the status for the latest build is shown. The entire frame is a drop-zone accepting
archives, libraries, 4gl-files and root-directories.

If the build is being processed by the server, the dialog will be auto-updated every 2
seconds showing the status in the 3 boxes which match the 3 major steps in the CSM-
workflow.

Load
Box showing the status of the load process (1 of 3 steps):
(green) All files have been loaded at the build-area at the server.
(yellow) Files are being loaded.
(red) The package couldn’t be loaded.

Compile
Box showing the status of the compile process (2 of 3 steps):
(green) All programs have been compiled in the build-area at the AppServer.
(yellow) Compile not finished.
(red) An error occurred during the compilation.

Fix A16987 (see: Enhancements and related fix-packages) enable Compile log to be
triggered by a mouse-click in this box.

Deploy
Box showing the status of the deploy process (3 of 3 steps):
(green) The build has been deployed at the AppServer.
(yellow) Awaiting deployment.
(red) An error occurred during the deployment.

Fix A16987 (see: Enhancements and related fix-packages) enable Change log to be
triggered by a mouse-click in this box.

API PRO -14- Client Server Management

 The buttons in the bottom of the dialog provides 3 ways to start the work-flow:

Load & deploy

The standard “open-file-dialog” appears with relevant filters.
Besides zip-archives, progress-libraries can be loaded too.
Loading an archive or library will unpack the files to a temporary directory at the client and
then Load begins. The same happens if the archive is dropped in the drop-zone.

Recompile & deploy

Create a new empty build and mark it for a total compile.
This function can be used when changes are made to the translations setup.
Used at install-time to make the initial documentation of the updated application.

Import & deploy

The standard “open-directory-dialog” will allow directory-structures to be loaded.
Only roots of package are accepted, and at least one of the well-known sub-directories:
CLIENT/, CUSTOM/, XCODE/, WORK/ or special-files listed later needs to be present
otherwise the load will be rejected. The root can be dropped in the “drop-zone” to trigger
the same functionality.

To start the Load-phase the attached description is shown in a Load files?-dialog.

Here the user has to accept or reject the process to begin.

If the package is accepted the Load will start by creating a new build at the AppServer.
Then the files are uploaded from the client to the server without the need for a file-share.
The different ways of loading packages on this first Simple-tab, will all automatically
trigger the two next steps Compile and Deploy of the build.

API PRO -15- Client Server Management

 Advanced
The browser shows all the known builds and provides a broader set of functions to control
the CSM-workflow.

Unlike the deploy buttons found at the Simple-tab, the next steps of the CSM-work-flow are
not triggered automatically.

Load package
The standard “open-file-dialog” appears with relevant filters.
Besides zip-archives, progress-libraries may be used.
Loading an archive or library will unpack the files to a temporary directory at the client and
then Load begins.

Recompile
Create a new empty build and mark it for a total compile.
This function can be used when changes are made to the translations setup.

Import directory
Import a directory-structure to a new build.

Description
Show the description of the build having focus in the browser.

Compile build
Second step of the work-flow: Compile the build having focus in the browser.
A new batch-process is started at the AppServer.
Locked build can’t be compiled.
The process is documented in detail in the section: Compile.

API PRO -16- Client Server Management

 Deploy build
Third step of the work-flow: Deploy the build having focus in the browser.
The process is documented in detail in the section: Deploy.

Check
Do a manual check of the WORK/ and make a change-log if any changes are found,
including deletion of files. This function is part of the Deploy-phase.

Delete
Note: Fix A16959 (see: Enhancements and related fix-packages) or newer are required.

All selected builds (including related backups) and change-logs will be deleted in one
operation. Locked builds will be unlocked.

As an alternative to free up disk space, but keep the chronology of change-logs, old builds
can be unlocked and deleted.

API PRO -17- Client Server Management

 Initiator
This tab provides the capability to configure and make MSI-packages which ease the
installation at the clients.

Note: “WiX Toolset” found at: http://wixtoolset.org/ is required for making MSI-packages
and should be installed at the client running this setup.
Version 3.7, 3.8, 3.9, 3.10 & 3.11 of WiX have all been tested successfully.

Initial values are copied from the current installation:

System name
Default for title

Version
This value will follow the package even if the files are exported using the Initiator-option
and loaded and edited by another system running a different version of API PRO.
MSI-versions are numeric and values will be translated: 7.0.06 to 7.0.6.0,
8.0.00E to 8.0.0.5, 9.0.00 to 9.0.0.0 and 9.0.00B to 9.0.0.2.

License code
Default for installation directory, and part of a unique key for the package.

API PRO -18- Client Server Management

 Initially the setup will be loaded with copies of the initiator files from the active AppServer
(see: Workspace).

The most important values of the setup can be configured:

System/License
License code.

Version
MSI-versions are numeric and this field is not enabled by default.

Title
Used for the desktop shortcut, start-up menu, and control panel entry.

API PRO -19- Client Server Management

 AppServer URL
Connection parameter for the AppServer provided as an URL.
If this connection method is used, then leave AppServer Host, AppServer Port and
AppServer Name blank.
Sample value: http://workshop.apipro.com/aia/Aia?AppService=dkk004-
apitest9

Note: Fix-pack A13806 (See: Enhancements and related fix-packages) or newer are
required.

The setup is stored in the API PRO section of the .ini-file using the environment key:
AppServer-URL – see: Client configuration.

AppServer Host
Name of host, running the Name-server which provides the connection to the AppServer.
Sample value: workshop.apipro.com

The setup is stored in the API PRO section of the .ini-file using the environment key:
AppServer-Host – see: Client configuration.

AppServer Port
Port for Name-server on AppServer Host.
Progress default: 5162.

The setup is stored in the API PRO section of the .ini-file using the environment key:
AppServer-Port – see: Client configuration.

AppServer Name
Name of AppServer service.
Sample value: dkk004-apitest9

Note: This value is case-sensitive and typically assigned the same value as the name of the
AppServer, but this could be changed using Application service names:

The setup is stored in the API PRO section of the .ini-file using the environment key:
AppServer-Name – see: Client configuration.

API PRO -20- Client Server Management

 Reinstall method
Choose which method clients should use for a reinstallation.
This can happen if the chronology of the change-logs is broken (see: Issue reinstallation),
or be triggered by the options: Reinstall client or Reinstall clients.

Choose between:
• Default
Before the installation is removed the user has a chance to save local changes:

Answering:
Yes: Triggers the Export files (Client functions) option.
No: Proceed with the reinstallation and then a normal update.
Cancel: Leave the system. Next start-up will give the same dialog.
• Ignore request
Skip the reinstallation completly and proceed to a normal update.
• Show warning and enter
The dialog changes into a warning.

Answering:
OK: Skip the reinstallation and proceed with a normal update.
Cancel: Leave the system. Next start-up will give the same dialog.

API PRO -21- Client Server Management

 • Show error and quit
The dialog changes into an error and the system can not be entered:

• Reinstall silently
No dialog shows up.

• Disable option to export changes

The option is no longer available in the dialog:

Answering:
OK: Proceed with the reinstallation and then a normal update.
Cancel: Leave the system. Next start-up will give the same dialog.

• Do not delete the installation

The files and directories are not deleted.

The setup is stored in the API PRO section of the .ini-file using the environment key:
CSM-REINSTALL-METHOD – see: Client configuration.

API PRO -22- Client Server Management

 Check method
Choose which method clients should use to check the local client-image against the file-
system of the AppServer:

Programs have a MD5-value, which is used for tracking any change to the context.
Other data-files will only be compared looking at the file-size, since time-stamps are not re-
assigned after downloads.
Choose between:
• Default
Get a list of the changed files from last visit, or a complete list if the documentation
is missing.
This is the fast option which downloads changed client-programs (MD5-changed
and no database access). Other data-files are downloaded.
• Check all files
Get a complete list of programs and other data-files.
Client-programs will be downloaded if changed (MD5-changed and no database
access). Other data-files are downloaded, but if the server havn’t changed since last
visit only files with changed file-size will be updated.
Matches the LoadClient-command – see: Command line interface.

• Check all files, update data-files

Get a complete list of programs and other data-files.
Client-programs will be downloaded if changed (MD5-changed and no database
access).
All other data-files are downloaded.
Matches the ResetClient-command – see: Command line interface.
• Check and update all files
Get a complete list of programs and other data-files and download all.
Matches the ReloadClient-command – see: Command line interface.

The setup is stored in the API PRO section of the .ini-file using the environment key:
CSM-CHECK-METHOD – see: Client configuration.

API PRO -23- Client Server Management

 Restart notification
Note: Fix A17066 (see: Enhancements and related fix-packages) or newer are required.

Updating some files, like a .pf-file currently used by the client, require a restart before
changes are utilized and will normally issue this dialog after the update has completed:

The setup is stored in the API PRO section of the .ini-file using the environment key:
CSM-RESTART-NOTIFICATION – see: Client configuration.

Reject access after error

If any error occurs during update this option will reject access to API PRO:

The setup is stored in the APIPRO section of the .ini-file using the environment key:
CSM-REJECT-ACCESS – see: Client configuration.

API PRO -24- Client Server Management

 Hide ‘Remember me’
The login-dialog will hide the default Remember me-button.

Note: Fix A14611 (see: Enhancements and related fix-packages) or newer are required.

Can be useful for shared installations where the same instance of an .ini-file is used by
different users.
The setup is stored in the APIPRO section of the .ini-file using the environment key:
HIDE-SAVE-LOGIN – see: Client configuration.

Update ini-file
The AppServer values are written to the .ini-file (section: API PRO).
Other configuration-parameters are always updated.

Language
The default language when API PRO starts.

Update pf-file
The language value is written to the .pf-file.

Sample part of .pf-file

# client.pf
# CSM-client start-up '.pf'-file
# ========================================================================
-lng GBP # Language
...

API PRO -25- Client Server Management

 INSTALLDIR
Default installation directory at the clients.

“noconnect” file
File to launch in the default-viewer if connection to the AppServer fails.

Current setup
The location of the current workspace.

Shared package for all users

Normally the generated package will be installed for the current user only and NOT require
local administrator rights. Checking this toggle-box will change the package into a shared
installation for all users - i.e. using the same files at each client (even the .ini and .pf-
files) and will require local administrator rights to be installed as for the BaseLine.

Append “noconnect” file

If a noconnect-file is found, this could optionally be included to the package.
See: Reject login for more information.

Append additional files

If the workspace contains more files, these can be included to the package.
This could reduce the load of the first run.
See: Fat initiator for more information.

API PRO -26- Client Server Management

 Load setup
Load a previous saved setup into the workspace.
Subsequent Generate and Save set-up will update this workspace.

Note: The version of the package will not be changed, but keep the original value from
where the package was exported.

Generate
Choose a filename for the MSI-package.
If a named workspace is active, this will be updated.

Two utilities: candle.exe and light.exe of the “WiX Toolset” have to be located the
first time the client is used for making packages.

The setup will be saved in the current .ini-file under the API PRO-section:
...
[API PRO]
...
candle-command=C:\Program Files (x86)\WiX Toolset v3.11\bin\candle.exe
light-command=C:\Program Files (x86)\WiX Toolset v3.11\bin\light.exe
...

Note: If this setup is wrong – just delete the two lines from the .ini-file and point to the
right locations next time the function is used.

The WiX commands for making the package are:

candle.exe client.wxs -ext WixUIExtension -ext WixUtilExtension

and:
light.exe client.wixobj -ext WixUIExtension -ext WixUtilExtension -spdb -
out client.msi -sw1076

Save setup
If a named workspace is active, this will be updated otherwise the default temporary
workspace will be changed to the folder chosen.
Subsequent Generate and Save setup will update the same workspace.

Update setup
The entered values and initiator-files are stored at the AppServer.

API PRO -27- Client Server Management

 Test connection
Note: Fix A18947 (see: Enhancements and related fix-packages) or newer are required.

The entered values of the connection parameters for the AppServer AppServer Url or
AppServer Host, AppServer Port and AppServer Name are used and the result displayed
like:

or if the connection fails:

Remember the AppServer Name is a case-sensitive value.

API PRO -28- Client Server Management

 Workspace

The files used for the package (from the file-system at the AppServer) are:
Filename Description
CSM/banner.bmp Optional image.
CSM/client.cmd Client start-up script.
Should this file be missing the standard
WORK/client.cmd will be used.
CSM/client.ico Icon for desktop-shortcut and menu-item in the start-up
folder.
Should this file be missing the standard
WORK/image/apipro.ico or
WORK/image/api7.ico (for API PRO v7) will be used.
CSM/client.ini Client configuration including AppServer connection
parameters.
Should this file be missing WORK/apipro.ini will be
used.
CSM/client.pf Client configuration including language setup.
Should this file be missing the standard WORK/client.pf
will be used.
CSM/dialog.bmp Optional image.
Size should be: 493x312 pixels.

Sample:

WORK/csm/apilogo.bmp Image in top of start-up window.

Should this file be missing WORK/image/apilog5.bmp
which is used by the API PRO login, will be re-used.
Sample:

WORK/csm/apipro.ico Icon for start-up window.

Should this file be missing the standard
WORK/image/apipro.ico will be used.

API PRO -29- Client Server Management

 Filename Description
WORK/csm/client.r Start-up program which ensures the local application is up-
to-date before API PRO starts.
WORK/csm/*.ini Common shared .ini-files.
WORK/csm/*.pf Common shared .pf-files.
WORK/csm/noconnect. Optional “noconnect”-message.
{html,htm,txt} Launched in local file-viewer if connection to the AppServer
fails for the initiator.

These files are placed in a workspace:

Filename Description
client.cmd Client start-up script.
client.log Setup parameters for the package editor.
Will not be distributed in the package.
client.wxs Used by WiX to control packaging.
Will not be distributed in the package.
WORK/client.ico Icon for desktop-shortcut and menu-item in the start-up
folder.
Will not be distributed in the package.
WORK/client.ini Client setup.
WORK/client.pf Client setup.
WORK/csm/apilogo.bmp Splash image.
WORK/csm/apipro.ico Icon for start-up window.
WORK/csm/client.r Start-up program
WORK/csm/noconnect. Optional “noconnect”-message.
{html,htm,txt}

API PRO -30- Client Server Management

 Editor
This tab provides a mini-editor for editing CSM-related files at the AppServer without
having direct access to the file-system.

Note: Fix A15341 (see: Enhancements and related fix-packages) or newer are required.

The selected file is loaded from the active AppServer and a set of options can be used to
change the content or delete the file.

API PRO -31- Client Server Management

 AppServer file
Choose which file to edit:

A selection of files related to CSM is listed, regardless if the file currently exists or not.
The purpose of each of the listed files is described in the section: AppServer file-system.
Unless Fix A18378 (see: Enhancements and related fix-packages) is included, only files not
exeeding 30Kb can be edited – trying to load larger files will result in an error:

(Editor)
Text-box with the content of the selected file and a drop-zone accepting local text-files.

Load locally
Load content from a local file at the client.

Save locally
Save content to a local file at the client.

Save remotely
Save content to the file at the AppServer.
Consider doing a Check when all changes have been made. A Check is not done
automatically allowing this editor to be used for initial configuration of CSM.

Delete remotely
Delete the file at the AppServer.
Not all files can be deleted in this editor.

API PRO -32- Client Server Management

 Other options
The menu provides some additional options:

Workflow
Sub-menu with options which all triggers the complete CSM-workflow:

Load & deploy

The same option as the button found on the Simple-tab – see: Load & deploy.

Recompile & deploy

The same option as the button found on the Simple-tab – see: Recompile & deploy.

Import & deploy

The same option as the button found on the Simple-tab – see: Import & deploy.

API PRO -33- Client Server Management

 Load phase
Sub-menu with options related to the Load-phase of the CSM-workflow:

Load package
The same option as the button found on the Advanced-tab – see: Load package.

Recompile
The same option as the button found on the Advanced-tab – see: Recompile.

Import directory
The same option as the button found on the Advanced-tab – see: Import directory.

Description
The same option as the button found on the Advanced-tab – see: Description.

API PRO -34- Client Server Management

 Compile phase
Sub-menu with options related to the Compile-phase of the CSM-workflow:

Custom clean-up
When a build has been loaded and not yet compiled this option will examine the deployed
areas at the AppServer and look for files of the custom package. All previously deployed
files which are missing in the new build will be listed in a special build-file called
delete.cst which lists files to be deleted at the deploy phase.
All files being deleted or changed have a copy of the most recent version saved in the back-
up area.
Files checked are:
• CUSTOM/*
Custom programs and files
Note: csttrans.*-files are not deleted!
• WORK/fix-db/*.cst
Custom data files
• WORK/fix-db/design-custom/*
Custom designs

Program clean-up
When a build has been loaded and not yet compiled this option looks for sourceless
programs and add those to the special build-file delete.lst which lists files to be
deleted at the deploy phase.
All files being deleted or changed have a copy of the most recent version saved in the back-
up area.

Note: Fix A17066 (see: Enhancements and related fix-packages) or newer are required.

Compile build
The same option as the button found on the Advanced-tab.
The process is documented in detail in the section: Compile.

API PRO -35- Client Server Management

 Program list
Show the list of programs to be included in the compile using the standard viewer with
options to "Print" and "Save as" locally.

Compile log
Show the log from the compile using the standard viewer.
A header section lists the configuration of the compile including:
• Server deployed: The current deployed build at the server.
• Compile build: The build being compiled.
• Code page.
• Numeric and date format.
• Font settings.
For the application to look as intended the layout of DEFAULT and font 12 should
list these values (the screen resolution would change this):
...
"FONT-SIZE (DEFAULT):" "APIPRO(50x16)" "1234567890(70x16)"
...
"FONT-SIZE (12):" "APIPRO(40x13)" "1234567890(60x13)"
...
• Language setup for the translation.
• Databases used for translation.
• PROPATH: List of source directories.

Then follows sections for each of the list of programs – Compile file:
• File name to be compiled.
• Current MD5 value.
• Messages from the compiler including warning and errors.

Tip: Compile errors are typically lines starting with **

maint/server/work_order.p F5938AE61382BC20983A0EDEA163762B 13:58:49
** Unable to understand after -- "AND get-lparam". (247)
** C:\APISERVER\APIPRO9\XCODE\maint\logic\work_order.i Could not understand line 2867. (198)
** C:\APISERVER\APIPRO9\XCODE\maint\server\work_order.p Could not understand line 3. (198)
Error C:\APISERVER\APIPRO9\XCODE\maint\server\work_order.p

• Resulting MD5 value.

No change in MD5 value: The program will be deleted from the build-area
leaving only changed programs for the deploy-phase.

At the bottom totals are listed.

If the build is re-compiled this file will be re-created too.

Missing list
Show the list of programs which did not compile successfully using the standard viewer.

API PRO -36- Client Server Management

 Deploy phase
Sub-menu with options related to the Deploy-phase of the CSM-workflow:

Deploy build
The same option as the button found on the Advanced-tab.
The process is documented in detail in the section: Deploy.

Lock build
Lock the build for changes and compile.
Fix A16959 (see: Enhancements and related fix-packages) enables selection of multiple
unlocked builds for this option in the browser found in the Advanced-tab.

Unlock build
Unlock the build.
Fix A16959 (see: Enhancements and related fix-packages) enables selection of multiple
locked builds for this option in the browser found in the Advanced-tab.

API PRO -37- Client Server Management

 Delete build
Since the order of loaded builds dertimens the order in which they will be compiled and
deployed any build that fails to load will stop the workflow and should be deleted.
If a build have been deployed and should no longer be available for documentation or
rollback it can be deleted too, but only if it is unlocked.
Deleting a build will delete all related files in the CSM-workspace (including a backup
made during deployment) and can free up disk space and reduce filesystem back-ups done
at the AppServer.

Note: If any directory or file couldn’t be deleted the build will still be listed. Make sure no
files are kept open by editors, file-explores or set as current directory for a command line.

Fix A16959 (see: Enhancements and related fix-packages) enables selection of multiple
unlocked builds for this option in the browser found in the Advanced-tab.
Deleting multiple builds asks for a confirmation:

API PRO -38- Client Server Management

 Changes
Sub-menu with options related to changes to the AppServer file-system:

Check
The same option as the button found in the Advanced-tab.

Change log
Show the list of changes (from the previous change-log) using the standard viewer.

Delete changes
Delete the change-log which is the list of files changed at the AppServer since the previous
check.
These change-logs are the basis for updating clients to be in sync with the server.
If any of the required change-logs for a client be missing, then all files will be checked –
see: Reinstall method.

Fix A16959 (see: Enhancements and related fix-packages) enables selection of multiple
change-logs for this option in the browser found in the Advanced-tab.
Deleting multiple change-logs asks for a confirmation:

API PRO -39- Client Server Management

 Server functions
Sub-menu with other options for the AppServer:

Lock server
Lock CSM for changes. New packages can’t be loaded.

Unlock server
Unlock CSM allowing new packages to be loaded.

Reset server
The option requires a confirmation:

All data-areas of CSM at the AppServer are deleted, except for the change-log-value (this
sequence has to increase continuously) and the file-system is finally recorded (using
CheckWork).

AppServer log
Show the log from the AppServer using the standard viewer.

API PRO -40- Client Server Management

 Client functions
Sub-menu with other options for clients:

Export files (Client functions)

All changes made in the local WORK/-directory are exported to a directory. All created or
modified files are copied and required subdirectories are made to keep the structure intact. A
package.txt-file listing the changes is placed in the root of the directory. Progress
source files (.cls, .p or .w suffixes) will be placed under a CLIENT/-subdirectory and
other files under a WORK/-subdirectory. This function can be used to make a backup if the
client-image is to be updated or to upload the changes to the AppServer, which then will be
deployed to every client.

Note: Changes to WORK/client.ini and WORK/client.pf are not included since

these files are considered personal.

Note: Fix A14706 (see: Enhancements and related fix-packages) deals with a progress-bug
which causes shifts between winter- and summertime time to export too many files.

Restart client
Leaves API PRO and restarts your client, which triggers a load of optionally new changes.
Similar to pressing ALT+F5 in the login-dialog.

Note: Fix A17328 (see: Enhancements and related fix-packages) or newer are required.

Reset client
Leaves API PRO and restarts your client after all files have been updated.
Before fix A17328 (see: Enhancements and related fix-packages) you had to leave API
PRO manually.
Similar to pressing ALT+F12 in the login-dialog.

API PRO -41- Client Server Management

 Reinstall client
Leaves API PRO and restarts your client after a reinstallation have been made.
The client-configuration includes which method to use for reinstallation – see:
Reinstall method.

Similar to pressing CTRL+SHIFT+ALT+F12 in the login-dialog.

Note: Fix A17328 (see: Enhancements and related fix-packages) or newer are required.

Reinstall clients
This option will trigger a reinstallation the next time each client connects.
This could be useful if the chronology of the change-logs has been broken and the clients
should have deleted files no longer in use.
The client-configuration includes which method to use for reinstallation – see:
Reinstall method.

API PRO -42- Client Server Management

 Initiator
Sub-menu with other options for the client-initiator:

Export files (Initiator)

Export files for the client-initiator and some additional setup to a directory.
The directory can be zipped manually or be loaded and edited using the Load setup-option
to create a custom MSI-package.

Init.zip
Make a client-initiator package and pack this as a .zip-archive.
A save-file-dialog will ask for the filename of the client-initiator-package

init.msi
Make a client-initiator package and pack this as an .msi-archive using default values.
A save-file-dialog will ask for the filename of the client-initiator-package.

API PRO -43- Client Server Management

 Additional configuration
Using the Editor the special server-only file CSM/server.opt can extend different
features of CSM.
Options are case-insensitive.

Issue reinstallation

If the chronology of the required change-logs are broken the server will include all files
known for the clients, but files no longer present, might not be deleted.
The server-option issue-reinstall will in this case precede the update with a
reinstallation which by default will let clients save optional local changes, delete all files no
longer part of the initiator and then delete empty directories.
The actual steps done by each client is configured separately choosing a Reinstall method
for the package.

API PRO -44- Client Server Management

 Allow/Reject packages
By default, all packages confirming to the standard (see: Import & deploy) may be loaded
but a series of tests on the attributes of the package against the setup in CSM/server.opt
can ensure only certain packages are accepted:

Sample package not accepted by these tests:

The configuration distinguish between the different types of packages:

Type Typical name(s) Description
Accum 8.0SP00D08 Accumulated fix-package.
8000E.03
9000.02
Custom NLG033-8000C-2015-10-13-10-16.zip Customer package.
ATS013-9000-2017-01-30-15-38.zip
Feature 7.0SP06 Feature-package.
8.0SP01
9.0SP00A
Fix FIX150810-15674-DEV Standalone fix-package.
FIX150825-15733
Unknown C:\temp\upload Any “home-made” package.
newrtps.zip

API PRO -45- Client Server Management

 Depending on the type of the package, different attributes could eigther be allowed, rejected
or tested agains a minimum value:
Test(s) Test against Description
allow-dbhashes DB hash List of integer values that represent the
reject-
dbhashes
data-base layout/data-model.
allow-licenses Projects List of or licenses.
reject-
licenses
allow-types List of types as listed in the table
reject-types
above.
allow- System name Useful for master/slave(s) setups.
systemnames
reject- See: Master/slave(s) setup.
systemnames
allow-versions List of versions formatted using
reject-
versions
numbers only:
7.0SP05 = 7.0.5.0
8000D08 = 8.0.0.4
8000E = 8.0.0.5
9000 = 9.0.0.0
9000A = 9.0.0.1
minimum-accum Package version Minimum integer value for the
accumulated fix:
8000D08 =8
8000E.03 =3
9000.07 =7
9000A.08 =8
minimum-custom Jenkins build number Minimum integer value for the build:
Jenkins build number: 5 = 5

Additional configuration parameters:

Name Description
update-accum Update minimum-accum with value from the package.
update-custom Update minimum-custom with value from the package.
update-minimum Update minimum-accum and minimum-custom with values
from the package.

API PRO -46- Client Server Management

 Install a client

Install the BaseLine

To make CSM-clients work a set of packages are required to be installed on the PC and
these all require administrator rights to be installed.
Two different generations of the BaseLine are available:
1st generation for API PRO 7, 8 & 8.1.
2nd generation for API PRO 9 & 10.

Note: Both generations of the baseline can be installed and used at the same time.

Microsoft .NET Framework

Depending on the generation of the baseline different .NET Framework versions are
required:
1st generation for API PRO 7, 8 & 8.1 requires .NET Framework 3.0 or 3.5 (not 4.0).
2nd generation for API PRO 9 & 10 requires .NET Framework 4.6.

The installation will stop if this requirement is not fulfilled:

BaseLine
The BaseLine found in SETUP/ApiProBaseLine/baseline.exe provides packages
shared by all API PRO systems like Progress (also known as OpenEdge), Crystal Report
(handles printouts), and various tools, drivers and fonts. The configuration of the BaseLine
is located in SETUP/ApiProBaseLine/baseline.ini.

API PRO -47- Client Server Management

 Run the baseline.exe program by right-click and choose Run as administrator.

Note: Using a local administrator is in some configurations not sufficient – you still need to
choose: Run as administrator.

BaseLine-client
As an alternative SETUP/ApiProBaseLine/ provides baseline-client.exe
which will include a package for a single generic API PRO system.
This is done controlled by baseline-client.ini and can be customized in many
ways.
By default:
1) apilive9.msi will be install into C:\APIPRO\APIPRO9
2) client.ini will be copied into C:\APIPRO\APIPRO9\WORK\
Note: This overwrites the file installed by apilive9.msi

API PRO -48- Client Server Management

 Install an API PRO system
Using the Client Server Management-program a .msi-file can be configured and generated
for connecting to an AppServer.

When the .msi-file is opened (double click, right-click and choose Install) – the
installation process begins.

Choose Next

Note: If the installation fails to start it could be the file is blocked.

Look in Properties (right click) where it can be unblocked:

API PRO -49- Client Server Management

 The Destination Folder will be the root of the file-system used by this installation. All files
and sub-directories will be created when needed.
The disk quota required (starting from 200 Mb for a “light configuration”) varies according
to the number of build-in translations, customized programs or modules and other external
files.

Warning: If the system later will be uninstalled this Destination Folder and all the content
will be completely deleted.

API PRO -50- Client Server Management

 The API Maintenance Systems-Start-up menu will have a menu-item for the AppServer:

…and optionally a shortcut on the desktop for easy access:

Choose Next

API PRO -51- Client Server Management

 Final screen before the installation will begin.

Choose Install

API PRO -52- Client Server Management

 The green progress-bar will follow the process and then:

API PRO -53- Client Server Management

 The initial installation has finished and the new API PRO system can be found in the
control-panel:

If you choose Launch application? The CSM-client will be started and like all other future
calls go through a couple of steps ensuring the application is up-to-date.

API PRO -54- Client Server Management

 When the CSM-client first starts, it will connect to the AppServer.
If any of the connection-parameters are missing – the following dialog will prompt for the
setup:

If a connection can be made, the entered values are stored in the .ini-file for future use.

All the latest files which have been deployed for clients will be downloaded and placed in
required sub-directories.

API PRO -55- Client Server Management

 Command line install

If required, the API PRO system can be installed from a command-line using the same
.msi-file:

msiexec /i dkk004-apitest9-aia.msi INSTALLDIR=E:\apipro\apitest9

Adding option /qn makes the installation go completely “silent”:

msiexec /i dkk004-apitest9-aia.msi /qn INSTALLDIR=E:\apipro\apitest9

API PRO -56- Client Server Management

 Uninstall an API PRO system

All MSI-based API PRO systems can be uninstalled from the Control Panel:

Use the option: Export files (Client functions) to save any changes made locally before the
installation is removed.

Note: When a system is uninstalled, the Destination Folder will be completely removed.

API PRO -57- Client Server Management

Behind the scene

Start API PRO at a client:

1 A desktop-icon and a special folder in the start-up menu provide different access points for
the application.
The application starts by running a script called client.cmd.
2 Depending on the version starting, different nodes of the registry are queried for the
location of the baseline. If this fails (due to security setup) the environment variable DLC
will be used to look for the executable, and if this is missing or the value provided is
wrong the process quits with an error:

3 With current directory assigned to WORK/ (located next to client.cmd) the executable
then typical launches CSM/client.r as the first program called (setup in
client.pf).

4 A connection to the AppServer is established using the key-values of the API PRO-
section of the client.ini file – just like in apipro.w later.

5 The CSM/server.r program is loaded at the AppServer.

API PRO -58- Client Server Management

 6 As for the client side, the server will consider the directory where CSM/server.r
resides to be the WORK/-directory on this server.

7 The client looks for the current state (change-log) in the local CSM/client.log.

8 The server is asked for complete list of changes, given the installed change-log at the
client and this result in one of the listed scenarios:

Same If the server is at the same level (will typically be the case!) the client is
considered to be fully up-to-date and the application will start immediately.
Newer If the server is “newer”, all the change-logs in between are merged into a
resulting list of files. Should any of the required change-logs at the AppServer
be missing a complete client-image will be returned.
This could happen if the AppServer was initiated by: Reset server.
Older If the server is “older”, the value is rejected by the server and a complete
client-image will be returned.
This could happen if a system has been restored from a backup.
Unknown If the server is “unknown” a complete client-image will be returned.
This could happen if a system has not been configured – see:
File changes in AppServer.
For scenario newer and older the configuration could even ask for clients to do a
reinstallation – see: Issue reinstallation.
The list of files includes size and modification time and R-codes will list MD5-values.
Based on rules the list is divided into a list of files for the client-image – see:
Overwrite file-type and this can include deletion of files.

9 If the client is asked to do a reinstallation by the server, the actions taken are then up to the
configuration of the client – see: Reinstall method.
The default behavior will include a chance to save changes made locally before present
files and directories are deleted:

API PRO -59- Client Server Management

 10 The update proceeds with the list of files given by the server were the client might delete
unnecessary files as configured – see: Check method.
The default behavior will skip all r-codes with unchanged MD5-values and calculate the
total number/size of files of the update:

11 Files are downloaded – one file at the time, showing the status on the way and creating any
required sub-directories:

In version 7 this dialog had two progress-bars:

API PRO -60- Client Server Management

 12 Should an error occur the bar changes color:

A typical error is having two clients trying to access the same file:
** Cannot find or open file …/icons/cj1624/Windows8.cjstyles, errno = 13. (43)

or:
** Cannot find or open file .../external/Office2010.dll, errno = 13. (43)

Errors will be listed in CSM/client.err

Note: Fix A14663 (see: Enhancements and related fix-packages) closes some open files
preventing the client update from the login-dialog to succeed.

Note: Fix A15323 (see: Enhancements and related fix-packages) support an option to
prevent clients not fully updated to get access – see: Reject access after error.

13 If everything went ok the new value for change-log is stored in CSM/client.log

reducing the next installation to only look for new changes.
The file CSM/client.ok will be created.

API PRO -61- Client Server Management

 14 If the running program, any static classes (after initial load) or the current .ini-file
were updated the client will re-launch to make sure the interface for running the
application is up to date.

Updating .pf-files will make the client quit as they have to be available for setting
up the process and tuning it against the windows environment.

Note: Fix A17066 (see: Enhancements and related fix-packages) includes a

notification to inform the user why the client terminates after the update has
completed – see: Restart notification.

15 The standard apipro.r program is now called:

(If the Remember me button is not present it could have been hidden – see:
Hide ‘Remember me’.)
From this login-dialog some CSM-events are available using keyboard
combinations:
• ALT+F5:
Download new files since last refresh (as shutdown and restart).
Use-full when a build has been deployed after the client was started.
• ALT+F12:
Get a complete image of the required files.
Use-full if some files have (or might have) been lost at the client.
• CTRL+SHIFT+ALT+F12:
Reinstall the client – see: Reinstall method.

Note: Fix A17328 (see: Enhancements and related fix-packages) or newer

are required.

API PRO -62- Client Server Management

 Command line interface
Most of the functionality of CSM can be accessed from command-line through the -PARAM
option.

The start-up script used by clients: client.cmd (and program: CSM/client.r)

accepts the following values for -PARAM:

-PARAM syntax Description

(blank) Normal client start-up with optional file download and login.
CheckClient Used for updating the client installation only.
Any new changes will be downloaded, but the application will
not be launched.
CheckWork Forward the command to the AppServer – see: CheckWork.
CompileAll If the CSM is locked this command is rejected:

A new build will be created and the number will be reported:

Then the compile starts at the AppServer.

Note: The build will not be deployed to the AppServer when
the compilation has ended. Use the separate DeployBuild-
command.
"CompileBuild,number" Compile build number at the AppServer – see: Compile.
CreateBuild Get next build number from CSM/build.log and create the
CSM/build/number/ root.
A database-lock held during this check ensures only one
process have access to the files.

API PRO -63- Client Server Management

 -PARAM syntax Description
"CreateInit,directory" The files of the CSM-initiator will be exported to this
directory.
The value for directory will have its offset in WORK/ at the
client.
"DeleteBuild,number" If the build is locked it can’t be deleted:

Unlocked builds will have the CSM/build/number/ root

will be deleted and the build can no longer be used.
This can’t be undone.
"DeployBuild,number" The build has to be next in line or it will be rejected:

For futher description – see: Build not deployed.

"EmptyBuild,number" If the build is locked it can’t be emptied:

Unlocked builds will have the CSM/build/number/ root

left empty (all sub-directories and files are removed).
This can’t be undone.
LoadClient A full client-image will be tested.
Programs with matching MD5-value will be skipped and other
data-files will not be downloaded if they match in size with-in
the same change-log.

API PRO -64- Client Server Management

 -PARAM syntax Description
"LockBuild,number" Locks the builds for changes.
Loading archives or files will be rejected.
ReinstallClient The actual steps taken are configured in the set-up of the
client (see: Reinstall method), but the Destination Folder will
be fully updated and cleared for files and sub-folders no
longer part of the application – just like if the package was
uninstalled using option in the control-panel (see: Uninstall an
API PRO system).
This command is available from the standard login-dialog
using the keyboard combination CTRL+SHIFT+ALT+F12.
ReloadClient A full client-image will be downloaded.
The normal stripping of programs, with no change to MD5-
value, will be skipped.
ResetClient A full client-image will be downloaded, but programs with
matching MD5-value will be skipped.
This command is available from the standard login-dialog
using the keyboard combination ALT+F12.
RollBackLast The latest build deployed at the server will be rolled back. A
new build is created, and loaded with the source from the
backup-area.
All programs are then compiled and finally the new build is
deployed to the AppServer.
At this state a new RollBackLast–command will go
through the same steps and return the system to the state from
before the first RollBackLast.
StartClient Normal start-up.
New changes will be downloaded (like CheckClient) and
then the application will be launched.
This command is available from the standard login-dialog
using the keyboard combination ALT+F5.
"UnlockBuild,number" Unlock a locked build.
"UploadPackage,package
[,option]" Note: Fix A14510 (see: Enhancements and related fix-
packages) or newer are required.

Accepts the same types of packages as can be loaded using

Load package or Import directory.
The value for package will have its offset in WORK/ at the
client.
Optional the workflow can be started after load, by adding an
option:
• Compile: Triggers the compile-phrase after load
ended.
• CompileDeploy: Will trigger compile- and deploy-
phrase after load ended.

API PRO -65- Client Server Management

 Sample scripts:
CD /d E:\apipro\apitest9
client.cmd -param CheckClient

CD /d E:\apipro\apitest9
client.cmd -param RollBackLast

CD /d E:\apipro\apitest9
client.cmd -param "UploadPackage,C:\temp\ACCUM-9000.03.zip,CompileDeploy"

API PRO -66- Client Server Management

 At the server csm/server.p will accept the following values for -PARAM:

-PARAM syntax Description

CheckWork Run through WORK/ and check the status of each file against
the last known status stored in CSM/server.lst.
If any change is found a new change-log will be created and
each change will be recorded in the corresponding log-file
CSM/change/number.lst.
The new status is stored in CSM/server.lst.
A database-lock held during this check ensures only one
process have access to the files.
Consider using this command triggered from schtasks
(windows task scheduler) if files of WORK/ are modified
outside API PRO – see: Check AppServer continuously for
changes.
"CompileBuild,number" Compile build number.
See: Compile.
"CreateInit,directory" The files of the CSM-initiator will be exported to this
directory.
The value for directory will have its offset in WORK/ at the
server.
"DeleteBuild,number" If the build is locked it can’t be deleted and the will show an
error like:
"BEGIN:" "26/01-2017 09:30:31"
"CSMDIR:" "C:/APISERVER/APITEST9/CSM"
"WORKDIR:" "C:/APISERVER/APITEST9/WORK"
"PARAMETER:" "deletebuild,162"
"ERROR:" "Build locked"
"END:" "26/01-2017 09:30:31"
Unlocked builds will have the CSM/build/number/ root
will be deleted and the build can no longer be used.
This can’t be undone.
"DeployBuild,number" Deploy build number.
As for the command at the client, the build has to be next in
line and will be locked.
"LockBuild,number" Locks the builds for changes.
Loading archives or files will be rejected.
"UnlockBuild,number" Unlock a locked build.

API PRO -67- Client Server Management

 "UploadPackage,package
[,option]" Note: Fix A14510 (see: Enhancements and related fix-
packages) or newer are required.

Accepts the same types of packages as can be loaded using

Load package or Import directory.
Set package using full-path.
Optional the workflow can be started after load, by adding an
option:
• Compile: Triggers the compile-phrase after load
ended.
• CompileDeploy: Will trigger compile- and deploy-
phrase after load ended.

Sample script (placed in CSM/):

CD /D "%~dp0..\WORK"
prowin32.exe -pf ../CSM/batch.pf -ininame ../CSM/batch.ini -param
CheckWork >> ..\CSM\check.log

API PRO -68- Client Server Management

 Client configuration
The .ini-file used by clients (default: WORK/client.ini) can assign environment-
keys – and some of these are supported by CSM.
Sample API PRO-section with traditional AppServer set-up, and Joe as default User ID:
…
[API PRO]
AppServer-Host=workshop.apipro.com
AppServer-Port=5162
AppServer-Name=dkk004-apitest9
CodeJockVersion=16.2.4
LOGIN-USER-ID=joe
…

or:
…
[API PRO]
AppServer-URL=http://workshop.apipro.com/aia/Aia?AppService=dkk004-
apitest9
CodeJockVersion=16.2.4
CSM-CHECK-METHOD=LoadClient
CSM-REJECT-ACCESS=TRUE
HIDE-SAVE-LOGIN=TRUE
…

Connection using an URL, and no Remember me-button.

Environment-keys supported by CSM:

Key Description
AppServer-Host Host of the name-server providing access for the AppServer.
Requires AppServer-Name and AppServer-Port
See: Initiator.
AppServer-Name Name of AppServer connected through a name-server.
Requires AppServer-Host and AppServer-Port
AppServer-Port Port of the name-server providing access for the AppServer.
Requires AppServer-Host and AppServer-Name
AppServer-Url URL for an AppServer accepting access through AIA
(AppServer Internet Adapter).
CodeJockVersion The version of CodeJock which should be used.
Values depend of which packages have been installed.
See: Progress error 6087.
Defaults:
13.2.0 for API PRO 7, 8 and 8.1
16.2.4 for API PRO 9 and 10.

API PRO -69- Client Server Management

 Key Description
CSM-CHECK-METHOD The method which should be used for checking the client-image
at start-up.
See: Check method.
Known values (case-insensitive):
• LoadClient
• ResetClient
• ReloadClient
• StartClient (default value)
CSM-REINSTALL- The method used when the client is asked to do a reinstallation.
METHOD
See: Reinstall method.
Known values (case-insensitive):
• Error
• Ignore
• No-delete
• No-export
• Silent
• Warning
CSM-REJECT-ACCESS Should an error during update reject access to API PRO?
See: Reject access after error.
Known values (case-insensitive):
• TRUE
• FALSE (default value)
CSM-RESTART- Should the restart notification be visible?
NOTIFICATION
See: Restart notification.
Known values (case-insensitive):
• TRUE (default value)
• FALSE
HIDE-SAVE-LOGIN Hide the Remember me-button from the login-dialog.
See: Hide ‘Remember me’.
Known values (case-insensitive):
• TRUE
• FALSE (default value)
LOGIN-USER-ID Overwrite value from the OS for default User ID in the login-
dialog.

API PRO -70- Client Server Management

 CSM workflow

A detailed walk-through of the 3 steps of the workflow – 1: Load, 2: Compile, 3: Deploy.

Load
First step of the CSM workflow is used to setup a build which is a work-space for changes
that should be applied to the application. Builds are located at the AppServer under the
CSM/build/-directory, and numbered by a counter.
When a build is created, the workflow triggers the CSM-event: createbuild.

Changes can be fix-packages, complete custom-packages or customized changes made

locally and different functions can be used to load these from any client.
Zip-archives or progress-libraries will be unpacked at the client (to a temporary directory).
Using the normal connection to the AppServer, the files are uploaded to the build and
required sub-directories are created on the way.

Note: File-names with national characters may fail and can’t be handled by CSM.

The load finishes by creating a CSM/build/number/load.ok or

CSM/build/number/load.err file to signal the result and then trigger the workflow
event: loadend.
At this point the load-area turns green or red depending on the status.
The rest of the workflow will be processed in batch-mode at the AppServer – completely
independent of a connection to the client that initiated the load.

API PRO -71- Client Server Management

 Compile
Second step of the CSM workflow is to compile the build.
This is done into the separate CSM/build/number/WORK/ directory, leaving the
present application running untouched.
PROPATH of the compile-process includes the current server version and other outstanding
builds in correct sequence.
If a new build 13 is to be compiled, and build 12 is not yet deployed it would give a
complete compile-path:
1) CSM/build/13/CLIENT/
2) CSM/build/12/CLIENT/
3) CLIENT/
4) CSM/build/13/CUSTOM/
5) CSM/build/12/CUSTOM/
6) CUSTOM/
7) CSM/build/13/XCODE/
8) CSM/build/12/XCODE/
9) XCODE/
10) WORK/
Only existing directories are added to the list and WORK/ is included to provide other files
like images and icons.
The current MD5 value is likewise found looking in:
1) CSM/build/12/WORK/
2) WORK/
and compared to the new value of the compiled r-code in: CSM/build/13/WORK/
If the values are equal the r-code are deleted from build 13.
A re-compile of build 12 shouldn’t include 13 in the PROPATH.

Steps in the compile-phase:

1 Ensure CSM/build/number/WORK/ holds no r-code (leftovers from a previous
compile)
Status files are deleted prior to the compile:
CSM/build/number/compile.err
CSM/build/number/compile.log
CSM/build/number/compile.ok
CSM/build/number/missing.lst
2 Build CSM/build/number/delete.cst if the compile-options include
write-delete.cst.
3 Spawn a batch-process using the setup from CSM/compile.ini and
CSM/compile.pf
4 Trigger the workflow event: compilebegin
5 Configure the compile: PROPATH, LANGUAGES, translation-db…

API PRO -72- Client Server Management

 6 For every deleted source-file (see CSM/build/number/delete.cst and
CSM/build/number/delete.lst) an “illegal placeholder” is created.
PROPATH is then searched for ancestors and if found they will be copied to make
sure the compile will have the complete source.
Examples:
XCODE/file.i is seen as an ancestor for CUSTOM/file.i as CUSTOM/ is
placed before XCODE/ in PROPATH.
7 For every program:
Find current MD5-value.
Make required “save-into”-directory.
8 Compile the program and catch errors.
9 Compare new MD5-value with current value and delete if unchanged.
The check made for classes are however postponed until all programs have been
compiled to support inheritance.
If the compile-options include no-md5test this clean-up step is skipped and
could be used as a work-around if the built-in calculation fails to report changes
made.
10 When all programs are compiled, all empty directories are deleted.
11 Make a CSM/build/number/compile.ok or
CSM/build/number/compile.err file to signal the result.
12 Trigger the workflow event: compileend
13 If CSM/build/number/deploy.do is found and no errors occurred, then the
build will be deployed immediately to the AppServer. This feature should be used
with care during normal office hours as the clients will then run with potential
different versions of the business-logic at the same time.
The file CSM/build/number/deploy.tot will trigger deployment even if an
error occurred during compile.
If the compile is made by a restricted progress client (option -rx) the deployment-
process is spawned to a new batch process with the setup from CSM/batch.ini
and CSM/batch.pf files, allowing access to the database.

API PRO -73- Client Server Management

 Deploy
When a build is being deployed, files from build/number/ are copied to the active
directories of the AppServer. This process can be triggered automatically when the build
has been compiled, done manually using the Client Server Management-program or
launched by the CSM-command: DeployBuild from a command-line.
It’s not possible to deploy a build if the previous one hasn’t been deployed to the AppServer
and builds can’t be re-deployed.

Steps of the deploy-phase:

1 Trigger the workflow event: deploybegin
2 Lock the build if not already locked.
3 Status files are deleted:
build/number/deploy.ok
build/number/deploy.err
4 The associated backup-area: backup/number/ are cleared.
5 Files from: build/number/ are copied to their destination except for special
files of the build and files listed in build/number/delete.lst
Before the destination is over-written or deleted the previous contents is backed-up
by a copy to the backup-area.
6 Actions listed in: build/number/deploy.act are executed
7 The updated file-system is documented by a CSM-check.
8 The special file: build/number/fix-db.do will file spawn a new batch
process with the setup from CSM/batch.ini and CSM/batch.pf files
allowing access to the database and all executed programs being updated.
Here fix-db/fix-db.p will load the designs and other relevant data.

Note: Fix A14699 (see: Enhancements and related fix-packages) will setup
SUPERVISOR as the user for this process.

9 Trigger the workflow event: deployend

API PRO -74- Client Server Management

 How to

This section lists some common scenarios working with CSM.

Add/change some files

Some files placed locally should be part of the application.
Example: A new Crystal Reports Template called fiscal.rpt should be loaded into
WORK/crprint/.

1. Make a directory that will be the root of the package.

C:\temp\upload\

2. Create the required subdirectories to hold the file-structure of the changes:

C:\temp\upload\WORK\
C:\temp\upload\WORK\crprint\

3. Place the changed files:

C:\temp\upload\WORK\crprint\fiscal.rpt

4. Make a description of the changes in package.txt:

Edit C:\temp\upload\package.txt

5. Setup compilation. By default all known programs will be compiled but the file
compile.lst can be used to specify a smaller list (could be empty).
Make C:\temp\upload\compile.lst
Note: Make sure the suffix of the file is right and not ends up as “.lst.txt”

6. Load the root-directory into CSM and go through the 3 steps (load, compile, deploy).

7. Quit API PRO and start a new client.

8. Validate the changes were mirrored to the local image.

Now WORK\crprint\fiscal.rpt should be present.

9. Delete the local root-directory.

C:\temp\upload

API PRO -75- Client Server Management

 Local file-system required for this change:
C:\temp\upload\ Root-directory
C:\temp\upload\WORK\crprint\fiscap.rpt File to be loaded
C:\temp\upload\compile.lst Empty file
C:\temp\upload\package.txt Description

Fix-pack A13583 (See: Enhancements and related fix-packages) makes deployment of a

Crystal Reports Template very easy as the drop-zone and Load have a built-in workflow for
uploading the template to WORK/crprint/.

Add a program
Load a locally made program and make it part of the application on all clients.
Example: A new program hello.p

1. Load the program using “Load & deploy” or the drop-zone.

The source of locally made programs are placed in CLIENT/ at the AppServer (parallel
to WORK/).

2. Quit API PRO and start a new client.

3. Validate the changes were mirrored to the local image.

Note: Fix-pack A13777 (See: Enhancements and related fix-packages) is required to make
this function work in Progress run-time environments for source not encoded (using
XCODE).

API PRO -76- Client Server Management

 Delete some files
Fix-pack A13224 (See: Enhancements and related fix-packages) adds a special build-file
called delete.lst to the root-directory of the package.
If present, this file lists files to be deleted at the AppServer and clients.
Example: Delete hello.p and fiscal.rpt from the CR-templates.

1. Make a directory that will be the root of the package.

C:\temp\upload\

2. Setup delete.lst
Edit C:\temp\upload\delete.lst
Note: Notice the files are relative to the parent-directory of the application.

3. Make a description of the changes in package.txt:

Edit C:\temp\upload\package.txt

4. Setup compilation. By default, all known programs will be compiled but the file
compile.lst can be used to specify a smaller list (could be empty).
Make C:\temp\upload\compile.lst

5. Load the root-directory into CSM and go through the 3 steps (load, compile, deploy).

6. Quit API PRO and start a new client.

7. Validate the changes were mirrored to the local image.

Now WORK\hello.r and WORK\template\fiscal.rpt should be deleted.

8. Delete the local root-directory.

C:\temp\upload

Sample C:\temp\upload\delete.lst:
CLIENT/hello.p
WORK/hello.r
WORK/crprint/template/fiscal.rpt

API PRO -77- Client Server Management

 Fat initiator
The Append additional files option of the initiator setup provided by fix-pack A15969 (see:
Enhancements and related fix-packages) allows the initiator to install not only the minimum
required set of files to start the client, but include any number of additional files and reduce
the first download accordingly.

The steps for sizing up the initiator are:

1. Make a new directory that will be the root of the package.
C:\temp\fatclient\

2. Use the Save setup option of the Initiator to save the standard minimum required set of
files, and point to the root directory created.

3. Locate client.cmd in the root and open (run) this script.

The initiator will launch, connect to the AppServer and download the complete client
image. When this is completed, the login-dialog will appear – choose “Cancel” here.

4. At this point the content of WORK\ may be altered manually.

5. Switch back to the Initiator and select “Append additional files”:

6. Use the Generate option to generate the new setup.

7. Delete the root directory as it is no longer needed.

Note: The update status of all additional files installed this way will be checked like normal.

API PRO -78- Client Server Management

 Reject login
Fix-pack A13224 (or A12526) (see: Enhancements and related fix-packages) offers a way
to handle situations where the AppServer doesn’t respond.
This could be the case when system-work requires no user have access to the system (The
AppServer is stopped), during power-failure or even if the system crashes.
If connection to AppServer dkk004-apitest9 fails during start-up a series of
WORK/csm/noconnect* files are searched from the list below and the first found will
be shown:
1) noconnect-dkk004-apitest9.html
2) noconnect-dkk004-apitest9.htm
3) noconnect-dkk004-apitest9.txt
4) noconnect.html
5) noconnect.htm
6) noconnect.txt

Sample WORK/CSM/noconnect.html:
<head><title>No connection</title></head>
<body>
<h1>No connection</h1>
<p>The AppServer you are trying to connect to is currently
unavailable.</p>
<iframe src="http://www.apipro.com/rd/noconnect/dkk004-apitest9.html"
height="500" width="700">
</iframe>
</body>
</html>

Tip: Using an html-file with IFRAME pointing to an external webserver allows status
updates for most cases.

CSM event
Get signals from the CSM workflow.
Example: Send a mail after every compile with the log-file attached.
Sample CSM/event.cmd:
@ECHO OFF
REM event.cmd
REM Run scripts called from the different events of the CSM workflow
REM Parameters: event build buildhome
REM ======================================================================
IF NOT "%1"=="compileend" GOTO END
IF EXIST "%~3\compile.err" C:\APISERVER\tools\blat.exe "%~3\compile.log" -
to ppl@apipro.com -subject "Compile build %2 failed" -server 192.168.195.7
-f apitest9.rd.apipro.com@test.com
IF EXIST "%~3\compile.ok" C:\APISERVER\tools\blat.exe "%~3\compile.log" -
to ppl@apipro.com -subject "Compile build %2 finished" -server
192.168.195.7 -f apitest9.rd.apipro.com@test.com
:END

API PRO -79- Client Server Management

 Overwrite file-type
The client-image made by a selection of files from WORK/ at the AppServer, is based on a
series of rules, but some-times a certain file need to be included or rejected. Should a file be
listed in CSM/work.lst the normal rule will not apply and instead controlled by the
attached TAG:
• CLIENT Part of the image
• DELETED Should be deleted
• SERVER Not part of the image

Sample CSM/work.lst:
new.log CLIENT
old.lg DELETED
"Reports/My report.ini" CLIENT

Example: Delete old.lg on clients and make sure new.log and Reports/My report.ini
are not skipped (as other .ini and .log-files will be).

Note: Use only forward slashes (/), and quotes if the file (or path) contains spaces.

Even though it’s not recommended – this method can be used to update client.ini or
client.pf of all clients since the initiator uses the files located in WORK/ at the clients.
The steps required to make WORK/client.pf “shared” would be:
1. Overwrite the default logic of CSM so changes to WORK/client.pf will be mirrored
at clients by adding this line to CSM/work.lst:
client.pf CLIENT

2. Modify CSM/client.pf so it‘s fully updated and copy the context to

WORK/client.pf (and changed since last Check done by CSM)

3. Do a new Check – which will add client.pf to the change-log.

Note: Installing new packages could overwrite WORK/client.pf

API PRO -80- Client Server Management

 Advanced MSI-library
It’s possible to have a local library for MSI-packages including the setup they are based
upon.
Follow these steps:
1. Dump the setup from a system you want to manage locally into a directory using the
Initiator menu-option. This will take the current files for the initiator package from the
AppServer you are connected to.

2. The files can now be edited for special setup or requirements – like “default language”,
“CodeJock”-version…

3. Using the Load setup button found at the Initiator-tab this local directory can then be
loaded into any Client Server Management-program/AppServer and then these files will
be the source for the package generated by the Generate-button.

4. The entered values in the tab will be stored in client.log and client.wxs files
found in the root of the local directory.

UNC client
If a CSM-client should use a UNC-path for the client image some changes are required to
the set-up.

Note: Fix A13658 (see: Enhancements and related fix-packages) or newer are required.

The root of the system should be at: \\192.1.1.2\shares\apipro\apitest9\

Make a copy of client.cmd and client.ini to a local drive and make the following
changes:
Sample client.cmd:
:RUN
CMD /C START "APIPRO" "%PROEXE%" -T "%TEMP%" –pf
\\192.1.1.2\shares\apipro\apitest9\WORK\client.pf -ininame client.ini %1
%2 %3 %4 %5 %6 %7 %8 %9
:END
ENDLOCAL
1 Remove or comment: CD WORK
In newer versions of this script option: /D "%~dp0WORK" should be removed from the
START command instead
2 Prefix the root to client.pf

Sample client.ini:
…
[Startup]
PROPATH=\\192.1.1.2\shares\apipro\apitest9\WORK
…

1 Set full-path for WORK/

API PRO -81- Client Server Management

 Add an “interface”-database for compile
Some installations have an additional interface-database running, which should be
connected during the compile
Follow these steps:
1. Create an empty interface-database in the CSM/ directory.

2. Load the provided data-definitions – could be interface.df

3. Make sure CSM/compile.pf exist.

If this file is NOT found then take a copy from CSM/batch.pf

4. Add the database to CSM/compile.pf including option -RO.

Sample CSM/compile.pf:
-db C:\APISERVER\APITEST9\DB\api3
-db C:\APISERVER\APITEST9\CSM\interface -RO
…
-b # Batch mode
-rx # Enable compile of xcode
-p csm/compile.p # Startup Program

API PRO -82- Client Server Management

 Check AppServer continuously for changes
Using the CSM/check.cmd script the “Task Scheduler” can be used to capture any
changes made to WORK/ outside CSM on a regular basis:

Set current directory (“Start in”) to the WORK/-directory.

API PRO -83- Client Server Management

 Load new data-definitions
If the data-dictionary of a system should be changed follow these steps:
1. Update noconnect-files if used (see: Reject login) to tell users information like why the
system is closed, who to contact, and when it is expected to be online again.

2. Shut down the AppServer and database.

3. Make a back-up.

4. Follow the installation notes provided including: load the new data-dictionary (typical a
df-file with the changes) and install optional new application parts.

5. Compile the system using the SETUP/compile.cmd script.

6. Start the database.

7. Run fix-db.

8. Since all the data-areas of CSM are related to an older version of the data-model these
are no longer valid for rollback and could be removed by the menu-option: Reset server
of the Client Server Management-program.
If this option is not used then record the new files of WORK/ using the menu-option:
Check or run the CSM/check.cmd script.

9. Update noconnect-files if used.

10. If required, clients can be triggered to do a reinstallation.

This event could be part of the basic set-up of the AppServer (see: Issue reinstallation)
or fired manually using the option: Reinstall clients.

11. Start the AppServer.

API PRO -84- Client Server Management

 Change BaseLine location
By default, the installation-directory of the BaseLine is placed in the appropriate Program
Files-directory for the OS-version.
From 10.2.2.8d setting INSTALLDIR at the command-line will overwrite the default and
make sub-packages for Progress ODBC-driver and Progress Helpfiles follow to the new
location.
Sample baseline.ini:
[SETUP]
Title=API PRO Client BaseLine installation
…
[PACKAGE2]
PackageName=Progress and CodeJock
PackageProgram=msiexec
PackageParameter=/qn /i baseline-10.2.2.8d.msi INSTALLDIR=D:\APIPRO\BaseLine
[PACKAGE3]
PackageName=Progress ODBC-driver
PackageProgram=msiexec
PackageParameter=/qn /i odbc-10.2.2.8d.msi
…

Note: INSTALLDIR changed for the baseline only.

API PRO -85- Client Server Management

 Master/slave(s) setup
If two or more AppServers should share file-system and always have the exact same
software installed but connect to different databases one of the AppServers should be seen
as the master – and be the only AppServer used for controlling the software of the
installation.
As the file-system is reused the load and compile phases of the CSM-workflow are handled,
but the deploy phase (running “fix-db”) is only executed for the master database and needs
to be forwarded to the slave-databases by catching the deployend-event.

Note: Fix A17946 (see: Enhancements and related fix-packages) introduces allow-
systemnames and reject-systemnames to the setup and could be used to ensure
packages are only loaded in the master.

Beneath a sample setup with root of file-system in: C:\APISERVER\APITEST9:

Sample CSM/event.csm (Using deployend the signal is forwarded to a slave setup):

@ECHO OFF
REM event.cmd
REM Run scripts called from the different events of the CSM workflow
REM Parameters: event build buildhome
REM ======================================================================
SETLOCAL
:DEPLOYEND
IF NOT "%1"=="deployend" GOTO NEXT
REM Do something at deployend
SET "slavecmd=%~dp0slave.cmd"
IF EXIST "%slavecmd%" CALL "%slavecmd%" "fixdbbuild,%2"
GOTO END

:NEXT
REM More actions here...
GOTO END

:END
ENDLOCAL

Sample CSM/slave.cmd (Setup for batch-process against the slave database):

@ECHO OFF
REM slave.cmd
REM Run any? CSM command
REM ======================================================================
CD /D "%~dp0..\WORK"
prowin32.exe -pf ../CSM/slave.pf -ininame ../CSM/batch.ini -param %1 >>
..\CSM\slave.log

(The sample setup continues on the next page)

API PRO -86- Client Server Management

 Sample CSM/slave.pf (Copy of CSM/batch.pf with setup for the slave database):
-db C:\APISERVER\APITEST9\DB\testdb # Database
-ld api3 # Set logical name

-T C:\temp # Temporary Files

-b # Batch mode
-p csm/server.p # Startup Program

Note: Only some of the options related to this specific setup are listed above.

Protect files
The CSM-workflow can be used to ensure packages loaded will not overwrite certain files
(like important configuration) during deployment.
Using the loadend-event the loaded package can be examined and optionally changed since
this is done in a separate workspace.
In the sample beneath CSM/protect.lst optionally lists which files to protect at the
AppServer. Any of these files found in the package will be moved into a parallel directory-
structure under protect/:

Sample CSM/event.csm (Using loadend to get the package examined):

@ECHO OFF
REM event.cmd
REM Run scripts called from the different events of the CSM workflow
REM Parameters: event build buildhome
REM ======================================================================
SETLOCAL
:LOADEND
IF NOT "%~1"=="loadend" GOTO NEXT
SET "protectlist=%~dp0protect.lst"
IF NOT EXIST "%protectlist%" GOTO END
CD /D %~3
FOR /F %%f IN (%protectlist%) DO IF EXIST "%%f" CALL :MOVEPROTECT %%f
protect\%%f %%~nxf
GOTO END

:NEXT
REM More actions here...
GOTO END

:MOVEPROTECT
ROBOCOPY %~dp1 %~dp2 %3 /MOV /NFL /NDL /NJH /NJS /nc /ns /np
GOTO :EOF

:END
ENDLOCAL

(The sample setup continues on the next page)

API PRO -87- Client Server Management

 Sample CSM/protect.lst (List of files to protect from being overwritten):
CSM/batch.ini
CSM/batch.pf
CSM/check.cmd
CSM/client.cmd
CSM/client.ini
CSM/client.pf
CSM/compile.cmd
CSM/compile.pf
CSM/compile.ini
CSM/init.cmd
SETUP/apipro.cmd
SETUP/compile.cmd
WORK/apipro.ini
WORK/apipro.pf
WORK/autocomp.ini
WORK/autocomp.lng
WORK/autocomp.pf

API PRO -88- Client Server Management

 Translation

This section lists how CSM supports translations of the application.

Add/change translation databases

Two different databases are used for translation:
apitrans standard translations (placed in XCODE/)
csttrans custom translations (placed in CUSTOM/)

Both databases can be added or changed (individually or simultaneously) through CSM

using a local file-system like for Add/change some files.

Note: If you modified translations to any languages or added translations to the language
CST, please make sure you export your translations before loading a pack with apitrans
(System – Translation Tool, Options – Export to text file, one call of the option per
language modified) and import them after you loaded the pack (Translation Tool, Options –
Import from text file).

In rare cases, the apitrans pack includes corrections to translations which are part of a fix of
a program error. If there are translations you modified among them, you will need to merge
your changes with the standard corrections manually. The description of the corrections if
they exist is available in the package description.

API PRO -89- Client Server Management

 Local file-system required for adding standard translations (apitrans):
C:\temp\upload\ Root-directory
C:\temp\upload\xcode\apitrans.b1 Database (before-image)
C:\temp\upload\xcode\apitrans.d1 Database (data)
C:\temp\upload\xcode\apitrans.db Database (main)
C:\temp\upload\xcode\apitrans.lg Database (log-file)
C:\temp\upload\compile.tot Empty file
C:\temp\upload\package.txt Description

Local file-system required for adding custom translations (csttrans):

C:\temp\upload\ Root-directory
C:\temp\upload\custom\csttrans.b1 Database (before-image)
C:\temp\upload\custom\csttrans.d1 Database (data)
C:\temp\upload\custom\csttrans.db Database (main)
C:\temp\upload\custom\csttrans.lg Database (log-file)
C:\temp\upload\compile.tot Empty file
C:\temp\upload\package.txt Description

Load the local root using option: Import & deploy or Import directory.

Tip: If the database(s) should be loaded at a remote site, a ZIP-archive with all files and
subfolders made from inside C:\temp\upload will produce a loadable package.

The CSM-compiler will automatically include these databases if they are present when the
compile starts and here the PROPATH ensures the priority among found instances, but the
Translation tool requires CUSTOM/ to be listed in PROPATH of the AppServer-agent setup:

API PRO -90- Client Server Management

 Add/change languages
CSM general uses the MD5-value of compiled programs to determine if any changes have
occurred between two versions, and translations (added by the compiler) participates in this
calculation.
The compiler adds translations for the languages configured in WORK/autocomp.lng
(line 3) and stores the list in the compiled program:

API PRO -91- Client Server Management

 Add/change translations
Translations can be edited using the Translation tool (found in System menu)

If a custom translation database is available (See: Add/change translation databases above)

this can edited too:

Besides editing translations, this editor can start the Compile tool using Create compile list-
option or the Compile-button:

API PRO -92- Client Server Management

 This tool provides different options to compile and/or translate the application:

Compile directly at AppServer

This option is only available if the current client has direct access for the shared application
directory where the configuration files: WORK/autocomp.ini,
WORK/autocomp.lng and WORK/autocomp.pf are located – see: AppServer file-
system.

Use a CSM build for ‘Compile & Deploy’

If the Client Server Management feature has been configured this method can be used from
any client connected to the AppServer. A new build will be created and uploaded to the
AppServer where a separate batch-process will do the compile.
The compile option skip-missing will be set in compile.opt for translation based
on Changed translations only or Delete translations only – see: Build file-system.
A number of additional options for controlling the connections of the compiler to the
translations databases are available through compile.opt too.

API PRO -93- Client Server Management

 File-systems

This section lists the files and directories used by CSM.

Client file-system
List of the baseline directories located under INSTALLDIR – default:
programfiles\API Maintenance Systems:
Filename Description
ocx/ Libraries and files being registered during installation.
openedge/ 2nd generation home for DLC for API PRO 9 & 10.
progress/ 1st generation home for DLC for API PRO 7, 8 & 8.1.

List of files used by CSM at the clients for each AppServer installation:
Filename Description
client.cmd Start-up script.
WORK/apipro.r Normal start-up procedure.
WORK/client.ini Normal .ini-file configured for AppServer connection including:
NoSplash=yes
WORK/client.pf Normal .pf-file configured for AppServer connection including:
-mc
-p csm/client.p
WORK/csm/admin.r Administrator functionality (deprecated)
WORK/csm/client.r Client-initiator – called from “-pf client.pf".

API PRO -94- Client Server Management

 Filename Description
WORK/csm/client.log Contains the setup from the last update.
First line states:
Change-log,TimeStamp
Following lines lists files retrieved from the server.

If this file is lost (or deleted) a complete client-image will be

downloaded.
Otherwise the change-log is used to determine which files
needs to be installed to be in sync with the server.
WORK/csm/client.ok “Client image ok” signal.
WORK/csm/client.err Optional list of errors from latest start-up.
WORK/csm/client.lst List of files downloaded from the AppServer.
Every download is appended to this file as long as change-log is
accepted.
WORK/csm/apipro.ico Icon for window.
WORK/csm/apilogo.bmp Logo-image shown at start-up.
WORK/maint/client/ttcsm.r The Client Server Management-program (Client logic).

API PRO -95- Client Server Management

 Build file-system
List of build-files and directories used by CSM of packages being loaded:
Filename Description
CLIENT/ Files here will end in CLIENT/ at the AppServer and be part of the
compile and deploy phases.
compile.lst List of programs to be compiled.
Sample:
apphelp.p
apipro.w
compile.opt Options for the compile-process including:
• No-md5test (Note: Fix A20434 required)
Don't cleanup programs (and classes) after compile if the
MD5-VALUE was unchanged.
This is a work-around for Progress issues where the built-in
calculation fails to report changes.
• no-retry
Skip the default “error 477 work-around”
• no-rx
Skip Progress option ‘-rx’ from the compile-process.
• no-spawn
Don’t spawn the compile-process.
• skip-api-comp.tot
Skip api-comp.tot from total-compile.
• skip-apitrans.db (Note: Fix A16038 required)
Don't look for standard translations (APITRANS database).
• skip-apitrans.pf (Note: Fix A16038 required)
Don't look for a parameter-file for the APITRANS database.
• skip-client.lst
Skip CLIENT/client.lst from total-compile.
• skip-compile.ini
Don’t look for CSM/compile.ini when compile starts and
use CSM/batch.ini.
• skip-compile.pf
Don’t look for CSM/compile.pf when compile starts and
use CSM/batch.pf.
• skip-csttrans.db (Note: Fix A16038 required)
Don't look for custom translations (CSTTRANS database).
• skip-csttrans.pf (Note: Fix A16038 required)
Don't look for a parameter-file for the CSTTRANS database.
• skip-custom.lst
Skip custom.lst from total-compile.
• skip-missing
Down-grade a missing source-file to a warning.
Default this will count as an error.

API PRO -96- Client Server Management

 Filename Description
• write-delete.cst
Generate the custom clean-up list before the compile starts.
• write-delete.lst
Adds sourceless programs to delete.lst before the
compile starts.
compile.tot The presence of this build-file triggers a Total compile.
CUSTOM/ Files here will be end in CUSTOM/ at the AppServer and be part of
the compile and deploy phases.
delete.cst List of files to be deleted including the parent directory as they are
no longer part of a “custom package”.
Sample:
CUSTOM/fix-db/fix-cc-name.p
CUSTOM/fix-db/server/fix-cc-name.p
WORK/fix-db/ esolutio.cst
WORK/fix-db/design-custom/B_project().xml
delete.lst List for files to be deleted including the parent directory.
Sample:
XCODE/system/agrsfind.p
WORK/system/agrsfind.r
package.txt Description of the build in plain text.
WORK/ Files here will end in WORK/ at the AppServer and be part of the
compile and deploy phases.
WORK/api-comp.tot This file will overwrite the current setup deployed at the AppServer
– making a Total recompile locate the right programs.
WORK/custom.lst This file will overwrite the current setup deployed at the AppServer
– making a Total recompile locate the right programs.
XCODE/ Files here will be end in XCODE/ at the AppServer and be part of
the compile and deploy phases.

API PRO -97- Client Server Management

 AppServer file-system
List of files used by CSM at the AppServer:
Filename Description
CLIENT/ Home of any site-specific 4gl
CLIENT/client.lst List (1 of 3) of programs to be included in “compile all programs” –
listing the context of CLIENT/.
The other parts are WORK/api-comp.tot and
WORK/custom.lst.
CSM/backup/ Home of the backups made when a build in installed at the
AppServer.
CSM/backup/number/ Root of change number providing a base for the standard
directories: CLIENT/ CUSTOM/ WORK/ XCODE/
The number is formatted using 8-digits.
CSM/backup/number/backup.lst List of changes done at time of deployment.
If the build is rolled back “CREATED"-actions will be converted to
“DELETE" in the deploy.act-file of the new build.
CSM/banner.bmp Optional “Banner” for the MSI client-initiator.
Size should be: 493x58 pixels.
Sample:

CSM/batch.ini .ini-file for batch

CSM/batch.log Running log from batch processes
CSM/batch.pf .pf-file for batch
CSM/build/ Home of the builds
CSM/build/number/ Root of build number providing a base for the standard
directories: CLIENT/ CUSTOM/ WORK/ XCODE/
The number is formatted using 8-digits.
CSM/build/number/compile.do Trigger compile after load has finished.
CSM/build/number/compile.err Last compile had error(s).
The fill will be deleted if the build is re-compiled.
CSM/build/number/compile.lst List of programs to be compiled.
CSM/build/number/compile.log Log for last compile – see: Compile log.
CSM/build/number/compile.ok Last compile went OK
CSM/build/number/compile.opt Options for the compile-process – see:Build file-system.
CSM/build/number/compile.tot Make a “total recompile”.
This file is created by the package-loading if the message file
states: “…total recompile…"
CSM/build/number/CLIENT/ On-site 4gl

API PRO -98- Client Server Management

 Filename Description
CSM/build/number/CUSTOM/ Encoded customizations and/or csttrans-database.
CSM/build/number/deploy.act Special actions at deploy-time:
• DELETE file
Will move the file to the back-up area.
CSM/build/number/deploy.do Trigger deployment of the build after compile.
Note: Should the compile end with errors, this “trigger” is ignored.
CSM/build/number/deploy.err Build couldn’t be deployed due to some error.
CSM/build/number/deploy.ok Build has been deployed.
CSM/build/number/deploy.tot Trigger deployment of the build after compile regardless if any
error occurred unlike deploy.do.
CSM/build/number/load.err Some error occurred during load and should be deleted before any
compiles including this area can be started.
CSM/build/number/load.ok Build has been successfully loaded.
CSM/build/number/missing.lst Programs which failed to compile (did not produce r-code).
Can be used as source for a new compile.lst
CSM/build/number/package.dir Optional reference to a local directory loaded.
CSM/build/number/package.txt Description of the build in plain text.
CSM/build/number/WORK/ The resulting changes.
CSM/build/number/XCODE/ Encoded source and/or apitrans-database.
CSM/build.log The latest build reserved.
CSM/build.lck The CSM is locked for making builds.
Rejects makebuild() to make new areas.
Unlock using unlockbuild(0).
CSM/change/ Home of the changes documented.
CSM/change.log High-water mark from last change.
This is the only log-file which is not cleared by ResetServer.
CSM/change/number.lst List of changes of change number
The number is formatted using 8-digits.
CSM/check.cmd Script for recording the WORK/-directory.
Work just like the Check-menu-option in the Client Server
Management-program.
CSM/client.cmd Part of the client-initiator.
If this file is missing the standard WORK/client.cmd is used as
template.
CSM/client.ico Part of the client-initiator (MSI-version) used for making desktop-
shortcut and menu-item in the start-up folder.
If this file be missing the standard WORK/image/apipro.ico
is used as template.
For v7 systems the default was: WORK/image/api7.ico

API PRO -99- Client Server Management

 Filename Description
CSM/client.ini Part of the client-initiator
Should this file be missing WORK/apipro.ini is used as
default.
CSM/client.pf Part of the client-initiator.
If this file be missing the standard WORK/client.pf is used as
template.
CSM/compile.ini .ini-file for compile (in batch mode)
CSM/compile.pf .pf-file for compile (in batch mode)
CSM/dialog.bmp Optional “Dialog” for the MSI client-initiator.
Size should be: 493x312 pixels.
Sample:

CSM/event.cmd If this command is present, it will receive “events” from the CSM-
workflow.
The command will be executed with current-directory set to WORK/
and 3 parameters:
1. Unquoted character string in lowercase telling which event
is launched:
• createbuild
• loadend (A15602 or newer required)
• compilebegin
• compileend
• deploybegin
• deployend
• deletebuild
• createchange
• deletechange
2. Number of the build or change being processed.
3. Quoted path for the home of the build-workspace or
filename of the changelog.
CSM/event.log Optional log-file for output of CSM/event.cmd calls made.
CSM/fix-db.log Log from a fix-db-phase of deployment.

API PRO -100- Client Server Management

 Filename Description
CSM/init.cmd Script to export files for the CSM-initiator.
Work just like the Export files (Initiator) in the Client Server
Management-program.
CSM/launch.log Log from launching batch-processes at the AppServer.
Used in 7.0SP05 and replaced by CSM/batch.log in newer
versions.
CSM/server.lst Last known status of WORK/.
Used by CheckWork to find the files that have been created,
modified or changed.
CSM/server.opt Additional configuration – see: Additional configuration.
CSM/work.lst List of files where the default logic to determine if a file is CLIENT
or SERVER only can be overruled.
The format of each line is: filename action. (see sample :
Overwrite file-type).
Both values are in IMPORT-format (optional placed in quotes).
Actions are one of:
• CLIENT
Send this file to the clients.
• SERVER
Don’t send this file to the clients.
• DELETED
Delete the file at the clients but don’t raise an error if it
doesn’t exist.
CUSTOM/csttrans.db Translation database.
CUSTOM/csttrans.pf Optional parameters when the compiler connects to the database.
Option –RO is always set.
INIT/ Home of exported CSM-initiator files.
XCODE/apitrans.db Translation database.
XCODE/apitrans.pf Optional parameters when the compiler connects to the database.
Option –RO is always set.
WORK/api-comp.tot List (1 of 3) of programs to be included in “compile all programs” –
listing the context of XCODE/.
The other parts are WORK/custom.lst and
CLIENT/client.lst.
WORK/autocomp.lng Configuration (text-file). See: Add/change languages.
WORK/client.cmd Default client.cmd command file.
If needed the file can be copied to CSM/client.cmd and
modified (the client-initiator will then use this).
WORK/client.pf Default client.pf command file.
If needed the file can be copied to CSM/client.pf and modified
(the client-initiator will then use this).
WORK/csm/compile.r The CSM compiler, running in batch-mode at the AppServer.

API PRO -101- Client Server Management

 Filename Description
WORK/csm/noconnect- 4. Priority file which will be shown if connect fails during
appserver.html
start-up for the specific AppServer called: appserver in
the default file-viewer for the html-file-suffix – Typical
InternetExplorer or Firefox
Using “iframe” or “location” the actual status/reason could be
broadcasted to the clients trying to connect.
If this file is found the loop stops here – otherwise the client-
initiator will look for the 2. Priority.
WORK/csm/noconnect- 5. Priority file which will be shown if connect fails during
appserver.htm
start-up.
Only difference from 1. Priority is the spelling of the suffix.
If this file is found the loop stops here – otherwise the client-
initiator will look for the 3. Priority.
WORK/csm/noconnect- 6. Priority file which will be shown if connect fails during
appserver.txt
start-up.
Now the default file-viewer for the txt-file-suffix (typical notepad)
will be used.
If this file is found the loop stops here – otherwise the client-
initiator will look for the 4. Priority.
WORK/csm/noconnect.html 7. Priority file which will be shown if connect fails during
start-up for any AppServer.
If this file is found the loop stops here – otherwise the client-
initiator will look for the 5. Priority.
WORK/csm/noconnect.htm 8. Priority file which will be shown if connect fails during
start-up.
Only difference from 4. Priority is the spelling of the suffix.
If this file is found the loop stops here – otherwise the client-
initiator will look for the 6. Priority.
WORK/csm/noconnect.txt 6. Priority file which will be shown if connect fails during start-up.
WORK/csm/server.r Run by WORK/maint/server/ttcsm.r and
WORK/csm/client.r providing the logic at the AppServer.
WORK/csm/server.log Determine the most recent installed build and is used to control the
PROPATH of new builds (which should include all builds not yet
deployed).
The file is placed here (rather than in CSM/) to capture a restore of
WORK/.
First line states:
Build,TimeStamp
WORK/custom.lst List (1 of 3) of programs to be included in “compile all programs” –
listing the context of CUSTOM/.
The other parts are WORK/api-comp.tot and
CLIENT/client.lst.
WORK/maint/client/ttcsm.r The Client Server Management-program (Client logic).
WORK/maint/server/ttcsm.r The Client Server Management-program (Server logic).

API PRO -102- Client Server Management

 Data Base

Two Note-records are created to ensure single-user access to two critical flows.

Build-lock
Relates_to LOCK
Relate_Key csm/server.p|build
Type 1

Change-lock
Relates_to LOCK
Relate_Key csm/server.p|change
Type 1

API PRO -103- Client Server Management

 Knowledge base

Beneath some reported issues all related to CSM are listed – including the cause, and
possible solution or work-around.

Uninstall the present installed version first

Each MSI package has a unique GUID ("Globally unique identifier") and if the client
already knows this value the installation stops:

The GUID used by API PRO is based on the values used for connecting to the AppServer
and in some cases this calculation might accidentally produce the same value for two
installations – blocking the second from being installed.
A workaround for this could be to change the name of one of the AppServers (or the service
it provides) as described here: AppServer Name.

Live example of two configurations with colliding GUID: (32 last characters match)

System 1 System 2

Host cmms-dev.agcintranet.eu cmms-test.agcintranet.eu

Port 5162 5162

AppServer Production_AS Production_AS

Part used for GUID .agcintranet.eu5162Production_AS

API PRO -104- Client Server Management

 Initial window not on top
The initial window used by the initiator and login-dialog is not shown “on top” but hides
behind other applications (in windows 10) when started from a desktop-icon or a menu-item
in the start menu:

Change the RUN-attribute of the shortcuts from using Minimized to Normal window:

Note: Fix A16038 (see: Enhancements and related fix-packages) solves this too.

Clients always downloads

If clients are downloading the application at every start-up, it’s because the file-system of
the AppServer is in an unknown state.
Until the AppServer have been successfully configured and had a Check recording the files
of WORK/ only the MD5 matching done by the client will reduce the download.
Follow the steps (1 to 7) of the Installation section in this manual to solve this.

API PRO -105- Client Server Management

 System not compiled with chosen language
If language(s) with no influence to the “strings of apipro.w” (main login program) are added
to the list – this could result in a warning during login:

As a work-around it seems changing the order of the listed languages with “strings of
apipro.w” can solve this problem.

Load fails
A build (package) fails to load with the following message:

The root of the package should have one (or more) of the know sub-directories: CLIENT/,
CUSTOM/, XCODE/, WORK/ or special-files to be accepted.

Empty builds (only having a directory structure, but no files) can’t be loaded and this could
be the case if a ZIP-archive is protected by a password.

API PRO -106- Client Server Management

 The solution to this problem is to manually unzip the package to an empty local directory
(and provide the password required) and then load this directory using one of the Import
options.

File-names with national characters may result in load-errors too and these files can’t be
handled by CSM.

Compile fails
The program fix-db/fix-@#$.p fails to compile, but the log doesn’t list any specific
error message:
Program fix-db/dump-api.p 22EF92A4A17995B357EF6DFF81B84B87 14:21:26
Program fix-db/fix-@#$.p ? 14:21:26
Error: C:\APISERVER\APIPRO9\XCODE\fix-db\fix-@#$.p
Program fix-db/fix-acco-commit.p 515321A625ABB72734855DA6BA00A091 14:21:26

Make sure the setup used for the compile includes option –nocandodomain.

API PRO -107- Client Server Management

 Build not deployed
A build (package) compiles, but is not deployed.
Using the option: Deploy build brings up an error:

Builds have to be deployed in the right order and attempts to skip a build will be rejected.
Here build 3 and 4 are both successfully compiled, but both are not deployed – and build 4
then waits for 3.

Note: Fix A15969 (see: Enhancements and related fix-packages) disables work-flow
options (including the drop-zone) when a build is not deployed.

API PRO -108- Client Server Management

 CSM rollback
CSM/ have been deleted (but WORK/server.log survived).
CSM/build/00000001/compile.log looks like:

Compile start : 28/02/2014 09:15

Compile build : 1
Server deployed : 219
Compile setup failed

Or (older version installed):

Compile start : 28/02/2014 09:15

Session info:
GUI MS-WIN95
Screen esolution : 768 by 1024 pixels = 32 by 146,29
characters
Session code Page : UTF-8
Stream code Page : UTF-8
Numeric format : EUROPEAN = thousand delimiter ‘.’ decimal
poi
Date format : dmy
Font (DEFAULT): : APIPRO(50x16)1234567890(70x16)
Font (0): : APIPRO(42x14)1234567890(70x14)
Font (1): : APIPRO(40x13)1234567890(60x13)
Font (2): : APIPRO(42x14)1234567890(70x14)
Font (3): : APIPRO(42x14)1234567890(70x14)
Font (4): : APIPRO(40x13)1234567890(60x13)
Font (5): : APIPRO(50x16)1234567890(70x16)
Font (6): : APIPRO(46x13)1234567890(70x13)
Font (7): : APIPRO(40x13)1234567890(60x13)
Font (8): : APIPRO(42x14)1234567890(70x14)
Font (9): : APIPRO(50x16)1234567890(70x16)
Font (10): : APIPRO(48x16)1234567890(80x16)
Font (11): : APIPRO(48x15)1234567890(80x15)
Font (12): : APIPRO(40x13)1234567890(60x13)
Font (13): : APIPRO(40x14)1234567890(60x14)
Font (14): : APIPRO(40x13)1234567890(60x13)
Font (15): : APIPRO(40x13)1234567890(60x13)
Font (16): : APIPRO(38x13)1234567890(60x13)
Font (17): : APIPRO(38x13)1234567890(60x13)
Font (18): : APIPRO(50x16)1234567890(70x16)
Builds2201

WORK/csm/server.log:
219,28/02/2014 09:15:53

The compile fails when the server already has a higher build deployed (219) than the new
one (1).
The strange text “Builds2201" is from the code trying to build the PROPATH through the
CSM-workarea from server+1 to build…

A simple solution could be to use the option: Reset server.

API PRO -109- Client Server Management

 Progress error -127
An -127 error shows at start-up:

The –cpcoll option is assigned an unsported value.

Correct the –pf file used:
…
-cpcoll ICU-UCA # Default utf-8 linguistic collation
…

Progress error 43
Every time the client starts the entire application is checked and the file
csm/client.err shows errors like:
"" "csm/apilogo.bmp" ? 136134 2013-10-14T16:14:14.000
"** Cannot find or open file C:/APIPRO8/BEF069/work/csm/apilogo.bmp, errno = 13.
(43)"
"" "csm/apipro.ico" ? 110229 2013-10-14T16:14:14.000
"** Cannot find or open file C:/APIPRO8/BEF069/work/csm/apipro.ico, errno = 13.
(43)"

The user running the client-initiator should have access to create and update all files under
the chosen installation directory.
The fact that only errors from updating graphical files shows here is due to the additional
MD5 check for programs (skipping this from the download), but the remaining files initial
installed fails to be updated.

API PRO -110- Client Server Management

 Progress error 477
Compile build fails with some 477 errors like:
Unable to create r-code file
"C:\APIPRO\CLIENT\APIPRO8\csm\build\00000001\work\appserv\system.r". (477)
Error: C:\APIPRO\CLIENT\APIPRO8\xcode\appserv\system.p

Create directory fails?

If the programs failing all are the first program compiled for that directory, we have seen
this problem on very fast discs-systems. The directories are created on a “need to” basis and
if these operations are not made in sync this could go wrong. A “solution” for this strange
problem has been to do a recompile of the same build. Even though the work-area is cleared
before the compile start – the compile succeeds.

Multiple sessions?
The error listed above is from a total recompile – and here appserv/system.r is not the
first program for appserv/.
This time two different API PRO systems were using the same WORK/ (and thus CSM/
too!) and both systems had the total recompile started almost simultaneously.
When systems reuse the WORK/ – one of these systems should be known as the master and
be the only place where CSM-commands and operations are carried out.

Note: Fix A13777 (see: Enhancements and related fix-packages) will do a recompile
(unless compile-option no-retry is set) when the compiler fails with-out any message,
which is the case for error 477.

Progress error 1006

A program fails to run with the following error:

A CSM-client can’t run programs that access a database directly but requires a connection
through an AppServer. If this program should be available for CSM-clients it should be
changed to be “AppServer-aware”.

Note: Fix A13777 (see: Enhancements and related fix-packages) skips all programs
accessing a database from the client-image.

API PRO -111- Client Server Management

 Progress error 1403
The client fails to start:

This error could indicate that a 2nd generation baseline (based on OpenEdge v11.6 or newer)
is missing, but the 1st generation baseline (based on Progress v10.2) is found and fails on
one of the OpenEdge v11.6+ specific options:
…
-nocandodomain # Restore CAN-DO() functionality
…

Note: A 2nd generation baseline is required to run an API PRO 9 or 10 application.

Progress error 2886

Compile build fails with 2886 errors like:

Program system/agrsfind.p
FB470E078D63A225F58C0EEE1E64F246 15:18:37
Warning: object file
D:\AMSDK\APIPRO\TESTCASES\localtest\work\system\agrsfind.r
found before source system/agrsfind.p. (2886)
** "system/agrsfind.p" was not found. (293)
Error: ?

The program system/agrsfind.p is no longer part of the sources but required by the
list of programs to be compiled.
The fact that the current MD5-value is listed is due to an old version still placed under
WORK/.

The solution is either to retrieve the source required or update the list of programs.
If the program no longer should be part of the application, it should be deleted from WORK/.

API PRO -112- Client Server Management

 Progress error 2888
The option Generate (initiator) fails with 2888 error like:

or:

The setups can be loaded and generated anywhere – BUT only within the same major
version of Progress (OpenEdge).

API PRO -113- Client Server Management

 Progress error 4025
Login fails with progress error 4025 and subsequent 4104:

Registering the required prox.dll failed during installation.

1st generation baseline:
regsvr32 "C:\Program Files (x86)\API Maintenance Systems\ocx\prox.dll"
nd
2 generation baseline:
regsvr32 "C:\Program Files (x86)\API Maintenance Systems\ocx\11.7.1.0\prox.dll"

Make sure the baseline is installed while having proper administrator rights.

API PRO -114- Client Server Management

 Progress error 4454
Error trying to store user-id using the Remember me-button in the login-dialog:

The reason for error is the .ini-file being read-only:

API PRO -115- Client Server Management

 Progress error 5622
The initial compile fails with error 5622:
** Error 5622 in ..\XCODE\maint\logic\ttcsm.i at line 1718 column 10
UPDATE, SET, PROMPT-FOR, CHOOSE, INSERT, WAIT-FOR, and READKEY statements are not
permitted inside a user-defined function, or inside a non-void method or a property
GET or SET body. (5622)

The Progress version 10.2B, 10.2B01 should be updated (patched) to 10.2B08 or later.

Progress error 5898

Login fails with progress error 5898:

Registering the required prox.dll failed during installation.

1st generation baseline:
regsvr32 "C:\Program Files (x86)\API Maintenance Systems\ocx\prox.dll"
nd
2 generation baseline:
regsvr32 "C:\Program Files (x86)\API Maintenance Systems\ocx\11.7.1.0\prox.dll"

Make sure the baseline is installed while having proper administrator rights.

API PRO -116- Client Server Management

 Progress error 6087
Login fails with multiple progress errors – like 6087 and subsequent 5884, 5677:

The required CodeJock elements are not available.

By default, CodeJock 13.2.0 will be used, but in version 7.0SP05 the value could be
stated in the [API PRO open.7]-section of the .ini-file – and be either 13.2.0 or
15.2.1 depending on which baseline and subsequent packages have been installed at the
client.
…
[API PRO Open.7]
CodeJockVersion=15.2.1
…

API PRO -117- Client Server Management

 From version 7.0SP06 the [API PRO]-section of the .ini-file have higher prioritize and
supported versions are: 13.2.0, 15.2.1, 16.2.4 (or 16.2.5) – again depending on
which baseline and subsequent packages have been installed at the client:
…
[API PRO]
CodeJockVersion=16.2.4
…

If the CodeJock is correct then the problem has to do with commands like:
regsvr32 "C:\Program Files (x86)\API Maintenance Systems\ocx\
Codejock.Calendar.Unicode.v16.2.4.ocx"

failed during installation of the baseline (or separate CodeJock-package).

Make sure the baseline is installed while having proper administrator rights.

From version 9.0SP00 the default CodeJock version is 16.2.4.

API PRO -118- Client Server Management

 Progress error 9331
Login fails with progress error 9331:

A CSM-client can’t run programs that access a database directly but requires a connection
through an AppServer. If this program should be available for CSM-clients it should be
changed to be “AppServer-aware”.

Note: Fix A13777 (see: Enhancements and related fix-packages) skips all programs
accessing a database from the client-image.

Progress error 11274

The update of the client fails and csm/client.err shows errors like:
"MODIFIED" "crprint/template/cr-conf.rpt" ? 230912 2016-08-30T09:37:47.000 "Could
not write blob to file. Write to file system failed. (11274)"
"MODIFIED" "crprint/template/cr-po.rpt" ? 229376 2016-08-30T09:37:47.000 "Could not
write blob to file. Write to file system failed. (11274)"

Check the disk for free space.

API PRO -119- Client Server Management

 Error 0xc0150002
The client executable (prowc.exe) fails with error-code 0xc0150002:

Make sure “Microsoft Visual C++ 2005“ is installed while having administrator rights and
it‘s the right version available for download at: Microsoft Download Center or at the:
CSM extranet site

API PRO -120- Client Server Management

 Limitations

CSM has a number of limitations.

Package-size
Until fix A15488 (see: Enhancements and related fix-packages) downloading packages
which in total exceed 2Gb will be marked as failed, even if all files were successfully
updated.

File-size
Fix A13797 (see: Enhancements and related fix-packages) introduced a number of
restrictions to avoid misuse.
Maximum file-size of files examined by CSM is 2Gb and for upload/download is 128Mb.
Files listed in CSM/work.lst will however be controlled for download by this setup.

File-name
National characters should be avoided from file-names as they may not be handled
correctly.
Fix A15362 (see: Enhancements and related fix-packages) traps errors during the load-
phase.

Editor-size
Unless Fix A18378 (see: Enhancements and related fix-packages) is included, the Editor
for setting up system configuration files currently has a maximum file-size of 30.000 bytes.
This limit will not allow WORK/api-comp.tot being edited.

API PRO -121- Client Server Management

 Enhancements and
related fix-packages

This table lists CSM enhancements made over time and which fix-packages are available.

Date Enhancement Fix-package

12.02.13 7.0SP05
15.02.13 Separate compile process using CSM/compile.p and A11825
option –rx.
Setup in CSM/compile.ini and CSM/compile.pf
21.02.13 Built-in unzip A11837
22.02.13 Recommended fix for SP05. A11844
27.02.13 Deal with different drives when call OS-commands. (none)
19.03.13 Bug-fix dealing with changelog/build number mismatch. A11925
New command-line: CheckClient for Citrix?
16.04.13 Builds may contain new apitrans and/or csttrans A12027
databases which are then used for the compilation.
30.04.13 Run fix-db in separate process during the deploy-phase. A12045
Setup in CSM/batch.ini and CSM/batch.pf
04.06.13 Trigger CSM/event.cmd A12167
19.06.13 Trap STOP during load and leave. (none)
Previously the initiator would try to re-run (endlessly?) when
the AppServer is down.
02.07.13 A few more files considered “server-only”. (none)
02.07.13 Keeping data and focus in administrator. (none)
19.07.13 Only one smaller bar in APIPRO71 A12272
30.07.13 Missing quotes for some events added. A12284
31.07.13 Accumulative package with all changes. A12300
Note: api-comp.tot from A11825 is not included.
22.10.13 Show a noconnect-file if connection fails A12526

API PRO -122- Client Server Management

 27.12.14 8.0SP00A
20.02.14 7.0SP06
21.02.14 Skip “Schema holder”-files, and empty.txt from the A12936
client-image.
Introduce CSM/work.lst.
24.02.14 8.0SP00B
24.03.14 DELETED files from CSM/work.lst are appended to A13001
“download all”.
02.04.14 StartClient and ResetClient from login (A13034)
11.04.14 Introduce CSM/delete.lst. (A13112)
15.04.14 Shared MSI-packages (A13153)
24.04.14 Accumulative package with all changes since A12300 A13224
See: A13563
03.07.14 Bug-fixes during 8.0SP00C testing. A13563
Replaces A13224.
04.07.14 8.0SP00C
10.07.14 Support for easy deployment of crystal reports template: (A13583)
work/crprint/[<path>/]<file>.rpt.
16.07.14 Stop for load of empty packages (password protected zip?) (A13622)
28.07.14 Support for UNC-paths (A13645)
31.07.14 Accumulative package with all changes since 8.0SP00C A13658
08.09.14 Skip programs accessing a database from the client-image. A13777
Introduce compile.opt.
11.09.14 Large files (2Gb not seen, 128Mb not transferred) A13797
15.09.14 Connect through AIA A13806
30.09.14 Allow national characters in file-names of MSI-packages. (A13882)
30.09.14 Accumulative package with all changes since 8.0SP00C A13887
Replaces A13658
02.12.14 • Show version of the package at the Initiator-tab. A13970
• Ensure client.cmd and client.r are available for the
package
• Skip automatically re-launch of the client-startup program if
a new version failed to download (to avoid endless loop if
this file is write-protected).
26.01.15 • Allow simple upload of compile-lists (.lst-files). A14402
• Interface from translation tool.
05.02.15 Hide Remember me in login. A14611
06.02.15 • Programs for the SERVER will be deleted at the client. (A14663)
• Close open files when API PRO ends allowing the
ALT+F12 feature in the login-dialog update all files.

API PRO -123- Client Server Management

 09.02.15 Replace <several> with “Jenkins package information”. (A14666)
11.02.15 Handle phase until first CheckWork-command: (A14686)
• Use csm/server.r to determine if the client is running
at a server-installation.
• Client-images will be complete.
12.02.15 Use SUPERVISOR for running “fix-db” during deployment. (A14699)
16.02.15 Change between winter- and summer-time (due to Day-light- (A14706)
savings setting) will no longer report files as modified.
20.02.15 8.0SP00D
15.04.15 Initiator-tab re-designed, options: Save setup, Append (A15050)
“noconnect” file.
22.04.15 Handle custom packages: Custom clean-up, Options divided (A14963)
into sections.
26.05.15 Setting INSTALLDIR of baseline. (A15119)
04.06.15 Ensure clients are updated: (A15323)
• Control the method used for checking client image
• Support option to Reject access if client is not updated.
08.06.15 8.1SP00
11.06.15 Editor (A15341)
16.06.15 Trap load errors (A15362)
16.06.15 Accumulative package with all changes since 8.0SP00D A15398
See A15488
29.06.15 Accumulative package with all changes since 8.0SP00D A15488
(replaces A15398) including:
• Load locally directly followed by Save remotely failed.
• Disable compile after compile-error, like after load-error.
• Handle total down-loads above 2Gb.
17.07.15 Improvements: A14510
• Not only compile-related options are available in the
Simple-tab.
• Command-line interface includes UploadPackage.
24.07.15 Improvements: A15602
• Support for event loadend.
• Reset server deletes CSM/event.log.
• More files and options available for the Editor.
01.10.15 8.0SP00E

API PRO -124- Client Server Management

 14.10.15 New features for CSM: (A15969)
• “Fat initiator”: Add files to the initial installation, reducing
load of first run.
• Shared .ini and/or .pf files – managed by the
AppServer.
• Configure which packages to allow and/or reject (types,
licenses, db-hash)…
• Issue reinstallation of clients from the AppServer.
• Support compile of classes.
22.10.15 Control sensitivity of Update setup and restore values saved. (A16025)
27.10.15 The initial window is not shown “on top” in windows 10. (A16038)
02.12.15 Spawn compile-process. (A16215)
10.12.15 The client protects the current setup and rejects to delete (A16251)
.ini and/or .pf in use.
11.12.15 Supply AppService for noconnect using AIA (A16262)
15.12.15 If the client receives updated static classes after initial load the (A16276)
process has to relaunch.
22.06.16 New option to Delete part of the history. (A16959)
Options: Delete, Delete build, Delete changes, Lock build and
Unlock build allow selection of multiple lines in the browser
found in the Advanced-tab.
24.06.16 MD5 test for classes postponed until all programs have been (A16987)
compiled.
The layout of compile.log have been changed into
sections (less wide).
A mouse-click on Compile or Deploy in the Simple-tab will
trigger option Compile log or Change log.
21.07.16 The Advanced-tab shows the most recent records at top – like (A17066)
other standard browsers.
Text-files (file-suffix .txt) and data for translations located
in fix-db/ are all now considered having file-type SERVER
which reduces the client-image – see: Overwrite file-type.
Option Program clean-up set sourceless programs to deleted
at the deploy phase.
Additional set-up regarding: Restart notification – and
examine active .pf-file for actual changes.
19.09.16 Options for Restart client, Reset client and Reinstall client (A17328)
added to the client functions sub-menu.
Keyboard combination: CTRL+SHIFT+ALT+F12 in the
login-dialog issues the ReinstallClient command.
11.10.16 Introduce apitrans.pf and csttrans.pf as part of the (A17434)
database set-up.
30.12.16 9.0SP00
02.02.17 Allow/Reject packages: Introduce allow-systemnames (A17946)
and reject-systemnames for master/slave(s) setup.

API PRO -125- Client Server Management

 26.04.17 The compile-options of each build (located in (A18362)
compile.opt) has been extended to support options for
connections to translation databases: skip-apitrans.db,
skip-apitrans.pf, skip-csttrans.db and
skip-csttrans.pf
28.04.17 The Editor accepts larger files. (A18378)
28.04.17 9.0SP00A
06.07.17 Accept files like: append-program-empty.txt to be
loaded.
31.07.17 Option Test connection added to the Initiator-tab. (A18947)
11.10.17 9.0SP00B
21.11.17 Enable 64-bit executables. (A19716)
12.03.18 Support for compile-option: no-md5test. (A24034)
25.07.18 Avoid some duplicated error messages during load operations. (A21198)
9.0SP00C

API PRO -126- Client Server Management