Macro type: type S (E form/L form/D form/C form/M form) (see "Macro format")
The RFFSNAP macro restores files of a pubset from a pubset copy which was created on an associated Snapset. During the restore operation, single files are copied from the Snapsets onto the active pubset. The process is comparable to an HSMS restore from a backup archive.
The Snapset entry enables a specific backup status (the default is the latest Snapset backup) to be specified, or the user can specify that each file should be restored from the Snapset with the latest file status. Before restoration takes place, the user can use the LFFSNAP macro to obtain information on files which were saved to a Snapset.
All file attributes of a restored file are taken over from the original file unchanged (including the creation date, date of modification and the protection attributes). Only the allocation may differ from the original file, even in the case of files with physical allocation. Files on SM pubsets are restored to the “most suitable” volume set. This need not be the original volume set.
Individual file generations can only be restored with the entire file generation group. Files on private disk are ignored. In the case of migrated files and tape files, only the catalog entries are restored (without checking the availability of the associated tapes). When renaming takes place, these files are also ignored.
Nonprivileged users can only restore a file of a foreign user if they are the co-owner.
Overwriting by the restore operation must be explicitly permitted for existing files (REPLACE operand). For files which are protected against unauthorized overwriting by means of a password, the required password must be entered in the caller’s password table (ADD-PASSWORD command).
Files can also be restored under a new name. They are renamed by specifying another user ID (NUSERID operand) and/or a file name prefix (NPREFIX operand).
Optionally, files which were open in write mode at the time the Snapset was created can be restored (RESTOPN operand). A file restored in this way has the same status as after a system crash. ISAM files may need to be verified. Files with the OPNBACK attribute (see the macro "CATAL - Process catalog entry") which are opened in write mode are restored regardless of this option.
If required, the caller can have a log of restore processing output to SYSOUT (LIST operand). This log can cover either all files or only the files which, for particular reasons, could not be restored.
The Snapsets are temporarily not available if the SHC-OSD subsystem was not active when the pubset was imported. In this case the command is aborted with return code DMS0622. As soon as SHC-OSD is active, the Snapsets are subsequently activated when the SHOW-SNAPSET-CONFIGURATION command is called.
Privileged functions
Systems support (TSOS privilege), as co-owner, can restore all files under their original user IDs.
When a file which still exists is overwritten, systems support can explicitly bypass the file protection by means of the IGNPROT operand.
Systems support can only log the restoration of files via the SECOS component SAT if it has the calls used for deleting files (when overwriting) and for creating an entry in the file catalog logged.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
PATHNAM
Selects the files which are to be restored.
=<c-string 1..80: filename 1..54 with-wild(80)>
Path name of the file(s) on the Snapset. Wildcards can be used to specify a set of files.
The files must satisfy the following requirements:
They must be cataloged when the Snapset is created.
The pubset on which they are cataloged must be imported locally.
They may not reside on private disk.
The catalog and user IDs specified must be unique (i.e. contain no wildcards). Aliases (also partially-qualified aliases) may be specified. The name of a file generation group may be specified, but not the name of an individual file generation (individual file generations can only be restored within the group).
Privileged users (TSOS privilege) can restore files of all user IDs.
=<var: char:80>
Only possible with MF=M:
Symbolic address of a memory area of 80 bytes in which the path name or wildcard string for the required file(s) is stored.
SNAPSET
This operand may not be specified together with the SNAPID operand.
Specifies the Snapset from which restoration is to take place by means of the relative age.
=<integer -52..-1>
Specifies the Snapset explicitly by means of the relative age. The value -1 specifies the latest Snapset (also corresponds to *LATEST).
=*LATEST
Specifies the latest Snapset.
=*ALL
All Snapsets of the pubset concerned are used as a basis for restoration. Each file is restored from the Snapset with the latest file status, in other words with the latest backup of the file. A file which cannot be restored with the latest file status is in this case not restorable (i.e. older backup statuses are ignored).
SNAPID
This operand may not be specified together with the SNAPSET operand.
Specifies the Snapset from which restoration is to take place by means of the Snapset ID.
=<c-string 1..1: name 1..1 with-low>
Specifies the Snapset explicitly by means of the Snapset ID. The maximum of 52 Snapsets for a pubsets are distinguished by means of Snapset IDs specified which comprise letters from the 26 lowercase letters a to z and the 26 uppercase letters A to Z.
=<var: char:1>
Only possible with MF=M:
Symbolic address of a memory area of 1 byte in which the Snapset ID is stored.
Note
If neither SNAPSET nor SNAPID is specified, the latest Snapset is used.
REPLACE
Specifies whether the files to be restored may overwrite existing files.
=*NO
Existing files are not overwritten. This means that files with the names of existing files are not restored.
=*YES
Existing files may be overwritten by files which are to be restored provided the protection attributes permit this. For files which are protected against unauthorized overwriting by means of a password, the required password must be entered in the caller’s password table (see the ADD-PASSWORD command).
=<var: enum-of_replace_s: 1>
Name of the field with the value for REPLACE.
IGNPROT
This operand is only available to privileged users (TSOS privilege).
Specifies whether files are to be overwritten without taking into account any write protection which exists.
=*NO
Write protection is taken into account.
=*YES
Write protection is ignored.
=<var: enum-of_ignprot_s: 1>
Name of the field with the value for IGNPROT.
RESTOPN
Specifies whether files which were open in write mode when they were saved to the Snapset and for which the OPNBACK file attribute (see macro "CATAL - Process catalog entry") was not set are also to be restored.
=*NO
These files are not restored. Consequently only files which were not open in write mode when they were saved and files for which the OPNBACK file attribute was set are restored.
=*YES
These files are also restored. The consistency is the same as after a system crash (write accesses in the correct order). ISAM files may need to be verified (REPAIR-DISK-FILE command).
=<var: enum-of_restop_s: 1>
Name of the field with the value for RESTOPN.
NUSERID
Specifies that the files are to be renamed when they are restored and are to be restored under the specified user ID.
This operand may not be specified together with the NPREFIX operand.
=<c-string 1..8: name 1..8>
User ID.
=<var: char:8>
Only possible with MF=M:
Symbolic address of a memory area of 8 bytes in which the user ID is stored.
NPREFIX=
Specifies that the files are to be renamed when they are restored and are to be assigned the specified file name prefix.
This operand may not be specified together with the NUSERID operand.
=<c-string 1..8: name 1..8>
File name prefix.
=<var: char:8>
Only possible with MF=M:
Symbolic address of a memory area of 8 bytes in which the file name prefix is stored.
LIST
Specifies which processing results are to be logged to SYSOUT.
=*NO
No output is directed to SYSOUT.
=*SYSOUT
All files are listed. For files which could not be restored, the reason is displayed by means of a message code.
=*ERRORS-TO-SYSOUT
Only files which cannot be restored are listed. The reason is displayed by means of a message code.
=<var: enum-of_list_s: 1>
Name of the field with the value for LIST.
EQUATES
Control operand; for MF=C and MF=D only:
Specifies whether equates are also to be generated for the values of the fields of the parameter area when the parameter area is expanded.
= *YES
When the parameter area is expanded, equates are also generated for the values of the fields of the parameter area.
= *NO
When the parameter area is expanded, no equates are generated for the values of the fields of the parameter area.
Return codes
The return code is placed in the standard header of the parameter area. The parameter area may then not be located in the read-only area, otherwise the program terminates.
Standard header: ccbbaaaa
The following code relating to execution of the RFFSNAP macro is returned in the standard header(cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | No error |
X'00' | X'40' | X'0501' | Requested catalog not available |
X'00' | X'40' | X'0505' | Error in host communication |
X'00' | X'40' | X'0512' | Requested catalog not found |
X'00' | X'40' | X'051B' | Requested user ID not on the pubset |
X'00' | X'40' | X'051D' | LOGON password different on specified pubset |
X'00' | X'20' | X'0531' | Unexpected error during catalog access |
X'00' | X'40' | X'0535' | Specified file not accessible |
X'00' | X'82' | X'053C' | No space in the pubset’s catalog |
X'00' | X'82' | X'0541' | Not enough disk storage space available |
X'00' | X'40' | X'0554' | Format of file name invalid |
X'00' | X'40' | X'057F' | Migrated file cannot be renamed |
X'00' | X'20' | X'0584' | Internal error |
X'00' | X'82' | X'0594' | Not enough virtual memory |
X'00' | X'82' | X'05B1' | File lock exists for file |
X'02' | X'00' | X'05B6' | Incorrect time conversion in GTIME macro |
X'00' | X'40' | X'05BF' | Password not specified |
X'00' | X'82' | X'05C3' | File currently locked or in use |
X'00' | X'40' | X'05C6 | Expiration date not yet reached |
X'00' | X'20' | X'05C7' | Internal error in DMS |
X'00' | X'01' | X'05CB' | Incorrect first file name or foreign ID specified |
X'00' | X'01' | X'05EE' | Path name too long after completion |
X'00' | X'40' | X'05FC' | Specified user ID not on home pubset |
X'00' | X'40' | X'0610' | Execution of the function returned a return code for at least one of the selected file names |
X'00' | X'40' | X'0615' | The file does not reside on the available volume set |
X'00' | X'40' | X'0616' | Volume set cannot be accessed on SM pubset |
X'00' | X'40' | X'0620' | No restorable file found |
X'00' | X'40' | X'0621' | File already cataloged, restoration not performed |
X'00' | X'40' | X'0622' | Snapset not available |
X'00' | X'01' | X'0623' | Generation cannot be restored |
X'00' | X'01' | X'0624' | File name invalid |
X'00' | X'40' | X'0681' | DMS error when accessing file |
X'00' | X'40' | X'0684' | File does not exist |
X'00' | X'01' | X'06C5' | FGG name too long |
X'00' | X'01' | X'06C6' | Name of a tape file cannot be changed |
X'00' | X'40' | X'06CC' | No file name matches the wildcard string specified |
X'00' | X'40' | X'06D5' | File protected and consequently cannot be overwritten |
X'00' | X'01' | X'06F7' | Invalid operand value |
X'00' | X'01' | X'06FD' | Parameter area invalid or not accessible |
Further return codes, whose meanings are defined by conventions valid for all macros, can be found in the table on "Standard header" (standard header).
The calling program is terminated if one of the following errors occurs with respect to the parameter list:
the list is not assigned to the caller
the list is not aligned on a word boundary
the list is write-protected.
Layout of the operand list
Macro expansion with MF=D, and with default values for EQUATES, PREFIX and 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
Sample calling sequence
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,...