CCP4 Coordinate Library Project

Object interface: Error Handling and Return Codes.

It is common for Library functions and class functions to use integer return as an indicator on the success of operation. Successful operations normally return 0 (with a few exceptions for this rule; these are mentioned wherever necessary). An application may then check the return code and branch the execution according to that.

The Library provides a function which returns a sensible ASCII description for every error code. This feature may be not always convenient, since grammar of the message cannot be adjust to any situation; however it will definitely save for developing. A special function delivers location of problems arising at reading coordinate files. Description of these functions and table of error codes are found below.

Function Purpose
GetErrorDescription Returns a sensible ASCII description for error codes.
CMMDBManager::GetInputBuffer Retrieves the location of input error.


Table Description
Error Codes Library's error codes


pstr GetErrorDescription ( 
int  ErrorCode )
PURPOSE
Returns a sensible ASCII description for error codes.
ARGUMENTS
int ErrorCode
An error code returned by Library function.

NOTE : For successful operation (return code 0), this function returns non-empty line "No errors".


void CMMDBManager::GetInputBuffer ( 
pstr  Line, 
int & count )
PURPOSE
Retrieves the location of input error.
ARGUMENTS
pstr Line
A buffer to accept the information on input error; must be at least 100 bytes long (physical input buffer, from which the information is copied, is 500 bytes long).

int & count
An integer return code, which is interpreted as described below.

DESCRIPTION

The meaning of information, returned in Line, is determined by the value of return in count.

Non-negative values of count mean that the error was encountered on the stage of reading an input ASCII file. In this case, Line gives the erroneous input line and count gives its number as counted from the top of file.

If count returns -1, it means that the error was encountered at interpreting the mmCIF context, after the whole mmCIF file has been read. In this case, Line countains mmCIF item (category.name), which caused the fault.

If count returns -2, the error was found at reading the MMDB binary file. Line is set to an empty string ("") in this case; such errors are not recoverable and may occur only if the binary file was corrupted.


EXAMPLE

PCMMDBManager  MMDB;
char           S[100];
int            RC,lcount;

  MMDB = new CMMDBManager();

  // read a coordinate file
  RC = MMDB->ReadCoorFile ( CoorFileName );

  // Check for possible errors:
  if (RC) {
    //  first issue a general message identifying the nature of error:
    printf ( " ***** ERROR #%i READ:\n\n %s\n\n",RC,GetErrorDescription(RC) );
    //  now try to locate the error
    MMDB->GetInputBuffer ( S,lcount );
    if (lcount>=0)       // it was an erroneous line in input file
      printf ( "       LINE #%i:\n%s\n\n",lcount,S );
    else if (lcount==-1) // something was wrong with mmCIF context
      printf ( "       CIF ITEM: %s\n\n",S );
    else if (lcount==-2) // corrupted binary file
      printf ( "       CORRUPTED BINARY FILE\n\n" );
    else
      printf ( "       ERROR CANNOT BE LOCATED\n\n" );
    //  dispose instance of MMDB and quit:
    delete MMDB;
    exit ( 1 );
  }

  // go on working on coordinates
  ...............................


Error Codes

The Library's Error Codes are listed in file mmdb_defs.h; their names start with prefix Error_. Existing error codes are not likely to change in the future, however the list of codes may be expanded. Nevertheless it is strictly advisable to error codes them by their names (as given below) and not by their numerical values.

Code Name Value Description
Error_NoError
Error_Ok
0 No error encountered
Error_WrongSection 1 Records in PDB file are in a wrong order.
Error_WrongChainID 2 A sequence of PDB or mmCIF records that ought to have the same chain ID, shows different chain IDs.
Error_WrongEntryID 3 A PDB or mmCIF record that ought to display this entry's ID, shows an ID contradicting to that in header.
Error_SEQRES_serNum 4 Serial numbers of SEQRES records do not increment by 1.
Error_SEQRES_numRes 5 Different SEQRES records that belong to the same sequence show different number of residues in the sequence.
Error_SEQRES_extraRes 6 SEQRES records contain more residues than specified.
Error_NCSM_Unrecognized 7 Unrecognized numerical format of input in MTRIXn PDB records.
Error_NCSM_AlreadySet 8 A duplicate MTRIXn PDB record encountered.
Error_NCSM_WrongSerial 9 Wrong serial number in MTRIXn PDB record.
Error_NCSM_UnmatchIG 10 A sequence of MTRIXn PDB records that ought to have the same iGiven flag, shows different flags on different records.
Error_ATOM_Unrecognized 11 Unrecognized numerical format of data fields in a record from the Coordinate Section of a PDB file (ATOM, HETATM, SIGATM, ANISOU, SIGUIJ, TER, MODEL).
Error_ATOM_AlreadySet 12 Duplicate record from the Coordinate Section of a PDB file (ATOM, HETATM, SIGATM, ANISOU, SIGUIJ, TER, MODEL).
Error_ATOM_NoResidue 13 Missing residue name or sequence number or ambiguity in residue names/sequence numbers/insertion codes in record(s) from the Coordinate Section of a PDB file (ATOM, HETATM, SIGATM, ANISOU, SIGUIJ, TER).
Error_ATOM_Unmatch 14 Ambiguity between different records record(s) from the Coordinate Section of a PDB file (ATOM, HETATM, SIGATM, ANISOU, SIGUIJ, TER) belonging to the same atom.
Error_CantOpenFile 15 A file can not be opened.
Error_UnrecognizedInteger 16 Wrong ASCII format of an integer.
Error_WrongModelNo 17 Model number is not positive.
Error_DuplicatedModel 18 Repeating serial model number encountered.
Error_NoModel 19 No model defined.
Error_ForeignFile 20 Attempt to read a file of unknown type.
Error_WrongEdition 21 The MMDB binary file attempted to be read, was created by a higher-version Library.
Error_NotACIFFile 22 A file attempted to be read as a mmCIF file, was not recognized as such.
Error_NoData 23 Expected data field in mmCIF file (either following a tag or in loop) not found.
Error_UnrecognizedCIFItems 24 Unrecognized syntactical elements were encountered in a mmCIF file.
Error_MissingCIFField 25 Expected item(s) in mmCIF file were not found.
Error_EmptyCIFLoop 26 An empty CIF loop encountered.
Error_UnexpectedEndOfCIF 27 A mmCIF file is terminated incorrectly.
Error_MissgCIFLoopField 28 Inconsistent CIF loop (wrong number of loop fields).
Error_NotACIFStructure 29 A CIF category expected to be a structure, is a loop.
Error_NotACIFLoop 30 A CIF category expected to be a loop, is a structure.
Error_UnrecognizedReal 31 Wrong ASCII format of a real.
Error_NoSheetID 32 A PDB SHEET record is missing sheet ID code.
Error_WrongSheetID 33 A sequence of PDB SHEET records that ought to have the same sheet ID, shows different IDs on different records.
Error_WrongStrandNo 34 Non-positive strand serial number encountered.
Error_WrongNumberOfStrands 35 Contradiction in number of strands, derived from different categories of a mmCIF file for a given sheet.
Error_WrongSheetOrder 36 Incomplete category _struct_sheet_order in mmCIF file.
Error_HBondInconsistency 37 Inconsistency in category _struct_sheet_hbond in mmCIF file.
Error_EmptyResidueName 38 A PDB record from coordinate section does not have a residue name.
Error_DuplicateSeqNum 39 PDB records from coordinate section show the same sequence number and insertion code in the same chain assigned to more than one residue name.
Error_NoLogicalName 40 Logical file name was not found. This means that the corresponding environmental variable was not set properly.



Back to index