Examples

Modifying catalog entries

The following example shows the structure of an Assembler main program. The macro calls for structured programming with ASSEMBH (e.g. @IF) are not supported by ASSEMBH-BC (see the “ASSEMBH” manual [2]).

All reserved tapes with archive numbers in the range ABC001 to ABC099 are to be made shareable without restrictions (USER-ACCESS=ALL-USERS).

Structure of the Assembler main program

         :
         @CYCLE
MODIFY   DS    0H
         :
          @PASS EXTNAME=MAREN1PS,PAR=PAR1PS Aufruf MARENADM
         @CAS2 RETFLAG,COMP=CLI          CHECK RETURN FLAG
         @OF   RETFLAGA                  RETURN FLAG 'A' = OK
         MVC   ANWVSN,ARCHIVNR           SET VSN IN STATEMENT
         @IF   EQ                        SET NEXT FSEQ IN STATEMENT
         CLC   FSEQ,=C'*001'             SUPPRESSED VOLUME?
         @THEN
         MVC   ANWFSEQ,=C'0001'          IF YES - NEXT FSEQ = '0001'
         @ELSE
         PACK  DOWO,FSEQ                 OTHERWISE ADD 1 TO FSEQ
         AP    DOWO,=PL1'1'
         UNPK  ANWFSEQ,DOWO+5(3)
         OI    ANWFSEQ+3,X'F0'
         @BEND
         @OF   RETFLAGE                  RETFLAG 'E' = NO MORE ENTRIES
         :
         @OFRE                           ERROR EXIT
         :
@BEND
         @BEND
         :
DOWO     DS    D                         WORKAREA
STMT     DC    Y(STMTEND-STMT)         AREA FOR MARENADM STATEMENT
         DC    CL2' '
         DC    C'//MOD-VOL-ATTR VOL=*INT(FROM='
ANWVSN   DC    CL6'ABC001'
         DC    C',FROM-FSEQ='
ANWFSEQ  DC    CL4'0001'
         DC    C',TO=ABC099),'
         DC    C'SELECT=*RES,PROT=PAR(USER-ACCESS='
         DC    C'*ALL-USERS)'
STMTEND  EQU   *
         : 
         DS    OF
PAR1PS   DS    OF
         DC    A(STMT)
         DC    A(MARENA)
         DC    A(MARENP)
         : 
         MARENA MF=L,LAYOUT=V8           AREA FOR MAREN CATALOG ENTRY 
         MARENP MF=L                     AREA FOR MAREN PARAMETER RECORD
         :


Cyclical relocation of tapes

This example illustrates a more complex application of the MARENADM program interface.

Objective

Certain tapes in a data center are to be moved to a different location at specific intervals. For example, tapes from a backup are to remain on the system for a few days after they have been created (so that users can draw on them in order to restore files) and then transported to a fireproof cellar. As MAREN is not equipped with a special statement to deal with this delayed tape transfer contingency, this problem must be solved with the aid of the MARENADM program interface.

Possible approaches

The information on the relocation cycle should be stored in a catalog entry field where it can subsequently be queried.

It can be stored by means of a MAREN exit (see chapter “MAREN exits”). It makes sense to use exit that is called at a time when the tape has already been written to, i.e. not a reserve-request exit for example, as it is not certain in this case whether the tape is really available for use again when the exit is called.

In this context, the modify-request exit seems suitable. If this is called in the course of DMS close processing (LAFUNKNM=MAREN0C1) or in the case of tape swapping (LAFUNKNM=MAREN0E1), writing to the tape is completed. It is then possible to consult the catalog entry and check, using your own criteria, whether the tape that has just been created is to be stored at a series of different locations one after the other until it is released.

Possible criteria here (accompanied by the corresponding catalog entry fields in brackets) are:

• user ID under which the tape was created (CRUSERID if system-specific parameter CIDUID is set, otherwise also LAUSERID)

• name of the creation job (CRJOB)

• file name (FILENM41)

• name of the ARCHIVE directory with which the backup was performed (DIRNAME)

The steps involved in tape relocation may take up a great deal of space. For this reason, the catalog entry field selected to accommodate this information should be as large as possible. Furthermore, it must not be a catalog entry field that is updated by MAREN in the course of DMS access, as the information required for relocation would be lost.

The most suitable catalog entry field in this context is the USERFELD catalog entry field, which is really intended for entering user-specific data. This field can be modified by means of the USER-FIELD operand even in several MAREN or MARENADM statements, although MAREN users can only make changes to cataog entries of their own user ID (even in the case of tapes which are shareable without restrictions). Since the value range for the USER-FIELD operand corresponds to the data type “c-string”, it may only contain printable characters. Otherwise, smudge characters will be displayed for SHOW-VOL-ATTR VOL=<vsn> in the screen mask.

Suggested solution

The 54-byte catalog entry field USERFELD in the catalog entry is divided up as follows:

6 bytes:		C'CYCLE' indicating that the tape must be relocated cyclically.
48 bytes:		4 relocation statements of 12 bytes each. These are in turn broken down as follows:
		4 bytes:	Number of days after the creation date (CRDATE) when the next relocation is to be performed.
		8 bytes:	Location to which the tape is to be moved during the next relocation.

Example

USERFELD=CL54'CYCLE 0028CENTRAL 0090TRESOR 0365DVBUNKER'

Starting from the creation date in each case, the tape is to be

• stored in the central archive after 28 days

• stored in a special safe after 90 days

