CCP4 Coordinate Library Project

Object interface: Surfing the coordinate hierarchy.

The Library offers variety of tools for surfing the coordinate hierarchy. Any model, chain, residue or atom may be addressed directly using either characteristics like model number, chain ID, sequence number etc., or a special path string - the "coordinate ID" (CID), or by looking up the hierarchy's internal tables. Different methods provide different flexibility and efficiency. In general, access through internal tables is the most efficient one, while using the coordinate ID provides for maximum flexibility.

COMMON NOTATIONS

Coordinate ID
Coordinate ID is an ASCII string having the following format:
      /mdl/chn/seq(res).ic/atm[elm]:aloc
      
where
Item   Type   Description
mdl   integer   the number of model
chn   character string   chain ID
seq   integer   residue sequence number
res   character string   residue name
ic   character string   residue insertion code
atm   character string   atom name
elm   character string   chemical element ID
aloc   character string   alternative location indicator

All spaces in cooridnate ID are ignored. This means that certain atom names may be interpreted correctly only if chemical element name is supplied (compare Calcium CA[CA] and Carbon in alpha-position CA[C]). The residue name represents a redundant information if sequence number and a non-wildcard insertion code is specified.

Any item in coordinate ID may be replaced by a wildcard "*", which means indefinite value for that item. The wildcard value is automatically implied for any missing item except the chain ID, insertion code and alternative location indicator:

  • Missing chain ID is interpreted as empty ID "" if there is a slash "/" after it. In all other cases, missing chain ID is interpreted as a wildcard "*".
  • Missing insertion code is interpreted as a wildcard "*" if the residue sequence number is not specified or set to a wildcard. In all other cases, missing insertion code is interpreted as "" ('no insertion code').
  • Missing alternative location indicator is defaulted to a wildcard "*" if no atom name or chemical element name is given. If any value for atom and/or chemical element name, even though a wildcard, is provided, missing alternative location indicator is defaulted to "" ('no alternative location indicator').

A coordinate ID may be incomplete. Below are the rules for interpretation of incomplete IDs. Curling brackets {..} denote parts of ID string that may be omitted as a whole:

  1. If ID starts with slash "/" then it is interpreted as
          /mdl { /chn { /seq(res).ic { /atm[elm]:aloc }}}
                
  2. If ID starts with a letter:
                  chn { /seq(res).ic { /atm[elm]:aloc }}
                
  3. If ID starts with a (possibly negative) number, bracket "(" or dot ".":
                         seq(res).ic { /atm[elm]:aloc }
                
  4. If none of previous applies but ID string contains square bracket "[" or colon ":", it is interpreted as
                                        atm[elm]:aloc
                
Below are examples of valid coordinate IDs:

Coordinate ID   Description
/1/A/33(SER).B/CA[C].A   model 1, chain A, residue SER with sequence number 33 and insertion code B, C-alpha atom in alternative location A.
/1/A/*(SER).*   any SER residue in chain A, model 1.
/1/A/(SER)   any SER residue with no insertion code in chain A, model 1.
/1//(SER)   any SER residue with no insertion code in chain without a chain ID, model 1.
/1/A/*.*/CA[C]   any C-alpha atom with no alternative location indicator in chain A, model 1, in residues with any sequence number and insertion code.
/1/A/*/CA[C]   any C-alpha atom with no alternative location indicator in chain A, model 1, in residues with any sequence number and no insertion code.
A/*/CA   any C-alpha or Calcium atom with no alternative location indicator in chain A of any model, in residues with any sequence number and no insertion code.
CA[C]   any C-alpha atom with no alternative location indicator in any chain, any model, in residues with any sequence number and no insertion code.
CA   any atom of chain CA with no alternative location indicator, in any model, in residues with any sequence number and no insertion code.

The following coordinate IDs are incorrect:
  1.   /A/23/CA[C]
  2.   /1/CG[C]
  3.   /-15
  4.   */*(*).*/*[*]:*
      
In the present realization, the CID-using functions will not always recognize the incorrect coordinate IDs. For instance, for the incorrect IDs exampled above, the answers would be
  1. wrong numerical format for model number
  2. Ok, model 1, chain CG, item [C] is not interpreted
  3. Ok, model number is set to -15
  4. Ok, an empty coordinate ID.

If a CID-using function fails because of a wrong coordinate ID, the reason may be learnt from analysing the public CMMDBManager::CoorIDCode integer variable. If may take the following values:
Code Value Description
CID_Ok 0 no problem
CID_NoModel 1 model not found
CID_NoChain 2 chain not found
CID_NoResidue 3 residue not found
CID_NoAtom 4 atom not found
CID_WrongPath 5 the coordinate ID is incorrect

Default Coordinate ID
An application may set a default coordinate ID, which may be any valid, complete or incomplete ID. If a function needs a complete ID and incomplete one is supplied, the function will try to recover the missing items from the default CID. Here we don't imply analogy with a hierarchical file system. If the supplied CID has wildcard for sequence number, it will attempt to substitute it with that from default CID even if model number and/or chain ID differ.

Addressing by Coordinate ID
The following example demonstrates addressing to a residue by its coordinate ID (CID). The CID may be specified either as a string or as a set of CID items:
CMMDBManager MMDB;
int          RC;
PCResidue    res1,res2;

  // read coordinate file
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC) {
    .. checking for errors
    exit(1);
  }

  // get residue 34.B of chain A model 1 in way #1
  res1 = MMDB.GetResidue ( "/1/A/34.B" );

  // the same operation in way #2
  res2 = MMDB.GetResidue ( 1,"A",34,"B" );
Similar approach is used for getting models, chains and atoms. The models, chains and residues have similar functions for addressing the objects that they incapsulate.

Addressing in way #2 is slightly more efficient than that in way #1. Evidently way #2 is more convenient for a programmer, and way #1 is more natural for an interactive user (although it may be chosen by programmers as well). However, both of them bear overhead of decoding the coordinate ID and therefore they are recommended only for addressing individual objects. If an application needs to address objects in series (e.g. to perform a loop over all atoms in a given chain), the most efficient way to do that is through using the internal tables.

Addressing through internal tables
The following example demonstrates addressing to all atoms of model 1 using the internal tables:
CMMDBManager MMDB;
int          RC;
int          nChains,nResidues,nAtoms;
PPCChain     chain;
PPCResidue   res;
PPCAtom      atom;

  // read coordinate file
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC) {
    .. checking for errors
    exit(1);
  }

  //  get chain table of model 1
  MMDB.GetChainTable ( 1,chain,nChains );

  //  loop over all chains:
  for (i=0;i<nChains;i++)
    if (chain[i])  {
      // get residue table for current chain:
      chain[i]->GetResidueTable ( res,nResidues );
      // loop over all residues in current chain:
      for (j=0;j<nResidues;j++)
        if (res[j])  {
          // get atom table for current residue:
          res[j]->GetAtomTable ( atom,nAtoms );
          // loop over all atoms in current residue
          for (k=0;k<nAtoms;k++)
            if (atom[k])  {
              // doing something with atom, e.g.
              if (atom[k]->Ter)  printf ( "TER\n" );
              else {
                if (atom[k]->Het) printf ( "HETATM  " );
                             else printf ( "ATOM    " );
                printf ( " %10.4f %10.4f %10.4f\n",
                         atom[k]->x,atom[k]->y,atom[k]->z );
              }
            }
        }
    }

Addressing through internal tables provides for maximal efficiency achievable in MMDB. Each level of coordinate hierarchy has its own tables and functions for addressing them as well as functions for addressing the lower-level tables. Thus, in the example above,
      chain[i]->GetResidueTable ( res,nResidues );
      res[j]->GetAtomTable ( atom,nAtoms );
      
could be changed for
      MMDB.GetResidueTable ( 1,chain[i]->GetChainID(),res,nResidues );
      MMDB.GetAtomTable    ( 1,chain[i]->GetChainID(),
                             res[j]->GetSeqNum(),res[j]->GetInsCode(),
                             atom,nAtoms );
      
or even more simpler
      MMDB.GetResidueTable ( 1,i,res,nResidues );
      MMDB.GetAtomTable    ( 1,i,j,atom,nAtoms );
      
however such replacements are less efficient. The functions for addressing the lower-level tables come however handy if table of an individual object (e.g. a residue) needs to be retrieved. In this section, we consider only addressing capabilities of MMDB Manager. Addressing tools of other objects are discussed in other relevant sections.

It is important to remember that internal tables should never be deallocated, allocated or otherwise modified by application. Violation of this requirement will cause a major crash. The same restriction applies to all pointers on models, chains, residues and atoms that are obtained with functions described below.

 

 

Function Purpose
CMMDBManager::SetDefaultCoordID Setting a default coordinate ID
CMMDBManager::GetNumberOfModels Obtaining the number of models in the coordinate hierarchy.
CMMDBManager::GetModel Obtaining a model pointer by model number.
CMMDBManager::GetModel Obtaining a model pointer by coordinate ID.
CMMDBManager::GetModelTable Obtaining the model table.
CMMDBManager::GetNumberOfChains Obtaining the number of chains in a model by model number.
CMMDBManager::GetNumberOfChains Obtaining the number of chains in a model by coordinate ID.
CMMDBManager::GetChain Obtaining a chain pointer by model number and chain ID.
CMMDBManager::GetChain Obtaining a chain pointer by model number and chain number.
CMMDBManager::GetChain Obtaining a chain pointer by coordinate ID.
CMMDBManager::GetChainTable Obtaining the chain table by model number.
CMMDBManager::GetChainTable Obtaining the chain table by coordinate ID.
CMMDBManager::GetNumberOfResidues Obtaining the number of residues in a chain by model number and chain ID.
CMMDBManager::GetNumberOfResidues Obtaining the number of residues in a chain by model number and chain number.
CMMDBManager::GetNumberOfResidues Obtaining the number of residues in a chain by coordinate ID.
CMMDBManager::GetResidue Obtaining a residue pointer by model number, chain ID, sequence number and insertion code.
CMMDBManager::GetResidue Obtaining a residue pointer by model number, chain number, sequence number and insertion code.
CMMDBManager::GetResidue Obtaining a residue pointer by model number, chain ID and residue number.
CMMDBManager::GetResidue Obtaining a residue pointer by model number, chain number and residue number.
CMMDBManager::GetResidue Obtaining a residue pointer by coordinate ID.
CMMDBManager::GetResidueNo Obtaining a residue position in chain by model number, chain ID, residue sequence number and insertion code.
CMMDBManager::GetResidueNo Obtaining a residue position in chain by model number, chain number, residue sequence number and insertion code.
CMMDBManager::GetResidueTable Obtaining the residue table by model number and chain ID.
CMMDBManager::GetResidueTable Obtaining the residue table by model number and chain number.
CMMDBManager::GetResidueTable Obtaining the residue table by coordinate ID.
CMMDBManager::GetNumberOfAtoms Obtaining the total number of atoms in coordinate hierarchy.
CMMDBManager::GetNumberOfAtoms Obtaining the number of atoms in a residue by model number, chain ID, sequence number and insertion code.
CMMDBManager::GetNumberOfAtoms Obtaining the number of atoms in a residue by model number, chain number, sequence number and insertion code.
CMMDBManager::GetNumberOfAtoms Obtaining the number of atoms in a residue by model number, chain ID and residue number.
CMMDBManager::GetNumberOfAtoms Obtaining the number of atoms in a residue by model number, chain number and residue number.
CMMDBManager::GetNumberOfAtoms Obtaining the number of atoms in a residue by coordinate ID.
CMMDBManager::GetAtomI Obtaining an atom pointer by its absolute number in coordinate hierarchy.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain ID, sequence number, insertion code and atom name.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain ID, sequence number, insertion code and atom number.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain ID, residue number and atom name.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain ID, residue number and atom number.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain number, sequence number, insertion code and atom name.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain number, sequence number, insertion code and atom number.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain number, residue number and atom name.
CMMDBManager::GetAtom Obtaining an atom pointer by model number, chain number, residue number and atom number.
CMMDBManager::GetAtom Obtaining an atom pointer by coordinate ID.
CMMDBManager::GetAtomTable Obtaining the atom table of all atoms in coordinate hierarchy.
CMMDBManager::GetAtomTable Obtaining the atom table by model number, chain ID, sequence number and insertion code.
CMMDBManager::GetAtomTable Obtaining the atom table by model number, chain ID and residue number.
CMMDBManager::GetAtomTable Obtaining the atom table by model number, chain number, sequence number and insertion code.
CMMDBManager::GetAtomTable Obtaining the atom table by model number, chain number and residue number.
CMMDBManager::GetAtomTable Obtaining the atom table by coordinate ID.


