CALL FMFIND (GENAM,DDNAME,*LBANK*,IRC*)
This routine returns the bank address LBANK of the most suitable copy of the data referenced by the specified generic name GENAM. N.B. if LBANK is non-zero, the bank at this address will be used. This allows the user to make their own selection, e.g. by first calling FMGET, FMGETK or FMSELM, or to override some parameters in the Zebra bank for the specified generic name. If you do not wish to use this facility, you must drop the bank at LBANK using MZDROP.
When the calling program receives control, it may open the file on the logical unit corresponding to the DDNAME specified and read the data. Should the required data reside on tape, the FATMEN system will check access to the tape using the Tape Management System and STAGE the data on to disk.
The ddname, of type CHARACTER, may be specified as 'nn', e.g. 1 or 99, or as any valid logical unit such as FT93F005, IOFILE11, FOR003, fort.20 etc. If a one or two digit character is specified, it will be converted to the format used by FORTRAN on the host machine. (For files in EP or FX format on VM/CMS systems, the format IOFILEnn will be used). If the input bank-address is non-zero, the information in the bank to which it points will be used to accessed the data. If the bank-address is zero, FMLIFT will automatically call FMGET.
On VM/CMS systems only, a DDNAME of NOWAIT will result in a STAGE request with the NOWAIT option. This may be used to initialise the input staging of the tape i+1 while tape i is being processed. See the tutorial section of this manual for an example of using the NOWAIT option.
Example of using routine FMFIND
* Find a dataset using the default FATMEN selection
CALL FMFIND('//CERN/CNDIV/CHRIS/TAPE8','IOFILE13',LFAT,IRC)
IF(IRC.NE.0) PRINT *,'Return code',IRC,' from FMFIND.'
CALL FMMAKE (GENAM,DDNAME,*LBANK*,IRC*)
This subroutine creates a new disk or tape dataset, according to the
contents of the bank passed at LBANK
Before calling FMMAKE, the user should call
FMBOOK (see on Page 
)
and then set the various fields as required.
See the description of the FMFIND routine for information on the DDNAME parameter. N.B. if LBANK is non-zero, the bank at this address will be used. This allows the user to make their own selection, e.g. by first calling FMGET, FMGETK or FMSELM, or to override some parameters in the Zebra bank for the specified generic name. If you do not wish to use this facility, you must drop the bank at LBANK using MZDROP.
Example of using the routine FMMAKE
* Create dataset on IOFILE11.
* The bank at address LBANK was created by FMLIFT
CALL FMMAKE('//CERN/ALEPH/MDST/KELLNER/RUN123','IOFILE11',LBANK,IRC)
CALL FMOPEN (GENAM,DDNAME,*LBANK*,CHOPT,IRC*)
This routine accesses a dataset via its generic name GENAM and opens it on the logical unit specified by the character DDNAME. The following values are allowed for CHOPT.
F is specified, IQUEST(10) may be set to indicate
which form of I/O should be used. The default is FORTRAN I/O.
IQUEST(10) = 1 : C I/O
Corresponds to option L in FZFILE
IQUEST(10) = 2 : VM only : VMIO
(via \Rind{FZHOOK} to FATMEN routine)
IQUEST(10) = 3 : Package I/O, i.e. IOPACK on VM or MVS systems
Corresponds to option Y in \Rind{FZFILE}
Example of using the FMOPEN routine
CALL FMOPEN('//CERN/CHARM2/TEST/DST1/ELEC/HO20/NOM/E02/FILE3',
+ '3',LBANK,'R',IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMOPEN
Option D, when used with option R, will call the routine FMSMCF to automatically copy the data into the robot. Note that this facility is currently CERNVM specific, and requires that
Option Y is valid for stage operations only. Instead of issuing the
stage command, it will be written to the file specified by the
DDNAME parameter. No further action will be taken.
When running on systems that have the SHIFT/CORE software installed, the default access method for ZEBRA FZ files is via the XYOPEN/XYREAD interface to RFIO. FATMEN calls the FZ routine FZHOOK to channel I/O through a special routine that interfaces to RFIO. Alternatively, one may select the C I/O option as described above. In this case, the CFIO routines will be used. On SHIFT/CORE systems, these are compiled in such a way as to interface to RFIO.
To ensure that all staged files are placed in a common directory, one should set the environmental variables DPMUSER and STAGE_USER as shown below.
Example of setting the Shift environmental variables
setenv DPMUSER pubxx setenv STAGE_USER pubxx
CALL FMCLOS (GENAM,DDNAME,LBANK,CHOPT,IRC*)
Example of using the routine FMCLOS
*
CALL FMCLOS('//CERN/CNDIV/CHRIS/TAPE8','FT11F002',LBANK,IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMCLOS'
CALL FMCOPY (GN1,*LBANK1*,*KEYS1*,GN2,*LBANK2*,*KEYS2*,CHOPT,IRC*)
This routine copies the dataset pointed to by the generic name GN1 to the location pointed to by GN2. (Typically GN1 will be the same as GN2). 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. If CHOPT='S', the input file will first be STAGEd and then the STAGE CHANGE command used to write the output tape (assuming that input and output media are tape). In all other cases, the copy will be performed using the VMIO package.
The following options may be specified:
Example of using the FMCOPY routine
* In this example, both datasets are already catalogued
* IN points to the FATMEN source (FATMEN CARDS)
* OUT points to a robot tape. FMCOPY copies IN to OUT
* converting RECFM F to RECFM FB (due to catalogue entries)
CALL FMCOPY('//CERN/CNDIV/JAMIE/IN' ,LBANK1,KEYS1,
+ '//CERN/CNDIV/JAMIE/OUT',LBANK2,KEYS2,'S',IRC)
N.B.The FMCOPY routine allocates FORTRAN logical units
to perform the copy using the routine FMGLUN (see
on Page ).
These are freed
immediately after use by FMFLUN. For FMCOPY to work, first allocate
some units for use by FATMEN using the routine FMSETU (see
on Page ).
On VM systems, FATMEN uses the VMIO logical units corresponding to
the two units declared in FMSTRT (see on Page ) or
FMINIT (see on Page ). For example, if FMINIT
is called with logical units 1 and 2, FMCOPY will use VM01F001
and VM02F001.
When the copy is performed by STAGE CHANGE (stagewrt on Cray, WRTAPE on VAX), no additional logical units are required.
CALL FMCOPQ (GN1,*LBANK1*,*KEYS1*,GN2,*LBANK2*,*KEYS2*,CHOPT,IRC*)
This routine is called by FMCOPY when option K is specified. Rather than perform the copy directly, it is queued for transfer by CHEOPS. This is performed by writing a request file in a special queue directory. FMCOPQ may only be used at sites that are CHEOPS partners.
CALL FMRCOP (GN1,*LBANK1*,*KEYS1*,GN2,*LBANK2*,*KEYS2*,CHOPT,IRC*)
This routine is called by FMCOPY when it determines that a network copy is required.