Using BUILD JOB

The BUILD_JOB program is used to create several subroutines needed by ANALYSIS_CONTROL.

1. The routine ANSTUP initialises the primary YBOS array, as well as the YBOS arrays used for calibration, histogram and user interface packages. (It also optionally can initialise blank common, which is used by HBOOK3 or PAWC used by HBOOK.) The fact that BUILD_JOB is used to write this routine means the user can painlessly change the size of these YBOS arrays, thus tailoring them to meet his analysis needs.

2. The routines XXDECL are the "module declaration routines." Each routine defines a single module to ANALYSIS_CONTROL. These routines tell the driver what subroutines to call for each of the allowed entrypoints described in section 2.2.

3. The routine ANDECL specifies what modules the user wishes to include in his program. This routine calls the appropriate XXDECL routines and thus forces the correct code to be linked.

setup build_job <version>

and then type the command build_job. (Note: BUILD_JOB and ANALYSIS_CONTROL are automatically set up if the user executes the CDF offline setup.)

Once inside the program, the user has many options. For example, he can override the choice of utilities to be initialised, or change the default size of the YBOS arrays associated with these utilities. By default, BUILD_JOB initialises YBOS, UIPACK, HBOOK and the Calibration and RunConditions Databases. A given utility can be deactivated by typing:

SET UTILITY/<Utility Name>=OFF

or can be activated (for read access) by typing

SET UTILITY/<Utility Name>=ON

In addition, a given database will be initialised for write access if the user types

SET UTILITY/<Database Name>=WRIT

The storage size allocated to any active utility can be changed using the SET SIZE command. A user that is happy with the default utilities and sizes need not execute any of the above commands.

In order to tell BUILD_JOB what modules exist, the user specifies the name of a dictionary (or dictionaries) that describe the modules. A dictionary is read wheneveer the user gives the command:

DICTIONARY <Filename>

where Filename is the name of the dictionary file and where the default file extension (if no other is specified) is .UIC. Note on UNIX systems a file extension must be used. We now have a number of standard dictionaries. These dictionaries reside in the C$DIC directory of the CDF offline package. To determine what dictionaries are currently available on your machine, look in this area.

In order to include or define his own module to BUILD_JOB the user must either DEFINE the module interactively or provide his own DICTIONARY file. An example interactive BUILD_JOB session is provided in Appendix C of CDF-386. We will concentrate here on the case where the module is defined using a dictionary file.

The following is an example of dictionary file. Those wishing to use this file as a template for their own dictionary file can copy it from C$DIC:EXAMPLE_DICT.UIC:

!
!       **  Example dictionary definition file  **
!
!       The module is named MYANA, and it uses histograms
!       with id's in the range 1:100.
!
!       BUILD_JOB should write a subroutine defining the
!                 module and call this routine MYDECL
!       The run initialisation routine is called MYRINI
!       The event analysis is done in subroutine MYEVT
!       The run termination subroutine is MYRFIN
!       The histograms are booked in the routine MYBOO
!       The program initialisation is done by MYINIT
!       The "TALK_TO" routine for the module is MYTALK
!       The program termination routine is MYFINI
!       The abnormal termination routine is MYABTM
!       The routine to be called for unusual record types is MYOTHR 
!
!       Define the module:
!
Define MYANA/Descrip="My analysis module"/Hist=1:100
!
!       Specify the subroutines in the module:-
!
!       Note: The line Declare="MYDECL" tells BUILD_JOB
!       that the declaration subroutine it writes should
!       be called MYDECL
!
               Declare="MYDECL",
               Run_Init="MYRINI",
               Event="MYEVT",
               Run_Fin="MYRFIN",
               Book="MYBOO",
               Init="MYINIT",
               Talk="MYTALK",
               Finish="MYFINI",
               Abnorm="MYABTM",
               Other="MYOTHR"
!
!       Tell BUILD_JOB that the definition is done
!
OK
!       **  End of file  **

1. Lines starting with ! are comments and are ignored by the BUILD_JOB program.

2. A user does not need to include in the dictionary file any reference to entry points he does not use. For example, if the module does not have a program initialisation entry point, the line
   

   Init="MYINIT",
   

   should be omitted from the file. (Note: There is one exception to this rule: BUILD_JOB expects to find an event entrypoint. To tell the program that no such entrypoint exists, the user must explicitly type Event=" ")

3. A number of module definitions can be put in a single file. The command OK tells BUILD_JOB that the definition of a give module is complete. This command must be given after each definition.

4. Warning: By default, BUILD_JOB only recognises six character entrypoint names. Users who wish to use longer subroutine names MUST execute the command:
   

   SET NAMES/ENTRYPOINT=<max characters>

   BEFORE reading their dictionary file.

LINK <Module_Name> <Module_Name>

tells BUILD_JOB to create the code needed to make an executable image that contains only the two modules specified. (Note: the standard input and output modules used to read events from a file and to write events to a file are always linked by ANALYSIS_CONTROL. The user does not need to specify them in his BUILD_JOB session.)

When the user has finished specifying his analysis needs, the code necessary for his job is written to a file using the WRITE command, which will prompt the user for a filename. alternately, the file is written when the user types EXIT. The default name for this file is BUILD_JOB.CDF. (Users wishing to end a session without producing a file should type QUIT.)