( $RCSfile: description.all,v $ $Revision: 1.3 $ $Date: 1998/02/06 05:31:23 $ )
Table of Contents:
	I. Introduction.
	II. Purpose.
	III. How the library is accessed.
	IV. Interface routines.
	    A.  File opening and closing.
	    B.  Positioning in and reading from the input file.
	    C.  Writing to the output file.
	    D.  Error handling.
	V. Simple examples.

I. Introduction:

This document describes the purpose of the MMIO library, the way in
which user applications should link to it, and the way in which its
functions are used.  Example applications using the functions are
provided separately.

Recent Changes:

Revision 62 of the MMIO library introduces two new functions:
mmio_get_atomg() and mmio_put_atomg(), and their Fortran counterparts.
These get and set the grow-names, in addition to the other atomic
values gotten and set by the functions mmio_get_atom() and 
mmio_put_atom(), which are retained for back-compatibility.  The
grow-name is a new field which will be used by the MacroModel II
builder.  All new code should be "growname aware";  it should read,
store, and restore grownames to atom fields, even if it doesn't
use them, to avoid losing information in MacroModel files that
contain grownames.

Note that the files with and without grownames can be read with
both sets of API functions;  however, if grownames are present,
they will be lost if the old functions are used.

Bottom line for new code:  (1) use the new atom functions,
as described above;  (2) link with libmmio.a, which allows
either the Fortran or the C API to be used by the application;
note, however, that to resolve all links, you will have to link
with Fortran IO libraries provided by your operating system.

II. Purpose:

MMIO consists of a set of routines which can be used to read and
write MacroModel structures from and to files.  It is an API 
(application programmer interface), meaning that application 
programmers can use calls to MMIO to read and write MacroModel 
files.

Two API's are in fact provided: MMIOF, for use by Fortran 
programmers, and MMIOC, for use by C programmers.  There is
a 1:1 correspondence between the procedures provided in the two 
libraries, but of course the calling syntax varies between them,
following both the definition and the idiom of the underlying
language.

Prior to Revision 54, it was necessary to link to separate libraries
to access the C and Fortran versions, and a given program could
only link to a single such library.  Thus, a mixed C/Fortran
application could call MMIO from either its C or its Fortran
routines, but not both.  Starting with Revision 54, this limitation
is overcome by means of a new library containing both the C- and
the Fortran-callable routines.  The price that is paid for this
flexibility is that the Fortran- and C-callable routines are now
differentiated by name, the Fortran-callable routines containing an 
"F" as part of the prefix (as in "MMIOF_GET_ATOM()", whereas the 
corresponding C routine is called "mmio_get_atom()").

In Revision 53 and earlier of the MMIO library, Fortran code
linked to "libmmiof.c" and C code linked to "libmmioc.c", and
both libraries used the same routine names (modulo case).  For
back-compatibility, we continue to supply these libraries, so
that old Fortran code can continue to link to "libmmiof.c" and
use the old routine names.  We also continue to support "libmmioc.c",
which continues to contain only the C-callable routines.  For
new code, however, we recommend the use of "libmmio.a", the
combined library.
 
The API intentionally hides the MacroModel file format from the user.
User code employing these functions will be insulated against
against changes in the MacroModel file format, until or unless
it becomes necessary to add new information to the file format.

The current version of MMIO assumes that a given structure ("CT")
in a MacroModel data file may be in either a full or a compressed
format.  The compressed format gives, for each line, only the
atom number, the coordinates and the color of each atom;  furthermore,
this information may be present for only some of the atoms in the
molecule.  Any missing information, such as the atomic connectivity,
is assumed to be present in the last full CT in the file preceding
the compressed CT.  If the compressed CT has missing atoms, then the
coordinates and color of these atoms, as well as their connectivity
and so on, are assumed to be properly given in the corresponding
full CT.  The structure of the API is such that the calling
code may obtain the full information about each CT, even if
the actual file contained a compressed CT;  however, if desired,
the calling application also has the option of reading only
the information present in a compressed CT, if desired.  (But
this is nearly never desired!)

A MacroModel data file can thus be thought of as consisting of
a set of blocks, each block consisting of a full CT followed by
zero or more compressed CT's.  Each compressed CT can be thought
of as updating the information in the full CT that heads the
block in which it is found.  It is worth emphasizing that each 
compressed CT independently updates the last full CT that appeared 
in the file;  changes made by successive compressed CTs are not 
cumulative.  

The MMIO library is optimized for storage.  It stores, for each file 
opened, only the last full CT read or written, together with information 
from the current compressed CT, if any.  This, together with its use 
of dynamic memory allocation, guarantees that its storage requirements 
will remain small.  However, MMIO does keeps track of the location of 
each CT it has visited in each file, as well as certain other bookkeeping 
information.  This makes it well suited for repeated random access 
of CT's from a MacroModel structure file.  Still, bear in mind that
MMIO is not a database; it stores the minimal information necessary
to convey information about the current CT between the application
and a file.

A user application calling MMIO functions to read a MacroModel structure 
file can request to have full information returned to it even if only
a compressed CT is present in the file; alternatively, it can
request to have only the compressed information (updated coordinates
and color) returned to it when a compressed CT is found.  You will
nearly certainly want to request full-CT information from MMIO.

However, if you are writing a series of structures known to be
conformers of each other to a file, you will probably want to
write out compressed CTs, since the deletion of connectivity
information in all but the first CT will save disk storage.
This is especially true if even the coordinates of some atoms
do not change in CTs beyond the first one;  if so, even 
coordinate information is unnecessary for these atoms, and an
even greater disk saving is possible.

Multiple files may be simultaneously open for reading or writing from 
the calling application.