This manual is aimed primarily at those people responsible for the installation of the CERN Program Library on systems at CERN or elsewhere. Some of the material is only relevent for the CERN Program Library section of the CN/ASD group at CERN.
Having read this manual you should be able to:
,
where the PATCHY flags are described and Appendix ,
where reserved routine and common block prefixes are listed.
The CERN Program Library is a large collection of general purpose programs maintained and offered in both source and object code form on the CERN central computers. Most of these programs were developed at CERN and are therefore oriented towards the needs of a physics research laboratory. Nearly all, however, are of a general mathematical or data-handling nature, applicable to a wide range of problems.
The library contains several thousand subroutines and complete programs which are grouped together by logical affiliation into several hundred program packages. 80%of the programs are written in FORTRAN and the remainder in assembly code, or C usually with a FORTRAN version also available. The language supported is currently Fortran 77.
Each package is assigned a unique code, consisting of a letter and three or four digits. The letter is used to indicate the category in which the program or package resides. A package consists of one or more related subprograms with one package name and one or more user-callable entry names, all described briefly in a Short write-up [1], and if necessary, an additional Long write-up. The terms under which the library material and associated documentation may be distributed are given below.
Distribution to organizations not covered by the above rests at the discretion of the Director-General. Machine readable copies of the documentation are provided with the library and recipients are free to make copies for their users. Paper copies of the documentation are made available for a charge which covers the printing and handling cost. Charging is waived for cumulative orders of less than 100 Swiss Francs.
If your organisation is expected to pay a fee as described above, it will be billed by CERN after the material has been shipped. Please include special billing address and instructions, if any, with the request.
As of the publication date of this document the member states of CERN are Austria, Belgium, Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Italy, The Netherlands, Norway, Poland, Portugal, Slovak Republic, Spain, Sweden, Switzerland and the United Kingdom.
States with Observer status are Israel, the Russian Federation, Turkey, Yugoslavia (status suspended after UN embargo, June 1992), the European Commission and Unesco.
Programs and documentation are provided solely for the use of the organization to which they are distributed, and may not be redistributed or reproduced in large numbers without the express agreement of CERN. Note that such agreement may have to be established somewhere else in addition to or instead of CERN in the case of programs originating from sources outside CERN. The appropriate Short Write-up gives information about authorship. The material cannot be sold. CERN should be given credit in all references, library documentation, and publications based on the programs.
If the programs are modified beyond what is necessary to adapt them to the local machine/system environment, it should be made clear in local documentation that they are locally modified versions of the CERN originals. CERN should be informed of such modifications, and given the possibility of introducing the same modifications in the original version. If local modifications are so important as to change significantly the behaviour of the program, its name should also be changed in order to avoid confusion with the original. CERN welcomes comments concerning the Program Library service, but undertakes no obligation for the maintenance of the programs, nor responsibility for their correctness, and accepts no liability whatsoever resulting from the use of its programs.
PATCHY is a source code management system that has been in use in High Energy Physics for many years. It is used for the maintenance, distribution and installation of almost all of the routines and packages that make up the CERN Program Library.
PATCHY and the associated auxiliary programs serve in development, maintenance, and inter-computer transport of source programs. Suitably structured source files containing several versions of a given program permit code selection and code modification (down to single-statement-level) by simple control cards to YPATCHY. Compacting and structuring of card files for efficiency (YTOBIN), maintenance of compacted files at the deck level (YEDIT), creation of machine-independent, transportable files (YTOCETA) and listing of compacted files (YLIST) and others are simple auxiliary operations in this environment.
Each of the PATCHY programs is a self-contained executable module.
On Unix machines at CERN, these are typically found in the directory
/cern/pro/bin.
FCASPLIT is a program that splits a file containing a mixture of routines in various languages, such as Fortran, C and Assembler (from whence the name is derived), into separate files. The file names are composed of the routine name with a suffix to identify the language, such as .f for Fortran etc. In addition, FCASPLIT will create both a shell script and a MakeFile, either of which may be used to compile the various routines. The default file extensions, listed below, are machine dependant.
The FCASPLIT header lines are automatically created by PATCHY on VMS and Unix machines for Fortran and C streams. The following PATCHY control statement shows how to request FCASPLIT header lines should they not be generated automatically.
Requesting FCASPLIT header lines
+ASM,34,R=! ./*DECK ID>, !.h */
Default file extensions (most Unix systems):
Header lines for FCASPLIT
CDECK ID>, in cols. 1-12 for Fortran
/*DECK ID>, in cols. 1-12 for C
;DECK ID>, in cols. 1-12 for assembler
DECK ID>, in cols. 2-12 or
DECK ID>, in cols. 3-12 for anything else
name in cols. 13-40 gives the name
In the last two cases, or if name contains an extension, the file created will be name without extension .f, .c or .s added to it and without an entry into the script.
Example input file to FCASPLIT
CDECK ID>, FMCLR.
SUBROUTINE FMCLR
INTEGER SYSTEMF
IC = SYSTEMF('clear')
END
/*DECK ID>, FMH.H*/
#define MAXNAME 8
#define MAXJOBN 8 /* Was 16 */
#define MAXHOST 8
#define MAXINFO 8 /* Was 16 */
/*DECK ID>, FAEXIT. */
void faexit_(icode)
int *icode;
\{
exit(*icode);
\}
Running FCASPLIT on this input file produces the following output files:
Output from FCASPLIT
::::::::::::::
faexit.c
::::::::::::::
/*DECK ID>, FAEXIT. */
void faexit_(icode)
int *icode;
\{
exit(*icode);
\}
::::::::::::::
fmclr.f
::::::::::::::
CDECK ID>, FMCLR.
SUBROUTINE FMCLR
INTEGER SYSTEMF
IC = SYSTEMF('clear')
END
::::::::::::::
fmh.h
::::::::::::::
#define MAXNAME 8
#define MAXJOBN 8 /* Was 16 */
#define MAXHOST 8
#define MAXINFO 8 /* Was 16 */
::::::::::::::
temp.mkfca
::::::::::::::
ROUTINES = fmclr.o faexit.o
.f.o:
xlf -c -O -qextname -qcharlen=8192 $*.f
.c.o:
cc -c -O $*.c
.s.o:
as $*.s
temp: $(ROUTINES)
::::::::::::::
temp.shfca
::::::::::::::
xlf -c -O -qextname -qcharlen=8192 fmclr.f
cc -c -O faexit.c
Example of running FCASPLIT on an RS6000
zfatal:/home/cp/jamie/fatmen (42) fcasplit fmkuip.f
FCASPLIT executing.
Input file : fmkuip.f
Shell script : fmkuip.shfca
Make file : fmkuip.mkfca
Fortran name : xlf
Fortran options : -c -O -qextname -qcharlen=8192
CC name : cc
CC options : -c -O
Assembler name : as
Assembler options :
10315 lines written for 63 decks
16 trailing comment lines ignored.
Example of running FCASPLIT on an HP
[csf] (358) /cern/pro/bin/fcasplit fmkuip.f
FCASPLIT executing.
Input file : fmkuip.f
Shell script : fmkuip.shfca
Make file : fmkuip.mkfca
Fortran name : f77
Fortran options : -c -O -w +ppu
CC name : cc
CC options : -c -O
Assembler name : as
Assembler options :
10315 lines written for 63 decks
16 trailing comment lines ignored
Makefile generated by FCASPLIT on an HP
[csf] (359) more fmkuip.mkfca
ROUTINES = fatmen.o fmcd.o fmclr.o fmcopc.o fmcpc.o fmdumc.o \
fmedit.o fmexit.o fmextr.o fmfc.o fmfndc.o fmgime.o fminic.o \
fmkadd.o fmkadt.o fmkatt.o fmkcpl.o fmkdst.o fmkend.o fmkloc.o \
fmkmod.o fmkmtp.o fmksrc.o fmkuwd.o fmld.o fmlogc.o fmlogn.o \
fmlsc.o fmmakc.o fmmkdr.o fmmvc.o fmpwd.o fmquit.o fmrmc.o \
fmrmdc.o fmrmtc.o fmrzld.o fmscat.o fmscpl.o fmsdst.o fmseac.o \
fmsloc.o fmsmdk.o fmsmtp.o fmssrc.o fmstat.o fmsuwd.o fmtagc.o \
fmtchc.o fmthrg.o fmtrek.o fmulcc.o fmupdc.o fmzoom.o zabend.o \
fmslcc.o fmlokk.o fmsupd.o fmlnc.o fmrmlc.o fmnikk.o fmskan.o \
fmklcc.o
.f.o:
f77 -c -O -w +ppu $*.f
.c.o:
cc -c -O $*.c
.s.o:
as $*.s
fmkuip_all: $(ROUTINES)
Shell script generated by FCASPLIT on an HP
[csf] (360) more fmkuip.shfca f77 -c -O -w +ppu fatmen.f f77 -c -O -w +ppu fmcd.f f77 -c -O -w +ppu fmclr.f f77 -c -O -w +ppu fmcopc.f f77 -c -O -w +ppu fmcpc.f f77 -c -O -w +ppu fmdumc.f f77 -c -O -w +ppu fmedit.f f77 -c -O -w +ppu fmexit.f f77 -c -O -w +ppu fmextr.f f77 -c -O -w +ppu fmfc.f f77 -c -O -w +ppu fmfndc.f f77 -c -O -w +ppu fmgime.f f77 -c -O -w +ppu fminic.f f77 -c -O -w +ppu fmkadd.f f77 -c -O -w +ppu fmkadt.f f77 -c -O -w +ppu fmkatt.f f77 -c -O -w +ppu fmkcpl.f f77 -c -O -w +ppu fmkdst.f f77 -c -O -w +ppu fmkend.f f77 -c -O -w +ppu fmkloc.f ...
CMZ is a source code management system that is compatible with PATCHY at the level of directives. Whereas PATCHY is oriented more to batch-like execution, CMZ provides also an interactive interface through which one may develop and install code. Most of the development performed by the CN/AS group is done using CMZ.
The complete CERN library requires approximately 200MB of disk space. Slightly over 50MB may be saved if the sources are not kept locally.
The purpose of the rules described below is to improve the quality of the CERNLIB software whilst reducing the support effort.
Material should preferably be submitted in one of the following formats:
If, for historical or other reasons, the standard flags cannot be used, an interface should be provided to ease the installation process.
The CERN Program Library team will provide a tool that will enable developers to request the installation of one or more packages in the DEV area.
The log files from such installations will be written into /afs.
A brief summary of the installation request will be returned by mail to the requestor.
The CERN Program Library team will provide a tool that will allow developers (and installers) to monitor the progress of the installation and see, in tabular form, what is installed in the DEV, NEW and PRO areas on the various platforms.
Packages may be moved from the DEV to NEW area provided that a few basic criteria are met.
Packages will normally only move into the PRO area when a Program Library Release is performed.
Any new features relative to the previous release should be documented.
Certain packages, such as event generators, which are not maintained by the CN/ASD group, may move into PRO at the discretion of the CERN Program Librarian.
Routines that are in the PRO area should not generate any compilation warnings.
Testing of new releases should be performed both by the CERN Program Library team (the standard tests) and the developers (new features).
New or updated test procedures should be given to the CERN Program Library team as appropriate.
Bug fixes to PRO will be made using PATCHY cradles.
The correction cradles must be relative to the current PRO version.
A test program which shows the effect of the bug (and fix) is to be provided.
A README file is to be provided.
Bug fixes will only be made if there is no reasonable workaround.
There shall normally be no less than two releases per calendar year and no more than four.
The approximate release date shall be announced (to HEPLIB and in the CERN news groups) at least two months in advance.
The approximate content shall be discussed and agreed at least one month in advance.
The exact content shall be discussed and agreed at least two weeks in advance.
The final versions of the various packages should be made available to the CERN Program Library team to permit installation in the public NEW area together with an appropriate announcement in the HEPLIB news group at least one week prior to the announced release date.
In the case of minor last minute corrections uncovered during user testing, the final code should be delivered at least one working day prior to the release.
In the event that such a deadline cannot be met, the CERN Program Librarian may decide to delay the release or to revert to a previous version of the package.
Packages or routines must in all cases be documented.
The documentation should preferably be marked up in LaTeX, using the cernman style.
Should this not be the case, a postscript file should be provided.
Whereever possible, the documentation should be made available online, using the World Wide Web.
The reference environment shall be defined by the so-called reference platforms installed in the CERN Computer Centre.
These platforms will define things such as the compiler release level, operating system level, versions and revision levels of various products etc., that are used to generate the CERN Program Library.
The Program Library source and binaries will be made available via a reference server, currently asis01.cern.ch.
Certain services in the CERN Computer Centre may decide to install private copies of the CERN Program Library (e.g. PARC, Shift, VXCERN).
These copies should in no way be considered to be the reference versions.
The CERN Program Library office will attempt to announce changes in the reference environment to HEPLIB at least 2 months in advance.
The supported platforms shall be defined by the reference platforms.
The CERN Program Library may decide to subcontract support for various operating systems or packages to outside institutes.
Platforms that are not in the reference environment nor subject to an agreement with an outside institute will be supported on a best-effort basis. Typically, this involves incorporating feedback from outside users who have installed the library on the appropriate platform (e.g. DESY for MVS).
The CERN Program Librarian reserves the right to accept ready-built packages for redistribution. In such cases the author is responsible for providing a tar file containing ready-built libraries and/or executables for all packages that they are prepared to support.