Ändern von Katalogeinträgen
Das nachfolgende Beispiel zeigt den strukturellen Aufbau eines Assembler-Hauptprogramms. Die Makroaufrufe zur strukturierten Programmierung mit ASSEMBH (z.B. @IF) werden von ASSEMBH-BC nicht unterstützt (siehe Handbuch „ASSEMBH“ [2]).
Das Beispielprogramm soll erreichen, dass alle reservierten Bänder, deren Archivnummern im Bereich von ABC001 bis ABC099 liegen, uneingeschränkt mehrbenutzbar (USER-ACCESS=ALL-USERS) werden.
Struktureller Aufbau des Assembler-Hauptprogramms
:
@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
:
Zyklische Verlagerung von Bändern
In diesem Beispiel wird eine komplexere Anwendung der MARENADM-Programmschnittstelle aufgezeigt.
Problemstellung
In einem Data Center sollen bestimmte Bänder in gewissen Zeitabständen an einen jeweils anderen Lagerort gebracht werden. Beispielsweise sollen Bänder aus einer Sicherung noch einige Tage nach deren Erstellung am jeweiligen System verbleiben (um etwa Benutzern die Möglichkeit zu bieten, daraus noch Dateien zu rekonstruieren), und erst danach in einen Brandschutzkeller transportiert werden.
Da es in MAREN keine gesonderte Anweisung für einen derartigen zeitabhängigen Bandtransfer gibt, soll dieses Problem mit einer Anwendung der MARENADM-Programmschnittstelle gelöst werden.
Lösungsansätze
Die Informationen über den Verlagerungs-Zyklus sollen in einem Katalogeintragsfeld hinterlegt und dort später abgefragt werden.
Das Hinterlegen kann dabei mittels eines MAREN-Exits (siehe Kapitel „MAREN-Exits“) vorgenommen werden. Sinnvollerweise nimmt man dazu einen Exit, der zu einem Zeitpunkt aufgerufen wird, an dem das Beschreiben des Bandes bereits erfolgt ist, also nicht z.B. den Reserve-Request-Exit, bei dessen Aufruf noch nicht sicher ist, ob das Band auch tatsächlich verwendet werden kann.
In diesem Zusammenhang bietet sich der Modify-Request-Exit an. Wird dieser im Rahmen der DMS-Close-Verarbeitung (LAFUNKNM=MAREN0C1) oder bei einem Spulenwechsel (LAFUNKNM=MAREN0E1) aufgerufen, so ist das Beschreiben des Bandes abgeschlossen. Man kann dann anhand selbstgewählter Kriterien im Katalogeintrag prüfen, ob das soeben erstellten Band bis zu seiner Freigabe nacheinander an verschiedenen Lagerorten aufbewahrt werden soll.
Mögliche Kriterien dafür wären (in Klammern die entsprechenden Katalogeintragsfelder):
Benutzerkennung, unter der das Band erstellt wurde (CRUSERID, falls system-spezifischer Parameter CID-UID gesetzt, sonst auch LAUSERID)
Name des Erstellungs-Jobs (CRJOB)
Dateiname (FILENM41)
Name des ARCHIVE-Directories, mit dem die Sicherung durchgeführt wurde (DIRNAME)
Die Modalitäten der Bandverlagerung können u.U. viel Platz beanspruchen. Daher sollte ein möglichst großes Katalogeintragsfeld zur Aufnahme dieser Informationen ausgewählt werden. Außerdem muss es sich um ein Katalogeintragsfeld handeln, das nicht bei irgendwelchen DVS-Zugriffen auf das Band wieder von MAREN aktualisiert wird, da sonst die zur Verlagerung benötigten Informationen verloren gehen würden.
Das in diesem Zusammenhang am besten geeignete Katalogeintragsfeld ist das eigentlich zur Aufnahme von benutzerspezifischen Daten vorgesehene Katalogeintragsfeld USER-FIELD. Dieses kann auch bei mehreren MAREN- bzw. MARENADM-Anweisungen durch den des Operanden USER-FIELD modifiziert werden, wobei jedoch MAREN-Anwender immer nur die Änderungen an Katalogeinträgen der eigenen Benutzerkennung vornehmen können (dies gilt auch für uneingeschränkt mehrbenutzbare Bänder).
Da der Wertebereich für den Operanden USER-FIELD dem Datentyp „c-string“ entspricht, dürfen darin nur abdruckbare Zeichen vorkommen. Sonst werden bei der Bildschirmmaske zu SHOW-VOL-ATTR VOL=<vsn> Schmierzeichen ausgegeben.
Vorgeschlagene Lösung
Das 54 Bytes lange Katalogeintragsfeld USERFELD im Katalogeintrag wird folgendermaßen untergliedert:
6 Bytes: | C'CYCLE' als Kennzeichen dafür, dass es sich um ein zyklisch zu verlagerndes Band handelt. | |
| 48 Bytes: | 4 je 12 Bytes umfassende Verlagerungsanweisungen. Diese wiederum sind unterteilt in: | |
| 4 Bytes: | Anzahl Tage nach Erstellungsdatum (CRDATE), an dem die nächste Verlagerung stattfinden soll. | |
| 8 Bytes: | Lagerort, an den das Band bei der nächsten Verlagerung gebracht werden soll. | |
Beispiel
USERFELD=CL54'CYCLE 0028CENTRAL 0090TRESOR 0365DVBUNKER'
Das Band soll - jeweils ab Erstellungsdatum gerechnet -
nach 28 Tagen in das Zentralarchiv gebracht werden
nach 90 Tagen in einem Spezialtresor hinterlegt werden
nach 365 Tagen in einem speziell gesicherten, unterirdischen Raum gelagert werden
Ein vierter Lagerort ist nicht mehr vorgesehen. Nach der Freigabe wird das Band wieder an den bei FREE-LOCATION eingetragenen Lagerort zurückgebracht.
Programmtechnische Realisierung
Mithilfe eines die MARENADM-Programmschnittstelle aufrufenden Hauptprogramms werden sequenziell alle MAREN-Katalogeinträge gelesen und darin das Katalogeintragsfeld USERFELD ausgewertet. Finden sich dort die zuvor beschriebenen Verlagerungseinträge, so wird überprüft, ob auf Grund der seit der Dateierstellung verstrichenen Zeit nun eine Verlagerung ansteht. Ist dies der Fall, so wird mit der MARENADM-Anweisung MODIFY-VOLUME-ATTRIBUTES das Katalogeintragsfeld HOME-LOCATION auf den im ersten Verlagerungseintrag befindlichen Lagerort geändert. Dies hat zur Folge, dass beim nächsten Aufräumlauf des MAREN-Administrators (MARENADM-Anweisung RETURN-VOLUMES) für dieses Band eine Verlagerungsaufforderung ausgegeben wird.
Nach jeder erfolgten Modifikation wird, durch ein Verschieben der restlichen Verlagerungseinträge nach vorne, der soeben abgearbeitete Verlagerungseintrag gelöscht (dient der Programmvereinfachung).
Läßt man dieses Programm täglich oder zumindest vor jedem Aufräumlauf des MAREN-Administrators ablaufen, so hat man die Gewähr, dass die gewünschten Bandtransfers auch tatsächlich durchgeführt werden (sofern die zuständigen Operator den Verlagerungsaufforderungen Folge leisten).
Struktureller Aufbau des Assembler-Hauptprogramms
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