Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

RESTORE-FILE-FROM-SNAPSET

&pagelevel(3)&pagelevel

Restore files on the basis of a Snapset

Component:

BS2000

Functional area:

File processing                                                                                  

Domain:

FILE
SNAPSET

Privileges:

STD-PROCESSING
TSOS

Function

The RESTORE-FILE-FROM-SNAPSET command 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 operand 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 issue the LIST-FILE-FROM-SNAPSET command 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 or on Net-Storage 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. In this case, they can also restore a file of their own under the foreign user ID.

Overwriting by the restore 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 into the caller’s password table (see ADD-PASSWORD).

Files can also be restored under a new name (NEW-FILE-NAME operand). They are renamed by specifying either another user ID or a file name prefix.

Optionally, files which were open in write mode at the time the Snapset was created can be restored (RESTORE-OPEN-FILES operand). A file restored in this way has the same status as after a system crash. It may be necessary to call the REPAIR-DISK-FILE command for ISAM files. Files with the ONLINE-SAVE attribute 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 or SYSLST (OUTPUT operand). This log can cover either all files or only the files which, for particular reasons, could not be restored (REPORTING operand).

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 DMS0622. As soon as SHC-OSD is active, the Snapsets are subsequently activated when the SHOW-SNAPSET-CONFIGURATION command is called.

File restoration is not an explicit SAT event. The SECOS component SAT can only log the DELETE-FILE (for overwriting) and CREATE-FILE calls which are used internally.

Privileged functions

Systems support (TSOS privilege), as co-owner, can restore a file under its original user ID or under a foreign user ID.

When a file which still exists is overwritten, systems support can explicitly bypass the file protection by means of the IGNORE-PROTECTION operand.

Format

RESTORE-FILE-FROM-SNAPSET

FILE-NAME = <filename 1..54 without-gen with-wild(80)>

,SNAPSET = *LATEST / *ALL / <name 1..1 with-low> /<integer -52..-1> / *INTERVAL(...)


*INTERVAL(...)



|


OLDEST = -52 / <integer -52..-1>



|


,NEWEST = -1 / <integer -52..-1>

,REPLACE = *NO / *YES(...)


*YES(...)



|


IGNORE-PROTECTION = *NO / *YES

,NEW-FILE-NAME = *SAME / *BY-USER-ID(...) / *BY-PREFIX(...)


*BY-USER-ID(...)



|


NEW-USER-ID = *SAME / <name 1..8>


*BY-PREFIX(...)



|


NEW-PREFIX = *NONE / <filename 1..8 without-cat-gen-user-vers>

,RESTORE-OPEN-FILES = *NO / *YES

,REPORTING = *ERROR / *FULL

,OUTPUT = *NONE / list-poss(2): *SYSOUT / *SYSLST

Operands

FILE-NAME = <filename 1..54 without-gen with-wild(80)>
Selects the files which are to be restored. The files must satisfy the following requirements:

  • They must have been cataloged when the Snapset is created.

  • The pubset on which they are cataloged must be imported locally.

  • They may not reside on private disk or on a Net-Storage volume.

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 (individual file generations can only be restored within the group).

SNAPSET = *LATEST / *ALL / <name 1..1 with-low> / <integer -52..-1> / *INTERVAL(...) 
Specifies the Snapset from which the files are to be restored. Information about all existing Snapsets for a pubset can be obtained using the SHOW-SNAPSET-CONFIGURATION command.

SNAPSET = *LATEST
The files are to be restored from the latest Snapset (i.e. from the most up-to-date pubset backup).

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.

SNAPSET = <name 1..1 with-low>
Specifies a particular Snapset explicitly by means of the Snapset ID. The maximum of 52 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.

SNAPSET = <integer -52..-1>
Specifies a particular Snapset explicitly by means of the relative age. The value -1 specifies the latest Snapset.

SNAPSET = *INTERVAL(...)
Restoration takes place as with SNAPSET=*ALL. However, only Snapsets which lie in the specified age range are used as a basis:

