This file resides in D0$LEVEL2:L2SIM.DOC. 

 It is intended to familiarize users  with the available L2 tools and provide 
 simple instructions on how to use them with the VMS_FILTER Level 2 Framework. 

 Sep 16, 1992   (DRC)  Level 2 tools available at this date: 
                  L2_EM w/tracking option,L2ETMISS,L2JETS,MUON_L2
                  L2_PRESCALE,L2SUMET,L2_MIN_BIAS,L2_ETACUT,L2TAU
      with the Dzero ('Official Trigger List')specified cuts.
 RNO "Data Files" exist for each tool briefly summarizing their current status.
      See the respecitve D0$LEVEL2$DOCS:toolname.RNO for details.

    The Level 2  "Tools"  are  software  routines  that can be run in the real
 Level 2  environment  to filter events  or as part of a VMS_FILTER package to
 simulate triggers.  VMS_FILTER performs the Level 2 simulation. Level 2 Tools
 receive their  (electron and jet) candidate lists from the Level 1 TRGR bank.  
 Since, in fact, data with no TRGR bank will NOT be accepted by VMS_FILTER, it
 is neccessary that it be run in conjunction with the Level 1 simulator, L1SIM.

    Trigger bits are associated with Specific Trigger Definitions that fix the
 conditions under which  Level 1  marks an event  as acceptable.  Trigger bits
 are then mapped to specific "Filter Scripts".  Each Script initiates a unique
 sequence  of  calls to  Level 2  tools using specified parameter sets.  Since
 every Level 1 configuration must correspond to a complementary Level 2 Filter
 map, a predefined configuration file and filter map will be made available to
 the user,  for the Dzero Trigger Definition Set.

      Jan Hoftun's VMS_FILTER code and associated command files allow 
      the user to define L2 Tools and Filters for trigger simulations. 
        (See D0$L2CONTROL:LEVEL2_MANUAL.MEM for more information).  
                     
                                   Section I
     A short list of instructions for creating a Program Builder CALOR_OFF
     or D0USER executable.  The resulting package uses VMS_FILTER with all
    available level 2 tools set up for one of three predefined trigger sets. 

                                   Section II
      A brief introductory guide to running VMS_FILTER from within D0USER 

                                  Section III
      Modifying the trigger definitions from the available standard sets.

                                  Section IV
                           Generating new STP files


                                  Appendix I
 A description of the tool parameters (threshold cuts) that the user may modify

                                 Appendix  II
      A list of additional tool parameters some users may wish to modify

                                 Appendix III
                     The available Trigger Set definitions

For additional information see

     D0$CALOR_FILTER:L2JETS.DOC            D0$CALOR_FILTER:L2_EM.TEX
     D0$CALOR_FILTER:L2_ETMISS.DOC         D0$MUON_UTIL$L2SIM:MUON_ANALYSIS.MEM
     D0$L2CONTROL:LEVEL2_MANUAL.MEM        D0$LEVEL1:L1SIM.DOC
     D0$CALOR_UTIL:CADMAKE.DOC             D0$CONFIGS$COOR_SIM:COOR_SIM.DOC


                       I. Creating a VMS_FILTER package 


    $LIBPROD L2PROD ! gives you access to the most recent
                    ! LEVEL2 production release

    If you are interested in selecting a previous L2PROD release, INSTEAD

    $LIBPROD/OLD=V04_03  L2PROD         (for version 04.03.  Also available
                                                     04.07, 04.09, and 04.13)

    If you want to work under the special development area on FNALD0, 

             $LIBTEST ALL                  ! instead  of  any  LIBPROD,
                                           !           while
             $LIBTEST/GAMMA=D0$L2BETA  ALL ! <- is neccessary to access 
                                           ! the most  current releases


   If you have any code of your own intended as part of this package, edit in
   the file names to      [DEB_]VMS_FILTER_D0USER.OPT.     If linking to your
   own TOOLS, put the 'TOOL'_INIT object names into   [DEB_]D0_FILTER_STP.OPT.
   You can always do this later, of course.  This setup will provide you with 
   the LNK file you will need.

