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 updating 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 It 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.