FATMEN -- H2Fatmenuserguide-utility-routines

Utility routines

Search in names file

       +----------------------------------------------------------+
       | CALL  FMNICK (LUN,CHFILE,CHNICK,CHNAME,CHDESC,CHOPT,IRC*) |
       +----------------------------------------------------------+

LUN: Integer variable or constant giving the Fortran unit on which the names file should be read.
CHFILE: Character variable specifying the name of the names file. If blank, a default names file will be used. The default names file for a FATMEN group XYZ is FMXYZ.NAMES in the directory pointed to by the shell variable FMXYZ.
CHNICK: Character variable specifying the value of the :nick tag to be searched for in the names file
CHNAME: Character variable in which the value of the :GNAME tag corresponding to the above nick name is returned.
CHDESC: Character variable in which the value of the :DESC tag corresponding to the above nick name is returned.
CHOPT: Character variable, currently ignored.
IRC: Integer variable in which the return code is returned.

This routine searches in the specified or default names file for the generic name and description that matches the specified nick name. If the nick name contains a slash, then the characters after the slash are treated as a range and appended to the value of the :GNAME tag. Only characters upto the character before the slash are used to find the names file entry.

A range may be given in the standard FATMEN form (mm:nn) or as mm-nn.

              An example of using the FMNICK routine

      character*80 chname,chdesc
      call fmnick(1,'fmdelphi.names','RAWD91',chname,chdesc,' ',irc)
      print *,chname(1:lenocc(chname))
      print *,chdesc(1:lenocc(chdesc))
      call fmnick(1,'fmdelphi.names','LEPT92/(10:20)',
     +            chname,chdesc,' ',irc)
      print *,chname(1:lenocc(chname))
      print *,chdesc(1:lenocc(chdesc))
      call fmnick(1,'fmdelphi.names','RAWD91/17-77',
     +            chname,chdesc,' ',irc)
      print *,chname(1:lenocc(chname))
      print *,chdesc(1:lenocc(chdesc))
      end

             The names file used in the above example