Then execute the following command file:

              $ @D0$LEVEL2:SETUP_L2SIM p1 p2 

  If omitted, the user will be prompted for the parameters.
    
              p1 specifies the Program Builder frame: C(ALOR_OFF)
                                                      D(0USER)

              p2 identifies the type of data you expect to run on:

                    Analyzing  real DATA (D)
                    or data with CADMAKE (D)
                    Any MC with CADMAKE  (C)  or
                    Monte Carlo Series (N,P,Q,R,S)?

        A specific  STP  file must be designated,  and  a  software 
        version switch set (at the end of CL2HITS.RCP) to match the 
        Monte Carlo series of data  you intend to filter.  Logicals 
        will be defined, according to your response at this prompt, 
        to point to the appropriate files.   The series designation 
        (an alphabetical label - K,L,M,N, or P)  may appear in some 
        data file names.  Note, for example:

                        Directory MC_DATA$HROOT:[WZ]
        STA_K_ISAWTAU_09.GEN_G;1           STA_N_ISAWENU_01.GEN_G;1

        Otherwise check with the generators of your Mont Carlo data.

        L2SIM is intended to be run on RAW data tapes.  The CADMAKE 
        package, however, allows running on  STAs  by restoring the
        original CAD banks.

        Once  SETUP_L2SIM  has been done, the symbol CHANGE_VERSION 
        can  be  invoked  whenever  necessary to change the version 
        number  you want to run with,  without repeating the entire 
        SETUP procedure.
                             (See Section Ib).



   A basic set of DAT and INFO files defining and mapping tools to specific
   triggers,  and  OPT  files for linking,  will be pointed to as defaults.
   For  CALOR_OFF  users, SETUP_L2SIM will exit here, but the comments that 
   follow are still instructive.   D0USERs  will be prompted with

        Do you want:
              1    To run the standard VMS_FILTER_D0USER.EXE
                (Includes CALOR,CADMAKE,RERUN_L12,L1SIM,RECDDN)
              2    Program Builder to make a private version
                      (For inclusion of your own packages)
              3    Program Build a private package with L1SIM
                          but NOT L2SIM (VMS_FILTER)
              4    QUIT

              ?

   Selecting 1 will set you up to run an existing, ready-to-use EXE.

   Selecting 2 or 3 will initiate a section of dialogue guiding you through 
   the Program Builder options.  You may respond to its first question with 
            %L12SIM      ! To rebuild the standard package described above.
   If you have prepared any combined package which includes VMS_FILTER, you 
   can respond with %package_name at this point. Otherwise respond as shown:


   CALOR,[CADMAKE,] ! Give list of packages (separated by commas) to run before
  [RERUN_L12,]L1SIM ! VMS_FILTER.  L1SIM is REQUIRED for MC data.  If filtering 
      [,RECDDN]     ! STA data CADMAKE is needed to fill CAD banks (from CAEP).
                    ! CADMAKE is  NOT  needed for RAW data.  RECDDN is REQUIRED
                    ! when running on MC data  if a  TRACK_MATCH is REQUIREd in
                    ! in EM filters.  It REformats the  CDD (raw tracking data) 
                    ! banks in  MC  data to the  crate structure  of real data.
                    ! RERUN_L12 is for prefiltered data.  L1SIM requires CALOR. 

        <Ret>       ! List any packages to be run AFTER VMS_FILTER.

        800000      ! Monte Carlo events require increased ZEBCOM size
        1200000     !   "     "     "       "        "     ZEBSTP  "
 
                      (Expect lots of screen messages)


   If any  fortran files exist in your current directory that match bug-fixed
   code released in a recent  L2PROD  pass, a  LOCAL_PASS   will be performed 
   (see Section Ia). Then the LNK file will automatically be invoked.  If you
   have private code, not compiled by LOCAL_PASS,that you have not yet placed
   in the appropriate OPT files (see above), simply break out by CTRL-Y.  

   In addition to any Program Builder-built files,  you should find a copy of 
   L2LIB_SETUP.COM.  This was copied over locally, appended with some logical
   definitions  specific  to  the  data type chosen, and  executed during the 
   Program Builder stage above.

   If needed, you may, at any time,
          @VMS_FILTER_D0USER.LNK [debug]    to produce a new D0USER EXE.



                 Ia. Local_Pass of production released code

LOCAL_PASS.COM is an automatic part of SETUP_L2SIM, but may also need to be run 
independently by users.  The symbol LOCAL_PASS is defined by L2LIB_SETUP to run 
it from D0$LEVEL2$COMMAND_PROC.

All  D0  libraries necessary for the operation of  LEVEL2  (and its simulator,
VMS_FILTER) are frozen by a  PRODUCTION  procedure that insulates  LEVEL2 from 
changes (and resulting incompatibilities) introduced by  TEST  releases.  This
guarantees a stable  EXECUTABLE  is always available for data acquisiton.  Any
relevent  bug fixes or  TEST-released code deemed important enough to be built
into a new ONLINE filtering EXE are introduced to the PRODUCTION area
individually via 'pass releases.'

A feature of the PRODUCTION mechanism used by D0 is that all new pass-released 
code is collected  in a single area  and  compiled into one (eventually giant)
OBJ.  Link order  guarantees  that  this OBJ  is seen  even before  users' OPT
files.  As a  consequence,  if you are doing further development  on a routine
already  pass-released, the linker will  always  see the pass-released version
first. LOCAL_PASS provides a means to circumvent this process by concatenating 
compiled  local code  to a private copy of  VMS_FILTER/L1SIM_D0USER.OBJ.  This 
will override the  PASS_RELEASE.OBJ modules copied into it and allow continued 
testing of code already pass-released.  

LOCAL_PASS  searches your directory  for code that duplicates that existing in
L2PROD's  'NEW'  area  and is therefore  part of the current PASS_RELEASE.OBJ.  
If you  have  ANY  it notifies you,  by screen messages,  and  an output file, 
RECOMPILE.LIST, which files it has found.  These are compiled and concatenated
to your local copy of VMS_FILTER(or L1SIM)_D0USER.OBJ.  (This COM does NOTHING
under ordinary simple TEST or D0$L2BETA releases, since there PASS_RELEASE.OBJ 
is only an empty dummy).

