ccp4 lib

     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: 2005/05/17 12:44:59 $')
C open an input file:
      CALL CCPDPN(IN1, 'INFILE1','READONLY','F','F')
      .
      .
      .
C close the file
      CLOSE(IN1)
      CALL CCPERR(0, 'Normal termination')
      END

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 copiedSCAL(i)(byte)byte value to be copied into ARR1NTIMES(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 programIFLAG(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.

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 CCPALCto 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 callN(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': COMPLEXLENGTH(i)(character*(*))logical names representing the number of elements in each (array) argument of ROUTNELENDEF(i)(integer (*))default lengths for the argument arrays used if the appropriate LENGTH argument doesn't represent a defined logicalPRINT(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 valuesIBYT(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 the number of bytes per word or a value of 1 if no byte handling is available (4).

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

SUBROUTINE CCPCPI(IA,IB,MINEL,MAXEL,ITYP)

Copy an array of BYTE or INTEGER*2 elements into an integer array. NB is bytewise operation
To be implemented if CCPBYTfunction returns .TRUE. [for LAUE program?]

IA(o)(integer (*))to return valuesIB(i)(integer (*))holding data with data packed into adjacent BYTE or INTEGER*2 elements (in routine is byte)MINEL(i)(integer)Minimum element to copyMAXEL(i)(integer)Maximum element to copyITYP(i)(integer)Type =1 unsigned byte
=2 signed byte
=3 unsigned two byte integer
=4 signed two byte integer

Note: if MINEL > MAXEL elements will be copied in reverse order

SUBROUTINE CCPDAT(CALDAT)

Get calendar date

CALDAT(o)(character*8)variable returning date as dd/mm/yy (returned as a blank string if not available).

SUBROUTINE CCPDEX(INDX,N)

Periodicity reduction of 1024 [for PROLSQ]

INDX(i/o)(integer)array holding numbers for periodicity reductionN(i)(integer)no. of elements in INDX

SUBROUTINE CCPDPN(IUN,LOGNAM,STATUS,TYPE,LREC,IFAIL)

Calls CCPOPNto open a file, but with mnemonic arguments.

IUN(i) (integer)unit numberLOGNAM(i) (character*(*))logical file nameSTATUS(i) (character*(*))file status flag'UNKNOWN''SCRATCH''OLD''NEW''READONLY''PRINTER'TYPE(i) (character*(*))file type flag='F', 'SEQUENTIAL' 'FORMATTED'='U', 'SEQUENTIAL' 'UNFORMATTED'='DF', 'DIRECT' 'FORMATTED'='DU', 'DIRECT' 'UNFORMATTED'LREC(i) (integer)record length for direct access file (no. of characters for a formatted file or words for an unformatted file).
Not relevant for a sequential file.IFAIL(i/o) (integer)on input=0, stop on open failure=1, continue after open failure (only on file not found)on outputunchanged if file open OK=-1, error in opening file

INTEGER FUNCTION CCPE2I (NAME, DEFVAL)

Return an integer extracted from environment variable NAME. If NAME isn't defined, use DEFVAL as the default. If the value of NAME isn't a representation of an integer, abort.

NAME(I)(character *(*))DEFVAL(I)(integer)

SUBROUTINE CCPERR(ISTAT,ERRSTR)

Report error or normal termination and stop. Also reports latest system error iff ISTAT<0.

ISTAT(I)(integer)exit status (0 for normal termination, 1 for fatal error)ERRST(I)(character)*(*)message

LOGICAL FUNCTION CCPEXS(NAME)

Test if file or file assigned to logical name exists

NAME(i) (character*(*))file name/logical name

Returns CCPEXS ==.TRUE. if file exists.FALSE. if file does not exist

SUBROUTINE CCPFYP

Set up the environment in which the program runs (environ.def, default.def locations, etc) and then parses the command line arguments.

Note: A call to CCPFYP should be the first executable statement in ccp4 programs.

SUBROUTINE CCPGI2(IVAL,IA,N)

Get unsigned integer*2 value from 0 to 65535 from N'th unsigned integer*2 element of array.
To be implemented if CCPBYT== .TRUE. Used in density modification routines.

IVAL(o)(integer)returned integer values from 0 to 65535IA(i)(integer*2(*))array from which the unsigned INTEGER*2 value is to be retrievedN(i)(integer)position in 'IA' where the unsigned INTEGER*2 value is to be retrieved

SUBROUTINE CCPGTB(IVAL,IA,N)

Get unsigned byte value from 0 to 255 from N'th byte of array.
To be implemented if CCPBYT== .TRUE. Used in density modification routines.

IVAL(o)(integer)the returned integer value from 0 to 255IA(i)(byte(*))array from which the byte value is to be retrievedN(i)(integer)position in IA where the byte value is to be retrieved

SUBROUTINE CCPI2I(IA,I2,NE,SIGNED,SWAPB)

Copy an array of INTEGER*2 elements into an integer array.
To be implemented if CCPBYT== .TRUE. [for LAUE program?]

IA(o)(integer(*))Array to return INTEGER valuesI2(i)(integer*2)Array holding INTEGER*2 data (may be an INTEGER array for example with data packed into adjacent INTEGER*2 elements).NE(i)(integer)The number of elements to be copiedSIGNED(i)(logical)==.TRUE. Copy as signed INTEGER*2 values
==.FALSE. Copy as unsigned INTEGER*2 valuesSWAPB(i)(logical)==.TRUE. Swap bytes in the INTEGER*2 elements
==.FALSE. Do not swap bytes

SUBROUTINE CCPIBY(IBYT,IA,NB)

Copy array of integers into array of bytes. NOTE: No overflow checking is done (least significant figures only stored).
To must be implemented if CCPBYT== .TRUE. [for LAUE program?]

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

SUBROUTINE CCPII2(I2,IA,NE,SIGNED,SWAPB)

Copy array of integers into array of INTEGER*2 elements. NOTE: No overflow checking is done.
To be implemented if CCPBYT== .TRUE.) [for LAUE program?]

I2(o)(integer*2)Array returning INTEGER*2 data (may be an INTEGER array for example with data packed into adjacent INTEGER*2 elementsIA(i)(integer(*))Array holding INTEGER valuesNE(i)(integer)The number of elements to be copiedSIGNED(i)(logical)==.TRUE. Copy as signed integer*2 values
==.FALSE. Copy as unsigned integer*2 valuesSWAPB(i)(logical)==.TRUE. Swap bytes in the integer*2 elements
==.FALSE. Do not swap bytes

SUBROUTINE CCPLWC(STRING)

Convert a text string to lower case in situ

STRING(i/o)(character*(*))

SUBROUTINE CCPMDE(MODE,NBYT)

If byte handling is available then this subroutine returns the number of bytes per data item for the different modes used, in particular, in the map handling subroutines. [is routine actually called? no reference in map routines]
NOTE. byte handling is assumed to be available with 4 byte/word, see CCPBYT.

MODE(i)(integer)= 0, bytes
= 1, short (2 byte) integers
= 2, real/integer (single word)
= 3, short complex (2 * 2 byte integers)
= 4, complex (two words)NBYT(o) (integer)>0,CCPBYT == .TRUE. number of bytes infor the MODECCPBYT == .FALSE. number of words= 0, no value available for this mode= -1, invalid mode

Typical values:1 2 4 4 8if byte handling available with 4 bytes/word0 0 1 0 2if byte handling unavailable

SUBROUTINE CCPMVB(ARR1,I1,ARR2,I2,NTOMOV)

Move bytes from one non-character array to another if byte handling is available (assumed available).
[is routine actually called? no reference in map routines]

ARR1(i/o)(byte(*))Array to which bytes are to be copiedI1(i)(integer)The start byte number in ARR1 where bytes are to be copiedARR2(i)(byte(*))Array from which bytes are to be copiedI2(i)(integer)The start byte number in ARR2 from which the bytes are to be copiedNTOMOV(i)(integer)The number of bytes to be copied

SUBROUTINE CCPMVI(ARR1,ARR2,NUM)

Assign the first NUM words of ARR2 to ARR1

ARR1(o)(integer(*))ARR2(i)(integer(*))NUM(i)(integer)

SUBROUTINE CCPMVR(ARR1,ARR2,NUM)

Assign the first NUM words of ARR2 to ARR1

ARR1(o)(real(*))ARR2(i)(real(*))NUM(i)(integer)

INTEGER FUNCTION CCPNUN()

Return a currently unconnected i/o unit number. Use this to select an arbitrary unit for i/o to avoid clashes with other code. (The value returned will be the same until the unit in question is OPENed or a lower-numbered one is CLOSEd.)

LOGICAL FUNCTION CCPONL(IDUM)

See if program is being run interactively if this information is available. Tests if ft06 is tty.

IDUM(i)(integer)Dummy parameter

Returns.TRUE.if program is being run on-line.FALSE.if batch mode or status unknown

SUBROUTINE CCPPSF(FILNAM,PATH,NAME,TYPE,VERS)

Parse file name into components
Note: This routine contains machine dependent code

FILNAM(i)(character*(*))file name string (no embedded blanks assumed)PATH(o)(character*(*))returns path or, for VAX VMS the part of the file specification up to the end of the directory specification (includes terminating ] or : or /)
(blank if none)NAME(o)(character*(*))returns name (blank if none)TYPE(o)(character*(*))returns file type/extension (blank if none)VERS(o)(character*(*))returns the version (blank if none)

After the removal of the path and version parts of the string then, if there is at least one dot, the name is the string up to the last dot remaining and the type is the part of the string after the dot. If no dot is present then the remaining string is the name and the type is blank.

SUBROUTINE CCPRCS(ILP,PROG,RCSDAT)

Print program name and date of current version (also prints run date if available).

Interface to CCPVRS passing date in dd/mm/yy format (DATE). Takes RCS-format date string, e.g. '$Date: 2005/05/17 12:44:59 $' or its form expanded with RCS option `-kv', as for a CVS export, in which case it will have the leading `$Date: 2005/05/17 12:44:59 $' stripped. Initially, RCSDAT should be '$Date: 2005/05/17 12:44:59 $'.
See the RCS documentation.

ILP(i)(integer)Unit number of printer outputPROG(i)(character*(*))Variable holding program name (max of 10 characters)VDATE(i)(character*(*))Character variable holding RCS date string

SUBROUTINE CSETNV(LNAME,FILNAM,ENAME,ETYPE,EXTN,ICOUNT,LSKIP)

Associate `logical name' LNAME with value FILNAM using an environment variable LNAME. It is passed arrays of (name, type, extension) for ICOUNT number of name lines read from environ.def. Doesn't re-define existing name if LSKIP is true.

LNAME(i)(character*(*))Logical name (environment variable).FILNAM(i)(character*(*))File name, if extension is omitted it is appendedENAME(i/o)(character(150)*20)list of environment variables; if LNAME is not in list it is appended (also to ETYPE & EXTN arrays).ETYPE(i/o)(character(150)*5)list of in/out types.EXTN(i/o)(character(150)*4)list of extensions.ICOUNT(i/o)(integer)lengths of arrays ENAME, ETYPE & EXTN.LSKIP(i)(logical)if .TRUE. existing name not re-defined.

SUBROUTINE CCPPAG(IUN,NCOL,NLIN)

Return the number of columns and lines for a printer output page on a given fortran unit number if the information is available

IUN(i)(integer)Fortran unit numberNCOL(o)(integer)number of columns in the pageNLIN(o)(integer)number of lines in the page

Note: Returns 80,132 unless output is terminal whence 0,80.

SUBROUTINE CCPSI2(IVAL,IA,N)

Store integer in N'th unsigned integer*2 element (range 0-65535) of an array. To be implemented if CCPBYT == .TRUE. Used in density modification routines.
Note: no overflow check is done.

IVAL(i)(integer)Unsigned integer value. Should be in range 0 to 65535IA(o)(integer*2(*))Array into which the unsigned INTEGER*2 value is to be insertedN(i)(integer)Position in IA where the unsigned INTEGER*2 value is to be inserted

SUBROUTINE CCPSTB(IVAL,IA,N)

Store integer value, from 0 to 255, into N'th byte of array. To be implemented if CCPBYT == .TRUE. Used in density modification routines.
Note: no overflow check is done.

IVAL(i)(integer)Unsigned integer, value from 0 to 255IA(o)(byte*2(*))Array into which the byte value is to be insertedN(i)(integer)Position in IA where the byte value is to be inserted

REAL FUNCTION CCPSUM(A,N,L)

Returns sum of every l'th element of a vector array

A(i)(real(N))Array to be summedN(i)(integer)dimension of the arrayL(i)(integer)sum every L'th element

SUBROUTINE CCPTIM(IFLAG,CPU,ELAPS)

Get CPU and Elapsed times

IFLAG(i/o)(integer)== 0, initialise
<> 0, return times (documented 1, also -1 for dummy call which is not implemented)CPU(o)(real)cpu time in secondsELAPS(o)(real)elapsed time in seconds

SUBROUTINE CCPTOI(ARRAY,N,II,ITYP,IFAIL)

Extract n'th byte or INTEGER*2 element from non-character (real) array to and store in an integer. It is used by the map file handling routines and must be implemented if map modes 0,1,3 or 5 are to be used.
Overflow check is performed.

ARRAY(i)(real(*))Real array containing the element to be extractedN(i)(integer)Number of element to be convertedII(i)(integer)extracted valueITYP(i)(integer)Conversion type=1, byte to integer=2, integer*2 to integerFAIL(i/o)(integer)On input=0, Stop if conversion not available
=1, Return from subroutine alwaysOn outputunchanged if conversion carried out=-1 if conversion not available

SUBROUTINE CCPUFL()

Suppress underflow error messages if required and if the facility is available.
(Currently dummy.)

SUBROUTINE CCPUPC(STRING)

Convert a string to upper case

STRING(i/o)(character*(*))String to be converted

SUBROUTINE CCPVRS(ILP,PROG,VDATE)

Print program version number and date header. Extended to include html tags.

ILP(i)(integer)Unit number of printer outputPROG(i)(character*(*))Variable holding program name (max of 10 characters)VDATE(i)(character*(*))Character variable holding date of the current version as dd/mm/yy

ENTRY CCPPNM(NAME)

Entry point in CCPVRS
Returns the program name previously set by CCPVRS (/CCPRCS); if that isn't set, use arg(0).

NAME(o)(character*(*))Program name

SUBROUTINE CCPZBI(ARR1,NUM)

Set NUM bytes of the array ARR1 to zero

ARR1(i/o)(byte(*))NUM(i)(integer)

SUBROUTINE CCPZI(IARR1,NUM)

Set NUM words of an integer array IARR1 to zero.

IARR1(i/o)(integer(*))NUM(i)(integer)

SUBROUTINE CCPZR(ARR1,NUM)

Set NUM words of a real array ARR1 to zero.

ARR1(i/o)(real(*))NUM(i)(integer)

CHARACTER FUNCTION FDIR(FILNAM)

Returns the directory part of a file name.
Uses CCPPSF.

FILNAM(i)(character*(*))filename

CHARACTER FUNCTION FEXTN(FILNAM)

Returns the extension of a file name.
Uses CCPPSF.

FILNAM(i)(character*(*))filename

CHARACTER FUNCTION FROOT(FILNAM)

Returns the root of a file name (file name minus an extension).
Uses CCPPSF.

FILNAM(i)(character*(*))filename

LOGICAL FUNCTION LITEND(IDUM)

Determine endianness. Assumes integer*4 as the default.

Returns.TRUE.if little endian (VAX, FX2800, Ultrix, Convex).FALSE.if big endian (IBM,IRIS,ESV)

INTEGER FUNCTION LENSTR(STRING)

Returns length of string to last non-space

STRING(i)(character*(*)

INTEGER FUNCTION LUNSTI(IDUM)

Returns the fortran standard input unit number (=5)

INTEGER FUNCTION LUNSTO(IDUM)

Returns the fortran standard output unit number (=6)

INTEGER FUNCTION NBITST(IWORD,LSB,NBITS)

Return the (unsigned) integer value held within a bit field in a word
[for LAUE program?]

IWORD(i)(integer)The word containing the bits to be examinedLSB(i)(integer)The least significant bit offset for the bit fieldNBITS(i)(integer)The number of bits in the bit field (Must be less than the word length)

SUBROUTINE NOCRLF(LINE)

Output LINE supressing cr/lf.

LINE(i)(character*(*))Line to output.

SUBROUTINE QPRINT(IFLAG,MSG)

Conditionally print information. Normally, MSG is printed iff IFLAG is not greater than the `reference' level for messages. This reference level is set to the value of IFLAG on the first call (which won't print anything).

IFLAG(i)(integer)debug level 0-9 higher numbers give more outputMSG(i)(character*(*))the output message itself

ENTRY QPRLVL(LEVEL)

Entry point in QPRINT
Returns the current `debug level' used by QPRINT in the integer output variable LEVEL.

SUBROUTINE STBITS (IWORD,LSB,NBITS,IVAL)

Set a bit field within a word to a given (unsigned) integer value
[for LAUE program?]

IWORD(i/o)(integer)The word in which the bits are to be setLSB(i)(integer)The least significant bit offset for the bit fieldNBITS(i)(integer)The number of bits in the bit field (must be less than the word length)IVAL(I)(integer)The unsigned integer value to be set in the bit field (The user should ensure that this value will fit within the requested bit field)

LOGICAL FUNCTION CCPLIC(NAME)

Returns TRUE if it finds evidence that the CCP4 license
has been agreed to. It call CCPERR (1) (fail) if not.

NAME(i)(character*(*))Which license to test for. Only CCP4 currently works.