OLDEST = -52 / <integer -52..-1>
Specifies the oldest Snapset; the range begins with this Snapset.

NEWEST = -1 / <integer -52..-1>
Specifies the newest Snapset; the range ends with this Snapset.

REPLACE = *NO / *YES(...)
Specifies whether the files to be restored may overwrite existing files.

REPLACE = *NO
Existing files are not overwritten. This means that files with the names of existing files are not restored.

REPLACE = *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 into the caller’s password table (see the ADD-PASSWORD command).

IGNORE-PROTECTION = *NO / *YES
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.

NEW-FILE-NAME = *SAME / *BY-USER-ID(...) / *BY-PREFIX(...)
Specifies whether the files are to be renamed when they are restored. When they are renamed, either a different ID or a file name prefix can be specified.

NEW-FILE-NAME = *SAME
Each file is restored under the name of the original file.

NEW-FILE-NAME = *BY-USER-ID(...)
Each file is to be restored under the user ID specified. 

Only the co-owner (or TSOS) is able to restore the file under a user ID other than the original one.

NEW-USER-ID = *SAME / <name 1..8>
New user ID. The default is *SAME, i.e. the user ID of the original file is retained.

NEW-FILE-NAME = *BY-PREFIX(...)
Each file is to be restored under a new name. The name consists of the specified prefix and the original name, separated by a period.

NEW-PREFIX = *NONE / <filename 1..8 without-cat-gen-user-vers>
File name prefix (up to 8 characters). The default is *NONE, i.e. the original file name is retained.

RESTORE-OPEN-FILES = *NO / *YES
Specifies whether files which were open in write mode when they were saved to the Snapset and for which the ONLINE-SAVE file attribute was not set are also to be saved.

RESTORE-OPEN-FILES = *NO
These files are not restored.

RESTORE-OPEN-FILES = *YES
These files are 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).

REPORTING = *ERROR / *FULL
Determines the scope of the log if a processing log was requested in the OUTPUT operand.

REPORTING = *ERROR
Only files which could not be restored are listed. The reason is displayed by means of a message code.

REPORTING = *FULL
All files are listed. For files which could not be restored, the reason is displayed by means of a message code.

OUTPUT = *NONE / list-poss(2): *SYSOUT / *SYSLST
Specifies whether a processing log is to be output to SYSOUT and/or SYSLST. The default is *NONE, i.e. no log is output. 

Return codes

(SC2)

SC1

Maincode

Meaning


0

CMD0001

Command executed without error


1

CMD0202

Syntactical or semantic error in the command


32

DMS0584

A status occurred which prevents processing from continuing


32

DMS05C7

Unexpected internal error in DMS


64

CMD0102

Command aborted after interruption with K2


64

CMD0216

Required authorization not available


64

DMS0501

Requested catalog not available


64

DMS0512

Requested catalog not found


64

DMS051B

Requested user ID not in pubset


64

DMS051C

User not authorized to access pubset


64

DMS0535

Specified file not shareable


64

DMS057F

Migrated file cannot be renamed


64

DMS0585

Error detected when processing catalog or multiprocessor system


64

DMS05FC

Specified user ID not in home pubset


64

DMS0610

Action with wildcards: Error executing a function for one of the selected file names


64

DMS0616

Volume set in SM pubset cannot be accessed


64

DMS0620

No restorable file found


64

DMS0621

File already cataloged, restoration not performed


64

DMS0622

Snapset not available


64

DMS0681

DMS error when executing job


64

DMS0684

File does not exist


64

DMS06CC

No file name matches the specified wildcards


130

DMS053C

No space in the pubset’s catalog


130

DMS0582

The file is currently locked or in use and cannot be processed


130

DMS0585

Error detected when processing catalog or multiprocessor system


130

DMS0588

The disk storage assignment could not be executed


130

DMS0594

Not enough virtual memory available


64

DMS0616

Volume set not accessible in SM pubset


64

DMS0620

No restorable file found