int CMMDBManager::SetDefaultCoordID ( 
pstr  CID )
PURPOSE
Setting a default coordinate ID
ARGUMENTS
pstr CID
A string of coordinate ID. The CID must be of valid syntax but may be incomplete.

DESCRIPTION

The function analyses the coordinate ID and stores it for future use. If an incomplete CID is then supplied to another CID-using function, it will try to get it complete by adding the missing items from the default CID. To disable this mechanism, simply call SetDefaultCoordID ( "" )


RETURN

The function returns:
0   - success
-1   - wrong numerical format for model number
-2   - wrong numerical format for sequence number

NOTE : The function performs no checks on the actual presence of items of given CID in the coordinate hierarchy.


int CMMDBManager::GetNumberOfModels ( 
 )
PURPOSE
Obtaining the number of models in the coordinate hierarchy.
DESCRIPTION

The function returns the number of models currently contained in the coordinate hierarchy.


PCModel CMMDBManager::GetModel ( 
int  modelNo )
PURPOSE
Obtaining a model pointer by model number.
ARGUMENTS
int modelNo
The model number. Models are numbered from 1 on.

DESCRIPTION

The function returns pointer on the model having the specified model number. If model with such a number does not exist, the function returns NULL.


PCModel CMMDBManager::GetModel ( 
pstr  CID )
PURPOSE
Obtaining a model pointer by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

DESCRIPTION

The function returns pointer on the model answering the specified coordinate ID. If the provided CID does not specify a particular model (e.g. it has a wildcard for model) or if such a model does not exist in the coordinate hierarchy, the function returns NULL.


void CMMDBManager::GetModelTable ( 
PPCModel &  modelTable, 
int & NumberOfModels )
PURPOSE
Obtaining the model table.
ARGUMENTS
PPCModel & modelTable
The table of models.

int & NumberOfModels
The number of models.

DESCRIPTION

The function returns table of pointers on all models currently contained in the coordinate hierarchy, and their number. The models are assigned numbers from 1 to NumberOfModels, however they are indexed as 0..NumberOfModels-1 in the table.

NOTE 1: Certain editing operations might leave models empty. This results in empty cells in the model table. Therefore, it is a good practice for application to check that, for ith model, modelTable[i-1] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the model table.


int CMMDBManager::GetNumberOfChains ( 
int  modelNo )
PURPOSE
Obtaining the number of chains in a model by model number.
ARGUMENTS
int modelNo
The model number.

DESCRIPTION

The function returns the number of chains currently contained in the specified model of coordinate hierarchy. If the specified model number is invalid, the function returns 0.


int CMMDBManager::GetNumberOfChains ( 
pstr  CID )
PURPOSE
Obtaining the number of chains in a model by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

DESCRIPTION

The function returns the number of chains currently contained in the model of coordinate hierarchy answering to the specified CID. If the model number derived from CID is invalid (e.g. CID contains a wildcard for the model number), the function returns 0.


PCChain CMMDBManager::GetChain ( 
int  modelNo, 
ChainID chainID )
PURPOSE
Obtaining a chain pointer by model number and chain ID.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

DESCRIPTION

The function returns pointer on the chain with given chain ID in the specified model. If such a chain or model does not exist, the function returns NULL.


PCChain CMMDBManager::GetChain ( 
int  modelNo, 
int chainNo )
PURPOSE
Obtaining a chain pointer by model number and chain number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number.

DESCRIPTION

