III. How the library is accessed:
( $RCSfile: description.Fortran,v $ $Revision: 1.4 $ 
 $Date: 1998/02/06 05:31:23 $ )

Starting with Revision 54 of the library, a combined Fortran/C
API is provided.  This allows mixed Fortran/C programs to call MMIO
from both the Fortran and the C side, but requires the Fortran- and
C-callable routines to have different names.  The names shown
here are the new names.  For back compatibility, we also supply
a separate, Fortran-only library that uses the old names.  The
old names begin with "MMIO_", and the new Fortran-callable names
begin with "MMIOF_".  This convention applies only to names of
routines;  names of parameters and constants continue to begin
with "MMIO_", as in "MMIO_FULL", "MMIO_ERR", etc..

Any routine using the library functions should INCLUDE the file
'mmio.inc';  This file is to be found in the directory 
'$MMOD_ROOT/develop/include'.  In addition, the application must be 
linked with the arguments '-L$(MMOD_ROOT)/develop/lib -lmmiof'.
Here, MMOD_ROOT is an environment variable set to the root directory
of the MacroModel distribution.

The basic scheme by means of which the application utilizes the library
is as follows.  To read a file, the file is opened by calling the
function, MMIOF_OPEN() with mode MMIO_READ.  To initiate transfer of a
structure from the file, first the function MMIOF_GET_CT() is called.
This returns the number of atoms in the structure (call it "natom" for now)
and the title.  Then MMIOF_GET_ATOM() is called natom times; each call 
returns full information on a single atom.  For writing, MMIOF_OPEN() 
is called using mode MMIOF_WRITE or MMIOF_APPEND.  MMIOF_PUT_CT() is used 
to pass the number of atoms (natom) and a title to the library, and 
MMIOF_PUT_ATOM() is called natom times;  each call passes to the library 
information about a single atom.

The following section describes these routines in more detail, and
also describes several other routines which are supplied.

IV. Interface routines:

The following parameters will be defined in the file MMIO.INC:

C	*** maximum number of bonds to a given MacroModel atom:
	INTEGER MMIO_MAXBOND

C	*** length of long string variables passed to and from the library:
	MMIO_L_STRLEN
C	*** length of short string variables passed to and from the library:
	MMIO_S_STRLEN

C	*** status return values:
	MMIO_COMPRESSED
	MMIO_FULL
	MMIO_OK
	MMIO_EOF	! end of file
	MMIO_BOF	! beginning of file
	MMIO_DONE
	MMIO_ERR

C	*** file-opening modes:
	MMIO_READ
	MMIO_WRITE
	MMIO_APPEND

Unless otherwise indicated, if MMIO_ERR is returned in argument istat 
in any of these routines, none of the other return values can be assumed 
valid.

The commands listed below are grouped into categories:

    A.  File opening and closing.
    B.  Positioning within and reading from the input file.
    C.  Writing to the output file.
    D.  Error handling.


In this descriptive section, variable names in CAPS have values supplied
by the user's calling routines.  Variable names in lower-case point to
storage filled by the called (mmiof) routines.

A.  File opening and closing.

SUBROUTINE MMIOF_OPEN( idataset, FNAME, MODE, istat )
C *** Open a file for reading, writing or appending.  
C *** If successful, this command will return in idataset an integer 
C ***  uniquely identifying the open file to the mmio library.  This 
C ***  number has no intrinsic significance to the calling application 
C ***  (for example, it does not specify a Fortran IO unit);  rather, 
C ***  the client application must pass it back to the library on 
C ***  each attempt to access the the corresponding file.  It is,
C ***  however, guaranteed that IREAD will never be negative.
C *** If the special FNAME value '-' is passed to MMIOF_OPEN, then,
C ***  if MODE is MMIO_READ, the standard input will be used for
C ***  structure input;  similarly, if '-' is passed to MMIOF_OPEN
C ***  when mode is MMIO_WRITE or MMIO_APPEND, the standard output
C ***  will be used for structure output.  The FNAME string passed
C ***  to the function has to be declared as indicated below even in
C ***  this situation.
  INTEGER idataset	! a different integer for each open data file
  CHARACTER*(MMIO_L_STRLEN) FNAME		! file name to be opened
  INTEGER MODE		! MMIO_READ, MMIO_WRITE or MMIO_APPEND
  INTEGER istat		! MMIO_OK or MMIO_ERR

