CCP4 Coordinate Library Project

Object interface: Data class CResidue.

Data class CResidue represents a residue in the coordinate hierarchy.

CResidue contains all information, which is relevant to particular residue, and reference to chain that contains the residue. It also contains table of pointers on all atoms (represented as classes of type CAtom) that belong to the residue.

Public Data Fields


Function Purpose
CResidue::CResidue Default constructor.
CResidue::~CResidue The class' destructor.
CResidue::GetModelNum Obtaining number of model containing the residue.
CResidue::GetChainID Obtaining identifier of chain containing the residue.
CResidue::GetResName Obtaining the residue name.
CResidue::SetResName Setting the residue name.
CResidue::GetSeqNum Obtaining the residue sequence number.
CResidue::GetInsCode Obtaining the residue insertion code.
CResidue::GetChain Obtaining pointer on chain containing the residue.
CResidue::GetModel Obtaining pointer on model containing the residue.
CResidue::isInSelection Checking if residue is selected.
CResidue::GetResidueID Obtaining a full residue's coordinate ID.
CResidue::CheckID Checking the residue's ID by sequence number, insertion code and residue name.
CResidue::CheckIDS Checking the residue's ID by coordinate ID.
CResidue::GetNumberOfAtoms Calculating the number of atoms in the residue.
CResidue::GetNumberOfAtoms Obtaining the number of atoms in residue.
CResidue::GetAtom Obtaining an atom pointer by atom name, element name, and alternative location indicator.
CResidue::GetAtom Obtaining an atom pointer by atom number.
CResidue::GetAtomTable Obtaining the residue's table of atoms.
CResidue::DeleteAtom Deleting an atom by atom name, element name, and alternative location indicator.
CResidue::DeleteAtom Deleting an atom by atom number.
CResidue::DeleteAllAtoms Deleting all atoms in the residue.
CResidue::AddAtom Adding an atom to the residue.
CResidue::GetAtomStatistics Calculating the averaged properties of atoms in the residue.
CResidue::ApplyTransform Applying a transformation matrix to coordinates of all atoms in the residue.
CResidue::isAminoacid Checking if the residue represents an aminoacid.
CResidue::isNucleotide Checking if the residue represents a nucleotide.
CResidue::isSugar Checking if the residue represents a sugar molecule.
CResidue::isSolvent Checking if the residue represents a solvent molecules.
CResidue::isModRes Checking if the residue represents a modified standard residue.
CResidue::PutUDData Storing an integer User-Defined Data (UDD) in the residue.
CResidue::PutUDData Storing a real-type User-Defined Data (UDD) in the residue.
CResidue::PutUDData Storing a string-type User-Defined Data (UDD) in the residue.
CResidue::GetUDData Retrieving an integer User-Defined Data (UDD) from the residue.
CResidue::GetUDData Retrieving a real-type User-Defined Data (UDD) from the residue.
CResidue::GetUDData Retrieving a string-type User-Defined Data (UDD) from the residue, dynamic buffer.
CResidue::GetUDData Retrieving a string-type User-Defined Data (UDD) from the residue, fixed-size buffer.
CResidue::Copy Copying the residue contents.


PUBLIC DATA FIELDS

It is a good practice for any application not to modify the public fields directly if there are class' functions for doing that. Even better, avoid also direct reading them if the class provides functions for that, as the fields may be made protected in the future.

Type Field Ok to
Modify*
Description
ResName name N/R,R The residue's (3-letter) name, represented as a null-terminated string. The field is left-aligned, all spaces are cut.
int seqNum N/R,R The residue's sequence number.
InsCode insCode N/R,R The residue's insertion code, represented as a null-terminated string. The field is left-aligned, all spaces are cut. For a residue without insertion code, insCode is set to empty string "".
PCChain chain N Pointer on chain (class CChain) containing the residue. If this pointer is NULL, it indicates a serious problem in the coordinate hierarchy, not yet a crash.
int index N Index (position) of the residue in the parential chain's table of residues. The index ranges as 0.. on.
*N: modification of the field by application may cause malfunction or crash;
Y: the field may be modified by application;
R: reading function is available;
Y/H: the field may be modified by application however there are conditions;
N/R: modification of the field is generally harmless but not recommended.


 CResidue::CResidue ( 
 )
PURPOSE
Default constructor.
DESCRIPTION

Default constructor creates an empty CResidue object.


 CResidue::~CResidue ( 
 )
PURPOSE
The class' destructor.
DESCRIPTION

The destructor is called implicitely whenever the class instance is deleted. It deletes all atoms containing in the residue and the residue itself. If the residue is properly associated with the coordinate hierarchy, the destructor removes all references on the residue and its atoms from the hierarchy.

NOTE : Deleting a residue is an editing operation. If it is done by application explicitely, like in the following example:

    PCMMDBManager MMDB;
    PCResidue     res;
      res = MMDB->GetResidue ( "/1/A/33(SER).A" );
      delete res;  // this is where the destructor is called!
    
then the application must call CMMDBManager::FinishStructEdit function before using any results of such deletion(s).

If the deletion is done implicitely by a Library function in the course of other action(s), there is no need for application to call CMMDBManager::FinishStructEdit after that.


int CResidue::GetModelNum ( 
 )
PURPOSE
Obtaining number of model containing the residue.
DESCRIPTION

The function returns number of model that contains the residue. Models are numbered 1.. on. If residue is not properly associated with coordinate hierarchy, the function returns 0.


pstr CResidue::GetChainID ( 
 )
PURPOSE
Obtaining identifier of chain containing the residue.
DESCRIPTION

The function returns identifier of chain that contains the residue. If the chain does not have an ID, the function returns empty string "". If residue is not properly associated with coordinate hierarchy, the function returns NULL.


pstr CResidue::GetResName ( 
 )
PURPOSE
Obtaining the residue name.
DESCRIPTION

The function returns the residue name.


pstr CResidue::SetResName ( 
ResName  resName )
PURPOSE
Setting the residue name.
ARGUMENTS
ResName resName
New residue name.

DESCRIPTION

The function sets new residue name, i.e. renames the residue.


int CResidue::GetSeqNum ( 
 )
PURPOSE
Obtaining the residue sequence number.
DESCRIPTION

The function returns the residue sequence number.


pstr CResidue::GetInsCode ( 
 )
PURPOSE
Obtaining the residue insertion code.
DESCRIPTION

The function returns the residue insertion code. If the residue does not have insertion code, the function returns empty string "".


PCChain CResidue::GetChain ( 
 )
PURPOSE
Obtaining pointer on chain containing the residue.
DESCRIPTION

The function returns pointer on chain that contains the residue. If residue is not properly associated with coordinate hierarchy, the function returns NULL.


PCModel CResidue::GetModel ( 
 )
PURPOSE
Obtaining pointer on model containing the residue.
DESCRIPTION

The function returns pointer on model that contains the residue. If residue is not properly associated with coordinate hierarchy, the function returns NULL.


Boolean CResidue::isInSelection ( 
int  selHnd )
PURPOSE
Checking if residue is selected.
ARGUMENTS
int selHnd
Selection handle.

DESCRIPTION

The function returns True if residue is selected for the specified selection handle, and False otherwise.

NOTE : The function returns False if residue is not properly associated with coordinate hierarchy.


pstr CResidue::GetResidueID ( 
pstr  ResidueID )
PURPOSE
Obtaining a full residue's coordinate ID.
ARGUMENTS
pstr ResidueID
A string to accept the residue's coordinate ID.

DESCRIPTION

The function calculates a coordinate ID of the residue and returns it in the supplied string. The same string is returned as the function value.

If residue is not properly associated with coordinate hierarchy, the coordinate ID will contain dashes "-" for those elements that could not be identified.

NOTE : The function does not make any checks on the sufficiency of string buffer ResidueID to accept the information.


int CResidue::CheckID ( 
int *  sNum, 
InsCode inscode,
ResName resname )
PURPOSE
Checking the residue's ID by sequence number, insertion code and residue name.
ARGUMENTS
int * sNum
Pointer on sequence number. If sNum is set to NULL then this parameter is ignored.

InsCode inscode
The insertion code, represented as a null-terminated string without spaces. For a residue without insertion code, inscode should be set to empty string "" (default). inscode may be set to NULL or to wildcard "*", then this parameter is ignored.

ResName resname
The residue's name (3-letter code). resname may be set to NULL (default) or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function returns 1 if the residue is identified by given sequence number, insertion code and residue name, and 0 otherwise.

The residue is considered as identified, if all non-NULL, non-wildcard parameters do match. If all parameters are set NULL or wildcard, any residue is identified. Default values for inscode and resname correspond to 'no insertion code' and 'any residue name'.

NOTE 1: The model serial number and chain ID are not taken into account by this function.

NOTE 2: Comparison is case-sensitive. Consider that " " is not an empty string.


int CResidue::CheckIDS ( 
pstr  CID )
PURPOSE
Checking the residue's ID by coordinate ID.
ARGUMENTS
pstr CID
The residue's coordinate ID. Only the part of coordinate ID containing the sequence number, insertion code and residue name is taken into consideration.

DESCRIPTION

The function returns 1 if the residue is identified by residue sequence number, insertion code ans residue name found in the provided coordinate ID, and 0 otherwise.

The residue is considered as identified, if all identifying items in the provided coordinate ID do match those of residue. If all coordinate ID items are set to wildcards "*", any residue is identified.

NOTE 1: The model serial number and chain ID, as well as any atom-related information in the coordinate ID are not taken into account by this function.

NOTE 2: Comparison is case-sensitive. Any spaces in the coordinate ID are ignored.


int CResidue::GetNumberOfAtoms ( 
Boolean  countTers )
PURPOSE
Calculating the number of atoms in the residue.
ARGUMENTS
Boolean countTers
Flag specifying if any termination records ("TER") should be counted as atoms. In MMDB, the termination records are kept as a special case of CAtom objects. If countTers is set to True, the termination records will be counted as atoms, otherwise they are ignored.

DESCRIPTION

The function performs an actual calculation of all atoms in the residue, not just returning the length of atom tables. If some cells in the atom table are empty (set to NULL), they are not counted.


int CResidue::GetNumberOfAtoms ( 
 )
PURPOSE
Obtaining the number of atoms in residue.
DESCRIPTION

The function returns the number of atoms currently contained in the residue.

NOTE : The function actually returns the length of atom table of the residue. In the course of editing operations, the table may contain empty cells, which will be counted as atoms. Besides, a residue may contain a termination record ("TER"), which is kept in MMDB as a special case of CAtom object; the function will count such an object as atom.


PCAtom CResidue::GetAtom ( 
AtomName  aname, 
Element elname,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by atom name, element name, and alternative location indicator.
ARGUMENTS
AtomName aname
The atom name. It may or may not be aligned (as in a PDB file), only first word of the name will be considered (thus "CA", " CA" and " CA B" are all considered as "CA"). aname may be set to NULL or to wildcard "*", then this parameter is ignored.

Element elname
The atom's chemical element code. This parameter will work only if the element code was set up for the atom (which may take place in the case of reading atoms from old PDB files that do not contain the chemical element names; or if the atom was created in a tricky way by application). elname should be used to distinguish between, e.g. "Ca" and "C_alpha". All spaces in elname are ignored. elname may be set to NULL (default), or to wildcard "*", then this parameter is ignored.

AltLoc aloc
The atom's alternative location indicator. If atom does not have alternative location, this is indicated by empty string ""(default). aloc may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

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

The atom is considered as identified, if all non-NULL, non-wildcard parameters do match. If the specified parameters allow for identification of more than one atom in the residue, the first one from the begining of the residue's table of atoms is taken. Thus, if all parameters are set NULL or wildcard, pointer on the very first atom in the residue's table of atoms is returned. Default values for elname and aloc correspond to 'any element' and 'no alternative location indicator'.

NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.


PCAtom CResidue::GetAtom ( 
int  atomNo )
PURPOSE
Obtaining an atom pointer by atom number.
ARGUMENTS
int atomNo
The atom number, that is the atom's position in the residue's table of atoms. The atoms in the table are numbered as 0..NumberOfAtoms-1 where NumberOfAtoms is returned by CResidue::GetNumberOfAtoms.

DESCRIPTION

The function returns pointer on the atomNoth atom in the residue's table of atoms. If atomNo is invalid or if such an atom does not exist in residue, the function returns NULL.


void CResidue::GetAtomTable ( 
PPCAtom &  atomTable, 
int & NumberOfAtoms )
PURPOSE
Obtaining the residue's table of atoms.
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 residue. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If there is no atoms in the residue, 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 table of atoms. 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 table of atoms.


int CResidue::DeleteAtom ( 
AtomName  aname, 
Element elname,
AltLoc aloc )
PURPOSE
Deleting an atom by atom name, element name, and alternative location indicator.
ARGUMENTS
AtomName aname
The atom name. It may or may not be aligned (as in a PDB file), only first word of the name will be considered (thus "CA", " CA" and " CA B" are all considered as "CA"). aname may be set to NULL or to wildcard "*", then this parameter is ignored.

Element elname
The atom's chemical element code. This parameter will work only if the element code was set up for the atom (which may take place in the case of reading atoms from old PDB files that do not contain the chemical element names; or if the atom was created in a tricky way by application). elname should be used to distinguish between, e.g. "Ca" and "C_alpha". All spaces in elname are ignored. elname may be set to NULL (default), or to wildcard "*", then this parameter is ignored.

AltLoc aloc
The atom's alternative location indicator. If atom does not have alternative location, this is indicated by empty string ""(default). aloc may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function deletes all atoms in the residue that answer to the provided atom name, chemical element name and alternative location indicator. An atom is considered as answering the conditions if all non-NULL, non-wildcard parameters do match. Thus, if all parameters are set NULL or wildcard, all atoms in the residue are deleted. Default values for elname and aloc correspond to 'any element' and 'no alternative location indicator'.


RETURN

The function returns the number of deleted atoms.

NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.

NOTE 2: Deleted atoms are completely disposed and are not retrievable.

NOTE 3: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.


int CResidue::DeleteAtom ( 
int  atomNo )
PURPOSE
Deleting an atom by atom number.
ARGUMENTS
int atomNo
The atom number, that is the atom's position in the residue's table of atoms. The atoms in the table are numbered as 0..NumberOfAtoms-1 where NumberOfAtoms is returned by CResidue::GetNumberOfAtoms.

DESCRIPTION

The function deletes the atomNoth atom as found in the residue's table of atoms. If atomNo is invalid or if such an atom does not exist in residue, the function does nothing.


RETURN

The function returns the number of deleted atoms, that is 1 or 0.

NOTE 1: Deleted atoms are completely disposed and are not retrievable.

NOTE 2: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.


int CResidue::DeleteAllAtoms ( 
 )
PURPOSE
Deleting all atoms in the residue.
DESCRIPTION

The function deletes all atoms in the residue, leaving the residue empty.


RETURN

The function returns the number of actually deleted atoms.

NOTE 1: Deleted atoms are completely disposed and are not retrievable.

NOTE 2: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.

NOTE 3: The function does not dispose the residue; neither does it delete it from a chain.


int CResidue::AddAtom ( 
PCAtom  atom )
PURPOSE
Adding an atom to the residue.
ARGUMENTS
PCAtom atom
The atom that should be added to the residue.

DESCRIPTION

The function adds atom atom to the residue, placing it on the top of the residue's table of atoms. The atom and the residue may be or may be not associated with a coordinate hierarchy.

If atom atom is not associated with a coordinate hierarchy, it is taken over by the residue, which means that its pointer is saved in the residue's table of atoms. If atom atom already belongs to a coordinate hierarchy (even though that of the residue), the residue adopts its (automatically created) copy, thus the atom is not removed from its own coordinate hierarchy.

If residue is associated with a coordinate hierarchy, the newly added atom is automatically associated with it. Otherwise, the atom is checked in the hierarchy once the residue is checked in (see example below).


RETURN

Upon success, the function returns the number of atoms in the residue, which should be a positive integer greater than 0. A negative or zero return means that the atom is already in the residue, found at position equal to minus return.

NOTE 1: Note the difference between adding atoms associated and not associated with a coordinate hierarchy as described above.

NOTE 2: Calling CMMDBManager::FinishStructEdit function is not necessary after adding atoms. However, it is advisable to call CMMDBManager::PDBCleanup with input flags PDBCLEAN_SERIAL and PDBCLEAN_INDEX after adding all atoms (don't call CMMDBManager::PDBCleanup after every addition of an atom). PDBCLEAN_SERIAL will put atoms' serial numbers in due order, and "cleaning" on PDBCLEAN_INDEX is needed for the internal consistency of data.


EXAMPLE

Create a chain containing one residue having a few atoms, and add it to model 1 of a coordinate hierarchy:

CMMDBManager MMDB;
PCModel      model;
PCChain      chain;
PCResidue    res;
PCAtom       atom;
int          RC;

  // ... read data into MMDB
  RC = MMDB.ReadCoorFile ( filename );
  // ... check for errors -- see details for 
  // CMMDBManager::ReadCoorFile(..)
  if (RC)  {
    printf ( " errors.\n" );
    exit(0);
  }

  // ... create a new residue
  res = new CResidue();     // the residue IS NOT associated
                            // with MMDB

  // ... stuff it with atoms now:

  atom = new CAtom();       // the atom IS NOT associated with
                            // a residue or MMDB
  // ... set atom characteristics:
  atom->SetAtomName    ( " CA " );  // it has to be a PDB name!
  atom->SetElementName ( "C"    );
  atom->SetCoordinates ( x,y,z,occupancy,tFactor );
  // ... add atom to the residue:
  RC = res->AddAtom ( atom );
  if (RC<=0)  {
    // this may happen only if you try to add the same atom twice.
    printf ( " error adding atom.\n" );
    exit(0);
  }

  // ... a slightly different way of doing the same:
  atom = new CAtom ( res ); // the atom IS ALREADY associated with
                            // and added to the residue, but it
                            // IS NOT associated with MMDB
                            // NOTE: this way assures that the atom
                            // is added to the residue, because
                            // it was freshly allocated -- no other
                            // atom with the same pointer may exist.
  // ... we still need to set the atom's characteristics:
  atom->SetAtomName    ( " CB " );  // it has to be a PDB name!
  atom->SetElementName ( "C"    );
  atom->SetCoordinates ( x,y,z,occupancy,tFactor );

  // ... add other atoms as necessary ...

  // ... create a new chain
  chain = new CChain();       // the chain IS NOT associated with MMDB
  chain->SetChainID ( "X" );  // new chain ID
  // ... and add residue to it
  chain->AddResidue ( res );

  // ... now add the chain to the model 1 of MMDB:
  model = MMDB.GetModel ( 1 );
  if (!model)  {
    // MMDB was empty. We have to create a new model:
    model = new CModel();
    MMDB.AddModel ( model ); // add empty model on the top of MMDB
  }
  model->AddChain ( chain ); // at this point, the chain is associated with
                             // and added to MMDB, all its residues and
                             // atoms get associated automatically

  // The following call is more of a "gentleman" nature now,
  // but it may be an absolute must for compliency with later
  // versions of MMDB. You are strongly advised to call at least
  // PDBCleanup(PDBCLEAN_INDEX) after adding or inserting
  // atoms/residues/chains/models into MMDB. However don't make
  // this call after every insertion/addition for the sake of
  // computational efficiency. Do this call once as you finished
  // building the structure and are going to proceed further.
  MMDB.PDBCleanup ( PDBCLEAN_SERIAL | PDBCLEAN_INDEX );


void CResidue::GetAtomStatistics ( 
RSAtomStat  AS )
PURPOSE
Calculating the averaged properties of atoms in the residue.
ARGUMENTS
RSAtomStat AS
Reference to structure SAtomStat, which returns the average results. The structure has the following fields:

Type Field(s)   Description
int nAtoms   Number of averaged atoms
realtype xmin,ymin,zmin   Minimum X,Y,Z-coordinates
realtype xmax,ymax,zmax   Maximum X,Y,Z-coordinates
realtype xm,ym,zm   Average X,Y,Z-coordinates
realtype xm2,ym2,zm2   Square average X,Y,Z-coordinates
realtype occ_min,occ_max   Minimum and maximum occupancies
realtype occ_m,occ_m2   Average and square average occupancies
realtype tFmin,tFmax   Minimum and maximum isotropic temperature factors
realtype tFm,tFm2   Average and square average isotropic temperature factors
realtype u11_min,u22_min,
u33_min,u12_min,
u13_min,u23_min
  Minimum anisotropic temperature factors
realtype u11_max,u22_max,
u33_max,u12_max,
u13_max,u23_max
  Maximum anisotropic temperature factors
realtype u11_m,u22_m,
u33_m,u12_m,
u13_m,u23_m
  Average anisotropic temperature factors
realtype u11_m2,u22_m2,
u33_m2,u12_m2,
u13_m2,u23_m2
  Square average anisotropic temperature factors
word WhatIsSet   A word of bit flags, indicating which from the above fields have meaningful values. This field is identical to the WhatIsSet field of CAtom class. If any atom from the average does not have a particular attribute, the corresponding bit in WhatIsSet will be cleared and the averages for that attribute are not calculated.


DESCRIPTION

The function performs an actual calculation of averaged atom properties, none of them are stored as variables. It is therefore advised to avoid unnecessary calls to this function.


void CResidue::ApplyTransform ( 
mat44 &  TMatrix )
PURPOSE
Applying a transformation matrix to coordinates of all atoms in the residue.
ARGUMENTS
mat44 & TMatrix
The transformation matrix.

DESCRIPTION

The function applies the rotational-translational transformation given by matrix TMatrix, to coordinates of all atoms in the residue.

The transformation matrix TMatrix contains rotational part in columns 0,1,2, rows 0,1,2 (stands for x,y,z) and translational part in column 3, rows 0,1,2.


Boolean CResidue::isAminoacid ( 
 )
PURPOSE
Checking if the residue represents an aminoacid.
DESCRIPTION

The function returns True if the residue represents an aminoacid.


Boolean CResidue::isNucleotide ( 
 )
PURPOSE
Checking if the residue represents a nucleotide.
DESCRIPTION

The function returns True if the residue represents a nucleotide.


Boolean CResidue::isSugar ( 
 )
PURPOSE
Checking if the residue represents a sugar molecule.
DESCRIPTION

The function returns True if the residue represents a sugar molecule.


Boolean CResidue::isSolvent ( 
 )
PURPOSE
Checking if the residue represents a solvent molecules.
DESCRIPTION

The function returns True if the residue represents a solvent molecule.


Boolean CResidue::isModRes ( 
 )
PURPOSE
Checking if the residue represents a modified standard residue.
DESCRIPTION

The function returns True if the residue represents a modified standard residue.


int CResidue::PutUDData ( 
int  UDDhandle, 
int iudd )
PURPOSE
Storing an integer User-Defined Data (UDD) in the residue.
ARGUMENTS
int UDDhandle
The UDD handle.

int iudd
The integer number to be stored in the residue.

DESCRIPTION

The function stores an integer contained in iudd in the residue, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDInteger in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.


RETURN

The function may return:
Return Description
UDDATA_Ok the data has been successfully stored
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the residue, the data was not stored
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in residues, the data was not stored


int CResidue::PutUDData ( 
int  UDDhandle, 
realtype rudd )
PURPOSE
Storing a real-type User-Defined Data (UDD) in the residue.
ARGUMENTS
int UDDhandle
The UDD handle.

realtype rudd
The real number to be stored in the residue.

DESCRIPTION

The function stores the real number contained in rudd in the residue, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDReal in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.

The function is conceptually identical to CResidue::PutUDData, see returns there.


int CResidue::PutUDData ( 
int  UDDhandle, 
pstr sudd )
PURPOSE
Storing a string-type User-Defined Data (UDD) in the residue.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr sudd
The string to be stored in the residue.

DESCRIPTION

The function stores the string pointed by sudd in the residue, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.

The function is conceptually identical to CResidue::PutUDData, see returns there.


int CResidue::GetUDData ( 
int  UDDhandle, 
int & iudd )
PURPOSE
Retrieving an integer User-Defined Data (UDD) from the residue.
ARGUMENTS
int UDDhandle
The UDD handle.

int & iudd
The buffer to accept the integer data.

DESCRIPTION

The function retrieves an integer previously stored in the residue by function CResidue::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDInteger in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.

The data is returned in iudd.


RETURN

The function may return:
Return Description
UDDATA_Ok the data has been successfully retrieved.
UDDATA_NoData no data found for the handle UDDhandle in the residue. iudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the residue. iudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in residues. iudd does not change.


int CResidue::GetUDData ( 
int  UDDhandle, 
real & rudd )
PURPOSE
Retrieving a real-type User-Defined Data (UDD) from the residue.
ARGUMENTS
int UDDhandle
The UDD handle.

real & rudd
The buffer to accept the real-type data.

DESCRIPTION

The function retrieves a real number previously stored in the residue by function CResidue::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDReal in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.

The data is returned in rudd.


RETURN

The function may return:
Return Description
UDDATA_Ok the data has been successfully retrieved.
UDDATA_NoData no data found for the handle UDDhandle in the residue. rudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the residue. rudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in residues. rudd does not change.


int CResidue::GetUDData ( 
int  UDDhandle, 
pstr & sudd )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the residue, dynamic buffer.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr & sudd
A pointer to dynamically-allocated string accepting the data.

DESCRIPTION

The function retrieves a string previously stored in the residue by function CResidue::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.

The string is returned in buffer pointed by sudd. If sudd was not set to NULL, it will be deallocated first. The string is allocated within the function, and it is responsibility of the application to eventually deallocate it.


RETURN

The function may return:
Return Description
UDDATA_Ok the data has been successfully retrieved.
UDDATA_NoData no data found for the handle UDDhandle in the residue. sudd returns NULL.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the residue. sudd returns NULL.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in residues. sudd does not change.


int CResidue::GetUDData ( 
int  UDDhandle, 
pstr sudd,
int maxlen )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the residue, fixed-size buffer.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr sudd
A pointer to a string accepting the data.

int maxlen
A maximal number of characters, including the terminating NULL that sudd may to accept (not more than the physical length of sudd).

DESCRIPTION

The function retrieves a string previously stored in the residue by function CResidue::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.

The string is returned in buffer pointed by sudd, with no more than maxlen symbols, including the terminating NULL returned. The string sudd is not allocated or deallocated within the function.


RETURN

The function may return:
Return Description
UDDATA_Ok the data has been successfully retrieved.
UDDATA_NoData no data found for the handle UDDhandle in the residue. sudd returns empty string "".
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the residue. sudd returns empty string "".
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in residues. sudd does not change.


void CResidue::Copy ( 
PCResidue  residue )
PURPOSE
Copying the residue contents.
ARGUMENTS
PCResidue residue
The source residue, whose contents is to be copied.

DESCRIPTION

The function copies the content of residue residue into internal class' fields. The function does copy all the table of residue's atoms and it does redefine the atoms' residue for the destination one. As a result, a new residue is created that is identical to the source one, but physically they do not overlap.

NOTE : An application should never copy contents of classes by direct assignment; in most cases this will result in crash because of inducing a mess in cross-references. See the following example:

      PCResidue res1,res2;
      res1 = new CResidue();
      res2 = new CResidue();
      // doing something with res2
      
      *res1 = *res2;  // never do this!
      
      // the right way:
      res1->Copy ( res2 );
    
Function Copy is supplied for all classes in the Library.



Back to index