+----------------------------------------------+
|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'
+------------------+
|CALL FMEND (IRC*) |
+------------------+
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.
+--------------------+
|CALL FMLOGL (LEVEL) |
+--------------------+
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 [more info] 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 [more info] 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'
+------------------------------+
|CALL FMPUT (GENAM,LBANK,IRC*) |
+------------------------------+
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 [more info] 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 [more info] 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*) |
+----------------------------------------------------+
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*) |
+--------------------------------------------------+
Use the FMLN routine to make a link to an existing catalogue entry.
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*) |
+--------------------------------------------+
+--------------------------+
| CALL FMKDIR (CHDIR,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: