( $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.