FATMEN -- H2Fatmenuserguide-modify-contents-routines

Routines to modify the contents of the FATMEN banks

Set contents of FATMEN bank

             +----------------------------------------------+
             |CALL  FMFILL (GENAM,*LBANK*,*KEYS*,CHOPT,IRC*) |
             +----------------------------------------------+

GENAM

Character variable of maximum length 255 to specify the generic name.

LBANK

Integer variable to return the address of the bank corresponding to the input generic name GENAM. If LBANK is non-zero, the bank at this address will be used.

KEYS

Integer array of length 10 to return the keys vector associated with the specified generic name. If the keys vector is non-zero, it will be used by FMGETK to return the bank corresponding to a particular copy of a dataset.

CHOPT

Character variable to specify the options desired.

A: set all fields
C: clear comment field
F: zero file attributes, such as start/end record and block
K: reset keys to match generic name, default copy level, media type, location
L: clear logical attributes, such as FATMEN file format
M: clear media attributes, such as VSN, VID, file sequence number for tape files, set host type and operating system for disk files.
N: clear dataset name on disk/tape of this file
O: set owner, node and job of creator etc.
P: clear physical attributes, such as record format etc.
S: clear security details of this file (protection)
T: set date and time of creation, last access etc.
U: clear user words.
Z: display ZEBRA bank with FMSHOW.

IRC

Integer variable in which the return code is returned.

This routine sets the contents of the FATMEN bank corresponding to the input generic names GENAM, or at the address LBANK if non-zero. This routine either sets fields that can be automatically obtained, such as the date and time or current node, or sets them to zero or blanks as appropriate (user comment, vsn, vid etc.)

                Example of using the  FMFILL routine

*     Update owner information and time fields.
*     Z option causes the resultant bank to be displayed
*     via the routine  FMSHOW.
*
      CALL FMFILL('//CERN/L3/PROD/DATA/SDSUEE/CC00DCVY',
     +LBANK,KEYS,'OTZ',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMFILL'

Insert character data into FATMEN bank

              +--------------------------------------------+
              | CALL  FMPUTC (LBANK,STRING,ISTART,NCH,IRC*) |
              +--------------------------------------------+

LBANK: Integer variable containing the address of the bank to be updated, or -1, when called from the novice interface.
STRING: Character variable containing the data to be inserted into the bank.
ISTART: Offset at which this data should be written, e.g. MUSCFA
NCH: Number of characters to write.
IRC: Integer variable in which the return code is returned.

This routine updates the FATMEN bank at address LBANK with the character data in the string STRING. Attempts to write outside of bank boundaries will generate an error and a non-zero value of the return code IRC. When called from the novice interface, LBANK should be set to -1.

                Example of using the  FMPUTC routine

      CALL FMPUTC(LBANK,'I28901',MVSNFA,6,IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMPUTC'

Read character data from FATMEN bank

              +--------------------------------------------+
              |CALL  FMGETC (LBANK,STRING*,ISTART,NCH,IRC*) |
              +--------------------------------------------+

LBANK: Integer variable containing the address of the bank from which information is to be retrieved, or -1, when called from the novice interface.
STRING: Character variable in which the character data is returned.
ISTART: Offset at which this data should be read, e.g. MUSCFA
NCH: Number of characters to read.
IRC: Integer variable in which the return code is returned.

This routine returns character information from the FATMEN bank at address LBANK in the string STRING. Attempts to read outside of bank boundaries will generate an error and a non-zero value of the return code IRC.

When called from the novice interface, LBANK should be set to -1.

                Example of using the  FMGETC routine

      CALL FMGETC(LBANK,VSN,MVSNFA,6,IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMGETC'

Insert integer vector into FATMEN bank

             +----------------------------------------------+
             | CALL  FMPUTV (LBANK,IVECT,ISTART,NWORDS,IRC*) |
             +----------------------------------------------+

LBANK: Integer variable containing the address of the bank to be updated, or -1, when called from the novice interface.
IVECT: Integer vector containing the data to be inserted into the bank.
ISTART: Offset at which this data should be written, e.g. MUSWFA
NCH: Number of words to write.
IRC: Integer variable in which the return code is returned.

This routine updates the FATMEN bank at address LBANK with the data in the vector IVECT. Attempts to write outside of bank boundaries will generate an error and a non-zero value of the return code IRC.

When called from the novice interface, LBANK should be set to -1.

                Example of using the  FMPUTV routine

*     Insert user words vector into FATMEN bank
      CALL FMPUTV(LBANK,IWORDS,MUSWFA,10,IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMPUTV'

Read integer vector from FATMEN bank

             +----------------------------------------------+
             |CALL  FMGETV (LBANK,IVECT*,ISTART,NWORDS,IRC*) |
             +----------------------------------------------+

LBANK: Integer variable containing the address of the bank from which information is to be retrieved, or -1, when called from the novice interface.
IVECT: Integer vector in which the data is returned.
ISTART: Offset at which this data should be read, e.g. MUSWFA
NCH: Number of characters to read.
IRC: Integer variable in which the return code is returned.

This routine returns the information from the FATMEN bank at address LBANK in the vector IVECT. Attempts to read outside of bank boundaries will generate an error and a non-zero value of the return code IRC.

When called from the novice interface, LBANK should be set to -1.

                Example of using the  FMGETV routine

      CALL FMGETV(LBANK,IWORDS,MUSWFA,10,IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMGETV'

Insert integer value into FATMEN bank

                  +------------------------------------+
                  | CALL  FMPUTI (LBANK,IVAL,IOFF,IRC*) |
                  +------------------------------------+

LBANK: Integer variable containing the address of the bank to be updated, or -1, when called from the novice interface.
IVAL: Integer variable containing the data to be inserted into the bank.
IOFF: Offset at which this data should be written, e.g. MUSWFA
IRC: Integer variable in which the return code is returned.

This routine updates the FATMEN bank at address LBANK with the data in the variable IVAL. Attempts to write outside of bank boundaries will generate an error and a non-zero value of the return code IRC.

                Example of using the  FMPUTI routine

*     Insert use count into FATMEN bank
      CALL FMPUTI(LBANK,NUSE,MUSCFA,IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMPUTI'

Read integer value from FATMEN bank

                  +------------------------------------+
                  |CALL  FMGETI (LBANK,IVAL*,IOFF,IRC*) |
                  +------------------------------------+

LBANK: Integer variable containing the address of the bank from which information is to be retrieved, or -1, when called from the novice interface.
IVAL: Integer variable in which the data is returned.
ISTART: Offset at which this data should be read, e.g. MUSWFA
IRC: Integer variable in which the return code is returned.

This routine returns the information from the FATMEN bank at address LBANK in the variable IVAL. Attempts to read outside of bank boundaries will generate an error and a non-zero value of the return code IRC.

When called from the novice interface, LBANK should be set to -1.

                Example of using the  FMGETI routine

      CALL FMGETI(LBANK,NUSE,MUSCFA,IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from FMGETI'