INTRODUCTION
The /entrez/cdrom directory of the NCBI anonymous ftp server is used for
updates to the Entrez executables for a given release of the Entrez CD-ROMs.
This directory is cleared prior to a new release of the discs.
The Entrez application requires that you obtain the NCBI Entrez CD-ROMs. The
software updates in these directories are being made available to allow Entrez
testers to evaluate new versions of the application. To request subscription
information on Entrez, please send an email message to info@ncbi.nlm.nih.gov.
Include your full postal address and your phone and fax numbers.
This file contains instructions for downloading versions of Entrez for the SUN
SPARCstation (SunOS or Solaris operating systems), SGI Iris workstation,
Macintosh, or IBM-PC with Microsoft Windows platforms.
INSTALLATION
The Entrez databases are distributed on three discs, named Entrez1,
Entrez2 and Entrez3. You may wish to occasionally install the latest
version of the Entrez application, in order to take advantage of
improvements in the software. Entrez will perform disc swapping if you
have one or two CD-ROM drives.
Extraction of Entrez Software Archives
Installation of Entrez is a two-step process. In the first step, the
Entrez application, EntrezCf configuration program, and accessory files
and directories, are “extracted” from “archives” on the CD-ROM and
placed onto your hard disk. The Entrez1 disc contain self-extracting
archives for the Macintosh and PC/Windows versions of Entrez.
EntrezCf Configuration Program
In the second step, the EntrezCf program (extracted in the first step)
allows you to configure Entrez for your particular machine. EntrezCf
asks you to specify where the data sources are located (on the original
CD-ROMs, copied to a hard disk, or mounted on a file server), whether
you want to copy the index files to your hard disk for improved
performance of document retrieval, and how many CD-ROM drives you have.
The program may then ask you to enter your drive letters, or the network
paths if you have copied the disc images to a file server. It will
finish by copying the index files (if requested) and writing the ncbi
configuration file (discussed below).
ncbi and entrez Configuration Files
Two configuration files are necessary for running Entrez. The ncbi
configuration file specifies paths for access to the sequence and
MEDLINE records and to ASN.1 parse tables and accessory data and index
files. The entrez configuration file maintains persistent preferences,
allows built-in fonts to be overridden, and allows the save path and
default names to be changed. Although the configuration files have a
common format, their names and locations are decided by platform-
specific conventions. On the Macintosh, the files are of the form
xxx.cnf, and reside in the System Folder or the System
Folder:Preferences folder. Under Windows, they are of the form XXX.INI,
and reside in the Windows directory. The EntrezCf configuration program
ensures that the ncbi configuration file is created in the proper
location and is configured properly for your particular machine. The
Entrez application will set up the entrez configuration file with
certain default values, if one does not already exist.
UNIX DOWNLOADING AND SOFTWARE EXTRACTION
The Entrez update for the SUN and SGI is supplied as a compressed tar archive.
* Remove any old files from your hard disk, if desired.
* Type "ftp ncbi.nlm.nih.gov".
* Enter "anonymous" as the user name.
* Enter your Internet email address as the password.
* Type "bin" to set the binary transfer mode.
* Type "cd entrez".
* Type "cd cdrom".
* Type "get sun.tar.Z" or "get sol.tar.Z" or "get sgi.tar.Z".
* Type "quit".
* Type "uncompress sun.tar.Z" (or sol.tar.Z or sgi.tar.Z).
* Type "tar -xvf sun.tar" (or sol.tar or sgi.tar). This will extract into
the "entrez" and "entrezcf" applications and the "data" directory.
* Mount each CD-ROM with the following command:
mount -rt hsfs /dev/sr0 /cdrom
If you are not logged in as root, you may need the sudo command:
sudo mount -rt hsfs /dev/sr0 /cdrom
* Run a window manager, start the entrezcf application, and follow the
instructions in the CONFIGURATION section. The foreground and background
colors and multi click time for entrez and entrezcf can be modified with
command-line arguments, an example of which is given below:
(program name) -fg plum -bg "pale green" -xrm '*multiClickTime: 1000'
MACINTOSH DOWNLOADING AND SOFTWARE EXTRACTION
The Entrez update for the Macintosh is supplied as a Compact Pro (TM) self-
extracting archive. The following instructions are an example of downloading
using the HyperFTP (c) package.
* Remove any old files from your hard disk, if desired.
* Launch HyperFTP.
* Connect to "ncbi.nlm.nih.gov".
* Enter "anonymous" as the user name.
* Enter your Internet email address as the password.
* Set the BinHex file Transfer Mode.
* Double click on the "entrez" directory.
* Double click on the "cdrom" directory.
* Receive the "entrez.hqx" file, saving as "entrez.sea".
* Disconnect from the NCBI file server.
* Quit HyperFTP.
* Double click on the "entrez.sea" application. This will self-extract into
the "Entrez" and "EntrezCf" applications and the "asnload" and "data"
folders.
* Start the EntrezCf application, and follow the instructions in the
CONFIGURATION section.
MICROSOFT WINDOWS DOWNLOADING AND SOFTWARE EXTRACTION
The latest version of Entrez may be downloaded via anonymous ftp from the
NCBI file server. The Entrez update for the the PC under Microsoft Windows
is supplied as a PKZIP (R) self-extracting archive.
* Remove any old files from your hard disk, if desired.
* Type "ftp ncbi.nlm.nih.gov".
* Enter "anonymous" as the user name.
* Enter your Internet email address as the password.
* Type "bin" to set the binary transfer mode.
* Type "cd entrez".
* Type "cd cdrom".
* Type "get entrezZ.exe".
* Type "quit".
* Type "entrezZ -d". This will self-extract into the "ENTREZ.EXE" and
"ENTREZCF.EXE" applications and the "ASNLOAD" and "DATA" directories.
* Run Microsoft Windows, start the EntrezCf application, and follow the
instructions in the CONFIGURATION section.
CONFIGURATION
EntrezCf allows you to tailor your Entrez installation to suit your
particular computer and network resources. Press the Next button in the
opening window, leaving Show advanced settings unchecked. EntrezCf
should normally be able to find the asnload and data directories. If it
cannot, it will put up another window and ask you to enter the paths to
these directories.
EntrezCf then displays a window asking where the data sources are
located. You can choose between CD-ROM drive, Hard disk, and LAN
fileserver for each of the discs. If you choose Hard disk or LAN
fileserver, you or your LAN administrator will be expected to have
already copied the contents of the relevant Entrez discs.
+-----------------------------------------------------------------------+
| EntrezCf |
+-----------------------------------------------------------------------+
| |
| Entrez CD-ROM Data Sources |
| |
| The Entrez application normally reads information from the |
| CD-ROMs. Alternatively, you may copy the contents of one or |
| more Entrez CD-ROMs to a hard disk or LAN fileserver. For |
| each Entrez volume, please specify the desired option. |
| |
| |
| |
| +---------------------+ |
| Entrez1 | CD-ROM Drive | |
| +---------------------+ |
| |
| +---------------------+ |
| Entrez2 | CD-ROM Drive | |
| +---------------------+ |
| |
| +---------------------+ |
| Entrez3 | CD-ROM Drive | |
| +---------------------+ |
| |
| |
| /----------\ /-----------\ /-----------\ |
| | Cancel | | << Prev | | Next >> | |
| \----------/ \-----------/ \-----------/ |
| |
+-----------------------------------------------------------------------+
Press the Next button to move to the next screen.
If you have specified a CD-ROM drive for any of the discs, the next
window asks for the number of CD-ROM drives on your system. On a PC
with Microsoft Windows, it will also ask for the paths or drive letters
(e.g., D:\) for those drives. The Macintosh uses the volume names to
access the discs, and doesn't need this information. Entrez will swap
discs among one or two CD-ROM drives, if necessary. A new feature of
Entrez is that any disc can be placed in any drive.
If you have chosen Hard disk or LAN fileserver, another screen will
appear, asking for the paths to the various data sources. This
information depends upon where you have copied the data.
Press the Next button to continue with the configuration.
+-----------------------------------------------------------------------+
| EntrezCf |
+-----------------------------------------------------------------------+
| |
| Setup for CD-ROM Drives |
| |
| You have specified the "CD-ROM" option for one or more |
| Entrez volumes. Please supply the requested information |
| about your CD-ROM setup. |
| |
| |
| |
| Number of |
| +----CD-ROM Drives----+ |
| | | |
| | | |
| | (*) 1 | |
| | | |
| | ( ) 2 | |
| | | |
| | ( ) 3 | |
| | | |
| | | |
| +---------------------+ |
| |
| |
| /----------\ /-----------\ /-----------\ |
| | Cancel | | << Prev | | Next >> | |
| \----------/ \-----------/ \-----------/ |
| |
+-----------------------------------------------------------------------+
EntrezCf then asks for you to insert the Entrez1 disc. It will next
display a window asking if you want to copy index files to your hard
disk for faster document retrieval. Copying all of the index files will
take up around 15 Mbytes of space on your hard disk.
+-----------------------------------------------------------------------+
| EntrezCf |
+-----------------------------------------------------------------------+
| |
| Copy Index Files to Hard Disk |
| |
| If you have sufficient space, you may want to copy some Entrez |
| index files to your hard disk in order to improve performance. |
| |
| |
| |
| [ ] Index files for MEDLINE records 5755 Kbytes |
| |
| [ ] Index files for protein records 3808 Kbytes |
| |
| [ ] Index files for nucleotide records 4011 Kbytes |
| |
| |
| Total size of selected files: 0 Kbytes |
| |
| The files will be copied upon completion of the setup process. |
| |
| |
| /----------\ /-----------\ /-----------\ |
| | Cancel | | << Prev | | Next >> | |
| \----------/ \-----------/ \-----------/ |
| |
+-----------------------------------------------------------------------+
Press the Next button to move to the final screen.
The final window allows you to save the settings or to back up and
review (and revise) your configuration instructions. When you press the
Save settings button, EntrezCf will copy any requested index files and
will write the ncbi configuration file. You can then run Entrez.
+-----------------------------------------------------------------------+
| EntrezCf |
+-----------------------------------------------------------------------+
| |
| Entrez CD-ROM Data Sources |
| |
| You have entered all the necessary information. The |
| settings may now be saved to the configuration file. |
| The index files will then be copied to your hard disk |
| as requested. |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| /-----------------------------\ |
| | Save settings | |
| \-----------------------------/ |
| |
| /----------\ /-----------\ /-----------\ |
| | Cancel | | << Prev | | Next >> | |
| \----------/ \-----------/ \-----------/ |
| |
+-----------------------------------------------------------------------+
TROUBLESHOOTING
Disc Recognition Failure
On the PC, if Entrez cannot find the CD, and the Windows File Manager
also cannot open the CD icon (or indicates that there are no files on
the disc), the problem may be caused by Windows overwriting the memory
onto which the CD-ROM driver is mapped. You should exclude this region
from being considered as available memory. To do this, determine the
memory addresses that the CD-ROM drive is using (check the manual for
how to read the switch settings on the interface card or call the
manufacturer). Then, configure your memory manager or DOS extender
program to exclude these addresses (check the manual for what command
options to use or call the manufacturer for instructions).
On the Macintosh, if the CD is rejected as not being a “Macintosh disc”,
you may have an extension (e.g., DOS Mounter) that preempts recognition
of the ISO 9660 disc. If so, you should drag the offending file out of
the Extensions folder and restart the computer. Another possibility is
that your Foreign File Access and ISO 9660 File Access drivers did not
load properly. These are automatically installed along with the CD-ROM
driver in the Extensions folder. However, under System 7.0, they must
manually be dragged into the System Folder itself, and the computer must
then be restarted, in order for them to work. System 7.1 can use them
in the Extensions folder.
Application Software Problems
As a general rule, if you have a problem that occurs when you get a new
release of Entrez, you should delete the old software and extract the
version on the disc. The problem may have been noticed or reported, and
addressed in the most recent update of the application.
If Entrez fails, the cause may be that the ncbi configuration file has
become corrupted. You should try reinstalling and reconfiguring after
first deleting the existing ncbi configuration file. (On the Macintosh
this file is named ncbi.cnf, and resides in the System Folder or the
System Folder:Preferences folder. Under Windows it is named NCBI.INI,
and resides in the Windows directory.) If there is a problem it is best
to first configure without copying index files (after deleting the
configuration file). If this solves the problem then you can run
EntrezCf again to reconfigure with copying index files.
Printer fonts can now be specified independently from screen fonts. See
the section on Customization below. The DISPLAY font is used for
displaying (and printing) records in MEDLARS, GenBank flat file, and
FASTA formats, and for the MEDLINE and Sequence ASN.1 formats. These
reports do not word wrap, so the printer font should be adjusted if they
print past the right margin. The MEDLINE Report and Sequence Report
formats do perform word wrapping.
CUSTOMIZATION
The entrez configuration file has several possible sections. This file
can be edited with a text editor, after it is first created by Entrez.
(On the Macintosh it is named entrez.cnf, and resides in the System
Folder or the System Folder:Preferences folder, while under Windows it
is named ENTREZ.INI, and resides in the Windows directory.) The
explanations below are for those configuration file elements that are
not documented elsewhere or set under program control:
[Section] Explanation
Key=Value
[PREFERENCES]
MAXLOAD=200 Maximum number of documents that can satisfy
a Boolean query and still be retrieved.
[FONTS]
JOURNAL=Geneva,10,i These entries allow you to override the default
font specifications used by the Entrez
application. A printer font can be specified
after the screen font and a vertical bar (e.g.,
"Geneva,10,i | Times,12,i").
[SAVE]
PATH=C:\SAVEHERE\ Path for saving files with the Save and Save
All menu commands. Default is the current
directory, i.e., the directory in which the
Entrez application is located.
DEFREFFILE=ENTREZ.REF File name for saving MEDLINE records with the
Save and Save All menu commands. Default is
entrez.ref.
DEFSEQFILE=ENTREZ.SEQ File name for saving sequence records with the
Save and Save All menu commands. Default is
entrez.seq.
The PC/Windows version of Entrez allows you to set the TMP environment
variable to specify the path to the directory in which temporary files
will be created. You can add a statement setting this variable in your
AUTOEXEC.BAT file. This is useful for installations that allow Entrez
to be run over a local area network.
ENTREZ ON OTHER PLATFORMS
NCBI makes executables available for other computer systems as a
convenience to the community. These are available on an unsupported
basis by anonymous ftp. To obtain these files, ftp to ncbi.nlm.nih.gov,
enter anonymous as the user name and your email address as the password,
cd to entrez, and get the README file, which gives further instructions.
Will Gilbert of the University of New Hampshire makes available NCBI
software on DEC computers through an arrangement with Digital Equipment
Corporation. To obtain these files, ftp to ncbi.unh.edu, enter
anonymous as the user name and your email address as the password, cd to
entrez, and get the README file, which gives further instructions.
The source code for Entrez is available for persons who may wish to port
it to another platform.
MOUNTING ON UNIX MACHINES
Entrez users on Sun and SGI workstations can use the Entrez configuration
program and multi-CD configurations of Entrez, provided that they perform
some advance preparation prior to running the Entrez configuration program.
Users of hard-disk-based configurations need not perform any special
preparation.
The Entrez configuration program uses the name 'cdmount' by default as
the name of the mount/unmount script. However, you may select any name
you like instead and override 'cdmount' in the configuration program.
The following discussion and shell scripts are not supported by NCBI.
They are included for the convenience of individual users.
SPECIAL PREPARATION FOR SUN
Sun users who have Sun's "cdmount" utility installed on their system need
only verify that "cdmount" can be found using the "PATH" environment variable
which is in use at the time that the Entrez config program and the Entrez
application are run. To determine the existence of this command on your
system, try typing the "cdmount" command.
If the "cdmount" command is not available, then you must ask your system
administrator to install the "Sun cdmount" shell script in a protected
directory (writable only by system administrator), owned by "root", with
the set-userID-upon execution bit turned on. This can be done by your
system administrator as follows:
chown root cdmount
chmod 4755 cdmount
It is recommended that this program reside in /usr/local/bin, but it can
reside in any directory which is not writable by users, and generally
resides in the PATH of most users. Note that the protection against
user-writing is for security reasons.
If your system administrator is unable or unwilling to install this file,
then it is not feasible to use multi-CD configurations of Entrez.
The "Sun cdmount" script appears near the end of this file. Some site-specific
changes may need to be performed by your system administrator.
SPECIAL PREPARATION FOR SGI
Verify that the "cdromd" daemon is running on your system. For example,
"ps -e | fgrep cdromd" should indicate the presence of this daemon.
If the daemon is not found, and it cannot be installed by your system
administrator, then it is not feasible to use multi-CD configurations of
Entrez.
If the daemon is found, then install the following shell script as
"cdmount" in any directory that is part of your PATH. If there are many users
who will want this capability, then place it somewhere where they can
access it as well. Unlike the SUN script, no particular ownership or
permissions are required, except that the script must be "executable"
("chmod 755 cdmount").
OTHER UNIX SYSTEMS
CD-ROM ejection/mounting/unmounting is currently only supported for Entrez
on Sun and SGI systems. However, it may be possible to use a variation on the
Sun script which appears below, to manipulate CD-ROMs on other types of UNIX
systems. You will need to refer to your system documentation and apply
some changes to this script. Also, it will be necessary for your script
to eject the CD-ROM when processing the "-u" option. Be mindful of any
security weaknesses which you might be creating on your system by installing
your modified version of this script!
Please send an annotated copy of your debugged shell script to
toolbox@ncbi.nlm.nih.gov, for possible inclusion in a future release
of Entrez.
------------------------begin SGI 'cdmount'-----------------------------------
#!/bin/sh
#
# ejects a CD-ROM ... this automatically results in the CD-ROM's unmounting
# if the SGI 'cdromd' daemon is running ... similarly, the 'cdromd' daemon
# will mount the CD-ROM is it is inserted
#
case $1 in
-u)
eject $2;;
*)
;;
esac
exit $?
-------------------------end SGI 'cdmount'------------------------------------
------------------------begin SUN 'cdmount'-----------------------------------
#!/bin/sh
#
# Script to allow mounting or unmounting of CD-ROM drives only, at restricted
# mount points.
#
# J. Epstein, 2/2/93, NCBI
#
# Emulates a subset of the Sun unbundled 'cdmount' command
#
# The first argument is one of "-m" or "-u"
# The second argument is the device name; only {/dev/sr0,/dev/sr1}
# are permitted
# The third argument is the mount point (if "-m" option);
# the only permitted mount points are /cdrom and /cdrom2
#
PATH=/usr/bin:/usr/ucb:/usr/etc
export PATH
dev=/dev/sr0
mountpoint=/cdrom
case $1 in
-u)
mount=0;;
-m)
mount=1;;
*)
echo "$0:" Illegal option
exit 1;;
esac
if [ $# -gt 1 ]
then
case $2 in
/dev/sr0)
dev=$2;;
/dev/sr1)
dev=$2;;
*)
echo "$0:" Illegal device name $2
exit 1;;
esac
fi
if [ $# -gt 2 ]
then
case $3 in
/cdrom)
mountpoint=/cdrom;;
/cdrom/)
mountpoint=/cdrom;;
/cdrom2)
mountpoint=/cdrom2;;
/cdrom2/)
mountpoint=/cdrom2;;
*)
echo "$0:" Illegal mount point $3
exit 1;;
esac
fi
#
# mount High Sierra File System (hsfs), read-only
#
case $mount in
0)
/etc/umount $dev;;
1)
/etc/mount $dev $mountpoint;;
esac
exit $?
-------------------------end SUN 'cdmount'-----------------------------------
SYMBOLIC KEYBOARD MAPPINGS ON SUN
Entrez for UNIX machines uses the X11 windowing system and the OSF/Motif
toolkit. Motif provides virtual keysyms, which map particular key presses
to classes of actions. The symbolic mappings must reside in the XKeysymDB
file, which should be in the list of paths specified by the XFILESEARCHPATH
environment variable.
Many Sun systems don't have the proper osf-specific lines in XKeysymDB.
This results in a long list of error messages of the form:
Warning: translation table syntax error: Unknown keysym name: osfHelp
Warning: ... found while parsing '<Key>osfHelp: Help()'
The quick and dirty solution has been to send stderr to the null device:
entrez >&! /dev/null
Unfortunately, lack of appropriate keysym mappings prevented the backspace
or delete keys from working in Entrez.
A better solution is to provide the proper keyboard mappings. To do so,
find the XKeysymDB file, which must be in your machine's XFILESEARCHPATH
environment variable's list of paths. (Create the file if it does not
exist anywhere in these paths.) Cat (append) the following file to it:
---------------------------begin included file------------------------------
!
! OSF Keysyms
!
osfBackSpace :1004FF08
osfInsert :1004FF63
osfDelete :1004FFFF
osfCopy :1004FF02
osfCut :1004FF03
osfPaste :1004FF04
osfAddMode :1004FF31
osfPrimaryPaste :1004FF32
osfQuickPaste :1004FF33
osfPageUp :1004FF41
osfPageDown :1004FF42
osfEndLine :1004FF57
osfBeginLine :1004FF58
osfActivate :1004FF44
osfMenuBar :1004FF45
osfClear :1004FF0B
osfCancel :1004FF69
osfHelp :1004FF6A
osfMenu :1004FF67
osfSelect :1004FF60
osfUndo :1004FF65
osfLeft :1004FF51
osfUp :1004FF52
osfRight :1004FF53
osfDown :1004FF54
!
---------------------------end included file------------------------------