Makrotyp: S-Typ (E-Form/L-Form/D-Form/C-Form/M-Form) (siehe "Typen von Makroaufrufen")
Der Makro RFFSNAP restauriert Dateien eines Pubsets aus einer Pubset-Kopie, die auf einem zugehörigen Snapset erstellt wurde. Beim Restore werden einzelne Dateien von den Snapsets in den laufenden Pubset kopiert. Der Vorgang ist vergleichbar mit einem HSMS-Restore aus einem Backup-Archiv.
Mit der Snapset-Angabe kann ein bestimmter Sicherungsstand (voreingestellt ist die jüngste Snapset-Sicherung) vorgegeben werden oder es soll jede Datei jeweils von dem Snapset mit dem neuesten Dateistand restauriert werden. Vor dem Restaurieren kann sich der Benutzer mit dem Makro LFFSNAP über Dateien informieren, die auf einen Snapset gesichert wurden.
Alle Dateiattribute einer restaurierten Datei werden unverändert von der Originaldatei übernommen (auch Erstellungs- und Änderungsdatum sowie die Schutzattribute). Nur die Allokierung kann von der der Originaldatei abweichen, auch bei Dateien mit physikalischer Allokierung. Dateien auf SM-Pubsets werden auf dem „passendsten“ Volume-Set restauriert. Dieser kann von dem ursprünglichen Volume-Set abweichen.
Einzelne Dateigenerationen können nur mit der gesamten Dateigenerationsgruppe restauriert werden. Dateien auf Privatplatte werden nicht berücksichtigt. Bei migrierten Dateien und Banddateien werden nur die Katalogeinträge restauriert (ohne die Verfügbarkeit der zugehörigen Bänder zu prüfen). Im Falle einer Umbenennung werden diese Dateien ebenfalls nicht berücksichtigt.
Der nichtprivilegierte Benutzer kann die Datei einer fremden Benutzerkennung nur restaurieren, wenn er Miteigentümer ist.
Für bereits vorhandene Dateien muss das Überschreiben durch das Restaurieren explizit zugelassen werden (Operand REPLACE). Für Dateien, die mit Kennwort gegen unberechtigtes Überschreiben geschützt sind, muss das erforderliche Kennwort in der Kennworttabelle des Aufrufers eingetragen sein (Kommando ADD-PASSWORD).
Dateien können auch unter einem neuen Namen restauriert werden. Die Umbenennung erfolgt entweder durch Angabe einer anderen Benutzerkennung (Operand NUSERID) und/oder eines Dateinamenspräfix (Operand NPREFIX).
Optional können Dateien, die zum Zeitpunkt der Snapset-Erzeugung schreibgeöffnet waren, restauriert werden (Operand RESTOPN). Eine so restaurierte Datei hat einen Zustand wie nach einem Systemabsturz. Für eine ISAM-Datei kann ein Verify notwendig werden. Schreibgeöffnete Dateien mit dem Attribut OPNBACK (siehe Makro „CATAL - Katalogeintrag bearbeiten") werden unabhängig von dieser Option restauriert.
Bei Bedarf kann sich der Aufrufer ein Protokoll der Restore-Verarbeitung nach SYSOUT ausgeben lassen (Operand LIST). Das Protokoll kann entweder alle Dateien oder nur die Dateien, die aus bestimmten Gründen nicht restauriert werden konnten, umfassen.
Die Snapsets sind temporär nicht verfügbar, wenn das Subsystem SHC-OSD zum Zeitpunkt des Pubset-Imports noch nicht aktiv war. Der Makroaufruf wird in diesem Fall mit Returncode 0622 abgebrochen. Sobald SHC-OSD aktiv ist, werden die Snapsets bei Aufruf des Kommandos SHOW-SNAPSET-CONFIGURATION nachträglich aktiviert.
Privilegierte Funktionen
Die Systembetreuung (Privileg TSOS) kann als Mit-Eigentümer alle Dateien unter ihren Original-Benutzerkennungen restaurieren.
Beim Überschreiben einer noch bestehenden Datei kann die Systembetreuung den Dateischutz mit dem Operanden IGNPROT explizit umgehen.
Das Restaurieren von Dateien kann die Systembetreuung über die SECOS-Komponente SAT nur protokollieren, wenn sie die intern benutzten Aufrufe zum Dateilöschen (beim Überschreiben) und zum Erstellen eines Eintrags im Dateikatalog protokollieren lässt.
Format
Operation | Operanden |
|
|
| |
| |
|
PATHNAM
Auswahl der Dateien, die restauriert werden sollen.
=<c-string 1..80: filename 1..54 with-wild(80)>
Pfadname der Datei(en) auf dem Snapset. Mit Musterzeichen kann eine Auswahlangabe für eine Dateimenge erfolgen.
Die Dateien müssen folgende Voraussetzungen erfüllen:
Sie müssen zum Zeitpunkt der Snapset-Erstellung katalogisiert sein.
Der Pubset, an dem sie katalogisiert sind, muss lokal importiert sein.
Sie dürfen nicht auf Privatplatte liegen.
Katalog- und Benutzerkennung müssen eindeutig (also ohne Musterzeichen) angegeben werden. Die Angabe von Aliasnamen (auch teilqualifiziert) ist zulässig. Der Name einer Dateigenerationsgruppe darf angegeben werden, nicht aber der Name einer einzelnen Dateigeneration (einzelne Dateigenerationen können nur innerhalb der Gruppe restauriert werden).
Der privilegierte Benutzer (Privileg TSOS) kann Dateien aller Benutzerkennungen restaurieren.
=<var: char:80>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 80 Byte, in dem der Pfadname bzw. die Musterzeichenfolge für die gewünschte(n) Datei(en) abgelegt ist.
SNAPSET
Der Operand darf nicht zusammen mit dem Operanden SNAPID angegeben werden.
Bezeichnet den Snapset, von dem restauriert werden soll, über das relative Alter.
=<integer -52..-1>
Bezeichnet den Snapset explizit über das relative Alter. Der Wert -1 entspricht dem jüngsten Snapset (entspricht auch *LATEST).
=*LATEST
Bezeichnet den jüngsten Snapset.
=*ALL
Für die Restaurierung werden alle Snapsets des entsprechenden Pubsets als Basis herangezogen. Jede Datei wird jeweils von dem Snapset mit dem neuesten Stand dieser Datei (also mit der letzten Sicherung) restauriert. Eine Datei, die nicht mit dem neuesten Dateistand restauriert werden kann, ist in diesem Fall nicht restaurierbar (d.h. ältere Sicherungsstände werden ignoriert).
SNAPID
Der Operand darf nicht zusammen mit dem Operanden SNAPSET angegeben werden.
Bezeichnet den Snapset, von dem restauriert werden soll, über die Snapset-Id.
=<c-string 1..1: name 1..1 with-low>
Bezeichnet den Snapset explizit über die Snapset-Id. Die maximal 52 Snapsets zu einem Pubset werden unterschieden durch Snapset-Ids aus den 26 Kleinbuchstaben a bis z und den 26 Großbuchstaben A bis Z.
=<var: char:1>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 1 Byte, in dem die Snapset-Id abgelegt ist.
Hinweis
Wenn weder SNAPSET noch SNAPID angegeben sind, wird der jüngste Snapset verwendet.
REPLACE
Gibt an, ob die zu restaurierenden Dateien bereits existierende Dateien überschreiben dürfen.
=*NO
Bereits existierende Dateien werden nicht überschrieben. Das bedeutet, dass Dateien mit Namen bereits existierender Dateien nicht restauriert werden.
=*YES
Bereits existierende Dateien dürfen von zu restaurierenden Dateien überschrieben werden, soweit die Schutzattribute dies zulassen. Für Dateien, die mit Kennwort gegen unberechtigtes Überschreiben geschützt sind, muss das erforderliche Kennwort in der Kennworttabelle des Aufrufers eingetragen sein (siehe Kommando ADD-PASSWORD).
=<var: enum-of_replace_s: 1>
Name des Feldes mit dem Wert für REPLACE.
IGNPROT
Der Operand steht nur dem privilegierten Benutzer (Privileg TSOS) zur Verfügung.
Gibt an, ob Dateien ohne Beachtung eines bestehenden Schreibschutzes überschrieben werden sollen.
=*NO
Der Schreibschutz wird beachtet.
=*YES
Der Schreibschutz wird ignoriert.
=<var: enum-of_ignprot_s: 1>
Name des Feldes mit dem Wert für IGNPROT.
RESTOPN
Gibt an, ob auch Dateien restauriert werden sollen, die beim Sichern auf den Snapset schreibgeöffnet waren und bei denen das Dateiattribut OPNBACK (siehe Makro „CATAL - Katalogeintrag bearbeiten") nicht gesetzt war.
=*NO
Diese Dateien werden nicht restauriert. Restauriert werden also nur Dateien, die beim Sichern auf den Snapset nicht schreibgeöffnet waren, und Dateien, bei denen das Attribut OPNBACK gesetzt war.
=*YES
Auch diese Dateien werden restauriert. Die Konsistenz entspricht der nach einem System-Crash (Schreibzugriffe in korrekter Reihenfolge). Bei ISAM-Dateien kann ein Verify (Kommando REPAIR-DISK-FILE) notwendig werden.
=<var: enum-of_restop_s: 1>
Name des Feldes mit dem Wert für RESTOPN.
NUSERID
Gibt an, dass die Dateien beim Restaurieren umbenannt und unter der angegebenen Benutzerkennung restauriert werden sollen.
Der Operand darf nicht zusammen mit dem Operanden NPREFIX angegeben werden.
=<c-string 1..8: name 1..8>
Benutzerkennung.
=<var: char:8>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 8 Byte, in dem die Benutzerkennung abgelegt ist.
NPREFIX=
Gibt an, dass die Dateien beim Restaurieren umbenannt werden und dabei den angegebenen Dateinamenspräfix erhalten sollen.
Der Operand darf nicht zusammen mit dem Operanden NUSERID angegeben werden.
=<c-string 1..8: name 1..8>
Dateinamenspräfix.
=<var: char:8>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 8 Byte, in dem der Dateinamenspräfix abgelegt ist.
LIST
Gibt an, welche Verarbeitungsergebnisse nach SYSOUT protokolliert werden sollen.
=*NO
Es erfolgt keine Ausgabe nach SYSOUT.
=*SYSOUT
Es werden alle Dateien aufgelistet. Für die nicht restaurierbaren Dateien wird die Ursache jeweils mit einem Meldungsschlüssel angezeigt.
=*ERRORS-TO-SYSOUT
Es werden nur Dateien aufgelistet, die nicht restauriert werden konnten. Die Ursache wird jeweils mit einem Meldungsschlüssel angezeigt.
=<var: enum-of_list_s: 1>
Name des Feldes mit dem Wert für LIST.
EQUATES
Steuerungs-Operand nur für MF=C und MF=D:
Gibt an, ob bei der Expansion des Parameterbereichs auch Equates für die Werte der Felder des Parameterbereichs generiert werden sollen.
= *YES
Bei der Expansion des Parameterbereichs werden auch Equates für die Werte der Felder des Parameterbereichs generiert.
= *NO
Bei der Expansion des Parameterbereichs werden keine Equates für die Werte der Felder des Parameterbereichs generiert.
Returncodes
Der Returncode wird im Standardheader des Parameterbereichs abgelegt. Der Parameterbereich darf dann nicht im Read-only-Bereich liegen, sonst erfolgt Programmterminierung.
Standardheader: ccbbaaaa
Über die Ausführung des Makros RFFSNAP wird im Standardheader folgender Returncode übergeben (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Erläuterung |
X'00' | X'00' | X'0000' | kein Fehler |
X'00' | X'40' | X'0501' | angeforderter Katalog nicht verfügbar |
X'00' | X'40' | X'0505' | Fehler bei der Rechner-Kommunikation |
X'00' | X'40' | X'0512' | angeforderter Katalog nicht gefunden |
X'00' | X'40' | X'051B' | gewünschte Benutzerkennung nicht im Pubset |
X'00' | X'40' | X'051D' | LOGON-Passwort auf angegebenem Pubset anders |
X'00' | X'20' | X'0531' | Unerwarteter Fehler beim Katalogzugriff |
X'00' | X'40' | X'0535' | angegebene Datei nicht zugreifbar |
X'00' | X'82' | X'053C' | im Katalog des Pubsets ist kein Platz |
X'00' | X'82' | X'0541' | nicht genügend Plattenspeicherplatz |
X'00' | X'40' | X'0554' | Format des Dateinamens unzulässig |
X'00' | X'40' | X'057F' | migrierte Datei kann nicht unbenannt werden |
X'00' | X'20' | X'0584' | interner Fehler |
X'00' | X'82' | X'0594' | nicht genügend virtueller Speicher |
X'00' | X'82' | X'05B1' | für die Datei besteht eine Dateisperre |
X'02' | X'00' | X'05B6' | fehlerhafte Zeitkonvertierung GTIME-Makro |
X'00' | X'40' | X'05BF' | Kennwort nicht angegeben |
X'00' | X'82' | X'05C3' | Datei zurzeit gesperrt oder in Gebrauch |
X'00' | X'40' | X'05C6 | Freigabedatum noch nicht erreicht |
X'00' | X'20' | X'05C7' | interner Fehler im DVS |
X'00' | X'01' | X'05CB' | Fehlerhafter erster Dateiname oder fremde Benutzerkennung angegeben |
X'00' | X'01' | X'05EE' | Pfadname nach Komplettierung zu lang |
X'00' | X'40' | X'05FC' | angegebene Benutzerkennung nicht im Home-Pubset |
X'00' | X'40' | X'0610' | mindestens für einen der ausgewählten Dateinamen liefert die Funktionsausführung einen Returncode |
X'00' | X'40' | X'0615' | Datei liegt auf einem nicht verfügbaren Volume Set |
X'00' | X'40' | X'0616' | Volume Set in SM-Pubset nicht zugreifbar |
X'00' | X'40' | X'0620' | keine restaurierbare Datei gefunden |
X'00' | X'40' | X'0621' | Datei bereits katalogisiert, Restaurierung nicht ausgeführt |
X'00' | X'40' | X'0622' | Snapset nicht verfügbar |
X'00' | X'01' | X'0623' | Generation kann nicht restauriert werden |
X'00' | X'01' | X'0624' | Dateiname ungültig |
X'00' | X'40' | X'0681' | DVS Fehler bei Zugriff auf Datei |
X'00' | X'40' | X'0684' | Datei existiert nicht |
X'00' | X'01' | X'06C5' | FGG Name zu lang |
X'00' | X'01' | X'06C6' | Name einer Banddatei kann nicht geändert werden |
X'00' | X'40' | X'06CC' | kein Dateiname entspricht der angegebenen Musterzeichenfolge |
X'00' | X'40' | X'06D5' | Datei geschützt und damit nicht überschreibbar |
X'00' | X'01' | X'06F7' | Ungültiger Operandenwert |
X'00' | X'01' | X'06FD' | Parameterbereich ungültig oder nicht zugreifbar |
Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt
ist, können der Tabelle auf "Standardheader" (Standardheader) entnommen werden.
Das aufrufende Programm wird beendet, wenn bezüglich der Parameterliste folgende Fehler auftreten:
Die Liste ist dem Aufrufer nicht zugewiesen.
Die Liste ist nicht auf Wortgrenze ausgerichtet.
Die Liste ist gegen Schreibzugriff geschützt.
Layout der Operandenliste
Makroauflösung mit MF=D, sowie Standardwerten für EQUATES, PREFIX und MACID:
RFFSNAP MF=D DMARRFPL DSECT , DMARHDR DS 0A DMARFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER DMARIFID DS 0A 0 INTERFACE IDENTIFIER DMARFCTU DS AL2 0 FUNCTION UNIT NUMBER DMARFCT DS AL1 2 FUNCTION NUMBER DMARFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER DMARRET DS 0A 4 GENERAL RETURN CODE DMARSRET DS 0AL2 4 SUB RETURN CODE DMARSR2 DS AL1 4 SUB RETURN CODE 2 DMARSR1 DS AL1 5 SUB RETURN CODE 1 DMARMRET DS 0AL2 6 MAIN RETURN CODE DMARMR2 DS AL1 6 MAIN RETURN CODE 2 DMARMR1 DS AL1 7 MAIN RETURN CODE 1 DMARFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH * DMARPNAM DS CL80 PATHNAME DMARSNAP DS FL1 SNAPSET * SNAPSET - VALUES DMARSNIN EQU 0 SNAPSET=<integer> DMARSNCH EQU 1 SNAPSET=<char> DMARSNLT EQU 2 SNAPSET=*LATEST DMARSNAL EQU 3 SNAPSET=*ALL * DMARREPL DS FL1 REPLACE * REPLACE - VALUES DMARREPY EQU 0 REPLACE = YES DMARREPN EQU 1 REPLACE = NO * DMARIGNP DS FL1 IGNPROT * IGNPROT VALUES DMARIGNO EQU 0 IGNPROT = NO DMARIGYE EQU 1 IGNPROT = YES * DMARLIST DS FL1 LIST * LIST - VALUES DMARLSTN EQU 0 LIST = NO DMARLSYO EQU 1 LIST = SYSOUT DMARLSYE EQU 2 LIST = ERRORS * DMARNUSR DS CL8 NUSERID DMARNPRE DS CL8 NPREFIX DMARSNVL DS H SnapValue DMARSNID DS CL1 Snapid DMAROFLG DS AL1 FLAG BYTE DMARNUSP EQU X'80' S: NUSERID SPECIFIED DMARNPSP EQU X'40' S: NPREFIX SPECIFIED DMARRESB EQU X'3F' RESERVED DMARRESO DS FL1 RESTOPN * RESTOPN VALUES DMARRONO EQU 0 RESTOPN = NO DMARROYE EQU 1 RESTOPN = YES * DMARRES1 DS XL3 ALIGNMENT DMAR# EQU *-DMARHDR
Beispiel für eine Aufruffolge
MVC RFFSMFC(DMAR#),RFFSMFL
RFFSNAP MF=M,PATHNAM=':X:TTT',PARAM=RFFSMFC
RFFSNAP MF=E,PARAM=RFFSMFC
.
.
RFFSMFC RFFSNAP MF=C
RFFSMFL RFFSNAP MF=L,...