#################################################################
# *** $RCSfile: README,v $
# *** $Revision: 1.8 $
# *** $Date: 1998/02/06 06:04:49 $
#################################################################

		    Introduction to the MMIO library
	Peter S. Shenkin, March, 1995, shenkin@columbia.edu

1.  What it is and what it ain't.

    MMIO stands for "MacroModel Input-Output".

    The MMIO library is a linkable code library for reading and
    writing MacroModel structure files.  Communication
    with the calling application is by means of an API (Application
    Programmers' Interface), a set of function and subroutine
    calls.  Both a C and a Fortran API are provided.

    The main purpose of MMIO is to insulate the calling application
    from having to know anything about the actual file format that
    these files use.  For example, we have recently implemented
    a new, compressed, file format, and we are planning other
    changes in the future which will either save disk space or
    increase capabilities.  If calling applications use MMIO, they 
    will not have to worry about parsing the new format;  the present
    API will continue to be in force for some time.

    MMIO does not, however, know anything about chemistry.  It is
    still up to the user application to properly interpret MacroModel
    atom-types on reading and properly specify them on writing.  Similarly,
    the calling application must properly interpret and specify bond
    orders.  It is possible that in the future we will produce another
    code library that handles some of these chores;  for example, it 
    would contain a function that returns the atomic number, given a 
    MacroModel atom type.

2.  Provisions of use.

    The code is copyrighted;  please read the copyright notice that is
    printed in all code modules.

    However, you may do nearly anything you wish with MMIO, including 
    incorporating it into a commercial product free of charge.  You
    may also redistribute the source.  You may not remove the copyright 
    notice from the source.  Also, if you redistribute the source with 
    changes you have made, you must also communicate those changes back 
    to us so that we can redistribute them as well, if we wish to do so.

    Changes you make for your own proprietary purposes need not be 
    communicated back to us if you do not redistribute source code.

    Though MMIO works properly as far as we know, and though we will
    do our best to correct errors or deficiencies as we become aware of 
    them, we do not warrant the correctness of MMIO in any way.  Use
    MMIO at your own risk.

3.  Documentation.

    Two files, README.C and README.Fortran, will be produced when you
    make the libraries.  These describe how to use the libraries and 
    document the API fully.  Several code examples are provided.  You 
    should study at least one example before using MMIO in your own 
    application.  The sample programs are:

       Fortran API:
          fmmio.f
          mmio_uncompress.f
       C API:
          cmmio.c
          mmio_convert.c  ( Complicated example -- save for last. )

    These programs are heavily commented.

3.  Making the libraries and documentation.

    This is described in the file README.src.  

    The file RCS_version describes the current and past versions of 
    MMIO.  If you are considering upgrading from a previous MMIO version, 
    consulting this file will help you decide whether it's worthwhile
    to do so.

4.  Platforms.  
    MMIO is known to run on the following platforms:
                SGI, IBM, DEC/OSF, HP, FUJITSU, Cray
    Compilation flags are supplied for several other platforms, but
    these have not all been tested.  MMIO ought to port easily to any 
    UNIX platform.  It also ought to port easily to non-UNIX platforms, 
    since it is written entirely in ANSI C, with the exception of some 
    Fortran routines in the Fortran interface, only.  The hardest part
    of any port will likely be grokking the Fortran-C string-passing
    conventions.