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

Any routine using the library functions should include the file
'mmio.h'; a '-I$(MMOD_ROOT)/develop/include' flag will also, in general,
be necessary.  In addition, the application should be linked with
the arguments '-L$(MMOD_ROOT)/run/develop/lib -lmmioc'.  Here,
MMOD_ROOT is assumed to be defined in the compile-time environment, 
either as an environment variable or as a makefile macro.  It should
be set to the MacroModel parent directory.

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 mmio_open() with mode MMIO_READ.  To initiate transfer of a
structure from the file, first the function mmio_get_ct() is called.
This returns the number of atoms (call it "natom" for now) and
the name of the structure ("title").  Then mmio_get_atom() is called 
natom times; each call returns full information on a single atom.  
For writing, mmio_open() is called using mode MMIO_WRITE or MMIO_APPEND.
mmio_put_ct() is used to pass the number of atoms (natom) and a title 
to the library, and mmio_put_atom() is then 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_defs.h, which
is automatically included when mmio.h is included:

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

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

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

	/* file-opening modes */
	MMIO_READ
	MMIO_WRITE
	MMIO_APPEND

If MMIO_ERR is returned by any of the mmioc routines, none of the 
other return values can be assumed valid.

The functions listed below are grouped into categories:

    A.  File opening and closing.
    B.  Positioning in 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 (mmioc) routines.

A.  File opening and closing.

int mmio_open( int *idataset, char *FNAME, int MODE );
/* Open a file for reading, writing or appending.  
 * If successful, this command will return in idataset an integer 
 *  uniquely identifying the open file to the mmio library.  This 
 *  number has no intrinsic significance to the calling application;  
 *  rather, the client application must pass it back to the library on 
 *  each attempt to access the the corresponding file.  It is guaranteed
 *  that mmio_open() will never return a negative value of *idataset.
 * If the special FNAME value "-" is passed to MMIO_OPEN, then,
 *  if MODE is MMIO_READ, the standard input will be used for
 *  structure input;  similarly, if "-" is passed to MMIO_OPEN
 *  when mode is MMIO_WRITE or MMIO_APPEND, the standard output
 *  will be used for structure output.  The FNAME string passed
 *  to the function has to be declared as indicated below even in
 *  this situation.
 * Function arguments:
 *  *idataset:	unique identifier supplied by mmioc for each open data file
 *  FNAME:	file name to be opened
 *  MODE:	MMIO_READ, MMIO_WRITE or MMIO_APPEND
 * Return value:
 *  MMIO_OK: operation succeeded
 *  MMIO_ERR: operation did not succeed
 *      #include 
 *	int iread, status;
 *      status = mmio_open( &iread, "-", MMIO_READ );
 */

int mmio_close( int IDATASET );
/*  Close a file previously opened.
 *  Function arguments:
 *   IDATASET:	unique identifier supplied by earlier mmio_open() call
 *  Return value:
 *   MMIO_OK: operation succeeded
 *   MMIO_ERR: operation did not succeed
 *  Example; close file previously opened:
 *      #include 
 *	int status, iread;
 *      ...
 *      status = mmio_close( iread );
 */

B.  Positioning in and reading from the input file.  (These commands
 can be legally called only with IDATASET values returned from 
 mmio_open() calls for which MODE was MMIO_READ.)

int mmio_goto_ct( int IDATASET, int ICT );
/*  Positions us in the file just before CT numbered ICT.  It is not
 *   necessary to call mmio_goto_ct() when obtaining sequential CT's from
 *   the input file starting with the beginning of the file.
 *  Function arguments:
 *   IDATASET: unique identifier supplied by earlier mmio_open() call
 *   ICT: ordinal number (index-origin 0 -- 1st CT is #0) of CT we wish 
 *   to read next 
 *  Return value:
 *   MMIO_OK: we are prepared to read CT number ICT;  if we've never explored
 *    this far ahead in the file before, the possibility remains that this
 *    is in fact the end of file.
 *   MMIO_EOF: the request is known to have positioned us at or after the 
 *    end of file; we remain at end of file;
 *   MMIO_BOF: the request positioned us before the beginning of file; we
 *    remain at beginning of file;
 *   MMIO_ERR: the operation was unsuccessful.
 *  Example; goto the third CT in the input file:
 *      #include 
 *	int status, iread;
 *      ...
 *      status = mmio_goto_ct( iread, 2 );
 */

