NCBI C Toolkit Cross Reference

Beginning with Release 2.0 of the Entrez:Sequences and Pre-Release 1.0 of the
Entrez:MEDLINE CD-ROMs, it is possible for the Entrez application to access
one or both data sets. This will allow users to potentially have access to the
rich set of MEDLINE articles on the Entrez:MEDLINE disc, while simultaneously
having access to the sequence data on the Entrez:Sequences disc.

This functionality requires both
 i) a new version of the Entrez application software, and
ii) a more complex configuration file, to handle the wide variety of
    possible configurations.

Users who wish to use only _one_ of the Entrez:Sequences or Entrez:MEDLINE discs
(never in combination) will not need to make any changes in their configuration
files; the new Entrez software is backwards compatible with these old
configuration files. If you fall into this catagory and have already installed
Entrez on your machine, then there is no need to read further.

Note that the complex configuration mechanism which is discussed below is
not currently supported. We would, however, appreciating hearing about any
problems which you may encounter. A supported version with a user-friendly
configuration program will be provided with Release 3.0 of the Entrez:Sequences
CD-ROM.

Also note that, because there will be no pre-Release 2.0 Entrez:MEDLINE CD-ROM,
there will be a few MEDLINE abstracts which will be present on the latest
Entrez:Sequences CD-ROM (Release 2.0), but not on the latest Entrez:MEDLINE
CD-ROM (Pre-Release 1.0). This is a deviation from future CD-ROM releases,
when the MEDLINE records on the latest Entrez:Sequences CD-ROM will be a
proper subset of those sequences on the latest Entrez:MEDLINE CD-ROM.

Users who wish to use both CD-ROMs on a single CD-ROM drive are advised to
make sure that they have two CD-ROM caddies available (one for each CD).
Frequent switching of CD-ROMs between a single caddy and the CD jewel boxes can
induce high levels of stress.

Seven pre-canned configuration files are made available, with corresponding
.ini and .cnf files for MS Windows and the Macintosh, respectively. The
selected file should be modified as appropriate for your machine, renamed
to NCBI.INI or ncbi.cnf, and used to replace the NCBI.INI or ncbi.cnf file, as
outlined on the Entrez manual's installation instructions.


The pre-canned configuration files are as follows:

    NCBISM1D.XXX      MEDLINE and Sequence CDs, with only one CD-ROM drive
    NCBISM2D.XXX      MEDLINE and Sequence CDs, with two CD-ROM drives
    NCBIMO.XXX        MEDLINE CD only
    NCBISO.XXX        Sequence CD only
    NCBISHMC.XXX      Harddisk-based Sequence CD image, and MEDLINE CD-ROM
    NCBISCMH.XXX      Harddisk-based MEDLINE CD image, and Sequence CD-ROM
    NCBISHMH.XXX      MEDLINE CD and Sequence CD images, both on hard disk

The following customizations may be necessary for your machine:

* For all files, the only changes to be made will be within the first 20-or-so
  lines of the configuration file, within the "NCBI" section and the media
  sections "ENTREZ_xxx_yD" (where xxx is one of "SEQ" or "MED", and y is one of
  "C" or "H").

* A copy of the CDROMDAT.VAL for each CD-ROM to be used must be stored on the
  hard disk, in the directory pointed to by the "VAL" field for the
  corresponding media. Note that these files are _different_ for the Sequence
  and MEDLINE CD-ROMs, and the correct file must be stored in each prescribed
  location.

* For improved performance, a copy of the index files should be copied onto
  the hard disk for each CD-ROM to be used, if space is available. These
  canned configuration files assume the availability of such index files on a
  hard disk. If you choose not to install the index files, then remove the
  "IDX=" lines from the configuration file which you have selected. Again,
  note that the index files are _different_ for the Sequence and MEDLINE
  CD-ROMs, and the correct files must be stored in each prescribed location.

* For MS-Windows, it is assumed that the first CD-ROM drive is drive D and the
  second CD-ROM drive (NCBISM2D.INI only) is drive E. Change this as necessary.

* For Macintosh systems, the hard disk name yourHardDisk should be changed to
  the name of your hard disk.

* For both types of systems, it is assumed that all hard disk files reside on
  the same hard disk. Change this as necessary.

* If you choose to copy both CD-ROMs to your hard disk (NCBISHMH.XXX), then
  you need not copy the medline directory from the Entrez:Sequences CD-ROM
  onto your hard disk, since this portion of MEDLINE is a proper subset of
  the MEDLINE on the Entrez:MEDLINE CD-ROM.