The function returns pointer on the chain that has the specified number in the given model. In a model, the chains are numbered as 0..NumberOfChains-1, where NumberOfChains is returned by CMMDBManager::GetNumberOfChains. If such a chain or model does not exist, the function returns NULL.

The chain number is defined by the order of the chain appearance in the coordinate file. Certain sections of PDB file (e.g. the SEQRES records) may in practice mention the chains in arbitrary order, but it is the order of chains in the coordinate section that matters here.


PCChain CMMDBManager::GetChain ( 
pstr  CID )
PURPOSE
Obtaining a chain pointer by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

DESCRIPTION

The function returns pointer on the chain answering the specified coordinate ID. If the provided CID does not specify a particular model and/or chain (e.g. it has a wildcard for chain), or if such model and/or chain does not exist in the coordinate hierarchy, the function returns NULL.


void CMMDBManager::GetChainTable ( 
int  modelNo, 
PPCChain & chainTable,
int & NumberOfChains )
PURPOSE
Obtaining the chain table by model number.
ARGUMENTS
int modelNo
The model number.

PPCChain & chainTable
The table of chains.

int & NumberOfChains
The number of chains.

DESCRIPTION

The function returns table of pointers on all chains currently contained in the specified model, and their number. The chains are indexed as 0..NumberOfChains-1 in the table.

If the specified model does not exist, the function returns NULL for chainTable and 0 for NumberOfChains.

NOTE 1: Certain editing operations might leave chains empty. This results in empty cells in the chain table. Therefore, it is a good practice for application to check that chainTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the chain table.


void CMMDBManager::GetChainTable ( 
pstr  CID, 
PPCChain & chainTable,
int & NumberOfChains )
PURPOSE
Obtaining the chain table by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

PPCChain & chainTable
The table of chains.

int & NumberOfChains
The number of chains.

DESCRIPTION

The function returns table of pointers on all chains currently contained in the CID-specified model, and their number. The chains are indexed as 0..NumberOfChains-1 in the table.

If the provided CID does not specify a particular model (e.g. it has a wildcard for the model number), or the specified model does not exist, the function returns NULL for chainTable and 0 for NumberOfChains.

NOTE 1: Certain editing operations might leave chains empty. This results in empty cells in the chain table. Therefore, it is a good practice for application to check that chainTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the chain table.


int CMMDBManager::GetNumberOfResidues ( 
int  modelNo, 
ChainID chainID )
PURPOSE
Obtaining the number of residues in a chain by model number and chain ID.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

DESCRIPTION

The function returns the number of residues currently contained in the specified chain and model of coordinate hierarchy. If the specified model number is invalid or the chain is not found in the model, the function returns 0.


int CMMDBManager::GetNumberOfResidues ( 
int  modelNo, 
int chainNo )
PURPOSE
Obtaining the number of residues in a chain by model number and chain number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

DESCRIPTION

The function returns the number of residues currently contained in the specified chain and model of coordinate hierarchy. If the specified model number or chain number is invalid, the function returns 0.


int CMMDBManager::GetNumberOfResidues ( 
pstr  CID )
PURPOSE
Obtaining the number of residues in a chain by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

DESCRIPTION

The function returns the number of residues currently contained in chain answering to the specified CID. If the chain ID or model number derived from CID is invalid (e.g. CID contains a wildcard for the model number or chain ID), the function returns 0.


PCResidue CMMDBManager::GetResidue ( 
int  modelNo, 
ChainID chainID,
int seqNo,
InsCode insCode )
PURPOSE
Obtaining a residue pointer by model number, chain ID, sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns pointer on the residue identified by sequence number, insertion code, chain ID and model number. If any of these characteristics is invalid, or such a residue does not exist in the coordinate hierarchy, the function returns NULL.


PCResidue CMMDBManager::GetResidue ( 
int  modelNo, 
int chainNo,
int seqNo,
InsCode insCode )
PURPOSE
Obtaining a residue pointer by model number, chain number, sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns pointer on the residue identified by sequence number, insertion code, chain number (within a model) and model number. If such a model, chain or residue does not exist, the function returns NULL.


PCResidue CMMDBManager::GetResidue ( 
int  modelNo, 
ChainID chainID,
int resNo )
PURPOSE
Obtaining a residue pointer by model number, chain ID and residue number.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns pointer on the residue identified by the residue number (within the chain), chain ID and model number. If such a model, chain or residue does not exist, the function returns NULL.


PCResidue CMMDBManager::GetResidue ( 
int  modelNo, 
int chainNo,
int resNo )
PURPOSE
Obtaining a residue pointer by model number, chain number and residue number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns pointer on the residue identified by residue number (within a chain), chain number (within a model) and model number. If such a model, chain or residue does not exist, the function returns NULL.


PCResidue CMMDBManager::GetResidue ( 
pstr  CID )
PURPOSE
Obtaining a residue pointer by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

DESCRIPTION

The function returns pointer on the residue answering the specified coordinate ID. If the provided CID does not specify a particular model, chain or residue (e.g. it has a wildcard for chain), or if such model, chain or residue does not exist in the coordinate hierarchy, the function returns NULL.


int CMMDBManager::GetResidueNo ( 
int  modelNo, 
ChainID chainID,
int seqNo,
InsCode insCode )
PURPOSE
Obtaining a residue position in chain by model number, chain ID, residue sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns the residue position (residue number) in the specified chain of the specified model. The residues in a chain are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues.


RETURN

Return Value Description
>=0 Ok - the residue number
-1 residue with given sequence number and insertion code does not exist in the chain
-2 chain with given ID does not exist in the model
-3 incorrect model number


int CMMDBManager::GetResidueNo ( 
int  modelNo, 
int chainNo,
int seqNo,
InsCode insCode )
PURPOSE
Obtaining a residue position in chain by model number, chain number, residue sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns the residue position (residue number) in the specified chain of the specified model. The residues in a chain are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues.


RETURN

Return Value Description
>=0 Ok - the residue number
-1 residue with given sequence number and insertion code does not exist in the chain
-2 incorrect chain number
-3 incorrect model number


void CMMDBManager::GetResidueTable ( 
int  modelNo, 
ChainID chainID,
PPCResidue & resTable,
int & NumberOfResidues )
PURPOSE
Obtaining the residue table by model number and chain ID.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

PPCResidue & resTable
The table of residues.

int & NumberOfResidues
The number of residues.

DESCRIPTION

The function returns table of pointers on all residues currently contained in the chain with chain ID chainID, model number modelNo. NumberOfResidues returns the number of residues. The residues are indexed as 0..NumberOfResidues-1 in the table.

If the specified model or chain does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might leave residues empty. This results in empty cells in the residue table. Therefore, it is a good practice for application to check that resTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the residue table.


void CMMDBManager::GetResidueTable ( 
int  modelNo, 
int chainNo,
PPCResidue & resTable,
int & NumberOfResidues )
PURPOSE
Obtaining the residue table by model number and chain number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

PPCResidue & resTable
The table of residues.

int & NumberOfResidues
The number of residues.

DESCRIPTION

The function returns table of pointers on all residues currently contained in the chain number chainNo, model number modelNo. NumberOfResidues returns the number of residues. The residues are indexed as 0..NumberOfResidues-1 in the table.

If the specified model or chain does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might leave residues empty. This results in empty cells in the residue table. Therefore, it is a good practice for application to check that resTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the residue table.


void CMMDBManager::GetResidueTable ( 
pstr  CID, 
PPCResidue & resTable,
int & NumberOfResidues )
PURPOSE
Obtaining the residue table by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

PPCResidue & resTable
The table of residues.

int & NumberOfResidues
The number of residues.

DESCRIPTION

The function returns table of pointers on all residues currently contained in the CID-specified chain and their number. The residues are indexed as 0..NumberOfResidues-1 in the table.

If the provided CID does not specify a particular chain (e.g. it has a wildcard for the model number and/or chain ID), or the specified model or chain does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might leave residues empty. This results in empty cells in the residue table. Therefore, it is a good practice for application to check that resTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the residue table.


int CMMDBManager::GetNumberOfAtoms ( 
 )
PURPOSE
Obtaining the total number of atoms in coordinate hierarchy.
DESCRIPTION