int mmio_skip_ct( int IDATASET, int NCT )
/*  Skip NCT CT's in the file.  NCT can be negative.
 *  Function arguments:
 *   IDATASET: unique identifier supplied by earlier mmio_open() call
 *   ICT: ordinal number (index-origin 0) of CT we wish to read next 
 *  Return value:
 *   MMIO_OK: we are prepared to read CT number ICT;  if we've never explored
 *    this far ahead in the file before, the possibility remains that this
 *    is in fact the end of file.
 *   MMIO_EOF: the request is known to have positioned us at or after the 
 *    end of file; we remain at end of file;
 *   MMIO_BOF: the request positioned us before the beginning of file; we
 *    remain at beginning of file;
 *   MMIO_ERR: the operation was unsuccessful.
 *  Example; skip the next two CT's in the input file:
 *      #include 
 *	int status, iread;
 *      ...
 *      status = mmio_skip_ct( iread, 2 );
 */

int mmio_count_ct( int IDATASET, int *nct )
/*  Find the number of CT's in the input file.  In general, this will 
 *   require reading ahead to EOF.  Library's file-pointer remains 
 *   where it was before this command was executed.
 *  Function arguments:
 *   IDATASET: unique identifier supplied by earlier mmio_open() call
 *   nct: number of CT's in file
 *  Return value:
 *   MMIO_OK: the operation succeeded
 *   MMIO_ERR: the operation was unsuccessful.
 *  Example; find out how many CT's are in the input file:
 *      #include 
 *	int nct, iread;
 *      ...
 *      status = mmio_count_ct( iread, &nct );
 *      printf( "There are %d CT's in the input file\n", nct );
 */

int mmio_get_ct( int IDATASET, int CT_TYPE, int *natom,
 char title[MMIO_L_STRLEN+1] );
/*  Initiate the reading of a CT from the current position in the file.
 *  Function arguments:
 *   IDATASET: unique identifier supplied by earlier mmio_open() call
 *   CT_TYPE: MMIO_FULL if you wish mmio to return information on all
 *    atoms, even if a compressed CT is found on disk;  MMIO_COMPRESSED
 *    if you are willing to accept compressed information only (coordinates
 *    and color), only for atoms whose information has been updated since
 *    the last full CT was read.
 *   natom: the number of atoms which will be returned.
 *   title: the title of the current CT being gotten.
 *  Return value:
 *   MMIO_FULL if the full CT information will be returned for all atoms
 *   MMIO_COMPRESSED if compressed CT information, only, will be returned,
 *    for possibly a subset of the atoms;
 *   MMIO_EOF if end of file was encountered when trying to read this CT;
 *   MMIO_ERR if an error occurred.
 *  Example: prepare to read the next CT; accept compressed data, if possible:
 *   #include 
 *   int iread, natom;
 *   char title[ MMIO_L_STRLEN + 1 ];
 *   ...
 *   status = mmio_get_ct( iread, MMIO_COMPRESSED, &natom, title );
 */

int mmio_get_atom( int IDATASET, int *mmio_atom, int *itype, int *nbond,
 int bond_atom[MMIO_MAXBOND], int bond_order[MMIO_MAXBOND], float xyz[3],
 float *charge1, float *charge2, char *chain, int *color, int *resnum,
 char *resname1, char resname4[MMIO_S_STRLEN+1], char pdbname[MMIO_S_STRLEN+1] )
/*  Get information on the next atom.  mmio_atom is the MacroModel
 *   atom number.
 *  If the preceding mmio_get_ct() returned MMIO_COMPRESSED in its istat
 *   parameter, then mmio_get_atom() only returns values in the following 
 *   arguments:  mmio_atom, xyz, color, and istat.  The remaining arguments
 *   will be untouched by the library;  thus, for example, junk values
 *   variables or constants may be passed as these arguments.
 *  Function arguments:
 *   IDATASET: unique identifier supplied by earlier mmio_open() call
 *   mmio_atom: MacroModel atom number
 *   itype: MacroModel atom type
 *   nbond: number of bonds to this atom
 *   bond_atom: numbers of the first nbond bonded atoms
 *   bond_order: bond orders of the first nbond bonded atoms
 *   xyz: xyz coordinates of this atom
 *   charge1, charge2: the two charge values
 *   chain: PDB chain name
 *   color: MacroModel atom color
 *   resnum: PDB residue number
 *   resname1: 1-character PDB residue name
 *   resname4: 4-character PDB residue name
 *   pdbname: PDB atom name
 *  Return value:
 *   MMIO_OK: for the first natom-1 atoms, if all goes well
 *   MMIO_DONE: for the last atom, if all goes well
 *   MMIO_ERR: if an error occurs
 *  Example: read the next atom:
 *   #include 
 *   int iread, status;
 *   int mmod_iatom;
 *   int itype;
 *   int nbond;
 *   int bond_atom[ MMIO_MAXBOND ];
 *   int bond_order[ MMIO_MAXBOND ];
 *   float xyz[ 3 ];
 *   float charge1;
 *   float charge2;
 *   char chain;
 *   int color;
 *   int resnum;
 *   char resname1;
 *   char resname4[ MMIO_S_STRLEN + 1 ];
 *   char pdbname[ MMIO_S_STRLEN + 1 ];
 *   ...
 *   for( i=0; i
 *   int iread;
 *   int ct_type = MMIO_FULL;
 *   int natom;
 *   int status;
 *   char title[ MMIO_L_STRLEN + 1 ];
 *   ...
 *   status = mmio_put_ct( iwrite, ct_type, natom, title );
 */

int mmio_put_atom( int IDATASET, int MMIO_ATOM, int ITYPE, int NBOND,
 int BOND_ATOM[MMIO_MAXBOND], int BOND_ORDER[MMIO_MAXBOND], float XYZ[3],
 float CHARGE1, float CHARGE2, char CHAIN, int COLOR, int RESNUM, 
 char RESNAME1, char RESNAME4[MMIO_S_STRLEN+1], char PDBNAME[MMIO_S_STRLEN+1] )
/*  Set information for the next atom.  mmio_atom is the MacroModel
 *   atom number.  Return status is normally MMIO_OK until the last atom is
 *   received;  with the last atom's information, istat will be MMIO_DONE.
 *   This function should be called natom times, where natom is the
 *   value passed to the previous mmio_put_ct() call to the same dataset.  
 *   The values of MMIO_ATOM must be in increasing order on successive calls.
 *  If the preceding mmio_put_ct() was passed MMIO_COMPRESSED in its ct_type
 *   parameter, then mmio_put_atom() only reads values from the following 
 *   arguments:  mmio_atom, xyz, and color.  The remaining arguments
 *   will not be referenced by the library;  thus, for example, junk
 *   values or constants may be passed in these arguments.
 *  Function arguments:
 *   IDATASET:		integer returned from a previous MMIO_OPEN/MMIO_WRITE
 *   MMIO_ATOM:		MacroModel atom number of current atom
 *   ITYPE:		MacroModel atom type of current atom
 *   NBOND:		number of bonds to this atom
 *   BOND_ATOM:		atoms bonded to this atom
 *   BOND_ORDER:	bond order of atoms bonded to this atom
 *   XYZ:		coordinates
 *   CHARGE1, CHARGE2:	charge1, charge2 fields in mmod file
 *   CHAIN:		pdb chain name
 *   COLOR:		MacroModel color code
 *   RESNUM:		pdb residue number
 *   RESNAME1:		single-char pdb residue-type code
 *   RESNAME4:		4-char pdb residue-type code
 *   PDBNAME:		pdb atom name
 *  Return value:
 *   MMIO_OK:		call succeeded (first natom-1  calls)
 *   MMIO_DONE:		call succeeded (first natom'th  call)
 *   MMIO_ERR:		call failed
 *  Example: write the next atom:
 *   #include 
 *   int iread, status;
 *   int mmod_iatom;
 *   int itype;
 *   int nbond;
 *   int bond_atom[ MMIO_MAXBOND ];
 *   int bond_order[ MMIO_MAXBOND ];
 *   float xyz[ 3 ];
 *   float charge1;
 *   float charge2;
 *   char chain;
 *   int color;
 *   int resnum;
 *   char resname1;
 *   char resname4[ MMIO_S_STRLEN + 1 ];
 *   char pdbname[ MMIO_S_STRLEN + 1 ];
 *   ...
 *   for( i=0; i
 *  int status;
 *  char message[ MMIO_L_STRLEN + 1 ];
 *  ...
 *  status = mmio_put_ct(...);
 *  printf( "mmio_put_ct() returns %s\n", mmio_return_code(status) );
 */

void mmio_errfile( FILE *FP );
/* Set the file unit to which any detailed error messages generated
 *  by the library will be sent.  This IO-unit should be one previously
 *  opened by the calling application.
 * If never called, error messages are not printed.  If called with NULL,
 *  error reporting is turned off.
 * Function argument:
 *  FP:		file-pointer to open file for error-message reporting
 * Example: turn on logging of MMIO errors to stderr:
 *  #include 
 *  #include 
 *  ...
 *  mmio_errfile( stderr );
 */

V. Examples.

See cmmio.c, a program that uncompresses or copies full or compressed
MacroModel files.  This program is heavily commented, and 
demonstrates how the basic library functionalities are to be used.

See also mmio_convert.c, an application to either compress or uncompress
MacroModel files.  This program, in addition to having capabilities
beyond the basics included in cmmio.c, also has several bells and
whistles (such as verbose output that can be turned on and off) that
make it a better "real-world" example of the use of the library than
is cmmio.c.