CCP4 Coordinate Library Project

RWBROOK interface functions: Data Exchange Between the Channels and Application.
Exchange of Atom Data.


INDEX:
XYZAtom1
XYZCoord1
XYZSetTer
XYZSetHet


subroutine XYZAtom1 ( iUnit,iSer,AtNam,ResNam,ChnNam,
                      iResN,ResNo,InsCod,AltCod,
                      SegID,IZ,ID,iRet )
PURPOSE:
Reads (from input channels) or writes (into output channels) the atom name, residue name, chain name and other listed parameters. The channel iUnit must be opened in the corresponding input/output mode with function XYZOpen or XYZOpen1 (see also XYZSetType). The internal channel pointer must previously be set on the atom's position in the channel with function(s) XYZAdvance1, XYZRewd, XYZBksp or XYZSeek.

PARAMETERS:

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

integer iSer
atom's serial number. Ideally but far from always, it coincides with the position of atom in the channel. The coincidence will be always assured if the channel was open for input with autoserial regime set on. The parameter is used for both input and output but it is never taken as the actual position of atom in the channel. The actual position is adjusted by functions XYZAdvance1, XYZRewd, XYZBksp or XYZSeek.

character*(*) AtNam
left-justified atom name. In order to align the field correctly on a PDB card, the ID parameter should be properly supplied. The parameter is used for both input and output.

character*(*) ResNam
residue name. No checks against dictionaries is done by RWBROOK. In a PDB file, this is a 3-character string. CIF files potentially may contain longer residue names. The parameter is used for both input and output.

character*(*) ChnNam
chain name. In a PDB file, this is always a 1-character string. CIF files may contain longer chain names. The parameter is used for both input and output.

integer iResN
residue sequence number given as an integer. The parameter is used for both input and output.

character*(*) ResNo
residue sequence number given as a string. The parameter is used only for input (retrieving information from a channel) and is left for compatibility with former rwbrook.f.

character*(*) InsCod
residue insertion code. Known examples include only 1-character values. The parameter is used for both input and output.

character*(*) AltCod
the alternate conformation code (1-character string). The parameter is used for both input and output.

character*(*) segID
segment ID, normally a 4-character string (CIF files potentially may contain longer identifiers). The parameter is used for both input and output.

integer IZ
atomic number as calculated from atom name and element type. If the calculation fails, 7 is returned. The parameter is used only for input (retrieving information from a channel) and is left for compatibility with former rwbrook.f.

character*(*) ID
atomic ID, composed as 2-character element name (' C', 'Ca', ' F', 'Fe' and so on) plus the ionic state (e.g. '+2', '-3' etc.). The parameter is used for both input and output.

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. XYZAtom1 may return RWBERR_NoChannel or RWBERR_EmptyPointer as an error code.

Non-negative return codes contain bit-encoded warnings. XYZAtom1 may set the following warning flags:

RWBWAR_WrongSerial
the serial number differs from the atom's position number in the file (quite a common case)
RWBWAR_UnkFormFactor
unknown formfactor has been met
RWBWAR_AmbFormFactor
ambiguous formfactor encountered

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

XYZAtom1 replicates function XYZAtom from former rwbrook.f. The information is merely passed between the Library and application, with a little bit of calculations for parameters IZ and ID (input only). If atom position was not properly adjusted in input channel, iRet will return RWBERR_EmptyPointer. For output channels, the atom data given will replace any existing data that might have been previously output at a given channel pointer (e.g. if the output is being made into channel opened first for input and then redirected for output). NOTE that the regim of transferring the data by XYZAtom1 is solely determined by the channel input/output mode set in XYZOpen or XYZOpen1 (see also XYZSetType).

 


subroutine XYZCoord1 ( iUnit,XFlag,BFlag,x,y,z,occ,BIso,U,iRet )

