Installation troubleshooting guide

Below is a list of common ProTop installation and configuration issues that we come across regularly. If your issue isn't here, please contact us at support@wss.com for assistance.

Wrong ProTop Download

If you download a source code version of ProTop, you need a license that can compile code, such as a "4GL Development" license. If you only have an "Enterprise Database" license or similar, you need to download r-code (object code) for your version of OpenEdge. Use $DLC/bin/showcfg (or type showcfg from with a Proenv shell on Windows) to display the contents of the OpenEdge license file.

Window size too small (deprecated in ProTop RT 319)

ProTop is information-dense and used to require a minimum 160-column X 48-row terminal window. The larger screen allows you to see multiple panels of correlated information simultaneously, one of the biggest strengths of ProTop.

If you try to run ProTop RT on an old VT100 80X25 screen, you will now see a condensed version of ProTop RT we call Core.

To see the larger version, use putty or a similar xterm-type terminal emulator. You can download putty here.

Weird Colors

By default, ProTop expects a light-colored background to paint contrasting text. If your terminal has a dark background, use the Color Picker and select Dark Mode.
img00200

Weird Characters

The Progress character client does not support UTF-8 characters. If you see weird characters instead of pretty lines and boxes, change your emulator translation from UTF-8 to ISO8859.
img00100

Keyboard and Function Key Mapping

This issue has plagued CHUI applications since the dawn of time! While most ProTop screens don't require special function keys, occasionally, you will need to save or confirm an action through a GO, typically the F1 key. If that doesn't work, try Ctrl-X. Similarly, END-ERROR is usually mapped to the F4 key, but you can try Ctrl-E if F4 doesn't work.

Are control keys not working on Windows?

You might be faced with the ProTop RT control key sequences not working as expected on Windows.  See this article on ProTop and Windows control keys for likely solutions.

Unknown Terminal

On UNIX/Linux, the Progress character client needs to know what terminal you use to paint the screen correctly. Still, some terminal emulators use custom values for the TERM variable. Example:

Unable to use your terminal. Check your PROTERMCAP file. (443) 
** Could not find terminal type xterm-256colour in file /opt/protop/etc/protermcap.protop.Linux. (146)

Try plain xterm instead:

export TERM=xterm

Or download putty here.

Permissions

On both Windows and UNIX, the user ID running ProTop must have adequate permissions to open database files and shared memory segments.

On Windows, this often comes from running the OpenEdge AdminService using the SYSTEM account, whereas the user running ProTop is a regular user. You can try running ProTop as administrator or giving the user the appropriate permissions.

The OpenEdge client executable $DLC/bin/_progres is supposed to be owned by root and have the setuid bit set, but that is not always the case. You'll likely see an "errno=13" message on UNIX, which clearly indicates a permissions issue somewhere. Check by running the following command:

[/opt/protop] $ ls -al $DLC/bin/_progres 
-rwsr-xr-x 1 root root 13811949 Oct 10 2018 /usr/dlc117/bin/_progres

The "s" in "-rwsr-xr-x" is the setuid bit, meaning that the executable runs as the owner, in this case, root. Don't worry - this is not a security flaw. The process runs as root only during the initialization phase, after which it downgrades its permissions to those of the user running the process.

Dictionary Changes

The ProTop agent connects to your database to gather statistics and upload them to the web portal. If you attempt to make a dictionary change without selecting "Add objects online," the pt3agent could block the change. Read the Dictionary Changes guide on how to prevent this.

ProTop Service Paused on Windows

When stopping and starting the ProTop service on Windows, a file access conflict occasionally occurs, and the service pauses. In this case, first, delete all *.flg files in %PROTOP%\tmp, wait 30 seconds, then stop the Windows Service. You can then immediately restart the service. It will start normally, and you will see the dbmonitor.flg flag appear, then pt3agent.*.flg files appear as the pt3agent processes start.

No pt3agents Running

This one is a little tricky because there could be many reasons. Go through these steps to find and fix the root cause:

  1. Start the ProTop Real-Time Monitor using the friendly name defined in $PROTOP/etc/dblist.cfg. See Starting the Real-Time Monitor. Make sure the Real-Time Monitor works before getting the agent to work.

  2. Are you sure the pt3agent is not running? To be certain, check "ps -ef | grep pt3agent" on UNIX or Task Manager on Windows.

  3. Is the DBMonitor running? The DBMonitor reads $PROTOP/etc/dblist.cfg and starts pt3agents for any database with Monitor=yes.

  4. Check if Monitor = yes in $PROTOP/etc/dblist.cfg. For example:

