Quick reference guide for writing/building
                           an ANALYSIS_CONTROL job
                             KLOE Memo No. 19

                                 Flavia Donno
                                 14 July 1994
			    Last update, 14-01-1996



To have some ideas about what ANALYSIS_CONTROL is and how it works, please 
read the pages 1 to 10 of the A_C Introductory Manual :
    http://www.lnf.infn.it/kloe/private/offline/manuals/a_c/a_c.txt


1) To write an A_C module, divide your job in different tasks, thinking
   about what you want to have done at program initialization, run
   initialization, at each event, at run end, at program end. Write a
   subroutine for each task taking as skeleton the example below.
   All modules for the analysis of the Calorimeter Test Beam Data should
   reside in K$MOD, while the executables should be put in K$EXE.

C       =======================================================
C       MYMODU - Example A_C Module to process test beam events
C       =======================================================
C
C       Language:-
C       ==========
C       KLOE Fortran
C       
C       Modulename:-
C       ============
C       MYMODU.KLOE
C
C       Description:-
C       ==============
C       This file contains all the routines necessary for performing
C       my analysis of the Test Beam data.
C       The routines included are:
C
C       MYMDIN          Initialization routine executed at start of the job
C       MYMDRI          Run Initialization
C       MYMDEV          Executed for each event.
C       MYMDRF          Run End.
C       MYMDFI          Program End routine.
C       MYMDTK          Talk to Routine
C
C
C       Author:-
C       ========
C       XXXXXXXXXXXXXX
C       KLOE Group
C
C       Creation Date: XXXXXXXXXXXX
C       ===========================
C
C
        SUBROUTINE MYMDIN
C       =================
C
C       Description:-
C       =============
C       This routine is called at program initialisation time.
C
C       Call Parameters:-
C       ================
C       None
C
C       Return Parameters:-
C       ===================
C       None
C
C       Function Value:-
C       ================
C       None
C
C       Global Declarations:-
C       =====================
C
$$IMPLICIT
$$Include 'Ybos$library:Errcod.Inc'
$$Include 'K$Inc:Bcs.Inc'
C
C       External Functions:-
C       ====================
        INTEGER BLOCAT
C
C       Local Declarations:-
C       ====================
        INTEGER STATUS,I
        INTEGER IND, INDDAT
C
C       Locate the MY Bank
C       ==================
        STATUS = BLOCAT(IW,'MYBK',1,IND,INDDAT)
        IF(INDDAT.GT.0 .AND. STATUS .EQ. YESUCC)   THEN
C
C          Bank Found
C          ==========
           WRITE(6,*) 'Bank found'
        ELSE
C
C          Error:- No bank found
C          =====================
           WRITE(6,*) 'Bank not found!'
        ENDIF
C
C       Return to Caller
C       ===============
        RETURN
        END
C
        SUBROUTINE MYMDRI
C       =================
C
C       Description:-
C       =============
C       This routine is called at run initialisation time.
C
C       Call Parameters:-
C       ================
C       None
C
C       Return Parameters:-
C       ===================
C       None
C
C       Function Value:-
C       ================
C       None
C
C       Global Declarations:-
C       =====================
C
$$IMPLICIT
C
C
C       External Functions:-
C       ====================
C	None
C
C       Local Declarations:-
C       ====================
C       None
C
        WRITE(6,*) ' This is a new run'
C
C       Return to Caller
C       ===============
        RETURN
        END
C
        SUBROUTINE MYMDEV
C       =================
C
C       Description:-
C       =============
C       This routine is executed everytime a new event is read in.
C
C       Call Parameters:-
C       ================
C       None
C
C       Return Parameters:-
C       ===================
C       None
C
C       Function Value:-
C       ================
C       None
C
C       Global Declarations:-
C       =====================
C
$$IMPLICIT
C
$$Include 'K$Inc:BCS.Inc'
C
$$Include 'K$Inc:Jobsta.Inc'
C
C       External Functions:-
C       ====================
C	None
C
C       Local Declarations:-
C       ====================
C       None
C
C       Executable Code:-
C       =================
C
C       Print out the event and run number
C       ==================================
	WRITE(6,*) 'The  run  number is: ',NRUN
	WRITE(6,*) 'The event number is: ',NEV
C
C       Return to Caller
C       ===============
        RETURN
        END
C
        SUBROUTINE MYMDRF