PURPOSE:
Reads (for input channels) or writes (for output channels) the atom coordinates, occupancy and temperature factor. The channel iUnit must be opened in the corresponding input/output mode with function XYZOpen or XYZOpen1 (see also XYZSetType). The internal channel pointer must previously be set on the atom's position in the channel with function(s) XYZAdvance1, XYZRewd, XYZBksp or XYZSeek and the atom identification data must be already stored with XYZAtom1 if channel iUnit is opened for output.

PARAMETERS:

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

character*(*) XFlag
a key specifying in which coordinate system (fractional or orthogonal) the atom coordinates x, y and z should be received (for input channels) or are given for output (for output channels). XFlag='O' means coordinates are exchanged in orthogonal system, XFlag='F' sets the regime of fractional coordinates. In the case of output channel, XFlag may also take the values of 'HF' and 'HO' where 'F' and 'O' have the former meaning, and 'H' indicates that the atom should be marked as "Het-atom" (in PDB notation).
NOTE: using the fractional coordinate system requires that the crystallographic information be loaded into the channel. See more details here

character*(*) BFlag
a key specifying the units for the temperature factors. BFlag='O' stands for orthogonal units, and BFlag='F' - for fractional Us.
NOTE: using the fractional Us requires that the crystallographic information be loaded into the channel. See more details here

real*4 x,y,z
x, y and z- atomic coordinates either in orthogonal or fractional coordinate system as specified by parameter XFlag. The parameters are used for both input and output channels.

real*4 occ
the occupancy factor. The parameter is used for both input and output channels.

real*4 BIso
the isotropic temperature factor, either in orthogonal or fractional Us as specified by parameter XFlag. The parameter is used for both input and output channels.

real*4 U(6)
array of 6 reals of the anisotropic temperature factor, either in orthogonal or fractional Us as specified by parameter XFlag. The parameter is used for both input and output channels.
The anisotropic temperature factors are not always given. If only isotropic factor is known, U(1) receives its value, and all other elements of U are set to zero. This must be performed by application for output channels.

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. XYZCoord1 may return RWBERR_NoChannel (the channel was not opened), RWBERR_EmptyPointer (the ICP was not properly advanced), RWBERR_NoMatrices (the crystallographic information is absent) and RWBERR_NoCoordinates (coordinate information is missing) as an error code.

Non-negative return codes contain bit-encoded warnings. XYZCoord1 may set the following warning flags:

RWBWAR_NoOCcupancy
the occupancy factor is missing in the channel
RWBWAR_NoTempFactor
the isotropic temperature factor is missing in the channel
RWBWAR_AmbFormFactor
ambiguous formfactor encountered

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

XYZCoord1 replicates function XYZCoord from former rwbrook.f. The information is merely passed between the Library and application, with calculations for parameters x, y, z, BIso and U, if the corresponding fractional modes were specified. No calculations should be performed on the application side.

If atom position was not properly adjusted in input channel, iRet will return RWBERR_EmptyPointer. For output channels, this return will be issued also in the case if atom identification data (set by XYZAtom1) was not provided prior to the call of XYZCoord1. In output regime of the channel, the data given to XYZCoord1 will replace any existing data that might have been previously output at a given channel pointer (e.g. if the output is being made into channel opened first for input and then redirected for output). NOTE that the regim of transferring the data by XYZCoord1 is solely determined by the channel input/output mode set in XYZOpen or XYZOpen1 (see also XYZSetType).

An attention should be given to the length of real-type parameters. As a meter of standard, 4-byte real values are assumed. This is determined by the definition of apireal found in file mmdb_rwbrook.h of the Library. More likely than not, a mismatch in the length of real-type parameters passed between application and Library will lead to a crash.

 


subroutine XYZSetTer ( iUnit,iRet )

PURPOSE:
Sets the chain termination flag, so that the current atom will be converted into chain terminator and appear as ('TER') card in the output.

PARAMETERS:

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

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. XYZSetTer may return RWBERR_NoChannel (the channel was not opened) and RWBERR_EmptyPointer (the ICP was not properly advanced or atom identifying information was not set) as an error code.

