NAME
ANTELOPE, ANTELOPEMAKE, ANTELOPE_PYTHON_GILRELEASE, BNS_RESEND, BNS_SNOOP, BNS_TIMEOUT, DATAPATH, DBIDSERVER, DBLOCKS, EDITOR, ELOG_MAXMSG, ELOG_REFERENCE_TIME, ELOG_SIGNALS, ELOG_TAG, ELOG_DELIVER, ELOG_DEBUG, ELOG_STACK, ELOG_WAIT, FORBRECVTIME, GRX_PSCOLOR, GRX_FONTPATH, OPTIMIZATION, ORB_IP_ADDRESS, ORB_MAX_DATA_BYTES, NO_DYNAMIC_CONTROLS, PERLLIB, PFPATH, SCHEMA_DEFAULT, SCHEMA_DIR, TAUP_PATH, TAUP_TABLE, USER_LIBRARY, XEDITOR, ZONEINFO - ANTELOPE environment variables overview
DESCRIPTION
This document provides a central location for notes about
the various environment variables which are used in
Antelope software. These environment variables are typically
used by just one or a few library routines.
You may find more detailed information in the documentation for
that routine or library, indicated in the note for each
environment variable.
-
ANTELOPE
This environment variable indicates base directory for an Antelope
release, for example /opt/antelope/5.10.
(See datafile(3).)
ANTELOPE is usually set by the script setup.csh(1),
typically sourced from .cshrc or .tcshrc. For bourne/bash
shell users, the corresponding file is setup.sh, sourced
from .profile.
-
ANTELOPEMAKE
This environment variable should specify a makefile which is
included by all the Makefiles in the Antelope sw/src directory. It
defines rules for the standard targets in Antelope Makefiles.
More information about these targets is provided in the Antelope
man page antelopemakefile(5).
ANTELOPEMAKE is usually set by the script setup.csh(1), typically
sourced from .cshrc.
-
ANTELOPE_PYTHON_GILRELEASE
If this environment variable is set, the Antelope Python Extensions
release the Python Global Interpreter Lock (GIL) during selected
C subroutine calls.
-
BNS_RESEND
Connections which push data to the orbserver do not get feedback
about packets received. Consequently, when a connection is broken,
they may need to resend some packets. The default is to resend only the
last packet; setting BNS_RESEND to a value larger than 1 will cause
that many packets to be resent.
-
BNS_SNOOP
If this environment variable is defined when an orb connection is set up,
all the incoming and outgoing packets are written to a binary file specified by BNS_SNOOP.
-
BNS_SUPPRESS_SYNCERR
If this environment variable is defined, the bns(3) routines do not complain about
nor announce skipped bytes when searching for a missing sync string (per gbnsSync(3)).
-
BNS_TIMEOUT
When using the bns(3) routines to read from a socket, there is a default
timeout on reads of 60 seconds. When a read times out, the orb routines
attempt to verify the connection, and if necessary reconnect.
On the writing side (typically an orbserver), there is a system
default timeout which appears to be about 7.5 minutes.
BNS_TIMEOUT may be modified to specify a shorter or longer timeout; it should
be an integer number of milliseconds.
The default is 60000 (60 seconds), but this
may be too short for some very poor connections.
-
DATAPATH
This variable may be set to cause the routines datafile(3) and datapath(3)
to search directories other than the default $ANTELOPE/data. For instance,
to cause /opt/mydata to be searched in addition to $ANTELOPE/data,
try
setenv DATAPATH /opt/mydata:$ANTELOPE/data
-
DBIDSERVER
This variable is deprecated; instead set the idserver in the database descriptor file.
When this variable is set to a hostname (with an optional :portname
appended), the dbnextid(3) routine uses socket calls to an instance
of dbids(1) running on hostname (at port portname) to
generate new, unique ids for databases. See dbids(1) for more info.
-
DBLOCKS
This variable is deprecated; use the new database descriptor file
to specify locking behavior instead.
This environment variable affects how the Datascope routines handle
record additions and nextid operations. When DBLOCKS is set,
the affected files are locked before the operation and
unlocked afterwards, allowing multiple users
successfully add new records to tables.
Programs must be designed to expect dynamic tables, however -- for
instance, they must check the count of records in the table regularly
(using dbquery dbRECORD_COUNT), rather than caching table length.
Note that deletions are not similarly protected nor handled; dbmark(3)
should be used instead of dbdelete(3), and the tables should be
crunched (see dbcrunch(3)) at some time when the database is
inactive. Note that programs designed for dynamic tables must allow
for the possibility of reading a marked (null) row.
When DBLOCKS is set to some arbitrary value, the locking and unlocking
is effective only for databases on local disks, and only for users on that
machine. However, if DBLOCKS is set to nfs, the locking and unlocking is
effective across nfs mounted partitions and multiple machines. There is a price
in execution speed, which could be important in some situations.
When DBLOCKS is set to nfs, the environment variable DBIDSERVER must
also be set, and the dbids(1) id server must be running.
All users of the database being shared must
use the same value of DBLOCKS. It is not ok to have users on the machine
where the database resides set DBLOCKS to "", and users on remote
machines set DBLOCKS to nfs. Settings like this are
guaranteed to cause problems.
-
EDITOR
-
XEDITOR
The real time monitor program rtm(1) checks these environment variables
when deciding what editor to use for editing parameter files.
If XEDITOR is set, it should be an x-windows editor like xemacs or xvile.
If EDITOR is set, it should be some text editor like vim, vile, or vi.
If neither variable is set, then a very simple TCL/Tk editor is used.
-
ELOG_DEBUG
-
ELOG_DELIVER
-
ELOG_MAXMSG
-
ELOG_REFERENCE_TIME
-
ELOG_SIGNALS
-
ELOG_TAG
These environment variables override the default behavior
of the error handling library routines: whether a debugger is called
when a fault occurs, how error messages are delivered, how many
error messages may be kept in the internal log, what signals are captured,
and what the tag on each error message looks like. Please refer to elog(3)
for a complete description.
-
ELOG_STACK
This environment contains some combination of lncdfDa, which indicates
elog severity levels at which stack traces are printed on stderr.
When l is present, log messages are printed immediately rather than saved, which can
mean messages will appear that do not in normal operation (because they are
suppressed by the program). See elog(3) for a description of the severity
levels.
-
ELOG_WAIT
Set number of seconds to wait before launching debugger (default 10 sec)
-
EUROPEAN_DATE
If this environment variable is set, dates of the form
xx/xx/xx are interpreted as day/month/year. (When the first
number is large (>31), the form is still interpreted as
year/month/day). In addition, some of the default output formats
(e.g., strtime(3)) are switched to day/month/year instead of month/day/year.
However, this flexibility can lead to non-portability of databases where lddate
is kept as a string of the form month/day/year.
-
FORBRECVTIME
When this variable is set, recorded orb packet forb(5) files include
an epoch time for the time each packet was received. This is occasionally
useful in some specialized circumstances.
-
GRX_PSCOLOR
This variable defines the treatment of color in postscript
output from the niceplot library (this has no effect on the
appearance of the image in the X11 window). The variable may
be set to the following values:
full - Produces full color PostScript that looks just like
the X11 window on a color workstation.
fore - Produces color PostScript for contour images, and
foreground colors, but makes background colors
white. Attempts to adjust foreground colors to be
visible on a white background in cases where they
would be hard to distinguish (such as yellow).
color or any other non-blank setting
- Produces color PostScript only for color contour
images. Evrything else is black on white.
blank or not set
- Produces grayscale PostScript only for color contour
images. Evrything else is black on white.
-
GRX_FONTPATH
This path overrides the default location ($ANTELOPE/data/fonts.bin)
for the binary font file used by the niceplot library.
-
NO_DYNAMIC_CONTROLS
Setting this environment variable will cause programs to ignore any .dynamic_controls files.
-
OPTIMIZATION
The script compile which is used to call the c compiler in the Antelope
build scheme recognizes the OPTIMIZATION environment variable, as a way
of overriding the default level of optimization used in compiling c programs.
Note that the compile script has been currently decommissioned due to
re-engineering of the TOOLCHAIN mechanism.
If the environment variable OPTIMIZATION is non-zero, optimizing is
turned on for all compilations, regardless of the settings in the Make-
file or the existence of .no_optimizing files.
If the environment variable OPTIMIZATION is zero, optimizing is turned
off for all compilations, regardless of the settings in the Makefile or
the existence of .no_optimizing files.
-
ORB_IP_ADDRESS
On a machine with multiple ip addresses, cause outgoing orb connections
to bind to this specified address exclusively. This may be useful when
dealing with firewalls (and their administrators), for instance.
-
ORB_MAX_DATA_BYTES
Override the generous but arbitrary limit of 4,000,000 bytes on orb packets.
Of course, this environment variable must be set for all applications
which might potentially read or write the large packets.
-
PERLLIB
Some Antelope software uses perl, a freely available and popular
scripting language. These perl scripts may also use several
Antelope perl libraries, which are kept in $(ANTELOPE)/data/perl.
In versions 4.2 and later, it should not be necessary to
set PERLLIB provided Antelope is installed in the normal location
(/opt/antelope).
-
PFPATH
Some programs require input from a parameter file.
This variable overrides the default path to the parameter files:
$(ANTELOPE)/data/pf:.. See pf(3).
-
SCHEMA_DEFAULT
This is the name of the default schema to use when no descriptor
file is present. The current default is css3.0.
-
SCHEMA_DIR
This path overrides or extends the default location ($(ANTELOPE)/data/schemas)
for schema files. The db library looks for files named after the schema in each
directory of the path specified by SCHEMA_DIR; in addition, files found in directories named
<schema>.ext are included in the complete schema. Combined together, these files
define the database schema
used by the db library routines, and are required to run most
programs, including dbe(1) and dbpick(1). See dbopen(3), dbschema(5).
-
TAUP_PATH
Overrides the default directory ($(ANTELOPE)/data/tables/taup_ttimes)
for the tables for the Buland and Chapman tau-p travel calculator
-
TAUP_TABLE
(deprecated; use TTMETHOD and TTMODEL instead)
Overrides the default travel time model (iasp91) for the Buland and Chapman tau-p travel calculator
-
TTMETHOD
Overrides the default method (tttaup) for the tt travel time calculator used by many Antelope programs;
see also tt(3) for a description of trvltm.pf
-
TTMODEL
Overrides the default model (tttaup) for the tt travel time calculator used by many Antelope programs;
see also tt(3) for a description of trvltm.pf
-
USER_LIBRARY
By default, usermethod(3) attempts to open $ANTELOPE/lib/libuser.so. However, this environment
variable overrides the default. If it is not an absolute path, usermethod will look for the
library in $ANTELOPE/lib.
-
ZONEINFO
Override the default directory for timezone files.
The location of time zone files varies somewhat among different
versions of UNIX. Currently, Antelope looks for the timezone files
in /usr/share/lib/zoneinfo for Sun and /usr/share/zoneinfo
for other architectures (Linux and Mac).
-
LD_LIBRARY_PATH
Please *never* set this shell variable. It affects how the dynamic
loader looks for libraries to resolve references in executable programs
(and other dynamic libraries). It often leads to unpredictable failures
and mysterious results.
SEE ALSO
antelope(1)
antelope(3)
dbintro(3)
tempnam(3)
antelopemakefile(5)
setup.csh(1), setup.sh(1)
BUGS AND CAVEATS
Environment variables are easy to ignore, and the absence or presence of
an environment variable very commonly can cause problems
which are mysterious and difficult to debug.
LD_LIBRARY_PATH is
a particular example.
AUTHOR
Daniel Quinlan
Danny Harvey