Local Environment Tailoring

Local Environment Tailoring

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. 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)
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
CNXPARAM   Extra parameters for socket connections to the portal, i.e. "-clientConnectTimeout 500"

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 "0,0,0,0,5,7,14,6" boring - Header,Label,Browse,BrowseTitle,Data,Good,Warning,Alert
PTCOLORS "10,8,13,0,5,7,14,6" a much more a colorful example! (use with a light background)
PTCOLORS "9,8,13,0,9,7,14,6" "dark mode" (use with a black background)

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 a colorful example!

Obsolete

Variable Example Value Description
SENDTYPE JSON How to package data, choices are JSON or XML. Obsolete, everything is JSON now

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"
  • SERVER: The server name where the databases, and ProTop, are running
  • LOGDIR: If ProTop is installed in the same directory on both servers, you can use ${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"

     

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

     

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

To set the variable on Windows you must not use quotes, include + or - and the colon.

For Example:

 SET TZOFFSET=+02:00 

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. 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 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_INFO 0 info provided with every backup, regardless of alerting, if set to 1
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_INFO 0 info provided with every quiet point, regardless of alerting, if set to 1
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
AISW_INFO 0 info provided with every ai switch, regardless of alerting, if set to 1.
AISW_ALERT 20 alerts 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.