64

DMS0621

File already cataloged, restoration not performed


64

DMS0622

Snapset not available

Examples

The two examples below show Snapset use from the viewpoint of a nonprivileged user.

Example 1: Restoring deleted files

On 21 December 2011 the nonprivileged user is working in interactive mode under the user ID ARCHIVE8 and with the default pubset 2OS6.

/show-file-attr d* ————————————————————————————————————  (1)

%         3 :2OS6:$ARCHIVE8.DO.ERASE.ARCHIVE.8.0A.ST5385 
%         3 :2OS6:$ARCHIVE8.DO.ERASE.ARCHIVE.8.0A.ST5406

/show-snapset-conf ————————————————————————————————————  (2)

% PUBSET = 2OS6 , SAVE-POOL-NAME = *DEFAULT-POOL, REMOTE-COPY = *NO
% SNAP-ID CREATION-DATE/TIME  SESSION-ID  SNAP-ID CREATION-DATE/TIME  SESSION-ID
%  -1  g  2011-12-20 18:00:45  87C968B6    -2  f  2011-12-20 12:00:43  86C968B6
%  -3  e  2011-12-19 18:00:50  85C968B6    -4  d  2011-12-19 12:00:46  84C968B6
%  -5  c  2011-12-18 18:00:47  83C968B6    -6  b  2011-12-18 12:00:47  82C968B6
%  -7  a  2011-12-15 18:00:49  81C968B6    -8  z  2011-12-15 12:01:18  A9C968B6
%  -9  y  2011-12-14 18:01:01  A8C968B6   -10  x  2011-12-14 12:01:03  A7C968B6
% -11  w  2011-12-13 18:00:44  A6C968B6   -12  v  2011-12-13 12:00:46  A5C968B6
% -13  u  2011-12-12 18:00:46  A4C968B6   -14  t  2011-12-12 12:00:48  A3C968B6
% -15  s  2011-12-11 18:00:46  A2C968B6

/rest-file-from-snapset f-name=du.,snapset=*all,
                          report=*full,output=*sysout —————————————————  (3) 

%:2OS6:$ARCHIVE8.DU.BIND.FAR                                  RESTORED FROM f
%:2OS6:$ARCHIVE8.DU.CG.DIRCONV                                RESTORED FROM f
%:2OS6:$ARCHIVE8.DU.COMP.ALL                                  RESTORED FROM f
%:2OS6:$ARCHIVE8.DU.COMP.REST                                 RESTORED FROM f
%:2OS6:$ARCHIVE8.DU.COMP.ST                                   RESTORED FROM f
%:2OS6:$ARCHIVE8.DU.COMP.ST.ASS                               RESTORED FROM f
%:2OS6:$ARCHIVE8.DU.SYSRME.E                                  RESTORED FROM f
%:2OS6:$ARCHIVE8.DU.TF.LIB                                    RESTORED FROM f
                                                ————————————————————————  (4)

/show-file-attr du.tf.lib,inf=*par(history=*yes)   ——————————————————  (5)

%0000000030 :2OS6:$ARCHIVE8.DU.TF.LIB
%  ------------------------------- HISTORY      -----------------------------
%  CRE-DATE   = 2012-12-20  ACC-DATE   = 2012-12-20  CHANG-DATE = 2012-12-20
%  CRE-TIME   =   09:55:04  ACC-TIME   =   09:55:04  CHANG-TIME =   09:55:04
%  ACC-COUNT  = 211         S-ALLO-NUM = 0
%:2OS6: PUBLIC:      1 FILE  RES=        30 FRE=        5 REL=        3 PAGES

(1)

The user has all files listed whose names begin with “D”, and in doing so notices that no file with the prefix “DU” exists. As the files were still there a week ago, somebody must have accidentally deleted them!

(2)

The SHOW-SNAPSET-CONFIGURATION command provides information on all the available Snapset backups of the pubset 2OS6: There are 15 Snapsets with backups from 12:00 and 18:00 hours on the days concerned. The oldest backup was made at 18:00 on 11 December.