If your code is  new, or has  not  been pass-released,  just compile it as you 
ordinarily would and include it in the OPT files.  Only routines (few in early
passes,  perhaps  many  for  high  pass numbers) pass-released are affected by 
LOCAL_PASS.  Code compiled by  LOCAL_PASS  need  not  appear in an  OPT  file.  
As you  edit such routines  repeatedly, rather than recompile them, you should 

                    $ LOCAL_PASS   p1  [p2]

 Arguments : p1 = ALL [default]    Recompile  all  local .FOR files
                                   that duplicate entries in L2$NEW
                                   and  COPY/CONCATENATE  all  OBJs.

                = file1,file2,...  COMPILE and CONCATENATE just the
                                   specified file(s)

                = CLEAN            Rebuild  PASS_RELEASE.OBJ  locally  from
                                   scratch,  replacing  local code in favor
                                   of   pass-released   code.  This  slower
                                   option  will  avoid/undo  the continuing
                                   expansion of VMS_FILTER/L1SIM_D0USER.OBJ
                                   that  repeated   COPY/CONCATENATES  will
                                   produce.   It  also  eliminates the many
                                   MULTIPLY DEFINED  warnings  that result.


             p2 = VMS(_FILTER)     For linking VMS_FILTER packages.
                = L1SIM            For linking L1SIM packages.

                                   If   p2   is unspecified, checks whether
                                   you have local copy of  L1SIM_D0USER.FOR
                                   or VMS_FILTER_D0USER.FOR,and assumes the
                                   appropriate value.

                        Ib. Changing MC Data Versions


  You need  not  rerun  SETUP_L2SIM  if you later decide to analyze data 
  from  some different MC series. L2LIB_SETUP provides you with a SYMBOL 
  invoking  a  command file that can make  all  the neccessary switches.

  You can
                        $ CHANGE_VERSION  p1 p2      where

         p1 = 1 for Monte Carlo BEFORE Series N (most of the Grannis data)
              2 for Series N Monte Carlo (most of the QCD background runs)
              3 for Series P or Q Monte Carlo 
              4 for Series R,S or MC w/CADMAKE (newest Monte Carlo data)
              D for real data (the same for DATA w/CADMAKE)

         p2 = OLD    for muon geometry consistent with MC prior to 3.14
              NEW    for MC consistent with the updated muon geoemtry
              SRV    for geometry based on survey results for data run

  If p1 is omitted, the user will be prompted with

               SFTVSN=D (Setup for DATA SFTVSN=2 w/Mu_VSN=SRV)
               SFTVSN=D (Setup for DATA w/CADMAKE)
               SFTVSN=1 (MC series M or earlier)
               SFTVSN=2 (MC series N)
               SFTVSN=3 (MC series P or Q)
               SFTVSN=4 (MC series R,S or MC w/CADMAKE)
               SFTVSN=?

            Mu Version = OLD (MC before  3.14 or not recent VMS)
            Mu Version = NEW (MC version 3.14 or recent VMS)
            Mu Version = SRV (Survey results for DATA runs & MC series S)
            Mu Version = ?
                   

                           II. Running VMS_FILTER 


                At least once per login (per window session):

        $ @L2LIB_SETUP.COM                  !Performs the current LIBTESTing
                                            !and/or LIBPRODing required for
                                            !LINKing/running VMS_FILTER.
                                            !Update your copy per D0News
                                            !FILTER messages

    NOW you are ready to run the main program:


        $ D0USER   or   $DEB_D0USER    


    To write an output file, select

        4 : Output Data Files
        Output stream, 3 CHARACTERS> ! STA and DST are recognized stream names,
                                     ! but any 3 letter name is acceptable.
        Name for output file >
        You want exchange mode? :>
        Write only event records(no b-o-r or e-o-r)? >
        Want to add or remove from list of banks to be dropped from stream? >
                     (Here you can control what banks are 
                      passed along  to the  output stream)


    To begin a run, select

        1: Manual Process
        Store histograms ? 0=NO, 1=after each run, 2=end of job only > 
        Will you be reading files from tape? [N]>

        Name of input file >         ! Some LEVEL2 tools require CAD banks.
                                     ! This implies running on files complete
                                     ! with RAW calorimetry data.  
                                     ! STAs can be run provided your package 
                                     ! was built to include CADMAKE.

        Process all events for remaining runs? Y/N >  !If N you are asked:
                    Number of events > 
                    Number of events to skip. Default is 0 >




Once the specified number of events have been processed you land in the submenu

                SUB_LEVEL: DONE_WITH_DATA    SETUP

     1: Continue      - Allows you to run more data (same or new file)
     3: Status Report - Provides a report on the pass rate of each Filter
 --> 2: Finish        - Terminates with output of histograms
     6: QUIT          - Terminates with no output


          IIa. What you can expect from this run of VMS_FILTER

    VMS_FILTER will function as a genuine filter. Any output DATA file will    
    consist only of events passing at least one of the predefined triggers.
    For each event,  Filter Bits will be set   ON   for every Filter Script 
    passed.  It will call user routines (if they reside after VMS_FILTER in 
    the  package)  only  for  successfully  filtered  events.  The  default 
    configuration files, however, include a ZERO_BIAS trigger (SPEC_TRIG_1)
    which provides an  "always pass"  condition.  Since  VMS_FILTER  passes  
    according to the OR of all  defined triggers, every event is guaranteed 
    to  pass (at least under the ZERO_BIAS filter).  This mode of operation
    assumes that L1SIM is  being  operated  under its default condition  of 
    disabling   LEVEL1    prescales,   and   provides   the  user  with the
    opportunity to study events  that  pass  no triggers.  L1SIM   defaults
    can be  checked  (or changed)  within  the  User  Dialog   selection in
    the top  SETUP Menu  of  D0USER.  Most  settings  can  be  contolled by 
    L1SIM.RCP.  The default version is in D0$LEVEL2$L2SIM, but the logicals
    make a search list starting in your directory. Copy L1SIM_RCP  and  you
    can modify if as needed.
 
    The  32-bit  mask of specific (Level 1) triggers fired  can be found in 
    the  Zebra bank,  TRGR.    APPENDIX III   identifies  what triggers are 
    associated with each Trigger Bit.

    Bank Name : TRGR 
            IQ(L+6)          Trigger Mask (same as IQ(LHEAD+11) )

    The filter bits reside in the Zebra bank HEAD.   APPENDIX III lists the
    definitions of each. In the standard sets provided,filter bit numbering
    has been hardwired to match the numbering of the trigger bits that call
    call the filters (i.e. Trigger Bit 5 calls  Filter Script 5). Note that 
    only a small subset of the bits are actually in use.

        Bank name: HEAD
            IQ(L+15)      I  FILTER BITS  31-0 
                 16       I  FILTER BITS  63-32 
                 17       I  FILTER BITS  95-64 
                 18       I  FILTER BITS  127-96

    The logical function L2_PASSED() returns the OR of all the filter bits.
    It can be used to see whether ANY of the LEVEL2 bits passed.  A call to 
    L2BIT_PASSED(i)  with  i = 0-127  returns  the  logical  value  of  the 
    specified  filter  bit, i.

    Similar functions exist for LEVEL1:  L1_PASSED()  and  L1BIT_PASSED(i).

    Additional logical functions  providing information on LEVEL2 bits are
    described in the document D0$OFFLINE_UTIL:L2BITS.DOC. This document is
    currently  under    D0$L2BETA:[GENERAL.OFFLINE_UTIL.SOURCE]L2BITS.DOC.

    The VMS_FILTER output already includes the following histograms
     ===> Directory : //PAWC/L2FILT
      1000 (1)  Overall pass/fail vs Evt #          
     10000 (1)  Trigger bits set            OTHER timing histograms are
     10001 (1)  Number of L1 bits set       available thru L2SETUP (see 
     10002 (1)  Number of L2 bits set       D0$LEVEL2$DOCS:L2SETUP.DOC)
     10003 (1)  Time spent in MAIN_FILTER       

     in addition to the L1SIM booked histograms of
     ===> Directory : //PAWC/L1C   
      1001 (1)   NO OF EM TOWERS            1004 (1)   TOT ET
      1002 (1)   NO OF TOT TOWERS           1005 (1)   TRIGGER EFFIC
      1003 (1)   TOT EM_ET                  2001 (2)   EM_ET VS TOT_ET


    Near or at the bottom of this output you will find a summary of filter 
    pass rates and timing.

                FILTER REPORT AT SUMMARY TIME
               -------------------------------
 
                Try if  #Try/                 Pass   Time   RMS  Time/
                L1 bit?   Evt  #Pass/  #Try=  Rate   (ms)  (ms)  Total
               --------  ----   ----   ----   ----   ----  ----  -----
 FILTER bit  0 Always    0.98    196/   196=100.0%    1.9   0.3   0.1%
  # 1     TOOL1    Set  1        196/   196=100.0%
  # 7     L2SETUP  Set  1        196/   196=100.0%
 
 FILTER bit  1 Always    0.88    169/   176= 96.0%  126.2   1.4   3.5%
  # 6     L2ETSUM  Set  5        169/   176= 96.0%
 
 FILTER bit  2 Always    0.64    128/   128=100.0%    1.3   0.3   0.0%
  # 4     L2ETMISS Set  4        128/   128=100.0%
 
 FILTER bit  3 Always    0.41     82/    82=100.0%    2.3   0.5   0.0%
  # 2     L2JETS   Set  2         82/    82=100.0%
 
    :                     :         :                        :
    :                     :         :                        :

 FILTER bit 16 Always    1.00      1/   199=  0.5%  355.7  11.3  11.2%
  # 3     L2_EM Set  7          7/   199=  3.5%
  # 5     MUON_L2  Set  1          1/     7= 14.3%
 
    :                     :         :                        :
    :                     :         :                        :

 FILTER bit 29 Always    1.00    199/   200= 99.5%   27.9   2.9   0.9%
  # 6     L2ETSUM  Set  4        199/   200= 99.5%
  # 2     L2JETS   Set  1        199/   199=100.0%
 
 FILTER bit 30 Always    0.99      2/   198=  1.0%    1.5   0.3   0.0%
  # 5     MUON_L2  Set  2          2/   198=  1.0%
 
  Overall Filtering              200/   198=100.0% 3150.5  89.1
 
  L1 Bits Set/Event =  26.05 L2 Bits Passed/Event =   4.65
  #  Scripts/Event =   17.21;      T(Sum) Scripts/Filt =  0.996
 
 TOOL Results:
                     #Try/                Pass    Time   RMS  Time/
                       Evt  #Pass/  #Try= Rate    (ms)  (ms)  Total
                       ---   ----    ---  ----    ----  ----  -----
  1         TOOL1     0.98    196/   196=100.0%    0.6   0.2   0.0%
  2         L2JETS    2.00    399/   399=100.0%    6.1   0.3   0.4%
  3         L2_EM     5.78     42/  1157=  3.6%  335.1   2.4  61.5%
  4         L2ETMISS  0.64    128/   128=100.0%    0.2   0.1   0.0%
  5         MUON_L2   7.04     19/  1408=  1.3%  148.3  15.4  33.1%
  6         L2ETSUM   1.88    368/   376= 97.9%   66.9   3.3   4.0%
  7         L2SETUP   0.98    196/   196=100.0%    0.4   0.1   0.0%
 
    # Tools Called/Event = 19.30    T(Sum) Tools/Filt =  0.991



                           III. On Your Own


 The logicals  CTL and CFG, have been declared search lists (by L2LIB_SETUP)
 pointing first to your private work area, and finally  to D0$CONFIGS$SOURCE  
 where the "official" configuration files for a pre-defined trigger standard
 set reside.  Thus,  you can  modify parameters  for the tools used  in  any 
 trigger, by editing local copies of the relevant files.

 COOR_SIM  simulates the online program COOR, which COORdinates all requests 
 to  use  available detector resources  in  defining  specific trigger  sets. 
 "Configuration files"  communicate  to  COOR_SIM  the current resources and 
 and  any  requests  that  select  from  them  some subset for  a  given run. 
  (See D0$CONFIGS$COOR_SIM:COOR_SIM.DOC and D0$L2CONTROL:LEVEL2_MANUAL.MEM)

Configuration files  for the predefined Dzero trigger sets  have already been
prepared  for  you,  and run through  COOR_SIM.   The  output  messages  from 
COOR_SIM, which are to be passed along to the L1 and L2  frames  (actually to 
L1SIM and L2SIM) are written into the INFO files that  SETUP_L2SIM points you
to via logical name definitions.   This configuration is regularly updated to
reflect the most current trigger list used ONLINE.

You may prefer to work with some  earlier  trigger set, or modify portions of 
the current default list. Any changes you wish to make (in trigger thresholds  
for example) will involve four basic steps:    

    1) Copy over the appropriate -TRIGLIST file for the trigger list
       you are interested in. You can confirm what trigger lists are
       available by 

       $ DIR D0$CONFIGS$SOURCE:*.*TRIGLIST

    2) Regenerate the full set of trigger definition files 
       (through a program called TRIGPARSE);

    3) Identify the TRIG, LEV1 or FILT file(s) of interest and edit in 
       any changes  (for example, a new Et threshold);  then

    4) Run  COOR_SIM  to create new INFO files.

    As an example,

        $   COPY D0$CONFIGS$SOURCE:DZERO.GLB-TRIGLIST *
        $   COPY D0$CONFIGS$SOURCE:TRIG_RESOURCES.CTL *
        $   TRIGPARSE DZERO.GLB-TRIGLIST -resource trig_resources.ctl

    will fill your directory with a long list of TRIG, FILT, and LEV1 files.
    If not  editting any triggers or filters at this time, skip to the last
    half of Section IIIa for instructions in running COOR_SIM.

