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:
Full list of RWBROOK return codes:
subroutine RBErrStop ( iPlace,iRet,iUnit,iStop )
If there were no errors (iRet=RWBERR_Ok),
the function does nothing.
PARAMETERS:
and execution continues.
Example:
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:
*** RWBROOK error: point code unit function
*** 12 -3 3 XYZOpen
*** file : input.pdb
*** reason : cannot open a file
*** Execution stopped.
NOTE: RBErrStop will display
the name of RWBROOK function encountered the problem
(XYZOpen above) correctly if
only called immediately after it.
*** RWBROOK error: point code unit function
*** 12 -3 3 XYZOpen
*** file : input.pdb
*** reason : cannot open a file
*** continue running, may crash ...
call XYZOpen ( FName,RWStat,FType,iUnit,iRet )
call RBErrStop ( 12,iRet,iUnit,0 )
call XYZOpen ( FName,RWStat,FType,iUnit,iFail )
call RBCheckErr ( 12,0 )
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). |
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). |