• stored in a specially secure underground room after 365 days

No provision is made for a fourth storage location. On release, the tape is returned to the location specified for FREE-LOCATION.

Program implementation

With the aid of a main program which calls the MARENADM program interface, all MAREN catalog entries are read and the USERFELD catalog entry field is evaluated. If this field contains the previously written relocation entries, a check is carried out as to whether the time that has elapsed since file creation warrants a relocation. If so, the MARENADM statement MODIFY-VOLUME-ATTRIBUTES is used to modify the catalog entry field HOME-LOCATION to the location specified in the first relocation entry. This means that a relocation request for this tape will be issued the next time the MAREN administrator starts a clear-up run (MARENADM statement RETURN-VOLUMES).

Whenever a modification is made, the relocation entry that has just been processed is deleted (in order to keep the program simple) by shifting the remaining relocation entries forward.

If this program is run daily or at least before every clear-up run carried out by the MAREN administrator, it is ensured that the desired tape transfers are actually taking place (provided the relocation requests are dealt with by the appropriate personnel).

Structure of the Assembler main program

PSCYCLE CSECT
          :
         @CYCLE
READCAT  DS    0H    Read volume catalog sequentially
*
         MVC   STMTAREA,BLANKS
         MVC   STMTAREA,SHOWSTMT           Set statement area
         @PASS EXTNAME=MAREN1PS,PAR=STMTAREA  Call MARENADM
         @WHEN NE                          Query return code
         CLI   RETFLAG,RETFLAGA            Everything OK?
         @BREA                             Error occurred or
*                                          end-of-file reached
*
*
CHECKUF  DS    0H    Check USERFELD (CYCLE)
*
*              Do the first 6 bytes of USERFELD contain the
*                    character string C'CYCLE '?
*              No: Position to the next archive entry ( -> POSIT)
*              Position to the first relocation entry
*
*
CHECKUF2 DS    0H    Check USERFELD (relocation entries)
*
*              Do the first 4 bytes contain a numeric value?
*              No: Position to next archive entry (->POSIT)
*              Do the next 8 bytes contain a possible location,
*                    i.e. are we dealing with a character string
*                    of type <alphanumeric>, possibly filled
*                    to the right with blanks?
*              No: Position to the next archive entry (->POSIT)
*              Does USERFELD contain another entry, i.e.
*                    neither end of USERFELD reached nor the
*                    next 12 bytes all blanks?
*              Yes : Position to the next relocation entry;
*                    repeat CHECKUF2
*
*
CHECKDAT DS    0H    Check the relocation date
*
*              Add number from relocation entry to CRDATE
*              Calculated number >= current date?
*              No: Position to next archive entry (->POSIT)
*
*
MODIFY   DS    0H   Modify the archive entry
*
         MVC   MODVSN,ARCHIVNR             VSN from archive entry
         MVC   MODFSEQ,FSEQ                FSEQ from archive entry
         MVC   MODHOMEL,USERFELD+10        Location from USERFELD
         MVC   STMTAREA,BLANKS
         MVC   STMTAREA,MODSTMT            Set statement area
         @PASS EXTNAME=MAREN1PS,PAR=STMTAREA  Call MARENADM
         @WHEN NE                          Query return code
         CLI   RETFLAG,RETFLAGA             Everything OK?
         @BREA                             Error exit
*
*
SHIFT    DS    0H   Update USERFELD
*
         MVC   SAVELOC,USERFELD+6          Save relocation statements
         MVC   USERFELD+6(48),BLANKS       Delete old contents
         MVC   USERFELD+6(36),SAVELOC+12    Undo last relocation statement
*                                          executed
*
*
POSIT    DS    0H   Position to next archive entry
*
         MVC   SHOWFROM,ARCHIVNR           VSN from archive entry
         IF    EQ
         CLC   FSEQ,=CL4'*001'             Migrated volume?
         @THEN
         MVC   SHOWFRFS,=CL4'0001'
         @ELSE
         PACK  DOWO,FSEQ
         AP    DOWO,=PL1'1'                Increment FSEQ by 1
         UNPK  SHOWFRFS,DOWO+5(3)
         OI    SHOWFRFS+3,X'F0'
         @BEND
         @BEND                             Run through loop again
         .
         .
         .
*               Constant area
         .
         .
         .
         MARENA MF=L,LAYOUT=V8             Area for archive entry
         MARENP MF=L                       Area for MAREN parameters
         .
         .
         .
STMTAREA DS    CL80                        Area for MARENADM statement
*
SHOWSTMT DC    Y(SHOWENDE-SHOWSTMT)        Statement for reading
         DC    CL2' '
         DC    C'//SHOW-VOL-ATTR VOL=*INT(FROM='
SHOWFROM DC    CL6'*FIRST'
         DC    C',FROM-FSEQ='
SHOWFRFS DC    CL4'0001'
         DC    C')'
SHOWENDE EQU   *
*
MODSTMT  DC    Y(MODENDE-MODSTMT)          Statement for modifying
         DC    CL2' '
         DC    C'//MOD-VOL-ATTR VOL='
MODVSN   DS    CL6
         DC    C',F-SEQ='
MODFSEQ  DS    CL4
         DC    C',LOCATION=*PAR(HOME-LOC='
MODHOMEL DS    CL8
         DC    C')'
MODENDE  EQU   *
*
DOWO     DS    D
SAVELOC  DS    4*CL12                      Save area for relocation entry
BLANKS   DC    CL80' '
          :
         END