The  configuration  files  are  highly  modular.  The  top  level,  "Master" 
Configuration File, is a (long)  list of references to TRIG  subfiles.  Each  
of these,  in turn, reference additional sub-files.  For example, looking at 
DZERO.CFG you find

 !DZERO.CFG Master Configuration File
 !Generated from `dzero.glb-triglist'
 !This is a *GLOBAL* configuration.
 @reqs:zero_bias-v73.trig
 @reqs:mu_2_max2.trig
 @reqs:mu_1_high.trig
 @reqs:mu_1_max.trig
 @reqs:mu_2_low.trig
 @reqs:mu_2_high.trig
 @reqs:mu_1_jet.trig
 @reqs:mu_em_1.trig
 @reqs:mu_em_2.trig
 @reqs:mu_jet_high.trig
 @reqs:mu_jet_low.trig
 @reqs:scalar_et.trig
 @reqs:missing_et.trig
 @reqs:jet_3_miss.trig
 @reqs:jet_1_miss.trig
 @reqs:jet_2_gap.trig
 @reqs:jet_2_end.trig
 @reqs:jet_1_low.trig   ->  !jet_1_low.trig
 @reqs:jet_2_high.trig      !`dzero.glb-triglist'
 @reqs:jet_3_high.trig      !
 @reqs:jet_4_med.trig       spec_trig_18  jet_1_low
 @reqs:em_1_med.trig        @reqs:jet_1_low.lev1     ->  Defines the LEVEL1
 @reqs:em_1_high.trig       @reqs:d0_detector.req        trigger conditions
 @reqs:em_2_med.trig        l2_type   regular $all
 @reqs:em_2_high.trig       @reqs:jet_min.filt       ->  Sets parameters for
 @reqs:em_miss.trig         stream all                   the L2 tools called
 @reqs:em_jet.trig                                       by this Trigger Bit
 @reqs:inspill.trig                                 
 @reqs:lumin_mon.trig
 END_OF_CONFIG


 The files of interest to the user  are  usually  the deeply nested lower level 
 files carrying the extensions  LEV1, FILT, and  any files they  may  reference
 (for example the LEV1 reference sets with extension RS). APPENDIX III provides
 a table of the LEV1, FILT, and RS file names for the default Dzero trigger set.

        If you are interested in being more familiar with ALL the files 
        called in a configuration request, you are welcome to play with

                       $ EXPAND_CFG  CFG:DZERO.CFG

        which will expand the (approximately) 4 block  CFG file into an 
        (approxiamtely) 80 block local file for you, having fetched and 
        included  all  of the referenced subfiles.  You can then search 
        through  this  file  for  the  SPEC_TRIG_x  of  interest.



