CCP4 Coordinate Library Project

RWBROOK interface functions: Reading/Writing Files.


INDEX:
XYZOpen
XYZOpen1
AutoSerials
SetReadCoords
SimRWBROOK
XYZSetType
XYZSetName
XYZWrite
XYZClose


subroutine XYZOpen ( LName,RWStat,FType,iUnit,iRet )

PURPOSE:
Associates a coordinate file with channel number given in iUnit. If the file is to be opened for input, it is read and the hierarchical coordinate struicture is created in RAM.

PARAMETERS:

character*(*) LName
logical name of the file. This is name of the environmental variable (e.g. XYZIN or XYZOUT) containing the physical file name.

character*(*) RWStat
string 'INPUT' if the file is to be read, and string 'OUTPUT' if the file is to be written. If the channel is open for input, it is read and the coordinate hierarchy is created. If the channel is opened for output, an empty coordinate hierarchy is created in RAM.

character*(*) FType
string 'CIF' for mmCIF files and 'BIN' for the Library's portable binary file. Specifying an empty string ' ' will make the Library to attempt to identify the input file format automatically. In the case of output file, ' ' for file type means "use the format of the last read file on this channel or PDB if no files were read.

integer iUnit
the channel number; if zero than the channel number will be assigned automatically and returned in iUnit. If iUnit was previously associated with another or the same file, the file gets complete logical reinitialization, which means that all previous modifications to the file are lost unless stored on disk.

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.

Example:

iUnit = 0
call XYZOpen ( 'XYZIN','INPUT','PDB',iUnit,iRet )
if (iRet.ne.0)  then
  call XYZQuit
  write ( *,* )  'errors at reading the XYZIN file'
  stop
endif

 


subroutine XYZOpen1 ( FName,RWStat,FType,iUnit,iRet )

This function represents a slightly different version of XYZOpen.

The only difference is that first parameter must give the physical, rather than logical, file name. All other parameters and functionality are identical to those of XYZOpen.

NOTE:  CCP4 programs use logical file names.

 


subroutine AutoSerials ( iOnOff )

PURPOSE:
Switches On/Off the regime of automatic generation of atom serial numbers at reading from PDB ASCII file.

PARAMETERS:

integer iOnOff
non-zero: the autoserial regime is on, otherwise off. The setting will last until next call to AutoSerials for all channels in processing.

DEFAULT STATE:  Off.

DESCRIPTION:

When the autoserials regime is Off, all atom serial numbers in an input file are expected to be in strictly incremental order and any deviation from this rule will cause end of reading: XYZOpen will issue the RWBERR_AlreadySet error code. If this code is then passed to error checkers ( RBErrStop or RBCheckErr, the application will stop. It is Ok, however, for serial numbers to increment by 2 or more.

When the autoserials regime is On, XYZOpen does not pay attention to the serial numbers in the file and generates them for each atom on fly in a strict increment-by-one order. This will work correctly only if all atom records ('ATOM'/'HETATM', 'SIGATM', 'ANISOU' and 'SIGUIJ') are grouped for every atom as they ought to (precisely, 'ATOM' or 'HETATM' opens the group, then 'SIGATM', 'ANISOU' and 'SIGUIJ' should follow until next 'ATOM'/'HETATM' is encountered).

NOTE 1:  AutoSerials must be called before XYZOpen, whose behavior is to be affected.
NOTE 2:  the autoserials regime is one designed for reading imperfect PDB files. You don't have to use it if your PDB file is in due order.

 


subroutine SetReadCoords ( iOnOff )

PURPOSE:
Switches On/Off reading the atomic coordinates from a coordinate file.

PARAMETERS:

integer iOnOff
non-zero: the regime is on (coordinates are read), otherwise off. The setting will last until next call to SetReadCoords for all channels in processing.

DEFAULT STATE:  On.

DESCRIPTION:

The only purpose of this function is to save execution time and RAM when only e.g. crystallographic information is to be retrieved from a file.

NOTE:  SetReadCoords must be called before XYZOpen, whose behavior is to be affected.

 


subroutine SimRWBROOK ( iOnOff )

PURPOSE:
Switches On/Off the regime of exact following the old FORTRAN rwbrook.f's way of issuing the messages and warnings.

PARAMETERS:

integer iOnOff
non-zero: the regime is on (the old RWBROOK behavior is simulated), otherwise off. The setting will last until next call to SimRWBROOK for all channels in processing.

DEFAULT STATE:  Off.

DESCRIPTION:

This function is useful at converting CCP4 programs based on older rwbrook.h. When the simulation is On, RWBROOK will be issuing messages (info, warnings and errors) replicating those of older interface. As a result, the outlook of printout nearly does not change after converting.

 


subroutine XYZSetType ( iUnit,FType,RWState,iRet )

PURPOSE:
Changes the type and/or the read/write mode of channel iUnit, previously initialized with XYZOpen or XYZOpen1. The file is neither read from nor purged onto disk, and no change in data occurs.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the last mentioned (in the previous call to RWBROOK) channel number is taken.

character*(*) FType
the file type that should be assigned to the channel. This parameter has the same meaning and may take the same values as FType in XYZOpen or XYZOpen1 functions.

character*(*) RWState
the input/output mode that should be assigned to the channel. This parameter has the same meaning and may take the same values as RWState in XYZOpen or XYZOpen1 functions.

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. XYZSetType may return either RWBERR_Ok or RWBERR_NoChannel.

DESCRIPTION:

This function may be used for changing the format of output file. It must be used if a channel was initially open for input and its content is now to be stored on disk. Note that re-opening a channel with XYZOpen or XYZOpen1 would erase its content.

 


subroutine XYZSetName ( iUnit,FName,iRet )

PURPOSE:
Changes the file name for channel iUnit, previously initialized with XYZOpen or XYZOpen1. The file is neither read from nor purged onto disk, and no change in data occurs.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the last mentioned (in the previous call to RWBROOK) channel number is taken.

character*(*) FName
the new file name that should be associated with the channel. This parameter has the same meaning and may take the same values as FName in XYZOpen1 (not in XYZOpen) function.

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. XYZSetName may return either RWBERR_Ok or RWBERR_NoChannel.

DESCRIPTION:

This function should be used for writing coordinate data into a file different from that used for reading the data, if copying the data into another channel is not required.

 


subroutine XYZWrite ( iUnit,iRet )

PURPOSE:
Writes the content of channel iUnit into a disk file. The name of the file and its format are determined in calls to either XYZOpen/ XYZOpen1 or XYZSetType/ XYZSetName, whichever was the latest. No change in data occurs.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the last mentioned (in the previous call to RWBROOK) channel number is taken.

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.

DESCRIPTION:

This function should be used for writing the coordinate data into a file in the case if the data should be further modified and stored on disk again. An implicit (hidden) writing of the data is also done automatically when a channel, opened for output, is closed with XYZClose; see NOTE 2.

NOTE 1: it is perfectly legal to apply XYZWrite to channels opened for input! It will work properly.

NOTE 2: it is not a good practice to use both XYZWrite and XYZClose for channels opened for output. Although it will work correctly, XYZClose will rewrite the file over again: XYZWrite does not set any flag that the file was written. Therefore, if you are going "to write and dispose", use just

call XYZClose ( iUnit,iRet )

instead of

call XYZWrite ( iUnit,iRet )
call XYZClose ( iUnit,iRet )

 


subroutine XYZClose ( iUnit,iRet )

PURPOSE:
Closes the channel iUnit, which means that the data is disposed and iUnit is not a valid handle anymore. If the channel was opened for output, it is saved into a disk file prior to the disposal of the data. The name of the file and its format are determined in calls to either XYZOpen/ XYZOpen1 or XYZSetType/ XYZSetName, whichever was the latest.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the last mentioned (in the previous call to RWBROOK) channel number is taken. After the function returns, iUnit is no longer a valid channel number.

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.

DESCRIPTION:

This function should be used for disposal of any opened channel, when its content is no longer needed. Note that if the channel was opened for output, it will be purged onto disk before the disposal. Use XYZSetType to change the channel's input/output mode if you want to prevent this.

 


Back to index