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;
}
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 ) |
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.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.
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 ) |
The function is completely similar to CMMDBManager::ReadCoorFile but takes a logical, rather than physical, name of the file.
int CMMDBManager::ReadPDBASCII ( |
pstr FileName ) |
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.
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 ) |
The function is completely similar to CMMDBManager::ReadPDBASCII but takes a logical, rather than physical, name of the file.
int CMMDBManager::AddPDBASCII ( |
pstr FileName ) |
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.
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 ) |
The function is completely similar to CMMDBManager::AddPDBASCII but takes a logical, rather than physical, name of the file.
int CMMDBManager::PutPDBString ( |
pstr PDBString ) |
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.
The function returns the same codes as CMMDBManager::ReadPDBASCII.
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 ) |
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.
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 ) |
The function is completely similar to CMMDBManager::ReadCIFASCII but takes a logical, rather than physical, name of the file.
int CMMDBManager::ReadMMDBF ( |
pstr FileName ) |
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.
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 ) |
The function is completely similar to CMMDBManager::ReadMMDBF but takes a logical, rather than physical, name of the file.
int CMMDBManager::GetFileType ( |
) |
This function is useful when coordinate file is read with automatical format recognition (cf. CMMDBManager::ReadCoorFile).
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 |
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 ) |
The function makes a very fast check on whether FileName is a PDB ASCII file or not. No coordinate information is read.
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 ) |
The function makes a very fast check on whether FileName is a MMDB Binary file or not. No coordinate information is read.
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 ) |
The function makes a very fast check on whether FileName is a mmCIF file or not. No coordinate information is read.
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 ) |
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 ) |
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 ) |
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.
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.
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 ) |
The function is completely similar to CMMDBManager::WritePDBASCII but takes a logical, rather than physical, name of the file.
int CMMDBManager::WriteCIFASCII ( |
pstr FileName ) |
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.
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.
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 ) |
The function is completely similar to CMMDBManager::WriteCIFASCII but takes a logical, rather than physical, name of the file.
int CMMDBManager::WriteMMDBF ( |
pstr FileName ) |
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.
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.
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 ) |
The function is completely similar to CMMDBManager::WriteMMDBF but takes a logical, rather than physical, name of the file.