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