Module Entry-points

ANALYSIS_CONTROL allows user supplied code to be called under nine different circumstances. A module's author can supply "entry-points" to be called under any subset of these circumstances. These entry-points can be separate subroutines, ENTRY statements within a single subroutine, or a combination of the two. The allowed entry-points are:

1. Initialization
   The initialization entry-points for all linked modules are called once at the beginning of the program. These initialization routines can be used to set up default values or to initialize local arrays or control structures.

2. Run Initialization
   The run initialization entry-points for all active modules are called whenever a begin run or begin file record is encountered with a different run number than the previous run or when the run number changes. In addition, whenever the command BEGIN is used to start processing events, this entry-point is called. The run initialization entry-point can be used to zero run-oriented statistics, read run dependent databases or perform any other initialization that needs to be redone whenever event processing begins.

3. Event Analysis
   The event analysis entry-points for all active modules are called once for each event (excluding non-data logical records such as Begin run records, comment records, etc.) This entry-point is where most analysis is done. (Note: for online calibration, both event and calibration event records are sent to the event analysis entry-point.)

4. End Run
   The end run entry-points for all active modules are called when an end run record is encountered or when the run number changes. This entry-point is typically used to output run dependent information (as printout, as a file, or as a database entry). (Note: For calibration users, the end run entry point is called whenever the specified number of events has been processed so as to insure that a calibration database file is written. See Section 5.6 for details.)

5. Program Termination
   The termination entry-points for all linked modules are called once at the end of the analysis program. Uses of this entry-point include outputting final statistics and closing appropriate files or output devices.

6. Other Record
   The "Other record" entry-points for all active modules are called for all logical records that are not Event, Begin-Run or End-Run. This entry-point can be used to access such special records as comment and calibration. It is the author's responsibility to determine what logical record type is present. This can be done by unpacking the LRID bank, by using the offline common JOBSTA (which is defined in C$INC:JOBSTA.INC) or by using the fuction:
   

   STATUS = ANGRTY(RECTYP) or
   

   STATUS = ANALYSIS_GET_REC_TYPE(RECTYP)

   where RECTYP is the record type. (A list of possible record types can be found in RECTYP.CIN also in C$INC). STATUS is an integer error return that signals ANSUCC if the package is initialised properly. (The other possible error returns can all be found in A_C$LIBRARY:ANERROR.INC)

7. Talk_to
   The Talk_to entrypoint provides a means of accessing a user supplied subroutine on demand. This entrypoint is called when ANALYSIS_CONTROL detects the command (either interactively or from a command file):
   

   TALK_TO <Module_Name>

   One purpose of this entrypoint is to allow a mechanism for setting adjustable parameters within each module. Authors providing a Talk_to entrypoint for this purpose must supply the code that asks the appropriate questions (or displays the appropriate menu). Authors should use the UIPACK user interface routines for such IO (see CDF-372). In addition to protecting the program from invalid responses, the use of UIPACK means that the responses to questions asked by the Talk_to entrypoint can be driven from the same command file as the ANALYSIS_CONTROL dialog.

   Another use of the Talk_to entrypoint is to drop the user into non-event oriented modules. For example, we have a version of the CDF EVENT display program that can be linked to ANALYSIS_CONTROL. In order to enter it, the user types:
   

   TALK_TO DISPLAY

8. Histogram Booking
   ANALYSIS_CONTROL provides mechanisms for booking, clearing and deleting histograms on demand. In order to use these features of the package, the author must specify to ANALYSIS_CONTROL what subroutine is used to book his module's histograms and what range of histogram id's the module accesses IF the user is using HBOOK3 or YHIST. For HBOOK a users id's are isolated by being in different HBOOK subdirectories. A more detailed discussion of histogramming can be found in Section 5.

9. Abnormal Termination
   This entrypoint will be called for all linked modules if the analysis job terminates abnormally.