CCP4 Coordinate Library Project

RWBROOK interface: General Principles.

In RWBROOK interface, each data set (a content of the whole coordinate file) is associated with a single number -- a "channel" number. It may be viewed in quite a close analogy with FORTRAN input/output channel (unit) numbers used in FORTRAN operators read/write. In reality, however, it is merely a handle to a particular instance of the coordinate hierarchy. There is no principal limitation on the number of channels.

The coordinate file is read all at once when a channel is open for input. The coordinates of atoms may be then retrieved in a sequential manner, atom by atom, replicating the FORTRAN-style reading of 'ATOM' etc. cards from a PDB file. Unlike the older rwbrook.h, which physically read coordinates from a file each time they were requested, the new RWBROOK interface retrieves them from RAM. This eliminates inefficiency of older rwbrook.f in random accessing the coordinates; however all the process remains based on the notion of an "internal channel pointer" (ICP) running over atom indices. More details about ICP are found here.

Writing the coordinate file is imitated as a sequential process as well -- the atoms are added one by one to a coordinate hierarchy located in memory. The physical writing of the hierarchy into a file is done by issuing a special call or by closing the "channel".

The following important difference between the older rwbrook.f module and the newer RWBROOK interface should be realized:

rwbrook.f
shared the crystallographic information for all currently open channels.
RWBROOK interface
keeps the crystallographic information local to every channel.
It is therefore important that crystallographic information be copied from e.g. input channel to output channel, if the output goes along with transformation from fractional to orthogonal coordinates. Copying the crystallographic information is done with a single call to an interface function, and it is strictly advisable to perform this call (or otherwise set up the crystallographic information) whenever an output channel is opened. See more details here.

Technically, use of the library reduces simply to linking your code with mmdb.tar. On my Silicon Graphics, I do it as follows:

f77 fortcode.f ccode.c cppcode.cpp mmdb.a -lftn -lm -lc -lC

where fortcode.f, ccode.c and cppcode.cpp are sources of FORTRAN, C and C++ codes, correspondingly.