CCPLIB (CCP4: Library)

NAME

DESCRIPTION

ccplib contains various low-level utility routines which are potentially machine-dependent. It is built on Unix-specific code which is found in unix.m4 and library.c (for Unix systems), and on VMS-specific code which is found in vms.for and vmsdiskio.for (for VMS systems).

Contents of this file

• General information
  • Using the pre-processor in programs
  • Initialisation
  • Program termination
  • File opening
  • Version printing
  • Skeleton example CCP4 program
• List of subroutines
• Description of the subroutines

General information

Using the pre-processor in programs

To use the pre-processor in existing code you will need to add a call to the routine CCPFYP as the first executable statement in the program. This routine performs all the pre-processing and should be called before any other CCP4 library routines.

Initialisation

Fortran programs should call the routine CCPFYP initially (see "USING THE PRE-PROCESSOR"), allowing one to run them using the mechanism

        <program> hklin <file> hklout <file> ...

Program Termination

There should be no STOP statements within the code; rather, call the subroutine CCPERR. This has the form

        CALL CCPERR( <num> '<string>')

        CALL CCPERR(0, 'Normal termination')

To terminate a program because an error has been detected use

        CALL CCPERR(1, '<string>')

CCPERR can also be used to send 'warnings' (CCPERR level 2) and messages (CCPERR level 3).

File opening

There should be no OPEN statements in Fortran code. Instead call CCPDPN for general files, and appropriate library routines for the standard data formats (MTZ, PDB, CCIF, CCP4 maps etc).

Use the normal Fortran CLOSE to close files opened with CCPDPN. The standard data formats have specific library routines for closing files which should be used in preference to CLOSE in those cases.

Version printing

The version of the CCP4 library being used can be queried using the CCP4_VERSION routine. The program version number may be different, and can be set (and later retrieved) using CCP4_PROG_VERSION. A call to CCPVRS will output a banner including this version information. The comand line switch -i can also be used to get program and version information.

Skeleton example CCP4 program

      PROGRAM <name>
      <declarations>
C define the program version
      CALL CCP4_PROG_VERSION('7.2',0)
C call the pre-processor:
      CALL CCPFYP
C advertise the version:
      CALL CCPRCS(LUNSTO(1), '<name>', '$Date: 2001/04/24 14:39:40 $')
C open an input file:
      CALL CCPDPN(IN1, 'INFILE1','READONLY','F','F')
      .
      .
      .
C close the file
      CLOSE(IN1)
      CALL CCPERR(0, 'Normal termination')
      END

List of subroutines

Descriptions of the Subroutines

SUBROUTINE CCFILL(ARR1,SCAL,NTIMES)

Set specified number of elements of byte array

ARR1	(o)	(byte)	array to which bytes are to be copied
SCAL	(i)	(byte)	byte value to be copied into ARR1
NTIMES	(i)	(integer)	the number of bytes to be copied

SUBROUTINE CCP4_VERSION(VERSION)

Return current CCP4 version as string

VERSION

(o)

(character*(*))

current version of CCP4 suite

SUBROUTINE CCP4_PROG_VERSION(VERSION,IFLAG)

Set or retrieve program version as string

VERSION	(i/o)	(character*(*))	version of individual program
IFLAG	(i)	(integer)	if 0 then set version using VERSION argument, else if 1 then return version in VERSION argument

SUBROUTINE CCPALC(ROUTNE, N, TYPE, LENGTH)

Arrange to call subroutine ROUTNE with N array arguments each of length LENGTH (i) and type indicated by TYPE (i): 'i' == integer, 'r' == real, 'd' == double precision, 'c'==complex. TYPE elements may have either case. The calling of ROUTNE and allocation are performed by the machine dependant routine CCPAL1 (UNIX library.c, VMS vms.for, MVS w32mvs.f). Consider

        call ccpalc (fred, 3, types, lens)

with types = (/'i', 'r', 'c'/) and lens = (/1000, 2000, 3000/). This effectively does

       call fred (1000, arr1, 2000, arr2, 3000, arr3)

with

        subroutine fred (n1, foo, n2, bar, n3, baz)
               integer n1, n2, n3, foo (n1)
               real bar (n2)
               complex baz (n3)
               ...

Obviously all communication with ROUTNE must be by COMMON (or, possibly, extra ENTRYs). The allocated memory is freed on return from ROUTNE. As a concession, it's initially filled with zeroed bytes.

ROUTNE	(i)	(external)	routine to call
N	(i)	(integer)	number of arguments to ROUTNE (<=12)
TYPE	(i)	(character*1 (*))	type of arguments to ROUTNE: 'I': INTEGER 'R': REAL 'D': DOUBLE PRECISION 'C': COMPLEX
LENGTH	(i)	(integer*(*))	number of elements in each (array) argument of ROUTNE

SUBROUTINE CCPALE(ROUTNE, N, TYPE, LENGTH, LENDEF)

Arrange to call subroutine ROUTNE with N array arguments each of length LENGTH (i) and type indicated by TYPE (i): 'i' == integer, 'r' == real, 'd' == double precision, 'c'==complex. TYPE elements may have either case. LENGTH points to an array of environment variable (logical) names from which integer values are read, CCPE2I. The lengths default to values from LENDEF. This is a convenient interface to CCPALC to allow configuring of the memory requirements on the command line where appropriate. This may be useful if the memory requirements can't be determined initially and it's necessary to guess.

ROUTNE	(i)	(external)	routine to call
N	(i)	(integer)	number of arguments to ROUTNE (<=12)
TYPE	(i)	(character*1 (*))	type of arguments to ROUTNE: 'I': INTEGER 'R': REAL 'D': DOUBLE PRECISION 'C': COMPLEX
LENGTH	(i)	(character*(*))	logical names representing the number of elements in each (array) argument of ROUTNE
LENDEF	(i)	(integer (*))	default lengths for the argument arrays used if the appropriate LENGTH argument doesn't represent a defined logical
PRINT	(i)	(logical)	whether or not to print the values of the array lengths

SUBROUTINE CCPBYI(IA,IBYT,NB)

Copy array of unsigned (or signed) bytes into integer array
To be implemented if CCPBYT == .TRUE. [for LAUE program?].

IA	(o)	(integer)	array to return integer values
IBYT	(i)	(byte)	array holding byte data (may be an integer array, for example, with data packed into adjacent bytes).
NB	(i)	(integer)	if >0, the number of unsigned bytes to be copied if <0, -the number of signed bytes to be copied

LOGICAL FUNCTION CCPBYT(NBW)

Indicate whether byte handling is available. Used in maplib.
NOTE: is assumed to be available (.TRUE., NBW=4).

NBW (o) (integer)

Returns CCPBYT	== .TRUE.	byte handling and associated ccplib routines available (assumed).
	== .FALSE.	no byte handling available.