YPATCHY

The complete functionality of PATCHY is described in the PATCHY reference manual [5]. An introductory guide is given in the Patchy for beginners guide [6].

Rather than attempt to describe all of the features of PATCHY here, we will take the specific example of the HBOOK package.

To install HBOOK, two files are required. These are the HBOOK source file, typically kept in /cern/pro/src/car/hbook.car on Unix systems at CERN, and the so-called cradle.

The cradle for HBOOK, in /cern/pro/src/car/hbook.cra, is as follows.

Cradle for the installation of HBOOK

+EXE.
+USE,*HBOOK,$PLINAME.
+ASM,24.
+USE,QXNO_SC ,T=I,IF=QX_SC.
+USE,QX_SC   ,T=I,IF=QXNO_SC.
+USE,QXCAPT  ,T=I,IF=QXNO_SC,QX_SC.
+PAM,11,T=C,A.$CERN_ROOT/src/car/hbook
+QUIT.

Other cradles may be more complicated, but this will help describe the basic ideas. Let us examine each line of this cradle in turn.

1. +EXE.

   This tells YPATCHY to write out all 'material', typically source code, that has been selected. The material is written to the so-called Assembled Material file, or ASM file for short. Different streams exist for various types of material, as described below. They are all initially connected to the default stream on unit 21.

2. +USE,*HBOOK,$PLINAME.

   This, and other +USE statements, select the material of interest. Multi-level selection is possible. For example, *HBOOK will trigger all of the things in the hbook.car file in the PATCH *HBOOK.

   $PLINAME is set by the installation procedures. Typically, it is the machine type, e.g. DECS for DECstation, IBMRT for RS6000 etc.

   By convention, an asterix is used to indicate a so-called pilot patch, which will contain other +USE statements. The flags selected by $PLINAME are normally used to select machine specific features, as shown below.

   Flagging machine specific features using PATCHY

   +SELF,IF=IBMRT.
   *
   *     RS 6000 specific code
   *
   +SELF.
   

   The same effect can be achieved using the C preprocessor, as is shown below.

   Flagging machine specific features with C preprocessor statements

   #ifdef IBMRT
   
   /* RS 6000 specific code
    */
   
   #endif /* IBMRT */
   

3. +ASM,24.

   This tells PATCHY to establish a new output stream. By default, all material will be written to the stream 21, which is automatically initialised and does not require a +ASM directive to establish it. There are rules/conventions as to which streams are used for what:

   21

   Fortran

   22

   assembler

   23

   data

   24

   c

   31

   diverted Fortran

   ...

   The diverted streams are useful when different compilation options are required, e.g. static or noopt etc.

4. The next 3 +USE statements are to select the right sort of external names, typically for Fortran called C routines.

   The convention adopted is

   QX_SC

   external names are postfixed with an underscore, e.g. hbook1_. Most Unix systems append an underscore to external names in Fortran routines. On some systems, such as HP/UX and IBM RS6000, one must explicitly request this at compile time . The trailing underscore is typically used to avoid name clashes between C and Fortran run-time libraries.

   QX_NOSC

   no underscore

   QX_CAPT

   no underscore and uppercase

   Examples of styles of external names

   +SELF,IF=QXCAPT.
   int CDHSTC(hnf)
   +SELF,IF=QXNO_SC.
   int cdhstc(hnf)
   +SELF,IF=QX_SC.
   int cdhstc_(hnf)
   +SELF.
   char *hnf;
   

5. +PAM,11,T=C,A.$CERN_ROOT/src/car/hbook

   This directive tells PATCHY to read the 'card' format file which contains the HBOOK source.

6. +QUIT.

   All done.