SUBROUTINE MMIOF_CLOSE( IDATASET, istat )
C *** Close a file previously opened.  Either MODE=MMIO_WRITE or MMIO_APPEND
C ***  will close the file previously opened with either of these;  MMIO_READ
C ***  closes the file previously opened with this mode.
  INTEGER IDATASET	! an integer returned from a previous MMIOF_OPEN
  INTEGER istat		! MMIO_OK or MMIO_ERR

B.  Positioning in and reading from the input file.

SUBROUTINE MMIOF_GOTO_CT( IDATASET, NCT, istat )
C *** Positions us in the file just before CT numbered NCT (index-origin 1).  
C *** If istat returns MMIO_EOF, the library's file pointer remains
C ***  at end-of-file.  If istat returns MMIO_BOF, the library's file 
C ***  pointer remains at the beginning of the file.
C *** If istat returns MMIO_ERR, the library's file pointer remains where 
C ***  it was before this command was executed.  
  INTEGER IDATASET	! value returned from a previous MMIOF_OPEN w. MMIO_READ
  INTEGER NCT		! CT number to go to, index-origin 1 (1st CT is #1)
  INTEGER istat		! MMIO_OK, MMIO_ERR or MMIO_EOF

SUBROUTINE MMIOF_SKIP_CT( IDATASET, NCT, istat )
C *** This is a relative-positioning routine;  it will skip NCT CT's in
C ***  the file.  NCT can be negative.
C *** If istat returns MMIO_EOF, the library's file pointer remains
C ***  at end-of-file.  If istat returns MMIO_BOF, the library's file 
C ***  pointer remains at the beginning of the file.
C *** If istat returns MMIO_ERR, the library's file pointer remains where 
C ***  it was before this command was executed.  
  INTEGER IDATASET	! value returned from a previous MMIOF_OPEN w. MMIO_READ
  INTEGER NCT		! relative CT number to go to
  INTEGER istat		! MMIO_OK, MMIO_ERR or MMIO_EOF

SUBROUTINE MMIOF_COUNT_CT( IDATASET, nct, istat )
C *** Return the number of CT's in the input file.  This will require 
C ***  reading ahead to EOF, unless we've been there before.  Library's 
C ***  file-pointer remains where it was before this command was executed.
  INTEGER IDATASET	! integer returned from a previous MMIOF_OPEN/MMIO_READ
  INTEGER nct		! Cardinal number of CT's in the input file
  INTEGER istat		! MMIO_OK or MMIO_ERR

SUBROUTINE MMIOF_GET_CT( IDATASET, CT_TYPE, natom, title, istat )
C *** Initiate the reading of a CT from the current position in the file.
C *** CT_TYPE tells the library whether the calling program is willing to
C ***  receive the updated information, only, if a compressed CT is found.
C ***  If CT_TYPE is specified as MMIO_FULL, then the library will always
C ***  return the full CT, even if a compressed file is found on disk.
C ***  If CT_TYPE is specified as MMIO_COMPRESSED, then the library will
C ***  return only the atoms needed to update the most recently read
C ***  full CT, provided that (1) the current CT is indeed a compressed 
C ***  CT, and that (2) the last full CT read is the one which the 
C ***  current compressed CT updates.
C *** natom is the number of atoms for which information will be returned
C ***  (i.e., the number of times MMIOF_GET_ATOM should be called by the
C ***  user).  title is the title of the current CT.
C *** istat returns the type of CT corresponding to natom;  it may be
C ***  MMIO_FULL even if CT_TYPE is MMIO_COMPRESSED.  If istat is MMIO_EOF,
C ***  the file-pointer remains positioned at end-of-file;  otherwise,
C ***  it is positioned at the beginning of the next CT.
  INTEGER IDATASET	! integer returned from a previous MMIOF_OPEN/MMIO_READ
  INTEGER CT_TYPE	! MMIO_FULL or MMIO_COMPRESSED
  CHARACTER*(MMIO_L_STRLEN) title		! title of this CT
  INTEGER natom		! number of atoms to be returned
  INTEGER istat		! MMIO_ERR, MMIO_EOF, MMIO_FULL or MMIO_COMPRESSED

SUBROUTINE MMIOF_GET_ATOM( IDATASET, mmio_atom, itype, nbond, bond_atom, &
 bond_order, xyz, charge1, charge2, chain, color, resnum, resname1, &
 resname4, pdbname, istat )
C *** Get information on the next atom.  mmio_atom is the MacroModel
C ***  atom number.  istat is normally MMIO_OK until the last atom is
C ***  received;  with the last atom's information, istat will be MMIO_DONE.
C ***  This function should be called natom times, where natom is the
C ***  value returned by the previous MMIOF_GET_CT call.
C *** If the preceding MMIOF_GET_CT returned MMIO_COMPRESSED in its istat
C ***  parameter, then MMIOF_GET_ATOM only returns values in the following 
C ***  arguments:  mmio_atom, xyz, color, and istat.  The remaining arguments
C ***  will be untouched by the library;  thus, for example, junk variables
C ***  or constants may be passed as these arguments.
C *** N.B. In the current MMIO implementation, the entire CT is in fact
C ***  read when MMIOF_GET_CT is called.  The MMIO_GET_ATOM calls do not
C ***  perform disk IO, but merely transfer data from the MMIO's
C ***  private data cache to the calling routine's storage locations.
C ***  Thus, when MMIOF_GET_CT returns MMIO_OK, the calling application
C ***  can be certain that the full CT has been recovered from disk 
C ***  without error.
  INTEGER IDATASET	! integer returned from a previous MMIOF_OPEN/MMIO_READ
  INTEGER mmio_atom	! MacroModel atom number of current atom
  INTEGER itype		! MacroModel atom type of current atom
  INTEGER nbond		! number of bonds to this atom
  INTEGER bond_atom(nbond)	! atoms bonded to this atom
  INTEGER bond_order(nbond)	! bond orders of bonds to this atom
  REAL xyz(3)		! coordinates
  REAL charge1, charge2	! charge1, charge2 fields in mmod file
  CHARACTER chain	! pdb chain name
  INTEGER color		! MacroModel color code
  INTEGER resnum	! pdb residue number
  CHARACTER resname1	! single-char pdb residue-type code
  CHARACTER*(MMIO_S_STRLEN) resname4	! 4-char pdb residue-type code
  CHARACTER*(MMIO_S_STRLEN) pdbname	! pdb atom name
  INTEGER istat		! MMIO_ERR, MMIO_OK, MMIO_DONE

SUBROUTINE MMIOF_GET_ATOMG( IDATASET, mmio_atom, itype, nbond, bond_atom, &
 bond_order, xyz, charge1, charge2, chain, color, resnum, resname1, &
 resname4, pdbname, growname, istat )
C *** Just like MMIOF_GET_ATOM, except it also gets the growname, a
C ***  new field introduced after MacroModel 6.5.  The grownames are
C ***  used by the MacroModel II builder.  New code should use 
C ***  MMIOF_GET_ATOMG() instead of MMIOF_GET_ATOM();  this allows
C ***  the code to obtain, store, and pass through grownames even
C ***  if the code itself doesn't use them.
  ...
  CHARACTER*(MMIO_S_STRLEN) growname	! Mmod II growname

C.  Writing to the output file.

SUBROUTINE MMIOF_PUT_CT( IDATASET, CT_TYPE, NATOM, TITLE, istat )
C *** Prepare to write a CT to disk.  CT_TYPE tells whether the file
C ***  will be written in compressed or full format.  NATOM
C ***  should contain the number of atoms appropriate to this format, 
C ***  and MMIOF_PUT_ATOM should subsequently be called NATOM times.
C *** N.B.  It is the calling application's responsibility to ensure
C ***  that when a compressed CT is written, it corresponds to part of
C ***  the last-written full CT.  In particular, an application must
C ***  never write a compressed CT as the first entry in an output file,
C ***  if this file is later to be read by the MMIO library.  Finally,
C ***  we remind the user that each compressed CT must independently update
C ***  the last full CT written.  Upon reading, MMIO applies compressed-
C ***  CT information directly to the previous full CT;  changes made by 
C ***  successive compressed CT's are not cumulative.  Again, it is the
C ***  responsibility of the calling application, not the MMIO library,
C ***  to enforce this convention on output.
  INTEGER IDATASET	! integer returned from a previous MMIOF_OPEN/MMIO_WRITE
  INTEGER CT_TYPE	! MMIO_FULL or MMIO_COMPRESSED
  CHARACTER*(MMIO_L_STRLEN) TITLE		! title of this CT
  INTEGER NATOM		! number of atoms to be written
  INTEGER istat		! MMIO_ERR or MMIO_OK 

SUBROUTINE MMIOF_PUT_ATOM( IDATASET, MMIO_ATOM, ITYPE, NBOND, BOND_ATOM, &
 BOND_ORDER, XYZ, CHARGE1, CHARGE2, CHAIN, COLOR, RESNUM, RESNAME1, &
 RESNAME4, PDBNAME, istat )
C *** Output information for the next atom.  MMIO_ATOM is the MacroModel
C ***  atom number.  istat is normally MMIO_OK until the last atom is
C ***  received;  with the last atom's information, istat will be MMIO_DONE.
C ***  This function should be called NATOM times, where NATOM is the
C ***  value passed to the previous MMIOF_PUT_CT call.  The values
C ***  of MMIO_ATOM must be in strictly increasing order on successive calls.
C *** If the preceding MMIOF_PUT_CT was passed MMIO_COMPRESSED in its ct_type
C ***  parameter, then MMIOF_PUT_ATOM only passes values from the following 
C ***  arguments:  MMIO_ATOM, XYZ, AND COLOR.  The remaining arguments
C ***  will not be referenced by the library;  thus, for example, junk
C ***  variables or constants may be passed in these arguments.
C *** N.B.  Disk IO is not actually performed when MMIOF_PUT_CT is called,
C ***  or on the first NATOM-1 callse to MMIOF_PUT_ATOM.  Rather, the
C ***  entire CT is output at once when information on the last atom
C ***  is passed to MMIOF_PUT_ATOM.  Once this routine returns MMIO_DONE,
C ***  the CT has been written to disk.  This scheme ensures that no
C ***  writing to disk will be performed unless the MMIO library has
C ***  received self-consistent data on the entire CT.
  INTEGER IDATASET	! integer returned from a previous MMIOF_OPEN/MMIO_WRITE
  INTEGER MMIO_ATOM	! MacroModel atom number of current atom
  INTEGER ITYPE		! MacroModel atom type of current atom
  INTEGER NBOND		! number of bonds to this atom
  INTEGER BOND_ATOM(NBOND)	! atoms bonded to this atom
  INTEGER BOND_ORDER(NBOND)	! bond order of atoms bonded to this atom
  REAL XYZ(3)		! coordinates
  REAL CHARGE1, CHARGE2	! charge1, charge2 fields in mmod file
  CHARACTER CHAIN	! pdb chain name
  INTEGER COLOR		! MacroModel color code
  INTEGER RESNUM	! pdb residue number
  CHARACTER RESNAME1	! single-char pdb residue-type code
  CHARACTER*(MMIO_S_STRLEN) RESNAME4	! 4-char pdb residue-type code
  CHARACTER*(MMIO_S_STRLEN) PDBNAME	! pdb atom name
  INTEGER istat		! MMIO_ERR or MMIO_OK

SUBROUTINE MMIOF_PUT_ATOMG( IDATASET, MMIO_ATOM, ITYPE, NBOND, BOND_ATOM, &
 BOND_ORDER, XYZ, CHARGE1, CHARGE2, CHAIN, COLOR, RESNUM, RESNAME1, &
 RESNAME4, PDBNAME, GROWNAME, istat )
C *** Just like MMIOF_PUT_ATOM(), except allows growname to be specified.
C *** See notest for MMIOF_GET_ATOMG().  New code should use this
C ***  function instead of MMIO_PUT_ATOM().
  ...
  CHARACTER*(MMIO_S_STRLEN) growname	! Mmod II growname

D.  Error handling.

SUBROUTINE MMIOF_RETURN_CODE( STATUS, message )
C *** return the ascii name for an MMIO status code.
  INTEGER STATUS	! value returned in istat for some previous command
  CHARACTER*(MMIO_L_STRLEN) message	! name giving the meaning of istat

SUBROUTINE MMIOF_ERRFILE( IOUNIT, istat )
C *** Set the Fortran IO-unit to which detailed error messages generated
C ***  by the library will be sent.  This IO-unit should be one previously
C ***  opened by the calling application.
C *** If never called, such error messages are not printed.
  INTEGER IOUNIT ! IO-unit for err. msgs.;  if .LT. 0, turn off error reporting
  INTEGER istat		! return status of this command: MMIO_OK or MMIO_ERR

V. Simple examples.

See mmio_uncompress.f, a very simple program that uncompresses compressed
 MacroModel files (or, if the input CT's are full to begin with, copies 
 them to the output).

See also fmmio.f, which is just a little bit more complicated than
 mmio_uncompress.f.  This program allows the user to specify whether
 uncompression will take place;  it can also copy the input directly
 to the output.

Both of these programs are heavily commented, and are designed chiefly
 to demonstrate how the MMIO library might be used.