CCP4 Coordinate Library Project

Object interface: Reading/Writing Coordinate Files.

Reading/Writing coordinate files are functions of the Library Manager class (CMMDBManager). A typical application would always contain pieces like the following:

//  include the MMDB coordinate Manager file header
#ifndef  __MMDB_Manager__
#include "mmdb_manager.h"
#endif

................................

int           RC;
PCMMDBManager MMDB;

  //  create an instance of MMDB manager -- eesentially an
  //  empty coordinate hierarchy
  MMDB = new CMMDBManager();

  //  read coordinate file
  RC   = ReadCoorFile ( "coorfile.pdb" );
  //  interprete the return code
  if (RC)  {
    ............................
    return Error;
  }

  //  work with coordinates
  ..............................

  //  write coordinate file (if necessary)
  RC =  WritePDBASCII ( "output_coord.pdb" );
  //  interprete the return code
  if (RC)  {
    ............................
    return Error;
  }

The coordinate Manager provides a variety of functions for reading/writing coordinate files, supporting 3 data formats: PDB, mmCIF and Library's internal binary format (referred to as MMDB Binary). At present, mmCIF is supported only partially and does not allow for dynamical use of CIF dictionaries. MMDB Binary format is portable between different platforms. Below we list all functions which relate to reading/writing coordinate files.

Function Purpose
CMMDBManager::ReadCoorFile Reading coordinate files with automatical recognition of file format.
CMMDBManager::ReadCoorFile1 Reading coordinate files with automatical recognition of file format, by logical file name.
CMMDBManager::ReadPDBASCII Reading PDB coordinate files.
CMMDBManager::ReadPDBASCII1 Reading PDB coordinate files, by logical file name.
CMMDBManager::AddPDBASCII Adding data from a PDB coordinate file.
CMMDBManager::AddPDBASCII1 Adding data from a PDB coordinate file, by logical file name.
CMMDBManager::PutPDBString Adding data from a character string.
CMMDBManager::ReadCIFASCII Reading mmCIF coordinate files.
CMMDBManager::ReadCIFASCII1 Reading mmCIF coordinate files, by logical file name.
CMMDBManager::ReadMMDBF Reading MMDB Binary coordinate files.
CMMDBManager::ReadMMDBF1 Reading MMDB Binary coordinate files, by logical file name.
CMMDBManager::GetFileType Retrieves the type (format) of coordinate file that has been read.
isPDB Checking on PDB ASCII files.
isMMDBBIN Checking on MMDB Binary files.
isCIF Checking on mmCIF files.
CMMDBManager::SetFlag Setting flag(s) of extra functionality.
CMMDBManager::RemoveFlag Removing flag(s) of extra functionality.
CMMDBManager::WritePDBASCII Writing PDB coordinate files.
CMMDBManager::WritePDBASCII1 Writing PDB coordinate files, by logical file name.
CMMDBManager::WriteCIFASCII Writing mmCIF coordinate files.
CMMDBManager::WriteCIFASCII1 Writing mmCIF coordinate files, by logical file name.
CMMDBManager::WriteMMDBF Writing MMDB Binary files.
CMMDBManager::WriteMMDBF1 Writing MMDB Binary files, by logical file name.


int CMMDBManager::ReadCoorFile ( 
pstr  FileName )
PURPOSE
Reading coordinate files with automatical recognition of file format.
ARGUMENTS
pstr FileName
Name of file to be read.

DESCRIPTION

The coordinate file is read, the coordinate hierarchy is created and stored permanently in memory. Any data existing in the hierarchy before the reading, is automatically disposed.

The function automatically recognizes between PDB, mmCIF and MMDB binary formats. Format of a file that has been read, may be obtained through function CMMDBManager::GetFileType.


RETURN

Upon successful completion, the function returns 0. Non-zero returns indicate a problem, which prevented the Manager from completion the reading. See return codes and way of their handling in Error handling and return codes.


EXAMPLE

The following example reads a coordinate file and checks for errors:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  Location of the error may be identified as precise as line
    //  number and the line itself. This information is now
    //  retrieved from MMDB input buffer:
    MMDB.GetInputBuffer ( S, lcount );
    if (lcount>=0) 
      printf ( "       LINE #%i:\n%s\n\n",lcount,S );
    else if (lcount==-1)
      printf ( "       CIF ITEM: %s\n\n",S );
    exit(1);
  }


