HLPWWW (Version 8.7) JESS copyright (C) 1985-2019
Licensee : Webmaster, Murdoch University, Australia
Welcome. Sunday, 28-May-23 23:23
You are strongly urged to safeguard the effort you put into
developing any JESS database. A few precautionary steps can
prevent a great deal of aggravation!
In general it is wise to (i) make regular backup copies of the
database, usually in conjunction with the database housekeeping
procedures - consult the index searching for 'housekeeping' to
obtain details and (ii) make a working copy of the database prior to
execution of any program that opens the database with 'write access'
(i.e. as required to insert new data or modify existing data).
For example, with UPDJTH copy *.IND to *.SAV
             with UPDJLR copy *.KEY to *.SAV
         and during the GEM stages "doi save".
These copies are used in the recovery procedures following premature
program termination (in the event of a power failure, program crash
or whatever). Consult the index searching for "crash" (without quotes)
to obtain further details.
You should also be aware of the need to send newly entered
thermodynamic data to the authors on a regular basis so that it
can be incorporated into the JESS Parent Database, JPD. This
will prevent you from having to re-enter your data each time
a new version of JPD arrives at your site. Consult the index
searching for 'data transfer' to obtain details on how to
accomplish this.

To achieve rapid access, much of the data that are stored or manipulated within JESS occurs in files we call JESS Indexed Files or JIFs. These are FORTRAN direct-access files, typically with filename extensions such as *.USE, *.IND and *.KEY. JIFs are used to support various JESS databases, including in particular the thermodynamic databases, the literature reference databases, the dictionary and the thesauri. Since JIFs contain internal linkages which are complicated and large in number, it is desirable from several viewpoints that the data contained in them from time to time be written to sequential files and then re-loaded into a freshly-created JIF structure. We call the process of writing data in a JIF out to a sequential file 'dismounting the JIF'. Loading the data from the sequential file back into JIF form is likewise called 'mounting the JIF'. We also use the expression 'building a database' to mean mounting all the JIFs involved and (usually) constructing additional linkages between the JIFs. Accordingly, there are programs pre-fixed with DMT, MNT and BLD for each of the sub-systems dealing with the abovementioned databases. For example, for the thermodynamic databases, the programs are DMTJTH, MNTJTH and BLDJTH. It is worth noting that the dismount operations are performed much faster than the mount operations (since the latter involves re-creation of all the internal JIF linkages). Of course, building is the slowest of the three operations because it involves doing the most work.
The procedure we call 'building a database' involves the construction of the database files from one or more input files which provide the information in its most reduced form. This involves creating all the linkages which exist between the data and which make the database quick and convenient to use. The procedure can therefore be quite slow. Inspect the index for further details, using the search term "database + mount" (without quotes).
Printed output (hardcopy) can be obtained from both JLR and JTH databases using the programs appropriate to your particular requirement. Thermodynamic data are generally processed using the program WRTJTH. This produces a file with the necessary information either relating to a set of JTH species or a set of JTH reactions that you specify. Inspect the index specifying "WRTJTH" (without quotes) for further details. The list of reactions that you must specify to obtain output of their thermodynamic data is often generated most conveniently using program NUMJTH. Inspect the index specifying "NUMJTH" and specifying the term "input + file" to find out how this is achieved. Literature references are generally processed using the program FMTJLR. This produces a file with the necessary information presented in various formats according to pre-prepared instructions. These instructions can either come from an available set or can be specifically developed by you. Consult the index specifying "FMTJLR" for further details. Output of literature references (in the standard JLR format) can also be rapidly carried out using program WRTJLR.
JESS provides a variety facilities to transfer data between JTH databases. Data can be moved between databases on the same computer or from a database on one computer to a database on another. These procedures involve either the creation of a sub-database or a set of 'transfer files' or both. Producing a sub-database in the same directory as the source database is quite straightforward and is accomplished by programs SUBJTH and BLDJTH. However, since the JTH database system is very flexible in the way data can be entered and modified, the transfer of data between databases on different computers (or with different associated JLR databases) can be quite long-winded and complicated. You need to follow each step of the prescribed procedures carefully and in the proper order. You can find the necessary details by searching the index for "transfer" (without quotes). The main points for you to remember arise from the need to 'synchronize' the two databases before they are merged together. In particular, this means ensuring that the representations of data items such as chemical species, author names, publications, etc. are identical before the databases are combined. If they are not, the resulting database will have both forms included. Such duplication is a very serious error, with quite unacceptable consequences when the database is used later on.
Programs SUBJTH and BLDJTH are used to create a JTH sub-database. You specify the reactions which are to be put into the sub-database and SUBJTH produces a set of intermediate files which BLDJTH then builds into the required sub-database. The sub-database can be created in the same directory as the source database on in another one (possibly even on a different computer). Note that each JTH database is associated with a JLR database, either the common literature reference database in the JESS directory VEWDTA/ or present IN THE SAME DIRECTORY as the thermodynamic database. Indeed, a single JLR database is frequently associated with more than one JTH database. This means that when reactions and data are to be transferred to another directory (where the JLR database may be different) special steps must be taken to transfer and synchronize the associated literature references. This is done using PUTJLR and GETJLR. Consult the index, searching for SUBJTH, to obtain futher details of how a sub-database is created.
Programs PUTJTH and GETJTH are used to transfer ALL the reactions, data, species, etc. from one (source) thermodynamic database to another existing (target) database. If you only wish to transfer a subset of reactions you must first use programs SUBJTH and BLDJTH to produce a sub-database with the required data, which can then be processed using PUTJTH and GETJTH. Programs PUTJLR and GETJLR are used to transfer a specified set of references from one (source) literature database to another existing (target) database. To produce a set of files which contain all the information to be transferred, you first execute PUTJTH and then PUTJLR. These appear as output files with the file-name extension ".WRK". Program PUTJTH also produces a (*.VDU) file with all relevant literature reference numbers. This can be processed by PUTJLR in the usual way using the JESS "||||filename" input convention - consult the index searching for "input + sequential" (without quotes) for details. SOURCE TARGET Thermodynamic Database PUTJTH copy/ftp "SRC" ---------> SRC*.WRC ----------> new directory (SRC*.IND files) + or another computer SRCREF.VDU (lit. ref. | numbers) / Literature <-----' Database PUTJLR copy/ftp ---------> *.WRC ----------> new directory (*.KEY files) or another computer
Once the set of transfer files from PUTJTH and PUTJLR have been copied to their destination, creating a new database there or merging the information they contain with existing (target) databases can begin. The JLR transfer MUST BE COMPLETED FIRST so that the references of the incoming thermodynamic data can be converted to refer to the target literature database numbers. Further information on how to merge JLR databases can be obtained by searching the index for "GETJTH" (without quotes). Since this conversion can only be accomplished in a newly-created JTH database and since you are strongly advised to review the incoming thermodynamic data prior to its incorporation into an existing thermodynamic database, the next step is to create a new JTH database (by executing program CREJTH) and to incorporate all the incoming thermodynamic data into it. This intermediate database is called the 'synchronizing database' and it is typically given the name 'SNC'. Once the thermodynamic data has been synchronized, program PUTJTH is used to produce a new set of transfer files (SNC*.WRK) which are then incorporated into the target database directly using program GETJTH. The point of this is that the data processed by program GETJTH must be entirely consistent with the existing target database. If any inconsistencies are detected, GETJTH will fail and you will need to begin the merge procedures again (synchronizing the data properly and only then importing it using GETJTH). For this reason, it is very important to make a copy of the target database prior to executing GETJTH. Any failure of GETJTH renders the target database unusable. So you must be able to re-instate it in case a problem occurs. You will probably discover that such problems occur relatively frequently if you are working with more than one JTH database or exchanging data with other people. This is because changes that are made to the different databases often make them incompatible with one another, unless and until the data are properly synchronized. Typically, this happens when I/O symbols for chemical species are modified or the solvent, medium, or technique identifiers are updated.
The overall database merging procedure can be represented as follows. 1. SOURCE NEW (MERGED) Transfer GETJLR literature file of ---------> database lit. data (*.KEY) (SRCREF.WRK) 2. CREJTH ---------> New JTH database (SNC*.IND) 3. SOURCE Synchronizing | modified as Transfer GETJTH thermodynamic | necessary using file of ---------> database | programs UPDJTH thermo. data (SNC*.IND) | and MEDJTH (SRC*.WRK) 4. Synchronizing NEW (MERGED) thermodynamic PUTJTH transfer GETJTH thermodynamic database ---------> files ----------> database (SNC*.IND) (SNC*.WRK) (TGT*.IND)
It is your responsibility to ensure that data that you want to incorporate into an existing database has first been properly "synchronized". This means that you must ensure that the same data item is not referred to by two different names/descriptions in the two databases. The following deal with some important points to watch out for. (a) Using program MEDJTH, check that each of the solvent, background electrolyte and technique codes of the incoming data correspond to those that are in use in the target database. Recent changes to these descriptions that you may have made to the target database will almost inevitably require your attention. (It is for this reason that the descriptions of solvents, background electrolyte and techniques should only be modified when absolutely necessary and that a universal approach by all JESS users is highly desirable.) You can scan through the current entries of a JTH database using the "information at any time" or "query" facility of the JTH programs. At most prompts, you simply enter "?X A" followed by successive "?X"s where X is one of S (for solvent), B (for background electrolyte) or T (for technique). (b) Using program VEWJTH, check that the incoming primitive species are either not yet included in the target database or have an identical I/O symbol to that used in the target database. You can scan through the current entries for the I/O symbols of primitive species in a JTH database using the "View" command and selecting "I/O symbol". Once you have located an I/O symbol (by entering "A" say), you can scan through the remainder of the list simply by successively pressing ENTER. (c) Using the "Delete" or "Kill" facilities of program UPDJTH, remove any data, reactions or species that you do not want to be incorporated in the target database (if required). (d) Program GETJTH, by deliberate intent, rejects all data that appear to be duplicates. In other words, additions to the existing database are OK; modifications and/or deletions are not. Search the index for "GETJTH" (without quotes) to get further details.