(3)

As the user does not know exactly when the missing files were deleted, he/she specifies SNAPSET=*ALL in order to restore each of the files from the latest Snapset.

(4)

As all the files were restored from Snapset f, they must have been deleted between 18:00 on 19 December and 12:00 on 20 December. The restored files contain the original time stamps, just as if they had not been deleted.

(5)

The user checks the time stamps in the catalog entry of the last file.

Example 2: Resetting the processing state of a file

Under the user ID ARCHIV8B (with the same standard pubset), the user now wants to reset the processing state of the M.SS.ARCHIVE.V08.0B03.SRCLIB file because (faulty) changes were made in the past few days. The user checks the backed-up file statuses as follows:

/list-file-from-snapset f-name=sm.ss.archive.v08.0b03.srclib,
     inf=*all,snapset=*all ————————————————————————————————————————————  (1) 

%----------------------------SNAPSET g--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-20 10:42:12  STATE=CLOSED
%----------------------------SNAPSET f--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-20 10:42:12  STATE=CLOSED
%----------------------------SNAPSET e--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-19 14:16:25  STATE=CLOSED
%----------------------------SNAPSET d--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-14 13:36:19  STATE=CLOSED
%----------------------------SNAPSET c--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-14 13:36:19  STATE=CLOSED
%----------------------------SNAPSET b--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-14 13:36:19  STATE=CLOSED
%----------------------------SNAPSET a--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-14 13:36:19  STATE=CLOSED
%----------------------------SNAPSET z--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-14 13:36:19  STATE=CLOSED
%----------------------------SNAPSET y--------------------------------------%
      6906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  CRE-DATE=2012-12-14 13:35:49  CHANG-DATE=2012-12-14 13:36:19  STATE=CLOSED
%----------------------------SNAPSET x--------------------------------------%
 DMS0684 FILE ':2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB' DOES NOT EXIST
%----------------------------SNAPSET w--------------------------------------%
 DMS0684 FILE ':2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB' DOES NOT EXIST
%----------------------------SNAPSET v--------------------------------------%
 DMS0684 FILE ':2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB' DOES NOT EXIST
%----------------------------SNAPSET u--------------------------------------%
 DMS0684 FILE ':2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB' DOES NOT EXIST
%----------------------------SNAPSET t--------------------------------------%
 DMS0684 FILE ':2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB' DOES NOT EXIST
%----------------------------SNAPSET s--------------------------------------%
 DMS0684 FILE ':2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB' DOES NOT EXIST

/rest-file-from-snapset f-name=sm.ss.archive.v08.0b03.srclib,
                          snapset=d,replace=*yes ————————————————————  (2)

/show-file-attr sm.ss.archive.v08.0b03.srclib,inf=*par(history=*yes) ——  (3) 

%0000006906 :2OS6:$ARCHIV8B.SM.SS.ARCHIVE.V08.0B03.SRCLIB
%  ------------------------------- HISTORY      -----------------------------
%  CRE-DATE   = 2006-12-14  ACC-DATE   = 2006-12-14  CHANG-DATE = 2006-12-14
%  CRE-TIME   =   13:35:49  ACC-TIME   =   15:37:29  CHANG-TIME =   13:36:19
%  ACC-COUNT  = 2           S-ALLO-NUM = 0
%:2OS6: PUBLIC:      1 FILE  RES=      6906 FRE=      651 REL=      651 PAGES

(1)

The user displays information about the backed-up file statuses using LIST-FILE-FROM-SNAPSET.

(2)

From the output the user sees that the file was created on 14 December and was modified on 19 and 20 December. In order to undo changes on 19 December or later, the file must consequently be restored from Snapset d.

(3)

For safety’s sake, the user checks the time stamps in the restored file’s catalog entry: it now has the status of 14 December 12 once more, i.e. the processing state from before the changes which were made on or after 19 December.

Powered by Atlassian Confluence and Scroll Viewport.