Because no two OpenEdge environments are the same, your ProTop installation can be tailored to fit your specific situation.
This is done by configuring certain environment variables in a file called localenv (or localenv.bat on Windows). Your bin/localenv[.bat] file is called by bin/protopenv[.bat] which is used by most scripts and batch files in your ProTop environment. This file determines and sets all of the environment variables and OE startup parameters required by ProTop.
The localenv file is distributed in the bin subdirectory of the ProTop installation as localenv.x on UNIX and localenv.batx on Windows. To tailor your ProTop installation, copy $PROTOP/bin/localenv.x to $PROTOP/bin/localenv (or bin\localenv.batx to bin\localenv.bat) and make the required modifications.
Localenv "documents" most of the variables used by ProTop and their default values. Such lines appear as commented out (line begins #). If you need to change one of these default values, uncomment the line, set the value as required and restart ProTop by removing the *.flg files from PROTOPDIR/tmp. ProTop will restart shortly.
Below is a listing of localenv variables and their usage. Please don't change these unless you know what you're doing. If you're unsure, send us an email at any time and we'll do our best to respond within one business day.
Special Cases
The User Experience Monitor requires a separate environment file called "zipenv". It is distributed as zipenv.x (zipenv.batx) and must be copied to zipenv (zipenv.bat) and tailored for the User Experience Client/Server Monitor to function correctly. See details below.
The QAD Monitors require a separate environment file called localenv.qad. QAD component monitoring is only available in the commercial version of ProTop.
See your [PROTOPDIR]/bin/localenv.[x|batx] for all of the latest variables and their descriptions.
Global Settings
| Variable | Example Value | Description |
| PORTALPORT | 80 | port to use for portal communications, the default port is 80; use 443 for SSL |
| PORTALOPTIONS | "-ssl -nohostverify" | options to pass to the socket CONNECT() method for portal communications, use "-ssl -nohostverify" to enable SSL, "-clientConnectTimeout 500" is also possibly useful |
| PROXY | proxy.xyz.com:8080 | Proxy server string if needed for *portal" communications, also handles "username:password@proxyserver:proxyport" - watch out for magic characters like '$' |
| USESOCKETS | no | Totally disables all socket code. Should not be needed but if you want to be really sure... |
| WAITLIMIT | 5 | Modify the timeout value for socket communications; don't change this unless your name is "Tom" |
| MINWAIT | 0.1 | Minimum timeout value for socket communications; don't change this unless your name is "Tom" |
| READSIZE | 8 | The size of the socket read buffer in MB |
| VOTRX | 1800 | How old is a TRX before it is considered "very old"? (default 1800 seconds) |
| BOGOMIPS | 1000000 | How many spins to calculate bogoMIPs, 1MM is the default, 0 disables |
| IOFILENAME | /tmp/bigfile | CSV list of large files to randomly read (default is the list of database extents) |
| IORESP | 100 | Number of random seeks for ioResponse, 0 disables |
| USEREXP | no | Disables the "user experience" dashboard metric |
| PICACHECKINTERVAL | 900 | How often to shell out and check "pica" status, default 60 seconds, 0 disables |
| APPSRVSTUCK | 300 | How long an app server can be unresponsive before we consider it "stuck" (seconds) |
| ZOOMTO | 30 | When something interesting happens the pt3agent can "zoom" the sample interval into this frequency |
| NAGME | no | This turns OFF the "message of the day" tips and suggestions feature |
| LKTBLLIM | 9999 | How many lock table entries might we look at before giving up? (obsolete in OpenEdge v11.4+) |
| DFCMD | "df -p" | Alternative df command for disk info screens (Solaris, HPUX, and AIX might need this) |
| DFCMDI | "df -pix tmpfs" | Alternative df command for disk info screens inode info (currently only supported on Linux) (use DISABLE to disable) |
| MNTCMD | "mount" | Alternative mount command for disk info screens mount info (Solaris, HPUX and AIX might need this) (use DISABLE to disable) |
| PTSERVER | jim | A name for the server - using this is probably a bad idea |
| USERFUTIL | yes | Use rfutil rather than VSTs to determine ai extent status |
| AICHECKINTERVAL | 300 | How often to shell out and check ai status (pre oe11.6), default 60 seconds, 0 disables |
| USERLOCK | yes | Enable 11.7+ _UserLock stats on UIO screen -- can be very slow with large lock tables or many users |
| PTDLCMD | http | The command to use to download updates. The default is "http" (use internal socket code), "curl" or "wget" shell out |
| MAILCMD | "mailx &3 -s '&2' &1" | The command to send mail (the "@" command inside CHUI ProTop) |
| PTSCREENMAIL | tom@wss.com | where to mail screen contents when the @ key is pressed |
| SKIPLGSCAN | yes | Skip the scan of the .lg file at startup - this may result in unknown startup parameter values |
| UPDAREADATA | 21600 | Update storage area data and table/index xref bits obtained from dbanalys - default 6 hours, 0=disable |
| PTOLDPORTAL | yes | Support for obsolete backward compatibility for old-style "custid-data.portal..." configurations |
| DBIDOWNGRADE | yes | Downgrade PAGE to ALARM if an alert is related to area 6 or a DBI file (default=yes) |
| TERMHOTLINK | yes | Enables clickable links in the ProTop Real-Time Monitor on UNIX |
| XTRASTART | "cuwa" | Export an initial set of key commands for startup |
| USEACTBUFF | no | Do not use _actBuffer in dc/dashboard.p, 11.7, and 12.X introduced some new fields, and populating them is done by scanning ALL of -B which can be quite slow |
| OSINFOFREQINT | 60 | Frequency of osinfo samples via os-commands when running interactively (protop.p) (this feature does not impact Linux) |
| OSINFOFREQBAT | 3600 | Frequency of osinfo samples via os-commands when running in batch mode (pt3agent.p) (this feature does not impact Linux) |
| UPDATECHECK | 300 | Frequency of checks for update config files from the portal |
| RESPAWNCHECK | 300 | Frequency of checks for agents needing to be respawned |
| SAMPLELIMIT | 10 | exit after N samples - only applies to ProTop RT, pt3agent ignores this |
| HTTPVERSION | HTTP/1.0 | supported values are HTTP/1.0 and HTTP/1.1, 1.0 is the default |
| AUTORESIZE | no | turn off support for automatically detecting window resizing (Unix only), any value other than "no" is a yes |
| DYNLIBC | no | use dynamic libc.so call for detecting resizing, any value other than "no" is a yes |
| LIBOSGETWINSIZE | libc.so.6 | path to a shared object containing ioctl() (usually some variation on libc.so), defaults to libc.so.6 |
| UPLOADUIO | no | suppresses the upload of tt_uio to the portal, this allows userIOActivity to be enabled in pt3agent.cfg thus populating related alert enhancers without sending ridiculous amounts of data to the portal |
PRO2 Replication
| Variable | Example Value | Description |
| PRO2QSKIP2SEQ | 0 | Skip to replQueue sequence# - IOW skip orphans, 0 = don't skip any |
| PRO2QCOUNTLIM | 1000 | Do not count every record in the replication queue if it is deeper than this |
| PRO2QESTIMATE | yes | Estimate queue depth proportionally when queues get too deep to count |
Screen Colors
UNIX (etc/protermcap.protop.OSName)
| Variable | Example Value | Description |
| PTCOLORS | "2,8,8,11,19,47,2,6,12,5" | default (protop-320) |
| PTCOLORS | "0,0,0,0,0,0,0,0,0,0" | monochrome |
| PTCOLORS | "2,8,8,11,18,1,2,22,1,3" | accessible (high contrast) |
| PTCOLORS | "2,8,8,11,19,47,2,6,12,5" | dark mode |
Process list processing -protop checks running processes to determine when a new agent needs to be started, these variables help to manage that process
| USEWMIC4PS | no | default = yes for oe10, no for oe11+, if no then we will use System.Management.dll on Windows and avoid screen scraping |
| WMICPIDLBL | ProcessId | text of the ProcessId column label when WMIC is in use for process lists (default English = ProcessId) |
| GETPID | "ps -p &1 -f" | ps command to return a specific process' command line, alternate: 'ps -ef | grep " &1 "' (ps -p _should_ be *much* more efficient but isn't really) |
| GETAGENTLIST | 'ps -C _progres -f | grep "p util/pt3agent"' | return a list of running pt3agent processes |
Windows (etc/protop.ini)
| Variable | Example Value | Description |
| PTCOLORS | "0,0,0,0,2,7,3,6" | Boring - Header, Label, Browse, BrowseTitle, Data, Good, Warning, Alert |
| PTCOLORS | "4,4,2,0,2,7,3,6" | A much more colorful example! |
Obsolete
| Variable | Example Value | Description |
| SENDTYPE | - | How to package data, choices are JSON or XML. Obsolete, everything is JSON now |
| CNXPARAM | - | Extra parameters for socket connections to the portal, i.e. "-clientConnectTimeout 500" |
AI Purge: bin/aipurge.sh
| Variable | Example Value | Description |
| PURGEDAYS | 90 | The number of days of AI logs to keep, the default is 30 |
| AIARCDIR1 | /ailog/arc1 | First target directory. Required for AI log archiving. |
| AIARCDIR2 | /ailog/arc2 | Second target directory. Optional |
Log Rotation: bin/lgrot.sh and bin/logrotate.sh
| Variable | Example Value | Description |
| LGARCDIR | /archive/logs | Where to archive truncated .lg files when bin/lgrot.sh runs. Required. |
| LOGHIST | 52 | Number of weeks of full db.lg to retain. Default is 52. |
| FLOGHIST | 52 | Number of weeks of filtered db.lg to retain. Default is 52 |
| LOGFILTER | etc/logfilter.cfg | File containing strings to filter out, one string per line. Examples - (8873), (452), (453). Required to filter database log file. |
Unbuffered Disk Write Test: bin/syncio.sh
| Variable | Example Value | Description |
| SYNCIODIR | /db/tmp | Directory for bin/syncio.sh to use, syncio.sh command line argument takes precedence. Default is $PROTOP/tmp. |
Dump & Load Scripts: build.sh and load.sh
| Variable | Example Value | Description |
| NUMTBLS | 810 | Expected number of tables (optional) |
| JUSTDOIT | yes | Answer "y" to all prompts in the dump & load scripts. If not used, user must interact with the process while it runs. |
| DLBINX | '&1.&2.&3' | Template for dlbin directory name (default "friendlyName.dl" or "&1.dl.&2.&3" |
| DUMPRO | '-RO' | Use -RO connections for dumping rather than having a server running |
| DUMPTHRD | '-thread 1' | Optional multi-threaded binary dump options |
| OVERLAP | no | Do NOT overlap dumping and loading - wait for dump to complete before starting the load process. Default is yes |
| IDXBUILD | 'inline' | Use the proutil "build indexes" option table by table rather than one big bang after the load finishes. Default is blank. |
User Experience Monitor: bin/zipenv, used by bin/zippyng.sh
The User Experience Monitor, commonly referred to as "zippy", measures how fast a single-threaded OpenEdge client can read records from the buffer cache. It does so in three ways: a) through a shared memory connection; b) in client/server through the localhost network connection; and c) in client/server from another server on the LAN.
When configuring zippy to measure remote client/server performance, the log file on the remote server must be copied across the network back to the server hosting the database, as the same pt3agent must upload the three zippy metrics. The bin/zipenv file contains the copy command to use:
UNIX
You can use ssh, SCP or rsync, but ssh keys must be in place between the two servers so that no password is required. You can also mount an NFS drive - the implementation is up to you, as long as the file gets to $PROTOP/log on the database server.
export ZIPSYNC="rsync -avzqe ssh ${LOGDIR}/zippyng.${FRNAME}.log SERVER:/LOGDIR 1>${TMPDIR}/zippyng.${FRNAME}.err 2>&1"
- SERVER is the server name where the databases, and ProTop, are running.
- LOGDIR, if ProTop is installed in the same directory on both servers, can be ${LOGDIR} (or %LOGDIR%) for both instances of LOGDIR in the above command. Otherwise, hardcode the LOGDIR on the database server.
Example (assuming "superman" is the name of the database server):
export ZIPSYNC="rsync -avzqe ssh ${LOGDIR}/zippyng.${FRNAME}.log superman:/opt/protop/log 1>${TMPDIR}/zippyng.${FRNAME}.err 2>&1"
Windows
A simple copy command suffices, though again sufficient permissions have to be put in place, remembering that the zippy process will be launched by the same user that starts the ProTop Windows service:
SET ZIPSYNC=copy /y %LOGDIR%\zippyng.!FRNAME!.log \\SERVER\SHARE\protop\log\zippyng.!FRNAME!.log >> %PTTMP%\zipsync.copy.err 2>&1
- SERVER: Same as on UNIX: the server name where the databases, and ProTop, are running
- SHARE: The name of the Windows share that exposes the ProTop directory on the database server. For simplicity, we often share the %PROTOP%\log directory directly as PROTOPLOGDIR.
SET ZIPSYNC=copy /y %LOGDIR%\zippyng.!FRNAME!.log \\superman\myshare\protop\log\zippyng.!FRNAME!.log >> %PTTMP%\zipsync.copy.err 2>&1
Message Buffer Size
On OpenEdge 11.5 or earlier, the message buffer size (-Mm startup parameter) of the client must match the message buffer size of the server. If you are not using the default 1024 (you should not be!), set the ZIPPYMm variable in bin/localenv, NOT zipenv.
UNIX: export ZIPPYMm="-Mm 8192"
WIN: SET ZIPPYMm="-Mm 8192"
Version 9 DateTime-TZ Parameters
Version 9 lacks datetime-tz and thus needs a bit of help to get the timezone right.
This is only for v9 customers of the commercial version of ProTop. The lack of datetime-tz makes handling "summer time" difficult. There is no reliable, generic, cross platform way to get the offset so ProTop uses this variable to determine what offset to apply.
| Variable | Example Value | Time Zone | Season/Note |
| TZOFFSET | "-04:00" | EDT | summer |
| TZOFFSET | "-05:00" | EST | winter |
| TZOFFSET | "-05:00" | CDT | summer |
| TZOFFSET | "-06:00" | CST | winter |
| TZSTR | $(date +%Z) | Time zone command (*nix) |
Cross *nix platform example section to add to localenv for the Central Time Zone:
TZSTR=$(date +%Z)
if [ "$TZSTR" = "CDT" ]
then
TZOFFSET="-05:00" # Summer
else
TZOFFSET="-06:00" # Winter
fi
export TZOFFSET
Windows
You must not use quotes when setting these variables but do include + or - and the colon.
For Example:
SET TZOFFSET=+02:00
Temp-table Debugging (Demo Code: lib/ttinfo.p)
You can enable temp-table and user table statistics for ProTop debugging. The data can be viewed in the Show Session user*stat (Y) or Show Session temp-tables (^t) panels in protop.
Prerequisites
- OpenEdge 11 or higher
- Uncomment the -tt* parameters in etc/protop.pf
- Uncomment TTDEBUG in bin/localenv:
export TTDEBUG=yes
Commercial Version Settings
| Variable | Example Value | Description |
| PCTLASTX | yes | Turns ON alerts for the last fixed extent becoming close to full |
| LOGRDTHOLD | 10000 | Threshold for log2rec alerts |
| BIBKUP_INFO | 0 | Info provided with every backup, regardless of alerting, if set to 1 |
| BIBKUP_ALERT | 60 | Alerts if the bi backup phase takes longer than the value. Default 60 seconds |
| BIBKUP_ALARM | 120 | Alarm if the bi backup phase takes longer than the value. Default 300 seconds |
| BIBKUP_PAGE | 300 | Page if the bi backup phase takes longer than the value. No default, you MUST set a value to be paged |
| BKUP_INFO | 0 | Info provided with every backup, regardless of alerting, if set to 1 |
| BKUP_ALERT | 7200 | Alert if the backup takes longer than the value. Default 2 hours |
| BKUP_ALARM | 14400 | Alarm if the backup takes longer than the value. Default 4 hours |
| BKUP_PAGE | 28800 | Page if the backup takes longer than the value. No default, you MUST set a value to be paged |
| QP_INFO | 0 | Info provided with every quiet point, regardless of alerting, if set to 1 |
| QP_ALERT | 60 | Alert if a quiet point takes longer than the value. Default 60 seconds |
| QP_ALARM | 300 | Alarm if a quiet point takes longer than the value. Default 300 seconds |
| QP_PAGE | 600 | Page if a quiet point takes longer than the value. Default 600 seconds |
| AISW_* | Messages sent to the portal for the AISW_* variables below have a subject beginning: aiSwitch on [server:/database] ... | |
| AISW_INFO | 0 | Info provided with every ai switch, regardless of alerting, if set to 1. |
| AISW_ALERT | 20 | Alert if an ai switch takes longer than the value. Default 20 seconds. |
| AISW_ALARM | 60 | Alarm if an ai switch takes longer than the value. Default 60 seconds. |
| AISW_PAGE | 0 | Page if an ai switch takes longer than the value. No default, you MUST set a value to be paged. |
| DBSHUTNAG | 3600 | Nag interval for db shutdowns and crashes |
Startup Key Commands
Add this line to display at startup the ProTop panels you currently use most often.
export XTRASTART="iutw" # Export an initial set of key commands for startup
The quoted string of characters will be executed when you start ProTop. The example above will apply the "i", "u", "t", and "w" key commands for you. This will hide the Index, Table, and User Activity panels that appear by default when you start ProTop and display the Latches and Resources panel instead.