C       =================
C
C       Description:-
C       =============
C       This routine is called at run termination.
C
C       Call Parameters:-
C       ================
C       None
C
C       Return Parameters:-
C       ===================
C       None
C
C       Function Value:-
C       ================
C       None
C
C       Global Declarations:-
C       =====================
C
$$IMPLICIT
C
C       External Functions:-
C       ====================
C	None
C
C       Local Declarations:-
C       ====================
C	None
C
	WRITE(6,*) 'This is the end of the run'
C
C       Return to Caller
C       ===============
        RETURN
        END
C
        SUBROUTINE MYMDFI
C       =================
C
C       Description:-
C       =============
C       This routine is called at program termination.
C
C       Call Parameters:-
C       ================
C       None
C
C       Return Parameters:-
C       ===================
C       None
C
C       Function Value:-
C       ================
C       None
C
C       Global Declarations:-
C       =====================
C
$$IMPLICIT
C
C       External Functions:-
C       ====================
C
C       Local Declarations:-
C       ====================
C
C
C       Return to Caller
C       ===============
        RETURN
        END
C
C
	SUBROUTINE MYMDTK
C	=================
C
C	Description:-
C	=============
C	This talk_to routine prompts the User to choose
C	an option.
C
C       Call Parameters:-
C       ================
C       None
C
C       Return Parameters:-
C       ===================
C       None
C
C       Function Value:-
C       ================
C       None
C
C
C	Global Declarations:-
C	=====================
C
$$IMPLICIT
$$INCLUDE 'K$INC:ERLEVL.INC'
$$INCLUDE 'YBOS$LIBRARY:ERRCOD.INC'
$$INCLUDE 'UIPACK$LIBRARY:UINAMES.INC'
$$INCLUDE 'UIPACK$LIBRARY:UIPARAM.INC'
$$INCLUDE 'UIPACK$LIBRARY:UIERROR.INC'
$$INCLUDE 'A_C$LIBRARY:ANERROR.INC'
$$INCLUDE 'K$INC:BCS.INC'
$$INCLUDE 'K$INC:JOBSTA.INC'
$$INCLUDE 'K$INC:LOGUNI.INC'
$$INCLUDE 'S_I$LIBRARY:NoArgInc.Inc'
$$INCLUDE 'T_B$LIBRARY:TBInpD.Inc'
C
C	External Declarations:-
C	=======================
C
      INTEGER BLOCAT
      INTEGER ANPIST
C
C	Local Declarations:-
C	====================
C
      INTEGER IND,INDDAT
      INTEGER GROUP,MENUID,I
      INTEGER STATUS,FILLEN
      CHARACTER*128 FILNAM
      CHARACTER*40 VERB
C
C	Executable Code:-
C	=================
C
      STATUS = BLOCAT(IW,'$TBM',1,IND,INDDAT)
      IF (STATUS .NE.YESUCC) THEN
         CALL ERLOGR('TBRMTK',ERWARN,0,
     &               STATUS, 'Cannot locate menu bank $TBM')
	 STATUS = ANPIST(ANYBER)
	 RETURN
      ENDIF
      GROUP = IW(INDDAT)
      MENUID = IW(INDDAT+1)
C
 1000 CONTINUE
      STATUS = UIUSGP(GROUP,N$A)
  10  STATUS = UIACME(MENUID,VERB,N$A)
      IF (STATUS.EQ.UIABRT) RETURN
C
C     Process the DISK choice
C     =======================
      IF(VERB.EQ.'DISK') THEN 
          IW(INDDAT+2) = TBDISK		! Disk File
	  CALL TRNLOG('TBRMINP',FILNAM,STATUS)
	  STATUS = UIGTFI('File Name ',FILNAM,FILLEN,N$A)
          IF (STATUS .EQ. UISUCC .OR. STATUS .EQ. UIDFLT) THEN
             CALL CRELOG('TBRMINP',FILNAM(1:FILLEN),STATUS)
          ENDIF
          GO TO 1000 
C
C     Process the TAPE choice
C     =======================
      ELSE IF(VERB.EQ.'TAPE') THEN
          IW(INDDAT+2) = TBTAPE		! Tape File
          GO TO 1000           
C
C     Process the BUFFER choice
C     =========================
      ELSE IF(VERB.EQ.'BUFFER') THEN
          IW(INDDAT+2) = TBBUFF		! Buffer Manager Global Section
          GOTO 1000
C
C     Process the HELP choice
C     =======================
      ELSE IF(VERB.EQ.'HELP') THEN
          CALL UISIIN('HELP')
          CALL UIGTHE('Topic')
          GOTO 1000