REMARKS:

XYZSetTer does not have an analogue in former rwbrook.f. In RWBROOK interface, using this function is the only way to put chain terminator into channel.

NOTE that prior to using this function, the internal channel pointer should be advanced to the position of 'TER', the atom identification data should be stored with XYZAtom1 function (only the serial number, residue name, sequence number, insertion code and the chain name are important here), and only then this newly created atom may be converted into 'TER':

..........
call XYZOpen     ( 'XYZIN','OUTPUT','PDB',iUnit,iRet )
call RBCheckErr  ( 1,0 )
..........
iSer  = 0
iResN = 1
..........
call XYZAdvance1 ( iUnit,0,iRet )
call RBCheckErr  ( 2,0 )
iSer = iSer+1
call XYZAtom1    ( iUnit,iSer,'C','ALA','A',iResN,'----',
                   'F','-','----',0,'C',iRet )
call RBCheckErr  ( 3,0 )
call XYZSetTer   ( iUnit,iRet )
call RBCheckErr  ( 4,0 )
..........
call XYZClose    ( iUnit,iRet )
call RBCheckErr  ( 5,0 )

where we specified carbon for atom name and element type to avoid issuing any warnings on incorrect input. This example makes the following 'TER' card:

TER   4151       ALA A 431F

if iSer=4151 and iResN=431.

Note that the coordinate information (XYZCoord1) does not have to be set for converting atom into a chain terminator.

 


subroutine XYZSetHet ( iUnit,iRet )

PURPOSE:
Sets the heteroatom flag, so that the current atom will appear as 'HETATM' card in the output.

PARAMETERS:

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

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. XYZSetHet may return RWBERR_NoChannel (the channel was not opened) and RWBERR_EmptyPointer (the ICP was not properly advanced or atom identifying information was not set) as an error code.

REMARKS:

XYZSetHet does not have an analogue in former rwbrook.f. In RWBROOK interface, the "Het-atom" flag may also be set by XYZCoord1 function.

NOTE that prior to using this function, the internal channel pointer should be advanced to the position of 'TER', the atom identification data should be stored with XYZAtom1 function AND the atom coordinates should be provided with XYZCoord1 and only then this newly created atom may be converted into 'HETATM':

..........
call XYZOpen     ( 'XYZIN','OUTPUT','PDB',iUnit,iRet )
call RBCheckErr  ( 1,0 )
..........
iSer  = 0
iResN = 1
..........
call XYZAdvance1 ( iUnit,0,iRet )
call RBCheckErr  ( 2,0 )
iSer = iSer+1
call XYZAtom1    ( iUnit,iSer,'CA','ALA','A',iResN,'----',
                   'F',' ','A1',0,'C',iRet )
call RBCheckErr  ( 3,0 )
call XYZCoord1   ( iUnit,'O','O',x,y,z,occ,BIso,U,iRet )
call RBCheckErr  ( 4,0 )
call XYZSetHet   ( iUnit,iRet )
call RBCheckErr  ( 5,0 )
..........
call XYZClose    ( iUnit,iRet )
call RBCheckErr  ( 6,0 )

The following example does exactly the same:

..........
call XYZOpen     ( 'XYZIN','OUTPUT','PDB',iUnit,iRet )
call RBCheckErr  ( 1,0 )
..........
iSer  = 0
iResN = 1
..........
call XYZAdvance1 ( iUnit,0,iRet )
call RBCheckErr  ( 2,0 )
iSer = iSer+1
call XYZAtom1    ( iUnit,iSer,'CA','ALA','A',iResN,'----',
                   'F',' ','A1',0,'C',iRet )
call RBCheckErr  ( 3,0 )
call XYZCoord1   ( iUnit,'HO','O',x,y,z,occ,BIso,U,iRet )
call RBCheckErr  ( 4,0 )
..........
call XYZClose    ( iUnit,iRet )
call RBCheckErr  ( 5,0 )

 


Back to index