int CMMDBManager::ReadCoorFile1 ( 
pstr  LogFileName )
PURPOSE
Reading coordinate files with automatical recognition of file format, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be read. This is a name of environmental variable (e.g. "xyzin"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::ReadCoorFile but takes a logical, rather than physical, name of the file.


int CMMDBManager::ReadPDBASCII ( 
pstr  FileName )
PURPOSE
Reading PDB coordinate files.
ARGUMENTS
pstr FileName
Name of PDB file to be read.

DESCRIPTION

The function is identical to CMMDBManager::ReadCoorFile but reads only PDB coordinate files. Application may check for PDB format prior reading the file through function isPDB.


EXAMPLE

The following example reads a PDB coordinate file and checks for errors:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
  RC = MMDB.ReadPDBASCII ( "pdb1sar.ent" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  Location of the error may be identified as precise as line
    //  number and the line itself. This information is now
    //  retrieved from MMDB input buffer:
    MMDB.GetInputBuffer ( S, lcount );
    if (lcount>=0) 
      printf ( "       LINE #%i:\n%s\n\n",lcount,S );
    exit(1);
  }


int CMMDBManager::ReadPDBASCII1 ( 
pstr  LogFileName )
PURPOSE
Reading PDB coordinate files, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be read. This is a name of environmental variable (e.g. "xyzin"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::ReadPDBASCII but takes a logical, rather than physical, name of the file.


int CMMDBManager::AddPDBASCII ( 
pstr  FileName )
PURPOSE
Adding data from a PDB coordinate file.
ARGUMENTS
pstr FileName
Name of PDB file to be read.

DESCRIPTION

The function is identical to CMMDBManager::ReadPDBASCII, however it does not dispose data, which previously existed in the coordinate hierarchy. The newly read data is appended correspondingly to each item of the hierarchy.

The function is useful for composing a PDB file from parts, e.g. adding the REMARK records, CRYST data, SEQRES etc.. All the data will be put on proper place regardless the order in which the files are read. However the order of reading files will determine the order of records within PDB sections. Thus, for example, addition of two files containing SEQRES records yields two SEQRES blocks placed one after another in the order of their appearance, even if these blocks are identical; in contrary, adding several CRYST cards will leave the latest one only.


EXAMPLE

The following example reads a PDB coordinate file and appends data from another PDB file to it:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
  RC = MMDB.ReadPDBASCII ( "pdb1sar.ent" );
  if (RC) {
    // check for errors
    .........................
    exit(1);
  }
  RC = MMDB.AddPDBASCII ( "add.pdb" );
  if (RC) {
    // check for errors
    .........................
    exit(1);
  }


int CMMDBManager::AddPDBASCII1 ( 
pstr  LogFileName )
PURPOSE
Adding data from a PDB coordinate file, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be read. This is a name of environmental variable (e.g. "xyzin"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::AddPDBASCII but takes a logical, rather than physical, name of the file.


int CMMDBManager::PutPDBString ( 
pstr  PDBString )
PURPOSE
Adding data from a character string.
ARGUMENTS
pstr PDBString
A character string formatted as a valid PDB record.

DESCRIPTION

The function adds data from a single PDB record, given as a character string PDBString, to the coordinate hierarchy. The string is namely added, which means that it will be interpreted like a last string in its group, e.g. last "REMARK", last "JRNL", last "ATOM" etc. according to the PDB keyword found in it.


RETURN

The function returns the same codes as CMMDBManager::ReadPDBASCII.


EXAMPLE

The following example is identical to that given for CMMDBManager::AddPDBASCII but less efficient:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
CFile        f;
  RC = MMDB.ReadPDBASCII ( "pdb1sar.ent" );
  if (RC) {
    // check for errors
    .........................
    exit(1);
  }
  RC = isPDB ( "add.pdb" );
  if (RC<0)  {
    printf ( " file 'add.pdb' does not exist\n" );
    exit(2);
  }
  if (RC>0)  {
    printf ( " file 'add.pdb' is not a PDB file\n" );
    exit(3);
  }
  f.assign ( "add.pdb" );
  if (f.reset())  {
    RC = 0;
    while ((!f.FileEnd()) && (!RC))  {
      f.ReadLine ( S,sizeof(S) );
      RC = MMDB.PutPDBString ( S );
    }
    f.shut();
    if (RC) {
      // check for errors
      .........................
      exit(4);
    }
  } else
    printf ( " can't open file 'add.pdb'\n" );


int CMMDBManager::ReadCIFASCII ( 
pstr  FileName )
PURPOSE
Reading mmCIF coordinate files.
ARGUMENTS
pstr FileName
Name of mmCIF file to be read.

DESCRIPTION

The function is identical to CMMDBManager::ReadCoorFile but reads only mmCIF coordinate files. Application may check for CIF format prior reading the file through function isCIF.


EXAMPLE

The following example reads a mmCIF coordinate file and checks for errors:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
  RC = MMDB.ReadCIFASCII ( "amylase.mmcif" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  Location of the error may be identified as precise as line
    //  number and the line itself. This information is now
    //  retrieved from MMDB input buffer:
    MMDB.GetInputBuffer ( S, lcount );
    if (lcount>=0) 
      printf ( "       LINE #%i:\n%s\n\n",lcount,S );
    else if (lcount==-1)
      printf ( "       CIF ITEM: %s\n\n",S );
    exit(1);
  }


int CMMDBManager::ReadCIFASCII1 ( 
pstr  LogFileName )
PURPOSE
Reading mmCIF coordinate files, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be read. This is a name of environmental variable (e.g. "xyzin"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::ReadCIFASCII but takes a logical, rather than physical, name of the file.


int CMMDBManager::ReadMMDBF ( 
pstr  FileName )
PURPOSE
Reading MMDB Binary coordinate files.
ARGUMENTS
pstr FileName
Name of MMDB Binary file to be read.

DESCRIPTION

The function is identical to CMMDBManager::ReadCoorFile but reads only MMDB Binary coordinate files. Application may check for MMDB Binary format prior reading the file through function isMMDBBIN.

NOTE : MMDB Binary files cannot be edited, therefore no sensible identification of read errors is provided. Neglecting mistakes in the Library, errors at reading a MMDB Binary file may appear only if the file is corrupted.


EXAMPLE

The following example reads a MMDB Binary coordinate file and checks for errors:

CMMDBManager MMDB;
int          RC;
  RC = MMDB.ReadMMDBF ( "coor.mmdb" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  no further identification of the error may be given
    exit(1);
  }


int CMMDBManager::ReadMMDBF1 ( 
pstr  LogFileName )
PURPOSE
Reading MMDB Binary coordinate files, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be read. This is a name of environmental variable (e.g. "xyzin"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::ReadMMDBF but takes a logical, rather than physical, name of the file.


int CMMDBManager::GetFileType ( 
 )
PURPOSE
Retrieves the type (format) of coordinate file that has been read.
DESCRIPTION

This function is useful when coordinate file is read with automatical format recognition (cf. CMMDBManager::ReadCoorFile).


RETURN

The function returns one of the following codes:
Code Value Description
MMDB_FILE_Undefined -1 No file has been read
MMDB_FILE_PDB 0 A PDB file has been read
MMDB_FILE_CIF 1 A mmCIF file has been read
MMDB_FILE_Binary 2 A MMDB Binary file has been read


EXAMPLE

The following example reads a coordinate file and checks for its format after reading:

CMMDBManager MMDB;
int          RC;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC) {
    // check for errors
    ...................
    exit ( 1 );
  }
  // report format of the file
  switch (MMDBManager->GetFileType())  {
    case MMDB_FILE_PDB    : printf ( " PDB"         );  break;
    case MMDB_FILE_CIF    : printf ( " mmCIF"       );  break;
    case MMDB_FILE_Binary : printf ( " MMDB binary" );  break;
    default : printf ( " Unknown (report as a bug!)" );
  }
  printf ( " file %s has been read in.\n",CoorFileName );


int isPDB ( 
pstr  FileName )
PURPOSE
Checking on PDB ASCII files.
ARGUMENTS
pstr FileName
Name of file to check on.

DESCRIPTION

The function makes a very fast check on whether FileName is a PDB ASCII file or not. No coordinate information is read.


RETURN

The function returns one of the following codes:
-1 if file FileName does not exist
0 if file FileName is likely a PDB file
1 if file FileName is not a PDB file.


int isMMDBBIN ( 
pstr  FileName )
PURPOSE
Checking on MMDB Binary files.
ARGUMENTS
pstr FileName
Name of file to check on.

DESCRIPTION

The function makes a very fast check on whether FileName is a MMDB Binary file or not. No coordinate information is read.


RETURN

The function returns one of the following codes:
-1 if file FileName does not exist
0 if file FileName is likely a MMDB Binary file
1 if file FileName is not a MMDB Binary file.
2 if file FileName is likely a MMDB Binary file but of a wrong edition (produced by Coordinate Library of a higher version).


int isCIF ( 
pstr  FileName )
PURPOSE
Checking on mmCIF files.
ARGUMENTS
pstr FileName
Name of file to check on.

DESCRIPTION

The function makes a very fast check on whether FileName is a mmCIF file or not. No coordinate information is read.


RETURN

The function returns one of the following codes:
-1 if file FileName does not exist
0 if file FileName is likely a mmCIF file
1 if file FileName is not a mmCIF file.


void CMMDBManager::SetFlag ( 
word  flag )
PURPOSE
Setting flag(s) of extra functionality.
ARGUMENTS
word flag
The flag(s) to be set.

DESCRIPTION

Flags of extra functionality affect behavior of different Library functions. Several flags may be set up at once using the bitwise "or" ("|") operation. The following flags are defined:
Flag Hexagonal Value Description
MMDBF_AutoSerials 0x00000001 enforcing the serial numbers of atoms in Coordinate Section at reading a PDB file. Many PDB files violate requirement for strictly incremental order of serial numbers of atoms. Although such PDB files may be handled painlessly by Library, setting up this flag will assure that serial numbers of atoms will comply with PDB requirements.
MMDBF_NoCoordRead 0x00000002 ignoring the coordinates at reading coordinate file. This may save time if information from only file header is required.
MMDBF_SimRWBROOK 0x00000004 simulating messages, which were issuing by former RWBROOK interface at reading PDB file.
MMDBF_PrintCIFWarnings 0x00000008 enforcing printout of all warning messages at reading mmCIF coordinate files. Normally coordinate files are read silently, and all warnings are reported through return code. Setting this flag on will make Library to print all warning messages immediately on discovering a potential problem. This may give better identification of the problem(s) in certain cases.
MMDBF_EnforceSpaces 0x00000010 replacing unprintable characters for spaces at ASCII coordinate files. This affects symbols with decimal code less than 32 (<SPACE>), excluding <TAB>, <LF> and <CR>.
MMDBF_IgnoreDuplSeqNum 0x00000020 ignoring duplicate sequence numbers and insertion codes for different residues. In a correct PDB file, each residue should have a unique combination of sequence number and insertion code. This rule is sometimes violated for heterogroups. Setting this flag On switches off checking for unique sequence number and insertion code.
MMDBF_IgnoreSegID 0x00000040 ignoring different segment IDs met on different PDB records such as "ANISOU" that belong to the same atom. In a correct PDB file, this redundant information should be kept identical on all records belonging to the same file. Some programs violate this rule, hence there is an option to set this flag on.
MMDBF_IgnoreElement 0x00000080 ignoring different element names met on different PDB records such as "ANISOU" that belong to the same atom. In a correct PDB file, this redundant information should be kept identical on all records belonging to the same file. Some programs violate this rule, hence there is an option to set this flag on.
MMDBF_IgnoreCharge 0x00000100 ignoring different charges met on different PDB records such as "ANISOU" that belong to the same atom. In a correct PDB file, this redundant information should be kept identical on all records belonging to the same file. Some programs violate this rule, hence there is an option to set this flas on.


void CMMDBManager::RemoveFlag ( 
word  flag )
PURPOSE
Removing flag(s) of extra functionality.
ARGUMENTS
word flag
The flag(s) to be removed.

DESCRIPTION

Flags of extra functionality affect behavior of different Library functions. Several flags may be removed at once using the bitwise "or" ("|") operation. The list of defined flags is found above.


int CMMDBManager::WritePDBASCII ( 
pstr  FileName )
PURPOSE
Writing PDB coordinate files.
ARGUMENTS
pstr FileName
Name of PDB file to be written.

DESCRIPTION

The function outputs data from coordinate hierarchy as a PDB file. Only data which may be expressed in PDB terms is output. The data in the hierarchy does not change.


RETURN

Upon successful completion, the function returns 0. Non-zero returns indicate a problem, which prevented the Manager from completion the writing. See return codes and way of their handling in Error handling and return codes.


EXAMPLE

The following example reads mmCIF coordinate file and writes it back as a PDB file:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
  RC = MMDB.ReadCIFASCII ( "amylase.mmcif" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  Location of the error may be identified as precise as line
    //  number and the line itself. This information is now
    //  retrieved from MMDB input buffer:
    MMDB.GetInputBuffer ( S, lcount );
    if (lcount>=0) 
      printf ( "       LINE #%i:\n%s\n\n",lcount,S );
    else if (lcount==-1)
      printf ( "       CIF ITEM: %s\n\n",S );
    exit(1);
  }
  RC = MMDB.WritePDBASCII ( "amylase.pdb" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i WRITE:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    exit(2);
  }


int CMMDBManager::WritePDBASCII1 ( 
pstr  LogFileName )
PURPOSE
Writing PDB coordinate files, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be written. This is a name of environmental variable (e.g. "xyzout"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::WritePDBASCII but takes a logical, rather than physical, name of the file.


int CMMDBManager::WriteCIFASCII ( 
pstr  FileName )
PURPOSE
Writing mmCIF coordinate files.
ARGUMENTS
pstr FileName
Name of mmCIF file to be written.

DESCRIPTION

The function outputs data from coordinate hierarchy as a mmCIF file. Only data which may be expressed in predefined mmCIF terms is output. "Predefined mmCIF terms" basically include data set, which is equivalent to that of PDB. The data in the hierarchy does not change.


RETURN

Upon successful completion, the function returns 0. Non-zero returns indicate a problem, which prevented the Manager from completion the writing. See return codes and way of their handling in Error handling and return codes.


EXAMPLE

The following example reads a PDB coordinate file and writes it back as a mmCIF file:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
  RC = MMDB.ReadPDBASCII ( "pdb1sar.ent" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  Location of the error may be identified as precise as line
    //  number and the line itself. This information is now
    //  retrieved from MMDB input buffer:
    MMDB.GetInputBuffer ( S, lcount );
    if (lcount>=0) 
      printf ( "       LINE #%i:\n%s\n\n",lcount,S );
    exit(1);
  }
  RC = MMDB.WriteCIFASCII ( "1sar.mmcif" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i WRITE:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    exit(2);
  }


int CMMDBManager::WriteCIFASCII1 ( 
pstr  LogFileName )
PURPOSE
Writing mmCIF coordinate files, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be written. This is a name of environmental variable (e.g. "xyzout"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::WriteCIFASCII but takes a logical, rather than physical, name of the file.


int CMMDBManager::WriteMMDBF ( 
pstr  FileName )
PURPOSE
Writing MMDB Binary files.
ARGUMENTS
pstr FileName
Name of MMDB Binary file to be written.

DESCRIPTION

The function outputs data from coordinate hierarchy as a mmCIF file. All data which is contained in the hierarchy is output. The data in the hierarchy does not change.


RETURN

Upon successful completion, the function returns 0. Non-zero returns indicate a problem, which prevented the Manager from completion the writing. See return codes and way of their handling in Error handling and return codes.


EXAMPLE

The following example reads a PDB coordinate file and writes it back as MMDB Binary file:

CMMDBManager MMDB;
int          RC,lcount;
char         S[500];
  RC = MMDB.ReadPDBASCII ( "pdb1sar.ent" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  Location of the error may be identified as precise as line
    //  number and the line itself. This information is now
    //  retrieved from MMDB input buffer:
    MMDB.GetInputBuffer ( S, lcount );
    if (lcount>=0) 
      printf ( "       LINE #%i:\n%s\n\n",lcount,S );
    exit(1);
  }
  RC = MMDB.WriteMMDBF ( "1sar.mmdb" );
  if (RC) {
    //  An error was encountered. MMDB provides an error messenger
    //  function for easy error message printing.
    printf ( " ***** ERROR #%i WRITE:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    exit(2);
  }


int CMMDBManager::WriteMMDBF1 ( 
pstr  LogFileName )
PURPOSE
Writing MMDB Binary files, by logical file name.
ARGUMENTS
pstr LogFileName
Logical name of file to be written. This is a name of environmental variable (e.g. "xyzout"), whose value is physical name of the file.

DESCRIPTION

The function is completely similar to CMMDBManager::WriteMMDBF but takes a logical, rather than physical, name of the file.



Back to index