C
C     Process the DEFAULT choice
C     ==========================
      ELSE IF(VERB.EQ.'DEFAULT') THEN 
           IW(INDDAT+2) = TBDISK	! Disk File
           GOTO 1000
C
C     Process the SHOW choice
C     =======================
      ELSE IF(VERB.EQ.'SHOW') THEN 
         WRITE(6,*) 'The option chosen is:'
         WRITE(6,*) '====================='
         IF (IW(INDDAT+2) .EQ. TBDISK)
     &      WRITE (6,*) '   The input comes from the disk file : ',
     &                                             FILNAM(1:FILLEN)
         IF (IW(INDDAT+2) .EQ. TBTAPE) 
     &      WRITE (6,*) '   The input comes from the tape : '
         IF (IW(INDDAT+2) .EQ. TBBUFF) 
     &      WRITE (6,*) 
     &   '   The input comes from Buffer Manager Global Section'
         GOTO 1000
C
C     Process the RETURN choice
C     =========================
      ELSE IF(VERB.EQ.'RETURN') THEN 
         RETURN 
      ENDIF    
C
      END


Note on the $$ directives:
--------------------------
   The file above should have the extension .KLOE. A .KLOE file is a fortran
   file which has "EXPAND" directives in it. The EXPAND directives start with
   $$ on the first column. They are needed to write "machine independent"
   code. So, for instance, if the OPEN statement is different on UNIX and
   on the VAX you can write:

$$IF UNIX
C
C	Open statement for UNIX
C
...
$$ ELSE
C
C	Open statement for the VAX
C
...
$$ENDIF
  
  Then the command:

% expand -option=FORTRAN-comment=source mymodu.kloe

  will produce a FORTRAN file for the machine where the command above is
  executed.        

  "Machine independent" include files should be named *.CIN.

2) Once the A_C module has been written, you need to declare your module
   to A_C. You do so writing a file called mymodu_job.uic which looks
   like the following:

!
!  This is the BUILD_JOB Command File for the A_C job which uses
!  the MYMODU Module.
!
!
Set Names/Entrypoint=32         ! Set up for long name entry points
!
! Define the TBRM Input Module instead of the normal YBOS one.
!
Define tbrmim/declare=tbrmdc/Input
!
! Declare MYMODU to A_C.
!
Define MYMODU/Descrip="My Modulefor Test Beam Data Analysis"
!
	Declare="MYMDDC",
        Init="MYMDIN",
        Run_Init="MYMDRI", 
	Event="MYMDEV",
        Run_Fin="MYMDRF",
        Fini="MYMDFI",
        Talk="MYMDTK"
OK
!
! Set the size of the YBOS array to be 200000 words (200000*4 bytes)
!
Set size/ybos = 200000
Set size/database=0
!
! Set HBOOK4 off - we do not do histograms here.
!
Set utilities/hbk4 = off
!
! Link the modules TBRMIM and MYMODU into this job.
!
!==============================================================================
 link TBRMIM MYMODU
!==============================================================================
!
! Show what we have done
!
  show link
!
! Write out the BUILD_JOB file
!
 Write MYMODU_JOB.KLOE
!
! The End
!
 quit
OK

% build_job mymodu_job.uic

3) The command above generates a .KLOE file. You have to EXPAND and
   compile your MYMODU.KLOE and the file generated by BUILD_JOB:

% expand -option=FORTRAN-comment=source mymodu.kloe
% expand -option=FORTRAN-comment=source mymodu_job.kloe
% for mymodu.f mymodu_job.f

4) To Link your job, create an option file (mymodu.opt) containing the 
   following lines:

mymodu_job.o
mymodu.o

   Note: You could also avoid compiling your fortran files and the
         next command (link_ana) will do it for you. The flags used
         by link_ana in compiling your files are the same defined
	 by the "for" alias.

   Note: You can pass compilation flags to link_ana passing them as
         first line in your option file.

5) Link with the following command:

% link_ana $K_EXE/mymodu.exe $K_MOD/mymodu.opt no

  The command above will produce an executable called mymodu.exe in the
  directory pointed to by the environmental variable $K_EXE taking as input 
  the option file mymodu.opt in the directory pointed to by the env $K_MOD.
  If you do not pass arguments to link_ana, it will prompt you for arguments.
  Link_ana makes some checks. For instance, if the option file does not
  exist, link_ana aborts.

If you have questions, please contact flavia@hpcalc.lnf.infn.it.