# friendlyName|/dbpath/dbName|serverName|monitor[|dlc[|type]] 
#
s2k|/db/s2k|protoptest|yes|/usr/dlc117|
  1. Check if there is a flag file $PROTOP/tmp/pt3agent.friendlyName.flg. This file is created when the pt3agent starts, and its removal will normally cause the pt3agent to exit gracefully.

  2. Check the agent log file in $PROTOP/log/pt3agent.friendlyName.log for any errors.

  3. Check the error and debug files in $PROTOP/tmp/pt3agent.friendlyName.

  4. On Windows, compare the user that starts the ProTop service and the user that starts the OpenEdge AdminService. The ProTop user may not have the necessary permissions.

No Data in the Web Portal

This issue is almost always a web proxy issue. From the prompt, execute the following curl command. It should immediately return "test passed." Note: substitute the correct web portal if you're not trying to connect to demo.wss.com in North America.

$ curl --connect-timeout 5 demo.wss.com/proxy.test 
test passed

If instead, you see the following, then you cannot reach the web portal from your database server:

$ curl --connect-timeout 10 demo.wss.com/proxy.test 
curl: (28) Connection timed out after 10000 milliseconds

Ask your network administrator if you need to use a proxy, then try again with the proxy information:

$ curl --connect-timeout 10 --proxy proxyhost:8888 demo.wss.com/proxy.test 
test passed

NOTE": Curl is usually installed on all Linux servers. On Windows, you can find it in %PROTOP%\ubin. If you do not have curl execute the following OpenEdge program:

cd $PROTOP
_progres -p util/webget.p

To execute, fill in the same information used above (your ProTop web portal and proxy) and hit F1 (Ctrl-X).

Check for 200 OK:

If there are errors, you might see them in the form or at the bottom of the screen:

If this test fails using the demo.wss.com URL, try using its IP address: 35.174.99.210. If that works, then add this line to your respective host file:

35.174.99.210 demo.wss.com 

For Windows, place this line in:

C:\windows\system32\drivers\etc\hosts 

For Unix, add it to:

/etc/host

Provide the optional "Output File Name" for the full output and more detailed debugging information.

Use this tool to try different port numbers or credentials or wherever you think there might be an error in your configuration.

Blank Userid Not Permitted

If you get the error message "DB connection with blank userid not permitted," add -U and -P to one of the PF files described in protopenv.

Weird Data

Is ProTop telling you that you have no more empty AI extents when you do? Or is it incorrectly stating that you're running in no-integrity mode? Chances are that you upgraded OpenEdge versions without running Update VST. ProTop expects to find information in the VSTs, based on your version of OpenEdge, but that information isn't there. Fix it by running the following command, substituting your full DB path for "DB":

_proutil DB -C updatevst

Missing Table or Index Statistics

Suppose your -basetable, -tablerangesize, -baseindex, or -indexrangesize parameters are insufficient. In that case, there will be tables and/or indexes whose statistics will not be gathered by the associated data collector and, therefore, not displayed in the Real-Time Monitor nor uploaded to the web portal. You can check the Real-Time Monitor and the (T)able and Index Range Info screen.

Bonus: if your values are insufficient, the (T) screen will appear automatically at startup, but you should check them as the values may be sufficient but not optimal.

img00600
Bonus #2: The suggested values for these startup parameters are written to $PROTOP/tmp/friendlyName.range.pf.

No DB Analysis

ProTop provides much more meaningful information if a recent DB Analysis is available. If you start the Real-Time Monitor and see the following warning, please run DB Analysis and copy the output file to $PROTOP/dbanalys/friendlyName.dba:

img00700

You can run DB Analysis from within ProTop by hitting the "!" key (see the Help Page). This process can be quite disk intensive, so you may not want to run DB Analysis while the system is busy:

img00800

pt3autoUpdate Failed

If you see this error message in the Web Portal, ProTop cannot access the curl command for downloading configuration updates. Configure ProTop to use 4GL sockets instead of the curl command in this case. To do this, set PTDLCMD=http in $PROTOP/bin/localenv or %PROTOP%\bin\localenv.bat. See the localenv configuration page for more information.

Character Set Error

If you see this error while installing protop: error:

Character set UTF-8 requires DBE PROGRESS

Then add:  -cpinternal iso8869-1 to your etc/<custId>.pf. If it's not there, create it.