* Note that a copy of the appropriate seven configuration files for your
  platform (Mac or Windows) will be automatically copied by the installation
  procedure into the ENTREZ\CONFIG folder. You may, however, find an alternate
  copy of the configuration files on the CD-ROM in the SOFTWARE\CONFIG folder,
  inside the MAC and WIN folders.

* Note that the "ROOT=" field in the "[NCBI]" section of the multi-source
  configuration files (ncbi????.XXX) is not used by this version of Entrez,
  but is provided for backwards compatability with older versions of Entrez,
  as well as for compatability with other applications using the older
  version of our data access libraries.

* Because the MEDLINE entries on Release 2.0 of the Entrez:Sequences CD-ROM
  are not a proper subset of the entries on pre-Release 1.0 of the
  Entrez:MEDLINE CD-ROM, it may be necessary to set an additional configuration
  parameter, if you begin to encounter "Missing UID" errors when running
  Entrez. This is the only parameter which should be set in the
  entrez.[cnf/ini] configuration file; all other parameters should be
  set in the ncbi.[cnf/ini] configuration file. The parameter which should
  be set is "SHOWALLERRORS=FALSE", in the [PREFERENCES] section. It is
  strongly recommended that you first get your configuration of Entrez
  running properly, before adding this line to your entrez.[cnf/ini] file.
  This configuration option will mute many errors, which may make it
  difficult to debug your configuration difficulties.
  


EXAMPLE

You wish to use both CD-ROMs, on a single CD-ROM drive, under MS Windows.
Suppose that the device for your CD-ROM drive is named "F:", not "D:"

Install Entrez from Release 2.0 of the Entrez:Sequences CD-ROM, per the
installation/update instructions in the manual.

Make a copy of ncbism1d.ini from \ENTREZ\CONFIG\NCBISM1D.INI, first having
saved a copy of NCBI.INI (if you had one):

    COPY C:\WIN\NCBI.INI C:\WIN\NCBIINI.BAK
    COPY C:\ENTREZ\CONFIG\NCBISM1D.INI C:\WIN\NCBI.INI

Edit C:\WIN\NCBI.INI with your favorite editor, and change the occurrences
of ROOT=D:\ to ROOT=F:\. Save your changes and exit the editor.

Create some directories, if they don't already exist:
    MKDIR C:\ENTREZ\MED
    MKDIR C:\ENTREZ\MED\INDEX
    MKDIR C:\ENTREZ\SEQ
    MKDIR C:\ENTREZ\SEQ\INDEX

Copy the sequence index files, and CDROMDAT.VAL to your hard disk.
    COPY F:\INDEX\*.* C:\ENTREZ\SEQ\INDEX
    COPY F:\CDROMDAT.VAL C:\ENTREZ\SEQ

Now, eject the Entrez:Sequences CD, insert the Entrez:MEDLINE CD, and
copy the MEDLINE index files and CDROMDAT.VAL to your hard disk.
    COPY F:\INDEX\*.* C:\ENTREZ\MED\INDEX
    COPY F:\CDROMDAT.VAL C:\ENTREZ\MED

Now, start-up Windows (if it's not already running), and launch Entrez.
It doesn't matter which CD-ROM, if any, is inserted into the CD-ROM drive
(although, for convenience, it generally makes sense to insert the CD-ROM
which you would like to use first). The Entrez application will inform
you when it is time to insert the other CD-ROM.

NOTES

When using two CD-ROMs on a single CD-ROM drive, the Macintosh version will
automatically eject the CD-ROM which is currently inserted. Ejection
must be performed manually for the Microsoft Windows version.

Ejecting a CD-ROM at times other than that directed by the Entrez application
may result in undesirable effects.

If you _must_ eject a CD-ROM on the Macintosh when Entrez is running, it
is important to drag the CD-ROM icon to the trash can, rather than using
the Eject selection from the Finder's FILE menu. The latter may result in 
undesirable effects.



The remainder of this document is a technical discussion which should not
be necessary for the reader who only wants to install Entrez on their system.


----------------------------------------------------------------------------

                           TECHNICAL DISCUSSION

The new configuration files consist of a three-level structure. This
hierarchy is implemented by using unique user-specified names for sections
within the configuration file, as well as some reserved section names.

The top-level of the hierarchy consists of three reserved-named sections,
"MEDLINE", "SEQUENCE", and "LINKS", each of which contain a single _field_,
"CHANNELS". Channels are used to specify the mechanisms by which the
corresponding types of data can be obtained. For example, considering the
Entrez:MEDLINE and Entrez:Sequences CDs, it is possible to obtain some
MEDLINE information from either CD, but Sequence information may only be
obtained from the Entrez:Sequences CD. Therefore, the value of the channels
field for MEDLINE will contain two user-defined channel names, but the value
of the channels field for SEQUENCE will only contain one such channel name.

Each name listed on the right-hand-side of "CHANNELS=" must corresponding
to a section-name at the second-level of the hierarchy; the "Channels"
level. Each Channel-level entry consists of a list of priorities for 
the possible types of data associated with that channel. Priorities are used
by the Entrez software to determine which Channel it should attempt to
use for obtaining the corresponding data. A priority of 0 indicates that
this channel should never be used to obtain this data. For positive values,
a higher priority indicates a preference for that data channel. For example,
the Channel for obtaining MEDLINE records from the Entrez:Sequences disc
might have priority 1, while the corresponding Channel associated with
the Entrez:MEDLINE disc might have priority 2, because the latter is a better
source for this data. The integer-valued priorities may optionally be
followed by a comma and the keyword "NO_DRASTIC_ACTION". This means that,
if the priority for this channel is higher than any other, but a "drastic
action" would need to be taken to make this channel active (like ejecting
a different CD-ROM), then a channel with lower priority may be deferred to
(e.g., if the corresponding CD-ROM is currently inserted).

The possible data types for MEDLINE and SEQUENCE channels are:
    RECORDS   - Entire MEDLINE abstracts, or Sequence entries; these
                corresponding to double-clicking on a document summary
                in the Documents window
    DOCSUMS   - A document summary; these appear as a scrolled list in
                the document summary window
    TERMS     - These are the terms specified in term selection in the
                Query window
    BOOLEANS  - This is the operation performed during query refinement
The default priority for an unreferenced data type (e.g., TERMS) is 1.

A LINKS channel consists of an "INFO" priority, used to access global
information about Entrez status, and a set of links relationships. Links
relationships are specified by the "from" name, followed by two underscores,
followed by the "to" name. For example, the name for MEDLINE to SEQUENCE
links is "MEDLINE__SEQUENCE". The default priority for these double-underscored
names is 0, while the default priority for "INFO" is 1.

Each Channel section must also contain a "MEDIA" field. This references
the lowest-level level in the hierarchy, Media.

A Media, in turn, contains a "TYPE" field (currently this value must be either
CD or HARDDISK), and a set of fields which correspond to much of the original
set of fields which appeared in the "NCBI" section of the old-style
configuration field (namely: IDX, ROOT, etc.). There is an additional field,
"VAL", which must point to the filename for CDROMDAT.VAL. The default value for
"VAL" is the value specified by "ROOT".

A media section must also contain the field "FORMAL_NAME", which is
the formal name to be used for that media when the software addresses the
user (e.g. "Entrez:MEDLINE CD-ROM"). A media section may also contain
one or more fields of the form "DRASTIC_TO_mmm=1", where mmm is the
section name of another media. This is used in conjunction with the
"NO_DRASTIC_ACTION" option which may appear in some Channel fields.
For example, within a Media section "ENTREZ_MED_CD", the field
"DRASTIC_TO_ENTREZ_SEQ_CD" means that it is considered to be a drastic
action to switch from the Entrez:MEDLINE CD-ROM to the Entrez:Sequences
CD-ROM.

The "NCBI" section  must contain the DATA and ASNLOAD entries, indicating
where the data files and ASN.1 object loader definitions are to be found.
In addition, the "NCBI" section must contain a "MEDIA" field, which is
a comma-separated list of all the Media which will be used. Note that
this constitutes a deviation from the 3-level model mentioned earlier.

A discussion of the pathname redirection used in both old and new-style
configuration files is in order here, since it has never been fully
documented on earlier CD-ROMs or CD-ROM documentation. The pathname
specification field names are: "ROOT", "IDX", "TRM", "MED", "SEQ", "LNK".
All pathnames default as being relative to the directory specified by
"ROOT", which is a mandatory field. The remaining fields, which are all
optional, override the pathname specified by "ROOT" for a specific set of files,
as follows:
* IDX    - Index files
* TRM    - Term list files (and their associated indices and "posting files")
* MED    - ASN.1 data for MEDLINE documents
* SEQ    - ASN.1 data for sequence documents
* LNK    - Links among related documents
*