Restore job variables on the basis of a Snapset
Component: | BS2000 |
Functional area: | Job variables |
Domain: | JOB-VARIABLES |
Privileges: | STD-PROCESSING |
Function
The RESTORE-JV-FROM-SNAPSET command restores job variables of a pubset from a pubset copy which was created on an associated Snapset. During the restore operation, single job variables 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 job variable should be restored from the Snapset with the latest job variable status. Before restoration takes place, the user can issue the LIST-JV-FROM-SNAPSET command to obtain information on job variables which were saved to a Snapset.
All attributes of a restored job variable are taken over from the original job variable unchanged (including the creation date, date of modification and the protection attributes).
Nonprivileged users can only restore a job variable of a foreign user if they are the co-owner.
Overwriting by the restore must be explicitly permitted for existing job variables (REPLACE operand). For job variables 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).
Job variables can also be restored under a new name (NEW-JV-NAME operand). They are renamed by specifying either another user ID or a name prefix.
If required, the caller can have a log of the restore processing output to SYSOUT or SYSLST (OUTPUT operand). This log can cover either all job variables or only the job variables 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.
The restoration of job variables is not an explicit SAT event. The SECOS component SAT can only log the DELETE-JV (for overwriting) and CREATE-JV calls which are used internally.
Privileged functions
Systems support (TSOS privilege), as co-owner, can restore a job variable under its original user ID or under a foreign user ID.
When a job variable which still exists is overwritten, systems support can explicitly bypass the protection by means of the IGNORE-PROTECTION operand.
Format
RESTORE-JV-FROM-SNAPSET | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
JV-NAME = <filename 1..54 without-gen-vers with-wild(80)>
Selects the job variables which are to be restored. The job variables 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.
The catalog and user IDs specified must be unique (i.e. contain no wildcards). Aliases (also partially-qualified aliases) may be specified.
SNAPSET = *LATEST / *ALL / <name 1..1 with-low> /<integer -52..-1> / *INTERVAL(...)
Specifies the Snapset from which the job variables are to be restored. Information about all existing Snapsets for a pubset can be obtained using the SHOW-SNAPSET-CONFIGURATION command.
SNAPSET = *LATEST
The job variables 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 job variable is restored from the Snapset with the latest job variable status, in other words with the latest backup of the job variable.
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 job variables to be restored may overwrite existing job variables.
REPLACE = *NO
Existing job variables are not overwritten. This means that job variables with the names of existing job variables are not restored.
REPLACE = *YES(...)
Existing job variables may be overwritten by job variables which are to be restored provided the protection attributes permit this. For job variables 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 job variables are to be overwritten without taking into account any write protection which exists.
NEW-JV-NAME = *SAME / *BY-USER-ID(...) / *BY-PREFIX(...)
Specifies whether the job variables are to be renamed when they are restored. When they are renamed, either a different ID or a name prefix can be specified.
NEW-JV-NAME = *SAME
Each job variable is restored under the name of the original job variable.
NEW-JV-NAME = *BY-USER-ID(...)
Each job variable is to be restored under the user ID specified.
Only the co-owner (or TSOS) is able to restore the job variable 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 job variable is retained.
NEW-JV-NAME = *BY-PREFIX(...)
Each job variable 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>
Name prefix (up to 8 characters). The default is *NONE, i.e. the original job variable name is retained.
REPORTING = *ERROR / *FULL
Determines the scope of the log if a processing log was requested in the OUTPUT operand.
REPORTING = *ERROR
Only job variables which could not be restored are listed. The reason is displayed by means of a message code.
REPORTING = *FULL
All job variables are listed. For job variables 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 | DMS0585 | Error detected when processing catalog or multiprocessor system | |
64 | DMS05FC | Specified file not in home pubset | |
64 | DMS0610 | Action with wildcards: Error executing a function for one of the selected job variable names | |
64 | DMS0616 | Volume set in SM pubset cannot be accessed | |
64 | DMS0620 | No restorable job variable found | |
64 | DMS0621 | Job variable already cataloged, restoration not performed | |
64 | DMS0622 | Snapset not available | |
64 | DMS0682 | JVS error when executing job | |
130 | DMS053C | No space in the pubset’s catalog | |
130 | DMS0585 | Error detected when processing catalog or multiprocessor system | |
130 | DMS0594 | Not enough virtual memory available |