CCP4 Coordinate Library Project

RWBROOK interface functions: Error Handling and Return Codes.

Almost every RWBROOK interface function returns a code reporting on the success of the operation. Successful operation always returns RWBERR_Ok=0. An application may check the return code and branch the execution according to that.

In RWBROOK, serious problems are assigned negative return codes (error codes). A negative return generally (but not necessarily) implies that application may want to stop. In any event it means that a RWBROOK function, which returned such a code, has aborted its execution somewhere in the middle and the operation was not completed.

Less serious issues are referred to as warnings. Warning return codes are always positive and encoded as bits. One return may contain several warnings. Warnings generally do not suggest application to stop, and any RWBROOK function, which returned warning(s) guarantees that its execution was completed properly (at least from the point of system safety and stability).

RWBROOK interface provides two functions which automate the process of checking the return codes. These functions will suffice for most cases, so that there is no need to program error checker after each RWBROOK call and moreover, there is no need to go through all return codes.

The RWBROOK error checkers are:

RBErrStop
RBCheckErr

Full list of RWBROOK return codes:

Error Codes
Warning Codes

subroutine RBErrStop ( iPlace,iRet,iUnit,iStop )

PURPOSE:
Checks the return code got from one of the RWBROOK interface functions, and if it indicates an error, a message of the following type is issued:

*** RWBROOK error: point code unit function
*** 12 -3 3 XYZOpen
*** file : input.pdb
*** reason : cannot open a file
*** Execution stopped.

If there were no errors (iRet=RWBERR_Ok), the function does nothing.

PARAMETERS:

integer iPlace
should be given a number which is unique through an application; it serves for the identifying of the particular call which caused the problem. E.g., the above output example corresponds to the problem occured in point '12'.

integer iRet
return code issued by an RWBROOK interface function.

integer iUnit
number of channel used when the problem occured.

integer iStop
when iStop=0, the execution is termionated on error (iRet!=RWBERR_Ok). If iStop!=0 and there is an error, the following type of message is issued:

*** RWBROOK error: point code unit function
*** 12 -3 3 XYZOpen
*** file : input.pdb
*** reason : cannot open a file
*** continue running, may crash ...

and execution continues.

NOTE: RBErrStop will display the name of RWBROOK function encountered the problem (XYZOpen above) correctly if only called immediately after it.

Example: 

call XYZOpen ( FName,RWStat,FType,iUnit,iRet )
call RBErrStop ( 12,iRet,iUnit,0 )

subroutine RBCheckErr ( iPlace,iStop )

Represents a simplified call to RBErrStop. It will work correctly only if called immediately after an RWBROOK function. The meaning of parameters is exactly the same as for same-name parameters of RBErrStop.

Example: 

call XYZOpen ( FName,RWStat,FType,iUnit,iFail )
call RBCheckErr ( 12,0 )

RWBROOK Error Codes

The RWBROOK Error Codes are encoded in mmdb_rwbrook.h . They are not likely to change in the future, but nevertheless it is advisable for C and C++ programmers to use them by their names given below. FORTRAN developers are not given a chance other then to hardcode their numerical values.

Code Name Value Description
RWBERR_Ok 0 no problems
RWBERR_NoChannel -1 a major problem. The requested channel cannot be allocated in RAM. Most likely an application cannot proceed further.
RWBERR_NoFile -2 the requested channel was not associated with a file.
RWBERR_NoLogicalName -3 the file logical name is not found amongst defined environmental variables.
RWBERR_CantOpenFile -4 a file cannot be opened (I/O errors or wrong file name).
RWBERR_WrongInteger -5 wrong ascii format of an integer (being read from a file).
RWBERR_WrongModelNo -6 wrong model number (either non-positive or not incremented by 1 in a PDB file).
RWBERR_DuplicatedModel -7 duplicate model number (in a PDB file).
RWBERR_ForeignFile -8 format of input file cannot be automatically recognized.
RWBERR_WrongEdition -9 attempt to read a binary file which was created by a higher version of the Library. The binary files are not upward-compatible.
RWBERR_ATOM_Unrecognd -10 numerical information is not recognized on PDB's atom-related records (being read from a file).
RWBERR_ATOM_AlreadySet -11 duplicated information for the same atom found (in a file).
RWBERR_ATOM_NoResidue -12 no residue name was found for an atom (in a file).
RWBERR_ATOM_Unmatch -13 contradiction between several PDB records related to the same file ('ATOM', 'SIGATM', 'ANISOU', 'SIGUIJ').
RWBERR_NoAdvance -14 the internal channel pointer was not advanced when reading/writing atomic coordinates, or the pointer is out of range of atom indices.
RWBERR_EmptyPointer -15 the internal channel pointer points on empty place (no atom was allocated for a given atom index).
RWBERR_NoMatrices -16 coordinate transformation matrices were not calculated. Most probably, the cell parameters were neither set nor read from a file.
RWBERR_NoCoordinates -17 attempt to get atom coordinates from a channel where they were neither set nor read from a file.
RWBERR_Disagreement -18 essentially a warning: too large difference between newer and former cell parameters. Specifically, more than 10% change in the cell volume.
RWBERR_NoOrthCode -19 the orthogonalization code was neither set nor approprietly calculated.
RWBERR_NoCheck -20 the cell parameters were not properly checked. This should be fault of Library, rather then that of application.
RWBERR_NoCellParameters -21 the cell parameters were neither set nor read from a file.
RWBERR_NotACIFFile -22 the file requested to be read as a CIF file, does not appear as such.
RWBERR_NoData -23 no data was found in the file.
RWBERR_UnrecognCIFItems -24 input CIF file contains constructions which are not in complience with CIF syntax.
RWBERR_MissingCIFField -25 expected data field does not appear after data name in CIF file.
RWBERR_EmptyCIFLoop -26 an empty CIF loop encountered.
RWBERR_UnexpEndOfCIF -27 CIF loop or structure are improperly terminated by the end of file.
RWBERR_MissgCIFLoopField -28 wrong number of loop data fields in a CIF file.
RWBERR_NotACIFStructure -29 a CIF category was expected to be a structure, but appears to be a loop.
RWBERR_NotACIFLoop -30 a CIF category was expected to be a loop, but appears to be a structure.
RWBERR_WrongReal -31 wrong ascii format of a real (being read from a file).

RWBROOK Warning Codes

The RWBROOK Error Codes are encoded in mmdb_rwbrook.h . They are not likely to change in the future, but nevertheless it is advisable for C and C++ programmers to use them by their names given below. FORTRAN developers are not given a chance other then to hardcode their numerical values.

Code Name Value Description
RWBWAR_Warning 0x00004000 a general flag "this is a warning". If this flag is on and the return code is positive, then the return contains a warning.
RWBWAR_RewOutput 0x00004010 attempt to "rewind" or "backspace" an output channel. The requested operation is performed, however it is unusual.
RWBWAR_FileTop 0x00004020 attempt to "rewind" or "backspace" a channel with internal channel pointer already in the "before-the-first" position.
RWBWAR_WrongSerial 0x00004040 atom serial number is not equal to its index (position) in the channel. This means simply that atom serial number do not follow the strictly incremental-by-one order. In RWBROOK this is not exactly illegal, however against PDB convention.
RWBWAR_UnkFormFactor 0x00004080 atom formfactor cannot be recognized (when retrieving from a channel). This may indicates a problem with atom name or element type.
RWBWAR_AmbFormFactor 0x00004100 ambiguous atom formfactor encountered (when retrieving from a channel). This may indicates a problem with atom name or element type.
RWBWAR_NoOccupancy 0x00004200 atom occupancy factor is not found (when retrieving from a channel).
RWBWAR_NoTempFactor 0x00004400 atom isotropic temperature factor is not found (when retrieving from a channel).

Back to index

AltStyle によって変換されたページ (->オリジナル) /