One or more saved guards can be restored with this statement. The set of guards to be selected for restoration can be specified using wildcards. A nonprivileged user can only use the guards from his own ID while a guards administrator can use guards from all IDs.
Selection can be made between two types of restoration:
Restore immediately using GUARDS-SAVE
Create a procedure file with all necessary commands to transfer the desired guards into the system.
In this case, the created command procedure must be started by the user. If necessary, the procedure can be viewed and modified using a text editor such as EDT.
Only the guards of a single pubset can be restored with each statement. If multiple pubsets are to be restored, a separate restore run must be made for each pubset.
Guards can reference further guards. For example, rules for co-owner protection can contain references to guards of type STDAC. The RESOLVE operand can be used to control whether referenced guards are also automatically included in the restoration. In this case, all referenced guards are selected for restoration regardless of their name or type. This means that the GUARD-NAME and GUARD-TYPE operands are meaningless for them. A cross reference list is created and output to SYSOUT/ SYSLST. If a reference guard cannot be accessed, e.g. because it does not belong to the (nonprivileged) caller, it is included in the list of referenced guards with a corresponding error code.
RESTORE-GUARDS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GUARD-NAME = <filename 1..24 without-cat-gen-vers with-wild(40)>
Name of the guard(s) in a backup file that are to be restored. Guard names may contain wildcards but only a guards administrator may use wildcards in the user ID.
It is not allowed to specify a catalog ID in the path name, restoration is made to the pubset whose catalog ID was noted in the backup file at the time the backup was made. If the catalog ID is to be renamed, the NEW-PATH operand must be used.
Specifying the system default ID in guards names, e.g. $<filename> or $.<filename> is not supported.
Dependency to the SELECT operand
A type-dependent limitation can be made to the selected set of guards by specifying
SELECT=*BY-ATTRIBUTES(TYPE=...).Specifying
SELECT=*BY-ATTRIBUTES(RESOLVE=YES)causes referenced guards to also be restored, regardless of their name or type.
SELECT =
Specifies the criteria to be used in addition to the GUARD-NAME operand for selecting the guards to be saved.
SELECT = *ALL
Selects all guard types and all referenced guards. The reference guards are thereby selected regardless of their names.
SELECT = *BY-ATTRIBUTES(...)
Modifies the set of guards selected with the GUARD-NAME operand by further criteria.
TYPE =
Specifies the guard type to limit selection to.
TYPE = *ANY
Selects the guards regardless of their type.
TYPE = list-poss(6): <name 1..8>
Selects only guards of the specified type or types. The following entries are permitted:
Guard type | Meaning |
COOWNERP | Rule container for co-owner protection |
DEFAULTP | Rule container for default protection |
DEFPATTR | Attribute guards (default protection) |
DEFPUID | User ID guards (default protection) |
STDAC | Access condition guards |
UNDEF | Guards of undefined type |
RESOLVE =
Specifies whether the selected guards are to be searched for referenced guards.
RESOLVE = *YES
Selected guards are searched for referenced guards. Any referenced guards found are selected additionally, regardless of their name or type.
Guard type | Reference guards |
COOWNERP | Access condition guards specified in the rules |
DEFAULTP | Attribute and user ID guards specified in the rules |
DEFPATTR | Guards specified in the protection attributes |
DEFPUID | none |
STDAC | none |
UNDEF | none |
RESOLVE = *NO
The guards are not searched for referenced guards. Only the guards selected by their name (GUARD-NAME operand) and type (TYPE operand) are restored.
BACKUP-FILE-NAME = <filename 1..54 without-gen-vers>
Name of the backup file from which the saved guards are to be restored. Specifying the system default ID in file names, e.g. $<filename> or $.<filename> is allowed.
NEW-PATH =
Specifies whether the catalog ID, user ID or guard name is to be modified during restoration. It is also possible to specify whether the catalog ID is to be modified that is stored in an access condition of type PROGRAM in a saved STDAC guard (see ADMISSION=(PRO-GRAM) operand of the ADD-ACCESS-CONDITIONS or MODIFY-ACCESS-CONDITIONS command).
NEW-PATH = *SAME
No changes are to be made to the path names during restoration.
NEW-PATH = *BY-RULE(...)
Changes are to be made in the guard path names and/or in access conditions of type PRO-GRAM during restoration.
PUBSET-ID = *SAME
The catalog ID of the restored guard is to be taken over unchanged from the backup file.
PUBSET-ID = <catid 1..4>
New catalog ID that is to be used when restoring a guard.
USERID-ID = *SAME
The user ID of the restored guards is to be taken over unchanged from the backup file.
USER-ID = <name 1..8>
New user ID that is to be used when restoring a guard. The user ID specified in the GUARD-NAME operand for this entry may not contain wildcards. Specifying the system default ID, e.g. $ is not supported.
GUARD-NAME = *SAME
The name of the restored guard is to be taken over unchanged from the backup file.
GUARD-NAME = <name 1..8 without-cat-user-gen-vers>
New guard name that is to be used when restoring a guard. The guard name specified in the GUARD-NAME operand for this entry may not contain wildcards.
PROG-PUBSET-ID =
Specifies whether the catalog ID is to be modified that is stored in an access condition of type PROGRAM in a saved STDAC guard (see ADMISSION=(PROGRAM) operand of the ADD-ACCESS-CONDITIONS or MODIFY-ACCESS-CONDITIONS command).
PROG-PUBSET-ID = *SAME
The catalog ID in the path name of an access condition of type PROGRAM is to be taken over unchanged from the backup file.
PROG-PUBSET-ID =
New catalog ID that is to be inserted into the access condition of type PROGRAM in the file name while restoring a guard.
TARGET =
Specifies the way that guards are to be restored.
TARGET = *SYSTEM
The guards are restored directly into the running system by GUARDS-SAVE. The user has no influence on the restoration process.
TARGET = *PROCEDURE(...)
GUARDS-SAVE creates a procedure file with commands that are to restore the saved guards. The user has to carry out the actual restoration himself by executing the created procedure. The procedure can be edited with a text editor such as EDT prior to execution if necessary.
PROC-FILE-NAME = <filename 1..54 without-gen-vers>
Name of a file in which all procedure commands required for a restoration are to be written. The name is freely selectable. If a file of the same name already exists it will either be overwritten or the statement will be rejected with a corresponding error message, depending on the REPLACE-BACKUP-FILE operand.
REPLACE-PROC-FILE =
Specifies whether an existing procedure file is to be overwritten or not.
REPLACE-PROC-FILE = *NO
An existing procedure file is not overwritten.
REPLACE-PROC-FILE = *YES
An existing procedure file is overwritten. The set file protection attributes remain intact.
REPLACE-GUARD =
This operand specifies whether an existing guard is to be overwritten during a restoration.
REPLACE-GUARD = *NO
An existing guard is not overwritten.
REPLACE-GUARD = *YES
Ab existing guard is overwritten.
OUTPUT = list-poss(2):
This operand defines the destination for the output of a result logging.
OUTPUT= *SYSOUT
Output is sent to the data display terminal if the command was entered in dialog mode. In batch mode, the output destination depends on the specifications in the batch job.
OUTPUT = *SYSLST(...)
Output is sent to the system file SYSLST.
SYSLST-NUMBER = *STD
Output is sent to the system file SYSLST.
SYSLST-NUMBER = <integer 1..99>
Two-digit number nn used for forming the file name SYSLSTnn.
Example: Output after a program-controlled restoration run
//restore-guards guard-name=*,backup-file-name=g-save
% PRO7021 '2' GUARDS ARE RESTORED OUT OF BACKUP FILE ':XXXX:$MARY.G-SAVE<
%******************************************************************************
%GUARDS-SAVE RESTORE-GUARDS Started by User MARY 2017-12-07/17:31:15
% -------------------------
% *** Begin of Output ***
%******************************************************************************
%Backup File : :XXXX:$MARY.G-SAVE
%Backup Date : 2017-12-07/14:11:58
%Backup Pubset : XXXX
%Backup Guards : 2
%
%Restore Guard : :XXXX:$MARY.*
%Restore Type : COOWNERP, DEFAULTP, DEFPATTR, DEFPUID , STDAC , UNDEF
%Restore Resolve : *YES
%Restore Replace : *NO
%Restore Target : *SYSTEM
%
%New Pubset-Id : *SAME
%New User-Id : *SAME
%New Name : *SAME
%New Prog Pvs-Id : *SAME
%******************************************************************************
%Restored Guards : 2
%Faulty Guards : 0
%******************************************************************************
%
% Alphabetical List of Restored and Faulty Guards
%
%==============================================================================
%Guard Name Guard Type Error Status
%---------- ---------- ----- ------
%:XXXX:$MARY.STDAC STDAC restored
%:XXXX:$MARY.SYS.UCF COOWNERP restored
%==============================================================================
%
% Alphabetical List of Cross References
%
%==============================================================================
%:XXXX:$MARY.SYS.UCF COOWNERP -> :XXXX:$MARY.STDAC STDAC
%-----------------------------------------------------------------------------%:XXXX:$MARY.STDAC
STDAC <- :XXXX:$MARY.SYS.UCF COOWNERP
%==============================================================================
%
%******************************************************************************
%GUARDS-SAVE RESTORE-GUARDS Started by User MARY 2017-12-07/17:31:15
% -------------------------
% *** End of Output ***
%******************************************************************************
%//
In section "Procedure-controlled restoration" a generated procedure is shown.