IIIa. Changing LEVEL2 Filter Cuts


 From APPENDIX III you can find the name of the LEVEL2 FILT file you need to 
 edit. As an example, to modify the Et cut on jets in the DZERO  Trigger 18, 
                         $ EDIT JET_MIN.FILT
 Which contains


       !JET_MIN.FILT
       !Generated from `dzero.glb-triglist' by trigparse 1.19.
       !
       FILTER_BIT JET_MIN  pass_1_of 0   speed 1.0    Must_try
         L2JETS
           NUM_JETS  1
           ETMIN  15.
           CORE_DELTA_R  .3
           JET_DELTA_R  .3
           SIZE_MIN  -1.
           SIZE_MAX  1000.
           EMPCT_MIN  -1.
           EMPCT_MAX  100.
         L2_PRESCALE
           L2_PRESCALE_BY  1
       SCRIPT_END


    Perhaps obvious, in this example,  you need merely change the ETMIN
    ETMIN line.  APPENDIX I  defines/describes each of these parameters.




    To actually implement your modified cut, you need to invoke COOR_SIM,
    a symbol already defined for you by L2LIB_SETUP.


    $ COOR_SIM
    Resource file name:         RESOURCE           ! or CTL:COOR_SIM.CTL
    Configuration file name:    DZERO.CFG          ! Assuming, as above,
                                                   ! you  are  modifying 
                                                   ! a DZERO trigger.


    A full set of new INFO files,  COOR_SIM's  messages to the L1 and L2 
    frames will have been generated for you,  and  you are ready  to run        
    VMS_FILTER again under the new set of conditions.  Caution!! Be sure
    to pause a few seconds before running again. A spawned process makes
    RUN_000001.ZDAT, which contains the level 2 cuts.   To parallel  the 
    online world, the logicals CFG and CTL are defined and point to REQS.

IIIb. Changing LEVEL1 Trigger Cuts

From  APPENDIX III find the name of the LEV1 file you need to edit and copy it
over.   You will find it requires a Reference Set,  (@xxxxxx.RS)  that you may
need to copy over as well.  As an example, to modify the Et cut on jets in the 
DZERO Trigger 3, 
                         $ COPY CFG:JET_LOW.LEV1 *

        Level 1 configuration file
        Trigger on one or more jet towers w/transverse energy > 3 GeV
        Prescale factor is 500
            Readout_msec               30
            Prescale_cntrl             on
            Prescale_ratio             500
        NUM_JET_TOWERS   1       CFG:JET_LOW.RS        REQUIRE
    
within which you can alter  the number of jet candidates  required.  The file 
JET_LOW.RS  carries the  "reference set", a map of threshold values specified  
for every calorimeter trigger tower,
            TT_ETA(-20:20)  TT_PHI(1:32)  Thresh_Et #  (3.0) GeV

Here  all trigger towers  in the eta index range of (-20:-1), (1:20) and  phi 
(1:32)  have  the same threshold  applied.  EM  triggers  require  a  pair of 
references sets: one set for the  EM  section, another for  a  hadronic veto.  
For example, looking at EM_HIGH.LEV1, you find

NUM_EM_TOWERS   1       CFG:EM_High.RS      CFG:No_HAD_Veto.RS      REQUIRE
     where  both files  follow the same calorimeter RS format as above.  
     However, while the range of TT_ETA is -20:20 for the jet RS files, 
     it  is  -19:19  for  the  EM  and  hadronic veto  reference  sets.
Muon trigger declarations take a slightly different form.  Consider MU_LOW.LEV1.

        Level 1 configuration file
        Trigger on one or more muons in any region over 7 GeV/c pt
    
            Readout_msec               30
            Prescale_cntrl             off
            Prescale_ratio             1
        NUM_MUONS     1 (CF+EN+ES+SN+SS)                     REQUIRE
        NUM_MUONS_L15 1 (CF+EN+ES+SN+SS)   CFG:MUON_HIGH.RS REQUIRE

which triggers, at LEVEL1, on a muon candidate seen in  ANY region, and then
applies a LEVEL1.5 requirement of satisfying the minimum transverse momentum
specified in the reference set MUON_HIGH.RS

        THRESH_PT #  CF(7)  EN(7)  ES(7)  SN(7)  SS(7) GeV

At  LEVEL1, only a count and region are specifiable.  It is within  LEVEL1.5
that all Pt thresholds are applied. You will note the two-character initials 
appearing both in the RS file and within parenthesis in the LEV1 file.  They 
specify the following regions of muon coverage:
        CF  Central muon (to about eta=1.2)
        EN  North end WAMUS muon, including SAMUS overlap
        ES  South end   "    "    (eta from 1.0 to 2.2)
        SN  North end SAMUS only  (eta from 2.1 to 3.3)
        SS  South end SAMUS only

 with two additional regions available in  LEVEL1  triggering for  NUM_MUONS
        WN  North end WAMUS only  (eta from 1.0 to 1.7)
        WS  South end WAMUS only  

As instructed at the bottom of Section IIIa, you must run COOR_SIM following 
any changes made in these files.  This translates the LEV1s into INFO files.

                     IV. Generating new STP files

  Besides the tool parameters designated in  the FILT files, there is a set of 
  constants considered to be relatively  fixed (detector geometry, for example, 
  but also some internal cuts employed by the tool algorithms). A partial list 
  of such values are tabulated in APPENDIX II.  Although these parameters have 
  been  fixed by the tool authors and need not be changed, the more  ambitious  
  user may be interested in experimenting with these values.  

  At the Tool_INIT phase, performed within a standalone routine,VMS_FILTER_STP, 
  the entire collection of such constants, for ALL tools, is stored in a large 
  Zebra  file  for  downloading  by  the  L2  framework.  When  you  first ran 
  SETUP_L2SIM  (or subsequently ran  CHANGE_VERSION) a logical, VMS_FILTER_STP, 
  was defined within  L2LIB_SETUP to point to the STP appropriate to the Monte 
  Carlo  (or data)  version  you were running.  Different  STP  files had been 
  generated because of the need for  different  data unpacking flags, changing
  muon geometry, and evolving tool algorithms (reflected in new internal cuts).

  If you modify any of the  tool_init  RCPs, it will be neccessary to generate
  a new  STP.  Copy from  D0$LEVEL2$L2SIM the tool RCP(s) you wish to modify.



                       IVa.  No New TOOLS Defined
 

  If you have  NOT  created any new tools on your own, but have simply edited
  RCPs, you need only
                         $ NEW_STP  p1  p2  (p3)

  which defines symbols for running an official EXE, or, if requested, copies
  and compiles the VMS_FILTER_STP code locally. It declares the STP to now be
  local, as well as appending this new declaration to your L2LIB_SETUP  file. 

  The parameters are for      Data version (1,2,3,4 or D  - see Section Ib)
                              Muon version (OLD NEW or SRV- see Section Ib)
                                  (user will be prompted if omitted)

                     and      DEB  (optional)
Once completed

    RUN_STP   or   RUN_STP/NOSMG   will generate your new STP file, and you
    are ready to rerun VMS_FILTER using the new conditions you have defined.

To rerun with new conditions:   CHANGE_VERSION n m STP      
                                        where n=1,2,3 or D and m=OLD/NEW
                                RUN_STP          will save any re-compiling.


                       IVb.  New TOOLS Added

Make sure the 'TOOL'_INIT object names of your new tool are included in the
D0_FILTER_STP.OPT file copied from D0$LEVEL2$L2SIM.  

 $ DEASSIGN VMS_FILTER_STP      ! Logical name interfers with routine name
 $ DEFINE  CL2HITS_RCP  D0$LEVEL2$L2SIM:CL2HITS_n.RCP  ! n = MC version #
 $ @D0$VMS_FILTER:FILTER_MAKER  ! Taking the defaults until the STP prompts

   Do you want to run the TOOL_MAKER program? [N]
   Do you want Program Builder to make a new version? [N]
   Do you want to EDIT the OPTION files? [N] (Y to add your TOOL_INIT.OBJ)
   Do you need to compile any TOOLS? [N]
   Do you want to LINK the D0USER program? [N]
   Do you want to LINK the STP translation program? [N]   Y
   Do you want to RUN  the STP translation program? [N]   N
   Do you want to RUN D0USER? [N]

 $ @D0$LEVEL2$COMMAND_PROC:L2RCP_SETUP ! Override the FILTER_MAKER default RCPs
 $ RUN VMS_FILTER_STP
 $ DEFINE  VMS_FILTER_STP  VMS_FILTER.STP  <- also add to your L2LIB_SETUP.COM

                     Appendix I. The Tool Parameters. 

   L2JETS
     NUM_JETS         I      Cut on number of jets passing ETMIN
     ETMIN            R             
     CORE_DELTA_R     I      Size of jet 'core' (in eta-phi space)
     JET_DELTA_R      I      Size of 'full' jet
     SIZE_MIN         R      Bounds on jet "radius" (cuts on transverse size)
     SIZE_MAX         R             
     EMPCT_MIN        R      Maximum EM energy fraction of jets 
     EMPCT_MAX        R      Minimum EM energy fraction of jets
 

   L2_EM 
     NUM_EM           I      Number candidates required
     ETMIN_CC         R      Trigger tower Et cut for candidates in CC region
     ETMIN_EC         R      Trigger tower Et cut for candidates in EC region
     TRACK_MATCH      C      'REQUIRE' 'IGNORE' or 'VETO'
     DEL_ETA_TRACK    R      Road width for track-to-cluster match
     DEL_PHI_TRACK    R             
     SHAPE_CUTS       C      'ELECTRON' longitudinal and transverse shape cuts
                             'PHOTON'  same, but no cuts on EM1, EM2 fraction
                             'LONG'    do only longitudinal cuts
                             'TRANS'   do only transverse cuts (not implemented)
                             'IGNORE' do NO shape cuts
     DO_ISOLATION     L      TRUE to require isolation cut.
     CONE_DELTA_R     R      
     CONE_FRACT_MAX   R      


   L2ETMISS
     ETMISS_MIN       R     
     ETMISS_SIG_MIN   R      ETmiss "SIGNIFICANCE" cut.  0 is acceptable.
 

   MUON_L2
     NUM_MUONS        I      Number of muons required to pass 
     PTMIN            R      Pt cut on muons
     ABS_ETA_MAX      R      Maximum eta range for muons
     MUON_QUALITY     C      'TIGHT','COMMON','LOOSE','TYPICAL'
     TRACK_IN_ROAD    C      'CFALL_EFL10_WSL10_SXXX'
 

   L2ETSUM
     ETSUM_MIN        R      Minimum total scalar Et cut
     ETOT_MAX         R      Maximum Scalar Et cut


   L2ETSIM
     TIME_SCRIPT      L       TRUE or FALSE
     TIME_TOOL        L             "
     HISTO_SCRIPT     L             "
     HISTO_TOOL       L             "
     TIMING_TYPE      C       'CPU' or 'CLOCK'
     TMIN_SCRIPT      R       timing histogram limits
     TMAX_SCRIPT      R             "
     TMIN_TOOL        R             "
     TMAX_TOOL        R             "
     RAW_TO_DROP      C       names of raw data banks to drop eg
                              'CDD2' or 'MUD1_CDD2' or 'TRGRCAD1CAD2'
     BANKS_TO_DROP    C       names of other banks to drop eg
                              'CAHT' or 'MUHT_CAEP' or 'CAEPCATECAEH'
                              (24 chars or 6 banks max, no blanks)

                       Appendix II. The RCP files. 

   The logical names L2_EM_INIT_RCP, L2JETS_RCP, L2ETMISS_RCP,
   L2ETSUM_RCP, L2SETUP_RCP, L2TRAK_RCP, CL2HITS_RCP and MUON_L2_RCP
   designate the RCP files required by the Level 2 tools in their INIT
   stage.  Any modifications of these values will require creating a new
   STP file before running VMS_FILTER (See Section IV).

   These files exist as
                        D0$LEVEL2$L2SIM:L2_EM.RCP
                        D0$LEVEL2$L2SIM:L2JETS.RCP
                        D0$LEVEL2$L2SIM:L2TRAK.RCP
                        D0$LEVEL2$L2SIM:CL2HITS.RCP
    
   Parameter sets within these files have been fixed for MC running with the
   three sets of trigger definitions and need not be changed. The relevant 
   parameters are described below:

   L2_EM 
     CAHIT : If TRUE, L2_EM assumes user uses CAHITS to fill CAEP banks
     CL2   : If TRUE, L2_EM uses CL2 fast unpacking to fill CAEP banks

   L2JETS
     DUMP_JAUX : TRUE prints L2JETS results to an output file.  
                 The unit number is defined in L2JETS.PARAMS.
     RUN_ELN   : TRUE for real ELN. Otherwise, FALSE
     RUN_TB    : Does nothing.
     TRGR_READY: When TRUE the TRGR block will supply a hot tower list.
               : If not, but TRGR FADC values will be available, NJTHOT_FAKE 
               : and IHOT_ADR_JT_FAKE can be used to force L2JETS to use the 
               : trigger towers defined in IHOT_ADR_JT_FAKE as hot tower jet 
               : candidate with corresponding trigger masks IHOT_MSK_JT_FAKE
     USE_CL2   : FALSE, normal mode. If TRUE, then the jet core is clustered 
               : using fast CADX unpack instead of TRGR FADC values.
     L2JCAL_CEN: Calibration number for central region
     L2JCAL_CRA:  "          "       "  crack   region
     L2JCAL_END  "           "       "  endcap  region.
     L2JCAL_CEN_CL2: Similar values for use when USE_CL2 is true.
         (The jet ET's are multiplied by these numbers)
 

   CL2HITS
      controls what data format the tables will be built for
     D0_DATA     : [TRUE], set FALSE for NWA data (not supported yet)
     MONTE_CARLO : [TRUE] for MC running, FALSE for real data

     SFTVSN 1    ! 1 - Monte Carlo BEFORE Series N (most of the Grannis data)
                 ! 2 - Series N Monte Carlo (most of the QCD background runs)
                 ! 3 - Data AFTER Series N Monte Carlo
                 ! 0 - DATA or (new) Monte Carlo in CURRENT data format

   L2TRAK
     MONTE_CARLO : CDC installed rotated from its design (MC) orientation
     DELAY       : If TRUE delay lines (a cut in Z) will be used in tracking
     FDC         : TRUE or FALSE to select/deselect FDC tracking
     CDC         : TRUE or FALSE to select/deselect CDC tracking
     WIRE_MIN    : Number of wires/CDC cell (out of 7) required for hit
     MIN_DEL     : Minimum number of CDC delay lines (out of 4)

                               Appendix III.
                      The 'Official' DZERO Trigger Set
                   Top level configuration file: DZERO.CFG

 Specific     TRIG      Level 1 Trigger      FILT        Level 2  filter tools
 Trig Bit  Config File      Condition     Config File    and parameters called
 --------  -----------  ----------------  -----------    ---------------------
    1       ZERO_BIAS    MRBS_LOSS veto  ZERO_BIAS-V73          none
                                           MIN_BIAS     L2MINBIAS Fast_z_good

    2       MU_2_MAX2    2mu>0,1mu>3Gev   MU_2_MAX2     MUON_L2 2mu>10, 1mu>15
                          1mu  > 3 Gev

    3       MU_1_HIGH     1mu  > 7 GeV     MU_HIGH      MUON_L2 1 mu >15.0 GeV

    4       MU_1_MAX      1mu  > 7 GeV      MU_MAX      MUON_L2 1 mu >15.0 GeV
                                           MU_2_MAX     MUON_L2 2mu>10, 1mu>15

    5       MU_2_LOW     2mu>0,1jt>3GeV    MU_2_LOW     MUON_L2 2 mu > 3.0 GeV
                                                        L2JETS  1 jt >10.0 GeV

    6       MU_2_HIGH     2mu  > 0 GeV     MU_2_HIGH    MUON_L2 2mu>3, 1 tight

    7       MU_1_JET     1mu>0,1jt>3GeV    MU_1_JET     MUON_L2 1 mu > 3.0 GeV
                                                        L2JETS  1 jt >10.0 GeV

    8        MU_EM_1     1mu>0,1em>7GeV     MU_ELE      L2_EM   1 e  > 7.0 GeV
                                                        MUON_L2 1 mu > 5.0 GeV

    9        MU_EM_2     1mu>0,2e>2.5GeV   MU_ELE_2     L2_EM   1 e  > 2.5 GeV
                                                        MUON_L2 1 mu > 5.0 GeV

   10      MU_JET_HIGH    1mu>0,1jt>5GeV  MU_JET_HIGH   MUON_L2 1 mu > 8.0 GeV
                                                        L2JETS  1 jt >15.0 GeV

                                          MU_JET_MAX    MUON_L2 1 mu >14.0 GeV
                                                        L2JETS  1 jt >15.0 GeV
                                        
                                          MU_JET_MED    MUON_L2 2 mu > 4.0 GeV
                                                        L2JETS  1 jt >15.0 GeV

   11      MU_JET_LOW     1mu>0,2jt>3     MU_JET_LOW    MUON_L2 2 mu > 3.0 GeV
                                                        L2JETS  1 jt >10.0 GeV

   12       SCALAR_ET   ET_tot > 225 GeV   SCALAR_ET    L2ETSUM EtSUM_MIN>300  

   13       MISSING_ET   MPT>30,1jt>3GeV  MISSING_ET    L2ETMISS EtMISS_MIN>35

                                          MISS_ET_MON   L2ETMISS EtMISS_MIN>30
                                                        L2PRESCALE by 10

   14       JET_3_MISS   MPT>20,3jt>3GeV  JET_3_MISS    L2JETS 3 jet > 20. GeV
                                                        L2ETMISS EtMISS_MIN>25

   15       JET_1_MISS   MPT>20,1jt>7GeV JET_MISS_TAU   L2JETS  1 jt >20.0 GeV
                                                        L2ETMISS EtMISS_MIN>20
                                                        L2TAU

   16       JET_2_GAP    2 twr,Et>5.0GeV  JET_GAP_MED   L2JETS  2 jt >25.0 GeV
                                                        L2ETACUT > 4.0

   17       JET_2_END    2 twr,Et>5.0GeV  JET_END_MED   L2JETS  1 jt >50.0 GeV
                                                        L2ETACUT

   18       JET_1_LOW    1 twr,Et>3.0 GeV   JET_LOW     L2JETS 1 jet > 15 GeV
                                                        L2PRESCALE by 5

   19       JET_2_HIGH   2 twr,Et>5.0GeV  JET_END_MED   L2JETS  1 jt >50.0 GeV

   20       JET_3_HIGH   2 twr,Et>7.0GeV    JET_HIGH    L2JETS 1 jet > 80 GeV

   21       JET_4_MED    4 twr,Et>5.0 GeV   JET_MAX     L2JETS 1 jet >115 GeV

                                           JET_4_MED    L2JETS 4 jet >20.0 GeV

                                           JET_MULTI    L2JETS 5 jet >10.0 GeV
                                                        L2ETACUT < 2.5
  
                                          JET_MULTI_X   L2JETS 5 jet >15.0 GeV

                                          SCALAR_ET_JT  L2ETSUM EtSUM_MIN>300
                                                        L2PRESCALE by 5

   23       EM_1_MED     1e,Et>10.0GeV    ESC_HIGH     L2_EM 1e>60 No shapecuts

                                         GAM_HIGH_ISO  L2_EM 1e>30 Isolation cut

                                           ELE_HIGH    L2_EM 1e>20 Isolation cut

                                         ELE_HIGH_TRK  L2_EM 1e>20 w/TRACK_MATCH

   24       EM_1_HIGH    1e,Et>10.0GeV     ELE_MAX     L2_EM 1e>20 Isolation cut
                                                        L2ETMISS EtMISS>5,SIG>0
                                            
                                          ELE_MAX_SG   L2_EM 1e>20 Isolation cut
                                                        L2ETMISS EtMISS>0,SIG>5

   25       EM_2_MED     2e,Et> 7.0GeV    GAM_2_MED    L2_EM 2e>12 Gam shapecuts
                                                       L2_EM 1e>12 Isolation cut

                                          ELE_HIGH2    L2_EM 1e>20 Isolation cut

                                        ELE_HIGH2_TRK  L2_EM 1e>20 w/TRACK_MATCH

   26       EM_2_HIGH   2e,Et> 7.0GeV    ELE_2_HIGH    L2_EM 2e>10 Isolation cut

                                         ELE_2_MAX     L2_EM 2e>20 Isolation cut

                                          ELE_MAX2     L2_EM 1e>20 Isolation cut
                                                       L2ETMISS EtMISS>20,SIG>0

                                        ELE_MAX2_SG    L2_EM 1e>20 Isolation cut
                                                        L2ETMISS EtMISS>0,SIG>5

   27       EM_MISS  1e,Et>7,1jt>3,MPT>16  ELE_MISS     L2_EM  1 e > 15.0 GeV
                                                       L2ETMISS EtMISS>20,SIG>0

                                          EM_JET_MISS   L2JETS 1jt>15GeV,.3cone
                                                       L2ETMISS EtMISS>20,SIG>0

   28       EM_JET   1e,Et>10Gev,2jt>5GeV  ELE_JET     L2_EM  1e >15GeV,eta<2.5
                                                       L2JETS 2jt>10GeV,eta<2.5
                                                       L2ETMISS EtMISS>10,SIG>0

                                          ELE_JET_MAX  L2_EM  1e >15GeV,eta<2.5
                                                       L2JETS 2jt>10GeV,eta<2.5
                                                       L2ETMISS EtMISS>20,SIG>0