CCP4 Coordinate Library Project

RWBROOK interface functions: Data Exchange Between the Channels.


INDEX:
XYZCopy
XYZDelete


subroutine XYZCopy ( iUnit1,iUnit2,copyKey,iRet )

PURPOSE:
Copies the specified data from channel iUnit2 into channel iUnit1. The function does not append the data, which means that e.g. the coordinates in iUnit1 are disposed prior copying the coordinates from iUnit2. If however a particular type of data is not to be copied, it remains untouched in the destination unit (iUnit1) provided it was there. For example, crystallographic information remains unchanged in iUnit1 if only coordinates are to be copied from iUnit2.

PARAMETERS:

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

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

integer copyKey
a copy key specifying which type of data should be copied. The valid values are:

Value Description
1 copy all content of channel iUnit2
2 copy all except coordinates
3 copy title section only (PDB records HEADER, OBSLTE, TITLE, CAVEAT, COMPND, SOURCE, KEYWDS, EXPDTA, AUTHOR, REVDAT, SPRSDE, JRNL, REMARK, REMARK n)
4 copy crystallographic information section only (PDB records CRYST1, ORIGXn, SCALEn, MTRIXn, TVECT )
5 copy coordinate section only (PDB records MODEL, ATOM, SIGATM, ANISOU, SIGUIJ, TER, HETATM, ENDMDL )

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. XYZCopy may return RWBERR_Ok, RWBERR_NoChannel or RWBERR_NoFile.

REMARKS:

If value of copyKey is not in the valid range, the function does nothing. If data of the requested type are not present in the source channel iUnit2, the function does nothing but disposal of this type of data in the destination channel iUnit1; no warnings are issued.

IMPORTANT NOTICE:  in difference of the former rwbrook.h, the new RWBROOK interface does not share the crystallographic information between all opened channels, but rather keeps it local to every channel. It is therefore important for an application to explicitely take care of providing the crystallographic information to all channels where required.

For example, if an application needs to read fractional coordinates from channel iUnit1, and then store them into newly opened channel iUnit2 then the crystallographic information is to be provided for channel iUnit2 for proper backward conversion from fractional to orthogonal coordinates. This may be achieved as follows:

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

Crystallographic information may also be loaded from a file. The following example illustrates this possibility; here we switch off reading the coordinates for channel iUnit2 in order to save time and to keep the coordinate space in channel iUnit2 empty and ready to accept coordinate data from iUnit1:

call XYZOpen       ( 'XYZIN','INPUT','PDB',iUnit1,iRet )
call RBCheckErr    ( 1,0 )
...........
call SetReadCoords ( 0 )
call XYZOpen       ( 'XYZIN','INPUT','PDB',iUnit2,iRet )
call RBCheckErr    ( 2,0 )
call SetReadCoords ( 1 )
call XYZSetType    ( iUnit2,'CIF','OUTPUT',iRet )
call RBCheckErr    ( 3,0 )
call XYZSetName    ( iUnit2,'outfile.cif',iRet )
call RBCheckErr    ( 4,0 )
This approach is definitely less eleghant, plus it does not allow to use the logical file name 'XYZOUT' for the output file. Note also that, in 2nd example, channel iUnit2 gets loaded with header and other information from the PDB file as well (everything but coordinates is read in), which is not always desirable.

 


subroutine XYZDelete ( iUnit,delKey,iRet )

PURPOSE:
Deletes the specified data in channel iUnit.

PARAMETERS:

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

integer delKey
a key specifying which type of data should be deleted. It may take the same values as copyKey in XYZCopy, for specifying the same types of data to be deleted.

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. XYZCopy may return RWBERR_Ok, RWBERR_NoChannel or RWBERR_NoFile.

REMARKS:

If value of delKey is not in the valid range, the function does nothing. If data of the requested type are not present in the channel iUnit, the function does nothing; no warnings are issued.

 


Back to index