CALL FMINIT (IXSTOR*,LUNRZ,LUNFZ,DBNAME,IRC*)
This routine initialises the FATMEN system. LUNRZ and LUNFZ are the logical units that will be used to access the database for reading and writing. If read-only access is required, LUNFZ should be set to 0. The database name DBNAME is a character string indicating the name of the database that is to be accessed. This field must be of the form '//CERN/experiment'.
On VM systems, the virtual card punch is used to communicate updates with the service machine that handles the database. As the punch may be in use for other purposes, both positive and negative values of LUNFZ are foreseen. If LUNFZ > 0, the punch will be used directly, which implies that it cannot be used by the calling programme for any other purpose. If LUNFZ < 0, a temporary file will be created and sent via SENDFILE to the server. The disk with most free space that is accessed in WRITE mode will be used for this purpose. If LUNFZ > 0, FATMEN will assume that it can write directly to the PUN device.
Example of using the FMINIT routine
* Initialise FATMEN for group CPLEAR
CALL FMINIT(IXSTOR,1,2,'//CERN/CPLEAR',IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMINIT'
This routine should be called when no further access to the FATMEN file catalogue is required, normally at program termination. This routine automatically calls the routine FMUPDT to ensure that any outstanding updates are sent to the server.
Example of using the routine FMEND
CALL FMEND(IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMEND'
After a call to FMEND, a further call to FMINIT may be made, to look at the same or different FATMEN catalogue.
This routine establishes the LEVEL of diagnostic printing from the FATMEN package.
Example of using the routine FMLOGL
* Set maximum logging level to monitor FATMEN progress
CALL FMLOGL(3)
CALL FMUPDT (MAX,NGROUP,IFLAG,IRC*)
This routine controls the updating mode of the FATMEN package. MAX is the maximum number of updates that may be issued by a single job. NGROUP is the number of updates to send together. If IFLAG=-1, the system defaults of MAX=999, NGROUP=0 (send each update separately) will be applied. If IFLAG=0, MAX and NGROUP will be reset as specified, with any outstanding updates sent immediately. If IFLAG=1, MAX and NGROUP will be reset as specified, with any outstanding updates purged.
Example of using the FMUPDT routine
* Reset updating mode to the system defaults
CALL FMUPDT(MAX,NGROUP,-1,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMUPDT
* Cancel any outstanding updates and limit future updates to 10
CALL FMUPDT(10,NGROUP,1,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMUPDT
CALL FMPURG (PATH,KEYSEL,MAXSIZ,MINACC,MAXDAYS,MINCPS,LUNPUR,CHOPT,IRC*)
This routine searches for files matching the specified path and KEYSEL selection for entries eligible for deletion. A check may be bypassed by coding a -1 for the corresponding parameter. Thus, to purge files without checking on the number of accesses, specify a -1 for MINACC.
Example of using the routine FMPURG
DIMENSION KEYSEL(10)
* Restrict search to 3480s
KEYSEL(MKMTFA) = 2
* Restrict search to location code 1
KEYSEL(MKLCFA) = 1
* Make no check on Copy Level
KEYSEL(MKLCFA) = -1
*
* Print all files eligible for purge that are 80 MB or larger,
* have been accessed less than 10 times, have not been accessed
* in the last 60 days, and for which at least 3 copies exist.
*
CALL FMPURG('//CERN/CNDIV/J*',KEYSEL,80,10,60,3,0,'P',IC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMPURG'
CALL FMGET (GENAM,LBANK*,KEYS*,IRC*)
This routine returns the address of the bank LBANK
and the keys vector KEYS
for the specified generic name GENAM. Should multiple entries exist for
the given generic name GENAM, the FATMEN system will choose the most
appropriate, according to a simple algorithm. Should a specific
copy be required, the routine FMGETK should be used.
Warning: any bank at the address LBANK will be dropped by this
routine on input.
See the example on page
for an example of using a link area
to save the address of multiple banks, e.g. when calling this
routine in a loop.
The procedure for selecting a given copy of a dataset is as follows:
Where access to remote data is available, the procedure will then continue, searching for datasets on remote disks, in remote robots and finally on remote manually mounted tapes.
Example of using the FMGET routine
* Select a copy of a dataset using default FATMEN selection.
CALL FMGET('//CERN/CNDIV/CHRIS/TAPE8',LBANK,KEYS,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMGET'
CALL FMGETK (GENAM,LBANK*,*KEYS*,IRC*)
This routine returns the address of the bank LBANK for the
combination of the generic name GENAM
and key vector KEYS specified. This allows the user
to select a particular copy of a file.
Warning: any bank at the address LBANK will be dropped by this
routine on input.
See the example on page
for an example of using a link area
to save the address of multiple banks, e.g. when calling this
routine in a loop.
Example of using the FMGETK routine
Select a given copy of a dataset.
* The vector MYKEYS was obtained from FMSELK.
CALL FMGETK('//CERN/CNDIV/CHRIS/TAPE8',LBANK,MYKEYS(1,1),IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMGETK'
This routine enters the information in the bank with address LBANK
for the specified generic name GENAM in the database.
If a matching dataset already exists for this generic name, nothing
will be added to the database. In all other cases a new entry will
be made.
Before the entry is sent to the FATMEN server, the routine FMVERI
is automatically called. Should FMVERI return a non-zero return
code, the entry will not be sent to the server. This is to ensure
that the FATMEN catalogue is correctly updated and that the data
can be successfully retrieved.
See the description of the FMCOMP routine on
page for details of the association
of generic names and datasets.
Example of using the FMPUT routine
CALL FMPUT('//CERN/CHARM2/TEST/DST1/ELEC/HO20/NOM/E02/FILE1',
+LBANK,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMPUT'
CALL FMMOD (GENAM,LBANK,IFLAG,IRC*)
This routine is similar top the routine FMPUT, except
that it also allows an existing entry to be modified.
Before the entry is sent to the FATMEN server, the routine FMVERI
is automatically called. Should FMVERI return a non-zero return
code, the entry will not be sent to the server. This is to ensure
that the FATMEN catalogue is correctly updated and that the data
can be successfully retrieved.
See the description of the FMCOMP routine on
page for details of the association
of generic names and datasets.
Example of using the FMMOD routine
*
* Update an existing entry with the number of Megabytes written
IQ(LBANK+MFSZFA) = 200
CALL FMMOD('//CERN/CNDIV/CHRIS/TAPE8',LBANK,1,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMMOD
CALL FMBOOK (GENAM,KEYS*,LADDR*,*LSUP*,JBIAS,IRC*)
This routine will create a new ZEBRA bank for the specified
generic name GENAM and fill in default values.
The user may then modify these before
committing the changes via FMPUT.
If IRC is non-zero, the IQUEST vector will contain the error condition
signaled by MZBOOK.
See the description of MZBOOK in the ZEBRA manual.
The address of the bank lifted is the users responsibility and should be saved in a link area.
Example of using the FMBOOK routine
*
CALL FMBOOK(GNAME,KEYS,LUSRBK,LSUP,JBIAS,IRC)
FMBOOK returns warning conditions using the IQUEST vector. The following conditions may be reported:
CALL FMLN (CHSRCE,CHTRGT,CHCOMM,IVECT,CHOPT,IRC*)
In Unix parlence, the sourcefile is the real file and the targetfile the link that points to it. To avoid even further confusion, the same terminology is adopted here.
If the existing entry is itself a link, the link will point to the source of that link.
A link is identified by having location code 0. The source file name is stored in the FATMEN bank at the offset MFQNFA.
Links can be useful in the following scenario. DELPHI write single file 3480 cassettes which contain more than one run. There is a generic name for each run that points to the same file. Additionally, there is also a so-called SUMT entry (for summary tape). This can cause house keeping problems, particularly when making copies for data export.
A solution to the above problem is to make the run specific generic names links. Only the SUMT entries are copied, moved or deleted. When a file is accessed via a link, the link is automatically resolved. The FATMEN selection then procedes as if the sourcefile name had been given.
A limitation of the current implementation is that it does not cater for the situation when a single run is copied to hotter media, e.g. disk. This would involve some reworking of the selection logic and remains pending demand from actual usage.
CALL FMRM (GENAM,LBANK*,KEYS,IRC*)
This routine marks the entry generic name GENAM for deletion. An entry is uniquely identified by the following information: Host name, DSN (for disk files), Location, VID, VSN, File sequence number (for tape files), contained in the bank at address LBANK. Files may only be deleted by the creator. If a non-zero key vector KEYS is input, KEYS(1) will be used to select a specific copy of a file for deletion. If only one match for the specified name exists, KEYS(1) may be zero. If more than one entry for the specified generic name exists, KEYS(1) must specify the copy that is to be deleted.
Example of using the FMRM routine
DIMENSION KEYS(10)
CALL VZERO(KEYS,10)
LBANK = 0
CALL FMRM('//CERN/CHARM2/TEST/DST1/ELEC/HO20/NOM/E02/FILE1',
+LBANK,KEYS,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMRM'
CALL FMRMLN (CHLINK,LUN,CHFILE,CHOPT,IRC*)
This routine creates the specified directory CHDIR.
Example of using the routine FMKDIR
CALL FMKDIR('//CERN/ALEPH/MC/TEST',IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMKDIR
FMKDIR returns warning conditions using the IQUEST vector. The following conditions may be reported: