Macro type: type S (E form/L form/D form/C form/M form) (see "Macro format")
The RJFSNAP macro 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 LJFSNAP macro 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 operation 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 in 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 another user ID (NUSERID operand) and/or a name prefix (NPREFIX operand).
If required, the caller can have a log of the restore processing output to SYSOUT (LIST operand). This log can cover either all job variables or only the job variables 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 macro is aborted with return code 0622. 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 job variables under their original user IDs.
When a job variable which still exists is overwritten, systems support can explicitly bypass the protection by means of the IGNPROT operand.
Systems support can only log the restoration of job variables 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
JVNAME
Selects the job variables which are to be restored.
=<c-string 1..80: filename 1..54 with-wild(80)>
Path name of the job variable(s) on the Snapset. Wildcards can be used to specify a set of job variables.
The job variables 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.
The catalog and user IDs specified must be unique (i.e. contain no wildcards). Aliases (also partially-qualified aliases) may be specified.
Privileged users (TSOS privilege) can restore job variables 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 job variable(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 job variable is restored from the Snapset with the latest status of this job variable, in other words with the latest backup. A job variable which cannot be restored with the latest 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 pubset 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..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 job variables to be restored may overwrite existing job variables.
=*NO
Existing job variables are not overwritten. This means that job variables with the names of existing job variables are not restored.
=*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 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 job variables 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.
NUSERID
Specifies that the job variables 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 job variables are to be renamed when they are restored and are to be assigned the specified name prefix.
This operand may not be specified together with the NUSERID operand.
=<c-string 1..8: name 1..8>
Name prefix.
=<var: char:8>
Only possible with MF=M:
Symbolic address of a memory area of 8 bytes in which the name prefix is stored.
LIST
Specifies which processing results are to be logged to SYSOUT.
=*NO
No output is directed to SYSOUT.
=*SYSOUT
All job variables are listed. For job variables which could not be restored, the reason is displayed by means of a message code.
=*ERRORS-TO-SYSOUT
Only job variables which could not 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 RJFSNAP 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'0433' | JV not cataloged |
X'00' | X'40' | X'0435' | JV cannot be accessed |
X'00' | X'40' | X'0440' | JV name invalid |
X'00' | X'40' | X'04A0' | JV subsystem cannot be accessed |
X'00' | X'40' | X'04B1' | Password not specified |
X'00' | X'40' | X'04B6' | Expiration date not yet reached |
X'00' | X'40' | X'04B8' | Only read access permitted |
X'00' | X'40' | X'04BF' | Access not permitted because of JV protection |
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'82' | X'053C' | No space in the pubset’s catalog |
X'00' | X'20' | X'0584' | Internal error |
X'00' | X'82' | X'0594' | Not enough virtual memory |
X'02' | X'00' | X'05B6' | Incorrect time conversion in GTIME macro |
X'00' | X'20' | X'05C7' | Internal error in DMS |
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 JV names |
X'00' | X'40' | X'0620' | No restorable JV found |
X'00' | X'40' | X'0621' | JV already cataloged, restoration not performed |
X'00' | X'40' | X'0622' | Snapset not available |
X'00' | X'01' | X'0624' | JV name invalid |
X'00' | X'40' | X'0682' | JV error when accessing JV |
X'00' | X'01' | X'06F7' | Invalid operand value |
X'00' | X'01' | X'06FD' | Parameter area invalid or not accessible |
The return codes with the maincode X’04xy’ belong to the component JVS. A list which includes the meanings can be output using the JVSERROR macro (see also the “Job Variables” manual [21]).
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:
RJFSNAP MF=D * PARAMETER AREA DMAKHDR FHDR MF=(C,DMAK),EQUATES=NO DMAKHDR DS 0A DMAKFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER * DMAKIFID DS 0A 0 INTERFACE IDENTIFIER DMAKFCTU DS AL2 0 FUNCTION UNIT NUMBER DMAKFCT DS AL1 2 FUNCTION NUMBER DMAKFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER * DMAKRET DS 0A 4 GENERAL RETURN CODE DMAKSRET DS 0AL2 4 SUB RETURN CODE DMAKSR2 DS AL1 4 SUB RETURN CODE 2 DMAKSR1 DS AL1 5 SUB RETURN CODE 1 DMAKMRET DS 0AL2 6 MAIN RETURN CODE DMAKMR2 DS AL1 6 MAIN RETURN CODE 2 DMAKMR1 DS AL1 7 MAIN RETURN CODE 1 DMAKFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH * DMAKJNAM DS CL80 JVNAME DMAKSNAP DS FL1 SNAPSET * SNAPSET - VALUES DMAKSNIN EQU 0 SNAPSET=<integer> DMAKSNCH EQU 1 SNAPSET=<char> DMAKSNLT EQU 2 SNAPSET=*LATEST DMAKSNAL EQU 3 SNAPSET=*ALL * DMAKREPL DS FL1 REPLACE * REPLACE - VALUES DMAKREPY EQU 0 REPLACE = YES DMAKREPN EQU 1 REPLACE = NO * DMAKIGNP DS FL1 IGNPROT * IGNPROT VALUES DMAKIGNO EQU 0 IGNPROT = NO DMAKIGYE EQU 1 IGNPROT = YES * DMAKLIST DS FL1 LIST * LIST - VALUES DMAKLSTN EQU 0 LIST = NO DMAKLSYO EQU 1 LIST = SYSOUT DMAKLSYE EQU 2 LIST = ERRORS * DMAKNUSR DS CL8 NUSERID DMAKNPRE DS CL8 NPREFIX DMAKSNVL DS H SnapValue DMAKSNID DS CL1 Snapid DMAKOFLG DS AL1 FLAG BYTE DMAKNUSP EQU X'80' S: NUSERID SPECIFIED DMAKNPSP EQU X'40' S: NPREFIX SPECIFIED DMAKRES1 EQU X'3F' RESERVED DMAK# EQU *-DMAKHDR
Sample calling sequence
MVC RJFSMFC(DMAK#),RJFSMFL
RJFSNAP MF=M,PATHNAM=':X:JV1',PARAM=RJFSMFC
RJFSNAP MF=E,PARAM=RJFSMFC
.
.
RJFSMFC RJFSNAP MF=C
RJFSMFL RJFSNAP MF=L,...