:NICK.RAWD92
:GNAME.P01_ALLD/RAWD/NONE/Y92V00/*/R:DESC.RAW data of ALL events; 1992 data
*---------------------------------------------------*
:NICK.RAWD91
:GNAME.P01_ALLD/RAWD/NONE/Y91V00/*/R
:DESC.RAW data of ALL events; 1991 data
*---------------------------------------------------*
:NICK.RAWD90
:GNAME.P01_ALLD/RAWD/NONE/Y90V00/*/R
:DESC.RAW data of ALL events; 1990 data
*---------------------------------------------------*
:NICK.RAWD
:GNAME.P01_ALLD/RAWD/NONE/Y*/*/R
:DESC.RAW data of ALL events.
*---------------------------------------------------*
:NICK.LEPT92
:GNAME.P01_ALLD/DSTO/LEPT/Y92V>/*/R
:DESC.DST data of the LEPTONIC events; 1992 data, last proc.
*---------------------------------------------------*
:NICK.LEPT91
:GNAME.P01_ALLD/MDST/LEPT/Y91V>/*/R
:DESC.RTD data of the LEPTONIC events; 1991 data, last proc.
*---------------------------------------------------*
:NICK.LEPT91_D
:GNAME.P01_ALLD/MDST/LEPT/Y91V05/*/R
:DESC.RTD data of the LEPTONIC events; 1991 data, 5th proc. (DELANA_D)
:NICK.LEPT90
*---------------------------------------------------*
:GNAME.P01_ALLD/MDST/LEPT/Y90V>/*/R
:DESC.RTD data of the LEPTONIC events; 1990 data, last proc .
*---------------------------------------------------*
:NICK.LEPT
:GNAME.P01_ALLD/MDST/LEPT/Y[90:99]V>/*/R
:DESC.RTD data of the LEPTONIC events; last available processings.
*---------------------------------------------------*
:NICK.DSTLEP92
:GNAME.P01_ALLD/DSTO/LEPT/Y92V>/*/R
:DESC.DST-only data of the LEPTONIC events; 1992 data, last proc .
*---------------------------------------------------*
:NICK.DSTLEP91
:GNAME.P01_ALLD/DSTO/LEPT/Y91V>/*/R
:DESC.DST-only data of the LEPTONIC events; 1991 data, last proc .
*---------------------------------------------------*
:NICK.DSTLEP90
:GNAME.P01_ALLD/DSTO/LEPT/Y90V>/*/R
:DESC.DST-only data of the LEPTONIC events; 1990 data, last proc .
*---------------------------------------------------*
:NICK.DSTLEP
:GNAME.P01_ALLD/DSTO/LEPT/Y[90:99]V>/*/R
:DESC.DST-only data of the LEPTONIC events; last available processings.
*---------------------------------------------------*
:NICK.S2PR92
:GNAME.P01_ALLD/MDST/S2PR/Y92V>/*/R
:DESC.RTD data of 2-PRONG events for calib./align.; 1992 data, last proc
*---------------------------------------------------*
:NICK.S2PR91
:GNAME.P01_ALLD/MDST/S2PR/Y91V>/*/R
:DESC.RTD data of 2-PRONG events for calib./align.; 1991 data, last proc
*---------------------------------------------------*
:NICK.S2PR
:GNAME.P01_ALLD/MDST/S2PR/Y[90:99]V>/*/R
:DESC.RTD data of 2-PRONG events selected for calibration/alignment.
*---------------------------------------------------*
:NICK.DSTO92
:GNAME.P01_ALLD/DSTO/PHYS/Y92V>/*/R
:DESC.DST-only of the "OR" of the physics teams, 1992 data, last proc.
*---------------------------------------------------*
:NICK.DSTO91
:GNAME.P01_ALLD/DSTO/PHYS/Y91V>/*/R
:DESC.DST-only of the "OR" of the physics teams, 1991 data, last proc.
*---------------------------------------------------*
:NICK.DSTO91_D
:GNAME.P01_ALLD/DSTO/PHYS/Y91V05/*/R
:DESC.DST-only, "OR" of the physics teams, 91 data, 5th proc.(DELANA_D)
*---------------------------------------------------*
:NICK.DSTO90
:GNAME.P01_ALLD/DSTO/PHYS/Y90V>/*/R
:DESC.DST-only of the "OR" of the physics teams; 1990 data, last proc.
*---------------------------------------------------*
:NICK.DSTO
:GNAME.P01_ALLD/DSTO/PHYS/Y[90:99]V>/*/R
:DESC.DST-only of the "OR" of the physics teams; all available procs.
*---------------------------------------------------*
:NICK.PHYS90
:GNAME.P01_ALLD/MDST/PHYS/Y90V>/*/R
:DESC.RTD data of the "OR" of the physics teams; 1990 data, last proc .
*---------------------------------------------------*
:NICK.CRAW
:GNAME.P01_ALLD/CRAW/PHYS/Y*V>/*/R
:DESC.Raw data of events tagged by Delana; last proc .
*---------------------------------------------------*
:NICK.CRAW91
:GNAME.P01_ALLD/CRAW/PHYS/Y91V>/*/R
:DESC.Raw data of events tagged by Delana; 1991 data, last proc .
*---------------------------------------------------*
:NICK.PHYS
:GNAME.P01_ALLD/MDST/PHYS/Y90V>/*/R
:DESC.RTD data of the "OR" of the physics teams (only exist for 1990)
*---------------------------------------------------*
:NICK.HOTP90
:GNAME.P01_ALLD/MDST/HOTP/Y90V>/*/R
:DESC.RTD data of the "HOT PHYSICS" events; 1990 data, last proc .
*---------------------------------------------------*
:NICK.HOTP
:GNAME.P01_ALLD/MDST/HOTP/Y90V>/*/R
:DESC.RTD data of the "HOT PHYSICS" events (only exist for 1990).
*---------------------------------------------------*
:NICK.CRAWHAD90
:GNAME.P01_ALLD/CRAW/HADR/Y90V>/*/R
:DESC.Raw data of events tagged by TEAM 4; 1990 data,last proc .
*---------------------------------------------------*
:NICK.CRAWHAD
:GNAME.P01_ALLD/CRAW/HADR/Y90V>/*/R
:DESC.Raw data of events tagged by TEAM 4 (only exist for 1990).
*---------------------------------------------------*
:NICK.CRAWHADR90
:GNAME.P01_ALLD/CRAW/HADR/Y90V>/*/R
:DESC.Raw data of events tagged by TEAM 4; 1990 data, last proc .
*---------------------------------------------------*
:NICK.CRAWHADR
:GNAME.P01_ALLD/CRAW/HADR/Y90V>/*/R
:DESC.Raw data of events tagged by TEAM 4 (only exist for 1990).
*---------------------------------------------------*
:NICK.HADR90
:GNAME.P01_ALLD/CRAW/HADR/Y90V>/*/R
:DESC.Raw data of events tagged by TEAM 4; 1990 data, last proc .
*---------------------------------------------------*
:NICK.HADR
:GNAME.P01_ALLD/CRAW/HADR/Y90V>/*/R
:DESC.Raw data of events tagged by TEAM 4 (only exist for 1990).
*---------------------------------------------------*
:NICK.REST90
:GNAME.P01_ALLD/MDST/REST/Y90V>/*/R
:DESC.RD data of events NOT TAGGED by any team; 1990 data, last proc .
*---------------------------------------------------*
:NICK.REST
:GNAME.P01_ALLD/MDST/REST/Y90V>/*/R
:DESC.RD data of events NOT TAGGED by any team (only exist for 1990).
*---------------------------------------------------*
:NICK.PHDO90
:GNAME.P01_ALLD/DSTO/PHYS/Y90V>/*/R
:DESC.DST-only of the "OR" of the physics teams; 1990 data, last proc .
*---------------------------------------------------*
:NICK.PHDO
:GNAME.P01_ALLD/DSTO/PHYS/Y90V>/*/R
:DESC.DST-only of the "OR" of the physics teams; 1990 data, last proc .
*---------------------------------------------------*
:NICK.XDST
:GNAME.P01_ALLD/XDST/DETD/Y*V>/*/R
:DESC.DST + RAW data of RICH & HPC
*---------------------------------------------------*
:NICK.XDST92
:GNAME.P01_ALLD/XDST/DETD/Y92V>/*/R
:DESC.DST + RAW data of RICH & HPC  (1992)
*---------------------------------------------------*
:NICK.ALLD92
:GNAME.P01_ALLD/*/Y92V*/*/R
:DESC.All available Delphi 1992 real data.
*---------------------------------------------------*
:NICK.ALLD91
:GNAME.P01_ALLD/*/Y91V*/*/R
:DESC.All available Delphi 1991 real data.
*---------------------------------------------------*
:NICK.ALLD90
:GNAME.P01_ALLD/*/Y90V*/*/R
:DESC.All available Delphi 1990 real data.
*---------------------------------------------------*
:NICK.ALLD
:GNAME.P01_ALLD/*/*/R
:DESC.All available Delphi real data.
*---------------------------------------------------*
:NICK.*
:GNAME.P01_ALLD/*/*/R
:DESC.All available Delphi real data.
*---------------------------------------------------*
*----------   S I M U L A T I O N  -----------------*
*---------------------------------------------------*
:NICK.BABA91
:GNAME.P01_SIMD/DSTO/BABA/*JUL91*/*
:DESC.Bhabha events in barrel region, July 91 release (SIM35 ANA41).
*---------------------------------------------------*
:NICK.BAFO91
:GNAME.P01_SIMD/DSTO/BAFO/*JUL91*/*
:DESC.Bhabha events in barrel+forward region, July 91 SIM35 ANA41.
*---------------------------------------------------*
:NICK.MUMU91
:GNAME.P01_SIMD/DSTO/MUMU/*JUL91*/*
:DESC.Dimuon events, July 91 release (SIM35 ANA41).
*---------------------------------------------------*
:NICK.TAU291
:GNAME.P01_SIMD/DSTO/TAU2/*JUL91*/*
:DESC.Tau tau events, July 91 release (SIM35 ANA41).
*---------------------------------------------------*
:NICK.QQME91
:GNAME.P01_SIMD/DSTO/QQME/*JUL91*/*
:DESC.qqbar events Matrix Element, July 91 release (SIM35 ANA41).
*---------------------------------------------------*
:NICK.QQPS91
:GNAME.P01_SIMD/DSTO/QQPS/*JUL91*/*
:DESC.qqbar events Parton Shower, July 91 release (SIM35 ANA41).
*---------------------------------------------------*
:NICK.QQPN91
:GNAME.P01_SIMD/DSTO/QQPN/*JUL91*/*
:DESC.qqbar events Parton Shower, no B0 mixing. July 91 release.
*---------------------------------------------------*

                    Output of the above program

 P01_ALLD/RAWD/NONE/Y91V00/*/R
 RAW data of ALL events; 1991 data
 P01_ALLD/DSTO/LEPT/Y92V>/*/R(10:20)*
 DST data of the LEPTONIC events; 1992 data, last proc.
 P01_ALLD/RAWD/NONE/Y91V00/*/R(17:77)*
 RAW data of ALL events; 1991 data

Modify user words

            +------------------------------------------------+
            |CALL  FMMODU (PATH,UFORM,UVECT,UCOMM,CHOPT,IRC*) |
            +------------------------------------------------+

PATH

Character variable of maximum length 255 to specify the path name of containing the files for which the user words are to be modified. The path name may contain wild-cards, as for FMLDIR or FMSCAN.

PATH

Character variable of length 4 specifying the user file format.

PATH

Vector of length 10 containing the user words.

PATH

Character variable of maximum length 80 specifying the user comment.

CHOPT

Character variable to specify the type of operation required.

CHOPT = C: modify comment field
        F: modify user file format
        V: modify user vector

IRC

Integer variable in which the return code is returned.

This routine may be used to modify any or all of the user fields associated with all files in the specified path. The path name may contain wild-cards.

                Example of using the  FMMODU routine

      DIMENSION  IVECT(10)
*
*     Fill IVECT
...
*
*     Now update the user words for all files in the subtree
*     corresponding to the highest pass
*
      CALL FMMODU('//CERN/OPAL/PROD/PASS>/*',' ',IVECT,' ','V',IRC)

Declare logical units to FATMEN

                      +----------------------------+
                      |CALL  FMSETU (LUN,NLUN,IRC*) |
                      +----------------------------+

LUN: Array of length NLUN containing a list of logical units that may be used by FATMEN. This list must not include those declared in the call to FMSTRT or FMINIT.
NLUN: The number of logical units, maximum 99
IRC: Integer variable in which the return code is returned.

Get a free logical unit

                        +------------------------+
                        |CALL  FMGLUN (LUN*,IRC*) |
                        +------------------------+

LUN: Integer variable in which an unused logical unit is returned. A list of logical units must have first been declared using FMSETU (see on Page [more info]). On VAX/VMS systems, if no units have been declared or if the list has been exhausted, the routine LIB$GETLUN is called to obtain a new unit.
IRC: Integer variable in which the return code is returned.

Get a free logical unit

                        +------------------------+
                        | CALL  FMFLUN (LUN,IRC*) |
                        +------------------------+

LUN: Integer variable containing the number of the FORTRAN logical unit to be freed.
IRC: Integer variable in which the return code is returned.

Verify bank contents

               +------------------------------------------+
               |CALL  FMVERI (GENAM,LBANK,KEYS,CHOPT,IRC*) |
               +------------------------------------------+

GENAM

Character variable of maximum length 255 to specify the generic name.

LBANK

Integer variable to input the address of the bank corresponding to the generic name specified.

KEYS

Integer array of length 10 to contain the keys vector associated with the specified generic name.

CHOPT

Character variable specifying the required options.

: check entire bank
A: check entire bank, except option Q
C: check comment string
F: check file attributes
K: check keys
L: check logical attributes
M: check media attributes
N: check dataset name on disk/tape of this file
O: check owner, node and job of creator etc.
P: check physical attributes, such as record format etc.
Q: check that volume is known to TMS
S: check security details of this file (protection)
T: check date and time of creation, last access etc.

IRC

Integer variable specifying the return code.

This routine will check the contents of a FATMEN bank and the associated keys vector. FMVERI returns warnings via the IQUEST vector and error conditions via the return code IRC. Errors are generated when a value for a required field is not specified or if an invalid value is given.

                Example of using the  FMVERI routine

      CALL FMVERI(GENAM,LBANK,KEYS,'T',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMVERI

The following character options may be specified to cause FMVERI to check various parts of the FATMEN bank. See the table below for details of the formats of the various fields.

Errors and warnings returned via the IQUEST vector are given on the following page.

N.B. an error in the fields denoted by the options F,K,L,M,N,O,P or T will result in a non-zero return code. Banks containing such errors will not be added to the FATMEN catalogue.

IQUEST(3): 1 Comment is blank
: 2 Comment contains 'unseen' characters
IQUEST(6): 1 One or more file attributes missing
IQUEST(11): 1 File name in keys does not match generic name
: 2 Copy level, Media type or location code missing
: 3 Copy level, Media type or location code conflict (keys/bank)
IQUEST(12): 1 Invalid FATMEN format
IQUEST(13): 1 Host or O/S (disk files) or VSN,VID or FSEQ (tape files) missing
: 2 File size greater than maximum for specified media type
IQUEST(14): 1 Dataset name is missing
: 2 Dataset name is in invalid format
IQUEST(15): 1 Owner, node or job name missing
IQUEST(16): 1 Physical attributes missing or invalid
IQUEST(19): 1 (Security field - no check at present)
IQUEST(20): 1 Time or date fields are invalid
IQUEST(21): 1 All user words are zero
IQUEST(26): IQFOUL Invalid bank status word. Most likely caused by an assignment statement containing an undefined variable or by specifying an invalid bank address.

Pack date and time.

                 +--------------------------------------+
                 |CALL  FMPKTM (IDATE,ITIME,IPACK*,IRC*) |
                 +--------------------------------------+

IDATE: Integer variable with date in YYMMDD format.
ITIME: Integer variable with time in HHMM format.
IPACK*: Integer variable to store the date and time in packed format.
IRC*: Integer variable in which the return code is returned.

This routine allows a date and time to be stored in a 4 byte integer word. The CERNLIB routine DATIME, entry Z007, can be used to obtain IDATE and ITIME in the correct format. Should IDATE, ITIME be in invalid format, a non-zero return code will be returned and IPACK will be set to zero.

Unpack date and time.

                +----------------------------------------+
                | CALL  FMUPTM (IDATE*,ITIME*,IPACK,IRC*) |
                +----------------------------------------+

IDATE*: Integer variable to store the date in YYMMDD format.
ITIME*: Integer variable to store the time in HHMM format.
IPACK: Integer variable with date and time in packed format.
IRC*: Integer variable in which the return code is returned.

This routine unpacks the date and time from a 4 byte integer word. IPACK must be the result of a previous call to FMPKTM. Should IPACK be in invalid format, a non-zero return code will be returned and IDATE and ITIME will be set to zero.

Pack date and time for VAX format.

            +------------------------------------------------+
            | CALL  FMPKVX (CHDATE,IDATE*,ITIME*,IPACK*,IRC*) |
            +------------------------------------------------+

CHDATE: Character variable of length 23 containing the date and time in VAX format (dd-mon-yyyy hh:mm:ss.ff, e.g. 11-JUL-1991 17:14:41.37)
IDATE*: Integer variable with date in YYMMDD format.
ITIME*: Integer variable with time in HHMM format.
IPACK*: Integer variable to store the date and time in packed format.
IRC*: Integer variable in which the return code is returned.

This routines provides the functionality of the FMPKTM except that the input date is expected in VAX format.

Unpack date and time for VAX format.

            +------------------------------------------------+
            | CALL  FMUPVX (CHDATE*,IDATE*,ITIME*,IPACK,IRC*) |
            +------------------------------------------------+

CHDATE*: Character variable of length 23 in which the date and time are returned in VAX format (dd-mon-yyyy hh:mm:ss.ff, e.g. 11-JUL-1991 17:14:41.37)
IDATE*: Integer variable to store the date in YYMMDD format.
ITIME*: Integer variable to store the time in HHMM format.
IPACK: Integer variable with date and time in packed format.
IRC*: Integer variable in which the return code is returned.

This routines provides the functionality of FMUPTM for VAX date and time formats.