+--------------------------+
| CALL FMEXST (GENAM,IRC*) |
+--------------------------+
This routine returns the number of occurances of the input generic name GENAM in the FATMEN database. A return code of 0 indicates, therefore that no matches are found, whereas a return code of 3 would indicate that 3 copies were found. Routine FMSELK (see on Page [more info]) can be used to count the number of files with certain characteristics, such as location code or media type.
Example of using the FMEXST routine
CALL FMEXST('//CERN/CNDIV/JAMIE/IN',IRC)
PRINT *,IRC,' occurances in FATMEN database'
+------------------------------+
| CALL FMLS (GENAM,CHOPT,IRC*) |
+------------------------------+
This routine lists the files according to the specified generic name GENAM. Examples of valid generic-names are:
//cern/cndiv/goossens/*, //cern/cndiv/goossens/dcf/m%%%, //cern/cndiv/chris/tape8.
The generic-name may also contain numeric ranges specified as (mm:nn), such as (13:147) in the field following the last delimiter (/). See on Page [more info] for more details. If IRC < 0, then the specified pathname does not exist or is invalid. Otherwise, IRC returns the number of files found (which may be 0).
Example of using the FMLS routine
* List media details of files M%%% in //CERN/CNDIV/GOOSSENS/DCF
CALL FMLS('//CERN/CNDIV/GOOSENS/DCF/M%%%','M',IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMLS'
The allowed values of CHOPT and their meanings are as follows:
+----------------------------------------------+
|CALL FMSHOW (GENAM,*LBANK*,*KEYS*,CHOPT,IRC*) |
+----------------------------------------------+
This routine displays the contents of the FATMEN bank corresponding to the input generic names GENAM, or at the address LBANK if non-zero. See the description of the ls command for a description of the CHOPT argument. It is envisaged that this routine will be tailored to suit the requirements of individual experiments.
Example of using the FMSHOW routine
*
CALL FMSHOW('//CERN/CNDIV/GOOSENS/DCF/M123',LBANK,KEYS,'M',IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMSHOW'
The allowed values of CHOPT and their meanings are
+----------------------------------+
| CALL FMFILC (GENAM,NFILES*,IRC*) |
+----------------------------------+
This routine returns the number of files that match the specified generic name. The generic name is interpreted as for the FMLS routine (see on Page [more info]. That is, any characters following the last slash are assumed to be the filename, those preceeding the last slash are the pathname.
Example of using the FMFILC routine
CALL FMFILC('//CERN/DELPHI'//
+ '/ALLD/RAWD/CERN/V00%/E09%.00/P01R*/NONE/RUN*',
+ NFILES,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMFILC'
+--------------------------------------+
| CALL FMSCAN (PATH,NLEVEL,UROUT,IRC*) |
+--------------------------------------+
This routine scans the directory names in the directory tree specified by PATH. The directory tree may contain wild-cards (* or %) in any position, or numeric ranges specified as (mm:nn), such as (13:147). See on Page [more info] for more details. The path name PATH may also contain the wild-cards < or >. These wild cards may be used to find, for example, the highest PASS of a run. Assuming that, at a given level, the generic name has a field containing PASSn, e.g. PASS3, PASS1, specifying PASS> will cause FMSCAN to follow ONLY the PASS3 subdirectory
For each matching directory, FMSCAN will call the specified user routine with the matching directory name. Upon exit from the user routine, a non-zero return code will cause FMSCAN to stop the search.
On entry to the user routine, IQUEST contains the following information:
In addition, on return from FMSCAN, IQUEST(11) contains the total number of directories processed.
Example of calling the routine FMSCAN
EXTERNAL FUSCAN
*
* This should follow the path PASS5/GPMH/P5
*
ICONT = 0
1 CONTINUE
CALL FMSCAN('//CERN/OPAL/PROD/PASS>/GPMH/P<',99,FUSCAN,IRC)
Example of a user exit routine
SUBROUTINE UROUT(PATH,IRC)
CHARACTER*(*) PATH
COMMON/QUEST/IQUEST(100)
IRC = 0
*
* Set IRC^=0 to stop directory scan
*
PRINT *,'<< ',PATH(1:LENOCC(PATH))
END
+--------------------------------------+
|CALL FMLOOP (GENAM,NLEVEL,UROUT,IRC*) |
+--------------------------------------+
This routine is similar to FMSCAN, but expects a complete generic name on input, rather than just a path name.
For each matching generic name, FMLOOP will call the specified user routine with the generic name and keys vector. Upon exit from the user routine, a non-zero return code will cause FMLOOP to stop the search.
Upon entry to the user routine, IQUEST will contain the following information.
This routine respects the values set for medium type, location code and copylevel by the routines FMSETM, FMSETL and FMSETC respectively.
Upon return from the user routine, IRC < 0 will cause FMLOOP to skip to the next directory, IRC > 0 will cause FMLOOP to return.
Example of calling the routine FMLOOP
EXTERNAL UROUT
*
* List all files in all directories beginning with a J
* down to the maximum (99) number of levels
*
CALL FMLOOP('//CERN/CNDIV/J*/*',99,UROUT,IRC)
Example of a user exit routine
SUBROUTINE UROUT(GENAM,KEYS,IRC)
CHARACTER*(*) GENAM
PARAMETER (LKEYFA=10)
DIMENSION KEYS(LKEYFA)
IRC = 0
PRINT *,'Generic name = ',GENAM(1:LENOCC(GENAM))
PRINT *,'Keys: '
CALL FMPKEY(KEYS,LKEYFA)
END
+----------------------------------------------------+
|CALL FMLDIR (PATH,DIRS*,NFOUND,MAXDIR,*ICONT*,IRC*) |
+----------------------------------------------------+
Example of using the FMLDIR routine
PARAMETER (LKEYFA=10)
PARAMETER (MAXDIR=1000)
CHARACTER*255 DIRS(MAXDIR)
*
* This should follow the path PASS5/GPMH/P5
*
ICONT = 0
1 CONTINUE
CALL FMLDIR('//CERN/OPAL'//
+ '/PROD/PASS>/GPMH/P<',
+ DIRS,NFOUND,MAXDIR,IRC)
IF(IRC.EQ.-1) THEN
ICONT = 1
ELSE
ICONT = 0
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMLDIR'
ENDIF
+----------------------------------------------------------+
|CALL FMLFIL (GENAM,FILES*,KEYS*,NFOUND,MAXFIL,JCONT,IRC*) |
+----------------------------------------------------------+
This routine returns the file names in the directory tree specified by GENAM. The directory tree may contain wild-cards (* or %) in any position, or numeric ranges specified as (mm:nn), such as (13:147). See on Page [more info] for more details. The generic name GENAM may also contain the wild-cards < or >. These wild cards may be used to find, for example, the highest PASS of a run. Assuming that, at a given level, the generic name has a field containing PASSn, e.g. PASS3, PASS1, specifying PASS> will cause FMLFIL to follow ONLY the PASS3 subdirectory structure. NFOUND returns the actual number of files returned. IRC = -1 : more files found than can be returned in FILES(MAXFIL) FMLDIR should be called again with ICONT=0 to get the next MAXFIL batch of FILES. N.B. This routine returns ALL file names in in the order in which they were added to the catalogue. See the routine on Page [more info] for details of how to sort the FILES array.
Example of using the FMLFIL routine
PARAMETER (LKEYFA=10)
PARAMETER (MAXFIL=1000)
CHARACTER*255 FILES(MAXFIL)
*
* This should follow the path PASS5/GPMH/P5
*
* Indicate that this is a new call
*
JCONT = 0
1 CONTINUE
CALL FMLFIL('//CERN/OPAL/PROD/PASS>/GPMH/P<',
+ FILES,KEYS,NFOUND,MAXFIL,JCONT,IRC)
IF(IRC.EQ.-1) THEN
JCONT = 1
ELSE
JCONT = 0
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMLFIL'
ENDIF
*
* Process this batch of files...
*
* ...
*
* Get next batch of files...
*
IF(JCONT.NE.0) GOTO 1
+--------------------------------------------+
|CALL FMSORT (FILES,KEYS,NFILES,JSORT*,IRC*) |
+--------------------------------------------+
This routine returns in JSORT the sorted indices into FILES and KEYS in ascending order of FILES.
Example of using the FMSORT routine
PARAMETER (LKEYFA=10, MAXFIL=1000)
CHARACTER*255 FILES(MAXFIL)
INTEGER KEYS(LKEYFA,MAXFIL),JSORT(MAXFIL)
*
CALL FMSORT(FILES,KEYS,NFILES,JSORT,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMSORT'
*
* Print sorted files and associated keys
*
DO 10 I=1,NFILES
PRINT *,FILES(JSORT(I))
10 CALL FMPKEY(KEYS(1,JSORT(I))),LKEYFA)
+--------------------------------------------------+
|CALL FMRANK CHFILES,KEYS,NFILES,JSORT,CHOPT,IRC*) |
+--------------------------------------------------+
This routine returns a index into the arrays CHFILES and KEYS ranked by tape volume (MVIDFA) and file sequence number (MFSQFA). A maximum of 100 entries can be processed in one call.
It is foreseen that this routine be used prior to calling FMOPEN with the Q option.
+--------------------------------+
|CALL FMATCH (CHFILE,MATCH,IRC*) |
+--------------------------------+
This routine matches the input file name CHFILE against the pattern specified in MATCH and returns 1 in IRC if no match is found. MATCH may include wild-cards as in VAX/VMS or VM/CMS file names, where a ``%'' will match any single character and a "*" will match any number of characters. In addition, numeric ranges may be specified using the syntax (mm:nn), such as (1:135). This form can be useful for specifying a set of runs, LEP files etc. Note that if mm is shorter than nn, it will be left-padded with zeroes, thus (1:135) is equivalent to (001:135). CHFILE and MATCH are character variables and may be as long as 255 characters each.
Example of using the routine FMATCH
CHARACTER*255 CHFILE,MATCH
* Match against files RUN1-9 (or RUNx)
CALL FMATCH(CHFILE(1:LENOCC(CHFILE)),'RUN%',IRC)
IF(IRC.EQ.0) THEN
PRINT *,'Matching dataset found - ',CHFILE(1:LENOCC(CHFILE))
ELSE
PRINT *,'Dataset ',CHFILE(1:LENOCC(CHFILE)),' does not match'
ENDIF
+----------------------------------------------+
|CALL FMMANY (MATCH,FILES,NFILES,NMATCH*,IRC*) |
+----------------------------------------------+
This routine performs the same wild-card matching as FMATCH described above. In addition, if a < or > is specified in the MATCH pattern, it will return in NMATCH the element of the character array FILES which matches.
Example of using the routine FMMANY
CHARACTER*255 FILES(9),MATCH
FILES(1) = 'PASS3'
FILES(2) = 'TEST3'
FILES(3) = 'RUN13'
FILES(4) = 'HOTP'
FILES(5) = 'STUFF'
FILES(6) = 'PASS3'
FILES(7) = 'PASS5'
FILES(8) = 'PAZS9'
FILES(9) = 'POSS9'
MATCH = 'P%SS>'
CALL FMMANY(MATCH,FILES,9,NMATCH,IRC)
IF(NMATCH.NE.0) PRINT *,FILES(NMATCH)
+--------------------------+
| CALL FMPKEY (KEYS,NKEYS) |
+--------------------------+
This routine displays the contents of the FATMEN keys vector in the correct format, depending on the data type of the various elements (integer or hollerith).
Example of using the FMPKEY routine
CALL FMPKEY(KEYS,10)
+------------------------------------------------------+
|CALL FMSELK (GENAM,INKEYS,OUKEYS*,NKEYS*,MAXKEY,IRC*) |
+------------------------------------------------------+
This routine selects all datasets corresponding to the generic name GENAM on the basis of the keys vector INKEYS. By setting the relevant elements of INKEYS, datasets may be selected on media type, copy level and location code. Thus, by setting INKEYS(MKMTFA) to 1 (disk), all matching datasets on disk can be selected. If a key element is set to a negative value, it will not be used in the selection. Thus, by setting INKEYS(MKLCFA) to -1 and INKEYS(MKMTFA) to 2, all datasets with the specified generic name on 3480 cassette at any location will be returned. The number of datasets that match is returned in NKEYS, up to a maximum of MAXKEY. The array OUKEYS may then be used as input to the routine FMGETK.
Example of using the FMSELK routine
* Argument declarations
PARAMETER (LKEYFA=10)
PARAMETER (MAXKEY=999)
DIMENSION INKEYS(LKEYFA),OUKEYS(LKEYFA,MAXKEY)
* The following statements will select all datasets
* with copy level (MKCLFA) of 1 (i.e. a copy of an original file),
* media type of 1 (i.e. disk) and location code of 1 (i.e. CERN)
INKEYS(MKCLFA) = 1
INKEYS(MKMTFA) = 1
INKEYS(MKLCFA) = 1
CALL FMSELK('//CERN/CNDIV/CHRIS/TAPE8',INKEYS,OUKEYS,MAXKEY,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMSELK'
+--------------------------------------------------+
|CALL FMSELB (GENAM,INKEYS,NKEYS,UEXIT,ISEL*,IRC*) |
+--------------------------------------------------+
This routine allows the user to select a particular copy of a data set according to information contained in the FATMEN bank for the specified generic name. INKEYS is a matrix of dimension (10,NKEYS) containing the keys vectors for the various data sets matching the generic name, GENAM. This matrix is produced by a call to FMSELK to perform the appropriate initial selection, such as all data sets matching the input generic name that are on disk etc. For each matching data set, FMSELB will call the user-specified exit routine, which much be declared EXTERNAL, in the following way:
CALL UEXIT(GENAM,LBANK,KEYS,NKEYS,N,ISEL*,IRC*)
were
Example of using the FMSELB routine
* Argument declarations
PARAMETER (LKEYFA=10)
PARAMETER (MAXKEY=999)
DIMENSION INKEYS(LKEYFA,MAXKEY)
CALL FMSELB('//CERN/CNDIV/CHRIS/TAPE8',INKEYS,NKEYS,ISEL,IRC)
IF(IRC.NE.0) THEN
PRINT *,'Return code ',IRC,' from FMSELK'
ELSE
PRINT *,'Copy ',ISEL,' selected'
ENDIF
+------------------------------------------------------+
|CALL FMSELM (GENAM,LBANK*,KEYS*,KEYM,NKEY,CHOPT,IRC*) |
+------------------------------------------------------+
This routine takes each row of the input matrix KEYM in turn, and attempts to find a matching dataset. If no matching dataset is found, it then proceeds to the next row. Currently, checks are only made on media type (MKMTFA), location code (MKLCFA) and copy level (MKCLFA). A value of -1 indicates that no check on this item is to be made.
The following options are available:
I - issue FORTRAN inquire for disk datasets (with full support
for SHIFT files, Unix environmental variables, VM mini-disks,
SFS pools etc.)
N - check host name for disk datasets against current host
M - require that tape datasets reside on manually mounted volumes
R - require that tape datasets reside on robotically mounted volumes
Example of using the FMSELM routine
* Argument declarations
PARAMETER (LKEYFA=10)
PARAMETER (NKEY=3)
DIMENSION KEYS(LKEYFA),KEYM(LKEYFA,NKEY)
*
* Define search criteria: first, disk dataset in location 31,
* with no check on copy level,
* next, dataset on media type 2 in location 1,
* next, dataset on any media in any location
* with copy level 1
*
KEYM(MKMTFA,1) = 1
KEYM(MKCLFA,1) = -1
KEYM(MKLCFA,1) = 31
KEYM(MKMTFA,2) = 2
KEYM(MKCLFA,2) = -1
KEYM(MKLCFA,2) = 1
KEYM(MKMTFA,3) = -1
KEYM(MKCLFA,3) = 1
KEYM(MKLCFA,3) = -1
*
* Options NM: No check on host name for disk files,
* Manually mounted tape required
*
CALL FMSELM('//CERN/OPAL/DDST/PASS3/FYZ1/P20/R02222C01',
+ LBANK,KEYS,KEYM,NK,'NM',IRC)
PRINT *,'Return code from FMSELM = ',IRC
IF(IRC.EQ.0)
+ CALL FMSHOW('//CERN/OPAL/DDST/PASS3/FYZ1/P20/R02222C01',
+ LBANK,KEYS,'A',IRC)
+--------------------------------------------------------------------+
| CALL FMCOMP (GENAM1,*LBANK1*,*KEYS1*,GENAM2,*LBANK2*,*KEYS2*,IRC*) |
+--------------------------------------------------------------------+
This routine compares the FATMEN entries pointed to by the generic names GENAM1 and GENAM2. If either LBANK1 or LBANK2 is non-zero, the bank(s) at the corresponding address will be used. If either LBANK1 or LBANK2 are zero, the routine FMGETK will be used to obtain the corresponding bank. Should KEYS1(1) or KEYS2(1) be zero, the default FATMEN selection will apply. A zero return code indicates that the comparison succeeded. Other values of IRC are given below.
Example of using the FMCOMP routine
* Compare entries with following generic names
CALL FMCOMP('//CERN/OPAL/EVKI/MW34MH/R1200/P01',LBANK1,KEYS1,
+ '//CERN/OPAL/EVKI/JT72MH/R1100/P19',LBANK2,KEYS2,IRC)
IF(IRC.NE.0) PRINT *,'Comparison failed'