FATMEN -- H2Fatmenuserguide-novice-interface

Novice interface routines

These routines require no knowledge of Zebra to use FATMEN. They may be used in conjunction with the other FATMEN routines, provided that the same Zebra store is used.

Initialise FATMEN system

                 +--------------------------------------+
                 | CALL  FMSTRT (LUNRZ,LUNFZ,CHFAT,IRC*) |
                 +--------------------------------------+

LUNRZ: Integer variable specifying the FORTRAN logical unit for the FATMEN RZ file.
LUNFZ: Integer variable specifying the FORTRAN logical unit to be used to send updates to the FATMEN server.
CHFAT: Character variable to specify the database and group name in the form //database/group, e.g. //CERN/DELPHI.
IRC: Integer variable in which the return code is returned.

This routine initialises ZEBRA, unless it has already been initialised, and then the FATMEN system. The store /FAT/ in sequence FAT is used for this purpose. 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 CHFAT is a character string indicating the name of the database that is to be accessed. This field must be of the form '//CERN/experiment' for CERN experiments, '//DESY/experiment' for DESY experiments and so on.

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  FMSTRT routine

*     Initialise FATMEN for group CPLEAR
      CALL FMSTRT(1,2,'//CERN/CPLEAR',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMSTRT'

Access a dataset

                  +------------------------------------+
                  | CALL  FMFILE (LUN,GENAM,CHOPT,IRC*) |
                  +------------------------------------+

LUN: Integer variable specifying the FORTRAN logical unit to be used to access the dataset.
GENAM: Character variable specifying the generic name of the file to be accessed.
CHOPT: Character variable to specify the required options, as for the routine FMOPEN (see on Page [more info].)
IRC: Integer variable in which the return code is returned.

This routine accesses the dataset referenced by GENAM on FORTRAN unit LUN.

                Example of using the  FMFILE routine

      CALL FMFILE(11,
     +'//CERN/CPLEAR/REAMS/M2T3/RAWD/NONE/NONE/R08288',' ',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMFILE'

Deaccess a dataset

                  +------------------------------------+
                  | CALL  FMFEND (LUN,GENAM,CHOPT,IRC*) |
                  +------------------------------------+

LUN: Integer variable specifying the FORTRAN logical unit used to access the dataset.
GENAM: Character variable specifying the generic name of the file accessed.
CHOPT: Character variable to specify the required options, as for the routine FMCLOS (see on Page [more info].)
IRC: Integer variable in which the return code is returned.

This routine deaccesses the dataset referenced by GENAM on FORTRAN unit LUN.

                Example of using the  FMFEND routine

      CALL FMFEND(11,
     +'//CERN/CPLEAR/REAMS/M2T3/RAWD/NONE/NONE/R08288',' ',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMFEND'

Add a tape file

+------------------------------------------------------------------------------------------------------------+
|CALL  FMADDT (GENAM,VSN,VID,FSEQ,DSN,FFORM,CPLEV,HOST,RECFM,LRECL,LBLOCK, FSIZE,MEDIA,COMM,IVECT,CHOPT,IRC*) |
+------------------------------------------------------------------------------------------------------------+

GENAM

Character variable specifying the generic name of the file to be added.

VSN

Character variable specifying the volume serial number or magnetically recorded label of the tape on which the file resides.

VID

Character variable specifying the visual identifier or the 'sticky' or external label of the tape on which the file resides. This field may also be given in the 'extended VID' form, e.g. IN2P3.EP1234 if a VID prefix is required.

FSEQ

Integer variable specifying the file sequence number on the specified tape volume of the file to be added.

DSN

Character variable specifying the dataset name of the file to be added.

FFORM

Character variable specifying the logical format of the file to be added, such as FX, EP, RZ etc.

CPLEV

Integer variable specifying the copy level (or data representation type) of the file to be added.

HOST

Character variable specifying the name of the host through which the dataset is to be accessed. For tape volumes this is typically the same as the node on which the dataset was created as it is not used to check access to the data.

RECFM

Character variable specifying the record format of the file to be

LRECL

Integer variable specifying the record length of the file to be added, in units of 32 bit words.

LBLOCK

Integer variable specifying the block size of the file to be added, in units of 32 bit words.

FSIZE

Integer variable specifying the size of the file in Megabytes.

MEDIA

Integer variable specifying the media type, where 2=3480, 3=3420, 4=8200 etc. For tapes which are known to the TMS, this information is ignored.

COMM

Character variable containing the user comment for this entry.

IVECT

Integer array of length 10 containing the user words for this entry.

CHOPT

Character variable specifying the required options (none at present).

: the entry is added using FMPUT (see Page [more info]).
M: the entry is added using FMMOD (see Page [more info]).
N: the entry is not added to the catalogue but may be further manipulated with the FMPEEK/ FMPOKE routines described below.

IRC

Integer variable in which the return code is returned.

This routine adds an entry to the FATMEN catalogue.

                Example of using the  FMADDT routine

      CALL FMADDT('//CERN/CNDIV/JAMIE/TEST','I29021','I29021',1
     +'FATMEN.CARDS','AS',0,'CERNVM','FB',20,800,1,2,
     +'Backup of source to FATMEN',IVECT,' ',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMADDT'

Add a disk file

+-----------------------------------------------------------------------------------------+
|CALL  FMADDD (GENAM,DSN,FFORM,CPLEV,HOST,RECFM,LRECL,LBLOCK, FSIZE,COMM,IVECT,CHOPT,IRC*) |
+-----------------------------------------------------------------------------------------+

GENAM

Character variable specifying the generic name of the file to be added.

DSN

Character variable specifying the dataset name of the file to be added.

FFORM

Character variable specifying the logical format of the file to be added, such as FX, EP, RZ etc.

CPLEV

Integer variable specifying the copy level (or data representation type) of the file to be added.

HOST

Character variable specifying the name of the host on which the dataset resides.

RECFM

Character variable specifying the record format of the file to be

LRECL

Integer variable specifying the record length of the file to be added, in units of 32 bit words.

LBLOCK

Integer variable specifying the block size of the file to be added, in units of 32 bit words.

FSIZE

Integer variable specifying the size of the file in Megabytes.

COMM

Character variable containing the user comment for this entry.

IVECT

Integer array of length 10 containing the user words for this entry.

CHOPT

Character variable specifying the required options.

: the entry is added using FMPUT (see Page [more info]).
M: the entry is added using FMMOD (see Page [more info]).
N: the entry is not added to the catalogue but may be further manipulated with the FMPEEK/ FMPOKE routines described below.

IRC

Integer variable in which the return code is returned.

This routine adds an entry to the FATMEN catalogue.

                Example of using the  FMADDD routine

      CALL FMADDD('//CERN/CNDIV/JAMIE/VAX2',
     +'DISK$CERN:[JAMIE.ZFTP]FXFILE.DAT',
     +'FX',0,'VXCERN','F',8100,8100,10,
     +'Test Zebra exchange format file for ZFTP',IVECT,' ',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMADDD'

Return information on FATMEN entry

                 +--------------------------------------+
                 | CALL  FMPEEK (GENAM,IVECT,CHOPT,IRC*) |
                 +--------------------------------------+

GENAM

Character variable specifying the generic name of the file on which information is to be returned.

IVECT

Integer array of length NWDSFA in which the FATMEN information is returned.

CHOPT

Character variable specifying the required options.

: the last bank created by a call to FMADDT and FMADDD is returned.
G: the information is obtained from the FATMEN catalogue using the default FATMEN selection. (Note that there may be no entry with the current selection criteria - see the description of FMGET on page [more info] for details).
A: the first entry found in the catalogue is returned.
N: the next entry found in the catalogue is returned, which may be the first if no previous call with CHOPT = 'A' has been issued.
D: Drop bank after unpacking

IRC

Integer variable in which the return code is returned.

This routine returns in the vector IVECT the contents of the FATMEN bank associated with the specified generic name.

                Example of using the  FMPEEK routine

CALL FMPEEK('//CERN/CNDIV/JAMIE/VAX2',IVECT,'N',IRC)
IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMPEEK'

Add entry to catalogue

                 +--------------------------------------+
                 | CALL  FMPOKE (GENAM,IVECT,CHOPT,IRC*) |
                 +--------------------------------------+

GENAM

Character variable specifying the generic name of the file.

IVECT

Integer array of length NWDSFA in which the FATMEN information is contained.

CHOPT

Character variable specifying the required options.

: the information is simply copied into this bank.
N: the vector IVECT is ignored. This is useful if the bank has been modified using the FMPUTC/I/V routines.
M: the information is added to the catalogue using FMMOD. (see on Page [more info]).
R: the entry is replaced using FMMOD (see on Page [more info]).
P: the information is added to the catalogue using FMPUT. (see Page [more info]).

IRC

Integer variable in which the return code is returned.

This routine copies the vector IVECT into the FATMEN bank reserved for manipulation with FMADDD/ FMADDT, FMPEEK/ FMPOKE.

                Example of using the  FMPOKE routine

      CALL FMPOKE('//CERN/CNDIV/JAMIE/VAX2',IVECT,'M',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMPOKE'