CCP4 Coordinate Library Project

RWBROOK interface functions: Manipulations with the Internal Channel Pointer.

GENERAL REMARKS

Once a channel is opened for input or output (cf. XYZOpen and XYZOpen1), it automatically gets an internal channel pointer (ICP), hidden from the application. Initially it points on "before-the-begining" of the channel. This pointer is used to scan atoms in the channel. Before reading the atom's data (e.g., the coordinates), the ICP should be advanced to the needed atom. Similarly, for writing the atom's data, the ICP should be set onto appropriate position in the channel.

Each atom and each PDB 'TER' card occupy a separate position in the channel. There is no individual positions for other PDB coordinate-related records ('MODEL', 'SIGATM', 'ANISOU', 'SIGUIJ' and 'ENDMDL' ). Instead, all information read from these records, is assigned to the corresponding atom and is placed in its position in the channel. Once ICP is advanced to that position, all this information is ready for reading (input channels) or writing (output channels).

For historical reasons, rwbrook.f used the data structure peculiar to PDB files. Although this structure has little in common with that of CIF and binary files, the RWBROOK interface eliminates these differences for the application. RWBROOK functions will work uniformly on all files that can be read by XYZOpen and XYZOpen1).

INDEX OF ICP-RELATED FUNCTIONS:

XYZAdvance1
XYZRewd
XYZBksp
XYZSeek

integer iUnit

the channel number. It must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

integer iTer

a flag specifying the response on PDB 'TER' card for channels opened in input mode (cf. XYZOpen and XYZOpen1). If iTer is set to 1, then iRet returns 1 if the internal channel pointer advances to a 'TER' card. If iTer is set to 0 then XYZAdvance1 does not return on 'TER' card at all and the internal channel pointer automatically advances to the first atom of next chain.

integer iRet

the return code. Negative return code means an error. The error return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. XYZAdvance1 may return RWBERR_NoChannel or RWBERR_NoAdvance as an error code.

Non-negative return codes have the following meaning:

Value	Description
0	( =RWBERR_Ok) successful advancement of the internal channel pointer; RWBROOK is ready to retrieve or store the atom's data.
1	the internal channel pointer has been advanced to a PDB 'TER' card. This return is only available if parameter iTer was set to 1. If iTer was set to 0, then any PDB 'TER' card is neglected and the internal channel pointer advances automatically to the next atom.
2	the 'end-of-file' has been reached. This return is only available for channels opened in input mode. It means that the internal channel pointer is in the region beyond the very last atom in the channel.
3	successful advancement of the internal channel pointer to the next atom in the channel, which appeared to be a Het-atom in the PDB notation (a 'HETATM' PDB card has been encountered).

DESCRIPTION:

If channel iUnit is associated with input, XYZAdvance1 will set the internal channel pointer on the next atom in the file. The atom properties may then be retrieved using XYZAtom1 and XYZCoord1. Note that immediately after opening a channel (cf. XYZOpen and XYZOpen1) the internal channel pointer is set to "before-the-first" position, which means it has to be advanced once to get access to the first atom in the channel.

If channel iUnit is associated with output, XYZAdvance1 merely advances the internal channel pointer. No actual change in the data structure or on disk occurs. The new position will be filled with atom data only after execution of XYZAtom1 and/or XYZCoord1. NOTE that the internal channel pointer WILL NOT be advanced if neither of these functions was called since previous advancement. If this is the case, iRet will return RWBERR_NoAdvance. This mechanism prohibits a non-sequential writing of coordinate data into output channel: output positions cannot be skipped. After successfull advancement, iRet will return RWBERR_Ok.

Note that this function is slightly different from its analogue in former rwbrook.f. The following code gives the link between the former XYZAdvance and XYZAdvance1:

subroutine XYZAdvance ( iUnit,iOut,iTer,*,* )
integer       iRet
character*80  ErrLin
  call XYZAdvance1 ( iUnit,iTer,iRet )
  if (iRet.eq.1)  return 1
  if (iRet.eq.2)  return 2
  if (iRet.eq.RWBERR_NoChannel) then
    ErrLin = ' ERROR: in XYZADVANCE file has not been opened'
    call CCPErr ( 1,ErrLin )
  endif
  return
end

Thus, parameter iOut (channel for echoing the input header lines) IS NOT USED. The header lines may be output into a separate channel, if absolutely necessary, with the following code:

call XYZOpen    ( 'XYZIN','INPUT','PDB',iUnit,iRet )
call RBCheckErr ( 1,0 )
...........
call XYZOpen    ( 'XYZOUT','OUTPUT','CIF',iOut,iRet )
call RBCheckErr ( 2,0 )
call XYZCopy    ( iOut,iUnit,3,iRet )
call RBCheckErr ( 3,0 )
call XYZClose   ( iOut,iRet )
call RBCheckErr ( 4,0 )

integer iUnit

the channel number. It must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

integer iRet

the return (error) code. Return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. XYZRewd may return RWBERR_Ok or RWBERR_NoChannel. If the channel was opened for output, iRet will return a warning RWBWAR_RewOutput.

REMARKS:

After a call to XYZRewd the internal channel pointer is set into "before-the-first" position, which means that it should be advanced once (cf. XYZAdvance1) in order to get access to the first atom in the channel. NOTE that the file is not physically re-read, unlike it happened in former rwbrook.f.

integer iUnit

the channel number. It must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

integer iRet

the return (error) code. Return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. XYZBksp may return RWBERR_Ok or RWBERR_NoChannel. If the channel was opened for output, iRet will return a warning RWBWAR_RewOutput. An attempt to backspace from the "before-the-first" position will cause warning RWBWAR_FileTop and the ICP will remain in its position.

REMARKS:

After a call to XYZBksp the internal channel pointer shifts for one position back. Thus, combination of XYZBksp and XYZAdvance1 leaves the ICP unchanged unless a) the ICP was not in either the topmost or downmost position and b) XYZAdvance1 was not set to skip the 'TER' cards.

NOTE that PDB 'TER' card occupies an individual position in the channel. Note also that backspacing in RWBROOK interface is computationally a very cheap operation in contrary to that in former rwbrook.f.

integer iUnit

the channel number. It must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

integer fPos

position, into which the internal channel pointer should be set. "Position" is merely a serial number of either 'ATOM', 'HETATM' or 'TER' card, which is calculated at ignorance of all other cards in PDB file. In an ideal PDB file, "position" is exactly the atom's serial number. Be aware that, more often than not, this rule is violated.
The "before-the-first" position corresponds to 0. If fPos is set to 0, iRet will return warning RWBWAR_FileTop.

integer iRet

the return code. Negative returns correspond to an error. The error return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. XYZSeek may return RWBERR_Ok, RWBERR_NoChannel or RWBERR_EmptyPointer. The latter is issued if fPos-th position is not occupied by either atom or 'ter' data in the channel.

Non-negative returns are identical to those of XYZAdvance1 and are as follows:

Value	Description
0	( =RWBERR_Ok) successful setting of the internal channel pointer; RWBROOK is ready to retrieve or store the atom's data.
1	the internal channel pointer has been set onto a PDB 'TER' card. Unlike XYZAdvance1, 'TER' cards cannot be automatically skipped in XYZSeek.
2	the pointer came beyond the last atom (or 'TER' card) in the file.
3	the internal channel pointer is set onto a Het-atom in the PDB notation ( on a 'HETATM' PDB card).

REMARKS:

XYZSeek was not present in former rwbrook.f. It should provide an efficient addressing to arbitrary atoms in the channel. However, figuring out the atom position may be confusing.