The function returns the total number of atoms currently contained in the coordinate hierarchy.


int CMMDBManager::GetNumberOfAtoms ( 
int  modelNo, 
ChainID chainID,
int SeqNum,
InsCode insCode )
PURPOSE
Obtaining the number of atoms in a residue by model number, chain ID, sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int SeqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the coordinate hierarchy. The residue is identified by model number, chain ID, sequence number and insertion code. If any of these characteristics is invalid or if the residue is not found, the function returns 0.


int CMMDBManager::GetNumberOfAtoms ( 
int  modelNo, 
int chainNo,
int SeqNum,
InsCode insCode )
PURPOSE
Obtaining the number of atoms in a residue by model number, chain number, sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

int SeqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the coordinate hierarchy. The residue is identified by model number, chain number, sequence number and insertion code. If any of these characteristics is invalid or if the residue is not found, the function returns 0.


int CMMDBManager::GetNumberOfAtoms ( 
int  modelNo, 
ChainID chainID,
int resNo )
PURPOSE
Obtaining the number of atoms in a residue by model number, chain ID and residue number.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the coordinate hierarchy. The residue is identified by model number, chain ID and residue number. If any of these characteristics is invalid or if the residue is not found, the function returns 0.


int CMMDBManager::GetNumberOfAtoms ( 
int  modelNo, 
int chainNo,
int resNo )
PURPOSE
Obtaining the number of atoms in a residue by model number, chain number and residue number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the coordinate hierarchy. The residue is identified by model number, chain number and residue number. If any of these characteristics is invalid or if the residue is not found, the function returns 0.


int CMMDBManager::GetNumberOfAtoms ( 
pstr  CID )
PURPOSE
Obtaining the number of atoms in a residue by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

DESCRIPTION

The function returns the number of atoms currently contained in the residue answering to the specified CID. If the model number, chain ID, sequence number or insertion code derived from CID is invalid (e.g. CID contains a wildcard for any of these items), or if such a residue is not found, the function returns 0.


PCAtom CMMDBManager::GetAtomI ( 
int  atomNum )
PURPOSE
Obtaining an atom pointer by its absolute number in coordinate hierarchy.
ARGUMENTS
int atomNum
The atom number. This is an absolute index of the atom in the coordinate hierarchy, ranging as 0..TotalNofAtoms-1, where TotalNofAtoms is obtained from CMMDBManager::GetNumberOfAtoms. In an ideal PDB file, atomNum=serNum-1, where serNum is the atom's serial number.

DESCRIPTION

The function returns pointer on the atom number atomNum, which refers to all atoms in the coordinate hierarchy as described above. If there is no atom with the specified number, the function returns NULL.

NOTE : In an ideal PDB file, atomNum=serNum-1, as explained above. However practice shows that this is not a strict rule to rely on.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
ChainID chainID,
int seqNo,
InsCode insCode,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by model number, chain ID, sequence number, insertion code and atom name.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue sequence number, residue insertion code, chain ID and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
ChainID chainID,
int seqNo,
InsCode insCode,
int atomNo )
PURPOSE
Obtaining an atom pointer by model number, chain ID, sequence number, insertion code and atom number.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number. The atom number is the atom's index in the internal atom table of the residue. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CMMDBManager::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's internal table of atoms, residue sequence number, residue insertion code, chain ID and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
ChainID chainID,
int resNo,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by model number, chain ID, residue number and atom name.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue number (that is the residue's position in the chain's internal table of residues), chain ID and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
ChainID chainID,
int resNo,
int atomNo )
PURPOSE
Obtaining an atom pointer by model number, chain ID, residue number and atom number.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

