Local Environment Tailoring

Not every OpenEdge environment is the same and 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).

The localenv file is distributed in the bin subdirectory of the ProTop installation as localenv.x on UNIX and localenv.batx on Windows. In order 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 desired modifications.

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.

Global Settings

Variable Example Value Description
PROXY proxy.xyz.com:8080 Proxy server (if needed), also handles "username:password@proxyserver:proxyport"
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"
VOTRX 1800 How old is a TRX vefore 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 exerience" 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 in to 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)
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)
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)
SENDTYPE JSON How to package data, choices are JSON or XML. Obsolete, everything is JSON now
TERMHOTLINK yes Enables clickable links in the ProTop Real-Time Monitor on UNIX

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 in order 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 mesure 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:

On 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"

On 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

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.

export 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 Description
TZOFFSET "-0400" EDT
TZOFFSET "-0500" EST
TZOFFSET "-0500" CDT (summer)
TZOFFSET "-0600" CST (winter)
TZSTR \$(date +%Z) Time zone string

Example section to add to localenv

if [ "$TZSTR" | "CDT" ]
then
     TZOFFSET="-0500"
else
     TZOFFSET="-0600"
fi
export TZOFFSET

Temp-table Demo Code: lib/ttinfo.p

You can enable temp-table and user table statistics for ProTop debugging. The data can be viewed with the "Y" (user table stats) and ctrl-t (temp-tables) screens.

Prerequisites

  1. OpenEdge 11 or higher
  2. Uncomment the -tt* parameters in etc/protop.pf
  3. Add TTDEBUG to bin/localenv export PTDEBUG=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_ALERT 60 alerts if the bi backup phase takes longer than the value. Default 60 seconds
BIBKUP_ALARM 120 alarms 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_ALERT 7200 alerts if the backup takes longer than the value. Default 2 hours
BKUP_ALARM 14400 alarms 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_ALERT 60 alerts if a quiet point takes longer than the value. Default 60 seconds.
QP_ALARM 300 alarms 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.