int atomNo
The atom number. The atom number is the atom's index in the internal atom table of the residue. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CMMDBManager::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's internal table of atoms, residue number (that is the residue's position in the chain's internal table of residues), chain ID and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
int chainNo,
int seqNo,
InsCode insCode,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by model number, chain number, sequence number, insertion code and atom name.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. The chain number is the chain's index in the internal chain table of a model. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CMMDBManager::GetNumberOfChains or its overloaded analogue.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue sequence number, residue insertion code, chain number (that is, the position of chain in the internal chain table of a model) and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
int chainNo,
int seqNo,
InsCode insCode,
int atomNo )
PURPOSE
Obtaining an atom pointer by model number, chain number, sequence number, insertion code and atom number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. The chain number is the chain's index in the internal chain table of a model. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CMMDBManager::GetNumberOfChains or its overloaded analogue.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number. The atom number is the atom's index in the internal atom table of the residue. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CMMDBManager::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's internal table of atoms, residue sequence number, residue insertion code, chain number (that is, the position of chain in the internal chain table of a model) and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
int chainNo,
int resNo,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by model number, chain number, residue number and atom name.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. The chain number is the chain's index in the internal chain table of a model. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CMMDBManager::GetNumberOfChains or its overloaded analogue.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue number (that is the residue's position in the chain's internal table of residues), chain number - the position of chain in the internal chain table of a model - and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
int  modelNo, 
int chainNo,
int resNo,
int atomNo )
PURPOSE
Obtaining an atom pointer by model number, chain number, residue number and atom number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. The chain number is the chain's index in the internal chain table of a model. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CMMDBManager::GetNumberOfChains or its overloaded analogue.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

int atomNo
The atom number. The atom number is the atom's index in the internal atom table of the residue. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CMMDBManager::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's internal table of atoms, residue number (that is the residue's position in the chain's internal table of residues), chain number - the position of chain in the internal chain table of a model - and model number. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CMMDBManager::GetAtom ( 
pstr  CID )
PURPOSE
Obtaining an atom pointer by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

DESCRIPTION

The function returns pointer on the atom answering the specified coordinate ID. If the provided CID does not specify a particular model, chain, residue or atom (e.g. it has a wildcard for residue), or if such model, chain, residue or atom does not exist in the coordinate hierarchy, the function returns NULL.


void CMMDBManager::GetAtomTable ( 
PPCAtom &  atomTable, 
int & NumberOfAtoms )
PURPOSE
Obtaining the atom table of all atoms in coordinate hierarchy.
ARGUMENTS
PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the coordinate hierarchy and their number. The atoms are indexed as 0..NumberOfAtoms-1 and retain the order as read from the coordinate file.

NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the atom table. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the atom table.


void CMMDBManager::GetAtomTable ( 
int  modelNo, 
ChainID chainID,
int seqNum,
InsCode insCode,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the atom table by model number, chain ID, sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the residue identified by sequence number, insertion code, chain ID and model number. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the specified model, chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the atom table. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the atom table.


void CMMDBManager::GetAtomTable ( 
int  modelNo, 
ChainID chainID,
int resNo,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the atom table by model number, chain ID and residue number.
ARGUMENTS
int modelNo
The model number.

ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the residue identified by its position in the internal residue table of a chain, chain ID and model number. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the specified model, chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the atom table. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the atom table.


void CMMDBManager::GetAtomTable ( 
int  modelNo, 
int chainNo,
int seqNum,
InsCode insCode,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the atom table by model number, chain number, sequence number and insertion code.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the residue identified by sequence number, insertion code, chain number (that is, the position of the chain in the internal chain table of a model) and model number. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the specified model, chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the atom table. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the atom table.


void CMMDBManager::GetAtomTable ( 
int  modelNo, 
int chainNo,
int resNo,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the atom table by model number, chain number and residue number.
ARGUMENTS
int modelNo
The model number.

int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CMMDBManager::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CMMDBManager::GetNumberOfResidues or its overloaded analogue.

PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the residue identified by its position in the internal residue table of a chain, chain number (that is, the position of the chain in the internal chain table of a model) and model number. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the specified model, chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the atom table. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the atom table.


void CMMDBManager::GetAtomTable ( 
pstr  CID, 
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the atom table by coordinate ID.
ARGUMENTS
pstr CID
The coordinate ID.

PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the CID-specified residue and their number. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the provided CID does not specify a particular residue (e.g. it has a wildcard for the model number, chain ID or sequence number), or the specified model, chain or residue does not exist, the function returns NULL for atomTable and 0 for NumberOfAtoms.

NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the atom table. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the atom table.



Back to index