RSTUSRPRF (Restore User Profiles)

RSTUSRPRF Command syntax diagram

 

Purpose

The Restore User Profiles (RSTUSRPRF) command restores the basic parts of a user profile or a set of user profiles saved by the Save System (SAVSYS) or the Save Security Data (SAVSECDTA) commands. The RSTUSRPRF command restores only the special authority given in the Create User Profile (CRTUSRPRF) command; it does not restore the authority for the named objects owned by other users. To do that, the Restore Authority (RSTAUT) command must be used after the profiles, libraries, and objects are restored. If all user profiles are restored, the authorization lists and authority holders that existed when the SAVSYS command or SAVSECDTA command was run are also restored.

Before this command is specified, all other operations on the system must be stopped if USRPRF(*ALL) is specified. This requires ending all subsystems through the End Subsystem (ENDSBS(*ALL)) command or End System (ENDSYS) command or specifying this command when the operating system is started. The RSTUSRPRF command is normally used after the restore of the operating system but before the user libraries are restored. The user profiles must be restored before any libraries or objects belonging to them can be restored. After the libraries and their objects are restored, the authority for the objects is restored to the user profiles by the RSTAUT command. At the completion of the command, either message CPF3775 or message CPC3705 is sent to QHST. More information on restoring the system is in the Backup and recovery topic in the Information Center.

The following situations may apply to user profiles being restored by the RSTUSRPRF command:

The following applies to restoring passwords and group connections for restored user profiles:

Note: This command ignores all file overrides that are currently in effect for the job.

 

Restrictions

  1. This command is shipped with public *EXCLUDE authority.

  2. The user of this command must have *SAVSYS authority in the user profile, specified by SPCAUT(*SAVSYS).

  3. Before this command is specified, all other operations on the system must be ended if USRPRF(*ALL) is specified. The End System (ENDSYS) or End Subsystem (ENDSBS) command can be used to end these operations. You must have *JOBCTL authority to use the ENDSYS or ENDSBS command.

  4. To restore authorization lists and authority holders, USRPRF(*ALL) must be specified.

  5. When SECDTA(*PVTAUT) is specified, the user profile must exist on the system. Internal private authority objects will not be created for a non-existing user profile.

  6. The user must have both *ALLOBJ and *SECADM special authorities in order to specify SECDTA(*PWDGRP).

 

Required Parameters

DEV
Specifies the name of the device used for the restore operation. The device name must already be known on the system by a device description.

*SAVF: The save file specified on the SAVF parameter is used for the restore operation.

diskette-device-name: Specify the name of the diskette device used to restore the user profiles.

optical-device-name: Specify the name of the optical device used for the restore operation.

tape-media-library-device-name: Specify the name of the tape media library device used to restore the user profiles.

tape-device-name: Specify the names of one or more tape devices used for the restore operation. If more than one tape device is used, specify the names of the devices in the order in which they are used. Using more than one tape device permits one tape volume to be rewound and unloaded while another tape device processes the next tape volume.

 

Optional Parameters

USRPRF
Specifies the names of one or more user profiles to restore. To be restored, the user profiles must exist on the media from the Save System (SAVSYS) or Save Security Data (SAVSECDTA) commands.

*ALL: All of the user profiles, authorization lists, authority holders, and digital certificate manager information saved by the SAVSYS or SAVSECDTA commands are restored.

*NEW: All of the user profiles, authorization lists, and authority holders saved by the SAVSYS or SAVSECDTA commands which do not currently exist on the system are restored.

*NONE: No user profiles are restored.>

generic*-user-profile-name: Specify one or more generic names of sets of user profiles to restore. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic functions, refer to generic functions.

user-profile-name: Specify one or more names of specific user profiles that are restored. Both generic names and specific names can be specified in the same command.

VOL
Specifies the volume identifiers of the media or the cartridge identifiers of tapes in a tape media library device, from which the objects are being restored. The volumes must be in the same order as they were when the data was saved. The volume that contains the beginning of the file to be restored should be placed in the device. More information on this parameter is in Commonly used parameters.

Note: For tape, the user profiles are restored from the volumes placed on the tape devices, in the order that those devices were specified. This operation is normally performed immediately after a restore of the system is performed and the user profiles are on the same volume.

*MOUNTED: The objects are restored from the volumes placed in the device specified on the DEV parameter. For a media library device, the volume to be used is the next cartridge in the category mounted by the Set Tape Category (SETTAPCGY) command.

volume-identifier: Specify the identifiers of up to 75 volumes in the order in which they are placed in the devices and used to restore the user profiles.

SEQNBR
Specifies the sequence number of the tape file used for the restore process.

*SEARCH: The volume placed in the device is searched for a file containing the saved user profiles; when a match is found, the user profiles are restored. If a match is not found, load another tape and try the command again. If the last operation on the device specified ENDOPT(*LEAVE) (the tape is positioned at the location where the last operation ended), the file search starts with the first file beyond the current tape position. If ENDOPT(*LEAVE) was not used for the last operation (or if the tape was manually rewound since an ENDOPT(*LEAVE) operation), the search begins with the first file on the volume.

sequence-number: Specify the sequence number of the file. Valid values range from 1 through 16777215.

ENDOPT
Specifies the operation that is automatically performed on the tape or optical volume after the restore operation ends. If more than one volume is used, this parameter applies only to the last volume used; all other volumes are unloaded when the end of the volume is reached.

Note: This parameter is valid only if a tape or optical device name is specified on the DEV parameter. For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored.

*REWIND: The tape is automatically rewound, but not unloaded, after the operation has ended.

*LEAVE: The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive.

*UNLOAD: The tape is automatically rewound and unloaded after the operation ends. Some optical devices will eject the volume after the operation ends.

SAVF
Specifies the save file that contains the data from which to restore objects.

The name of the save file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

save-file-name: Specify the name of the file used to restore user profiles.

MAIL
Specifies whether the OfficeVision distribution objects saved from a release before V2R2M0 are restored.

Note: You can specify *YES on this parameter only if you specify *ALL on the USRPRF parameter.

*NO: Distribution objects that are part of your mail are not restored with the user profile.

*YES: Distribution objects that are part of your mail are restored with the user profile if the save data was created before release V2R2M0. Otherwise, no distribution objects are restored. For saved distribution objects created on V2R2M0 or later, specify DLO(*MAIL) on the Restore Document Library Objects (RSTDLO) command to restore your mail.

ALWOBJDIF
Specifies whether certain differences encountered during a restore are allowed. There are two differences for this command:

  • The owner of the object on the system is different than the owner of the object from the save.

  • The primary group of the object on the system is different than the primary group of the object from the save.

  • The object is secured by an authorization list and is being restored to a system other than the one on which it was saved.

Note: To use this parameter, *ALLOBJ authority is required.

*NONE: The differences described above are not allowed for the restore operation. For an ownership difference, the object is not restored. For primary group difference, the object is not restored. For an authorization list difference, the object is restored, but the object is not linked to the authorization list, and public authority is set to *EXCLUDE.

*ALL: The differences previously described are allowed for the restore operation. The object is restored. The following should be noted:

  • If the owners of the object do not match, the object will be restored, but the ownership and authorities it had before the restore operation are retained.

  • If the primary groups of the object do not match, the object will be restored, but the primary group it had before the restore operation is retained.

  • The informational message causes a diagnostic message to be sent indicating that security or integrity changes occurred during the restore. This results in an escape message for the restore function.

  • If the user is restoring objects to a system different from the one on which they were saved and the objects are secured by an authorization list, specifying *ALL automatically links the objects to the authorization list again. If the authorization list does not exist on the new system, a message that includes the name of the missing list is issued.

SAVASPDEV
Specifies the name of the auxiliary storage pool (ASP) device from which private authority information was saved. The private authority information is restored for later use by the Restore Authority (RSTAUT) function.

*ANY: The private authority information saved from all ASPs included in the save operation is restored.

*: The private authority information saved from the system ASP (ASP number 1), all basic user ASPs (ASP numbers 2-32), and, if the current thread has an ASP group, all independent ASPs in the ASP group is restored.

*SYSBAS: The private authority information saved from the system ASP and all basic user ASPs is restored.

*CURASPGRP: If the current thread has an ASP group, the private authority information saved from all independent ASPs in the ASP group is restored.

auxiliary-storage-pool-device-name: Specify the name of the independent ASP from which the private authority information was saved.End of change

OMITUSRPRF
Specifies the names of one or more user profiles to be omitted from the restore.

*NONE: None of the user profiles is omitted from the restore.

generic*-user-profile-name: Specify one or more generic names of sets of user profiles to be omitted from the restore. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic functions, refer to generic names.

user-profile-name: Specify one or more names of specific user profiles that are to be omitted from the restore. Both generic names and specific names can be specified in the same command.

SECDTA
Specifies whether all authority information or only the private authorities are restored for the specified user profiles and auxiliary storage. Also specifies whether the password and group linkages are to be restored for the specified user profiles.

*USRPRF: All of the specified user profiles, authorization lists, authority holders, and private authorities, saved by the SAVSYS or SAVSECDTA commands are restored.

*PVTAUT: Only the private authorities for the specified user profiles and auxiliary storage pools are restored. The information is used by the Restore Authority (RSTAUT) command to restore the private authorities to the referenced objects.

*PWDGRP: The passwords and group linkages for the specified user profiles are restored with the user profiles.

*DCM: Only the information required by Digital Certificate Manager (DCM) is restored.

Note: *PWDGRP cannot be specified if USRPRF(*USRPRF) is also specified.

Note: *PVTAUT cannot be specified if USRPRF(*NEW) is also specified.

Note: *DCM is only supported for save media that is at release V5R1M0 or later.



OUTPUT
Specifies whether a listing that shows information about the status of the object is created and directed to an output file. The listing shows the restore information and shows all objects, restored, not restored, and excluded. Information about each object's security is listed for the restored objects. More information on this parameter is in Commonly used parameters.

*NONE: No output is created.

*OUTFILE: The output is directed to the database file specified on the OUTFILE parameter.

Note: You must specify the database file name on the OUTFILE parameter when OUTPUT(*OUTFILE) is specified.

OUTFILE
Specifies the qualified name of the database file to which the information about the object is directed when *OUTFILE is specified on the OUTPUT parameter. If the file does not exist, this command creates a database file in the specified library. If a new file is created, the system uses QASRRSTO in QSYS with the format name QSRRST as a model.

The name of the database file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

database-file-name: Specify the name of the database file to which the output of the command is directed.

OUTMBR
Specifies the name of the database file member to which the output is directed. If a member already exists, the system uses the second element of this parameter to determine whether the member is cleared before the new records are added. If the member does not exist and a member name is not specified, the system creates a member with the name of the output file specified on the OUTFILE parameter. If an output file member name is specified, but the member does not exist, the system creates it.

Element 1: Member to Receive Output

*FIRST: The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified on the OUTFILE parameter.

member-name: Specify the name of the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it. If the member exists, the user can add records to the end of the existing member or clear the existing member and add the records.

Element 2: Operation to Perform on Member

*REPLACE: The existing records in the specified database file member are replaced by the new records.

*ADD: The new records are added to the existing information in the specified database file member.

OPTFILE
Specifies the path name of the optical file that is used for the restore operation, beginning with the root directory of the volume. For more information on specifying path names, refer to path names.

'*': The system searches the root directory of the optical volume for the default name generated by the corresponding save operation.

'optical-directory-path-name/*': The system searches the specified directory of the optical volume for the default name generated by the corresponding save operation.

Examples for RSTUSRPRF

Example 1: Restoring All Profiles 

RSTUSRPRF  DEV(TAP01)  SEQNBR(*SEARCH)  ENDOPT(*REWIND)

The saved version of all user profiles contained on the tape currently put on the tape drive named TAP01 is restored to the system. The tape is searched for the file, and the tape is rewound on completion or at the end of restore.

Example 2: Restoring Specific User Profiles 

RSTUSRPRF  DEV(TAP01)  USRPRF(USRA USRB USRC USER*)

The saved version of all the user profiles must exist on the tape placed on tape drive TAP01. User profiles USRA, USRB, and USRC, along with all the user profiles whose names start with USER, are restored to the system.

Example 3: Restoring User Profiles from a Save File 

RSTUSRPRF  DEV(*SAVF) USRPRF(USRX USRY)
  SAVF(QGPL/SAVESEC)

This command restores user profiles USRX and USRY to the system from the save file SAVESEC in library QGPL.

Example 4: Reporting Information about User Profiles Restored and Not Restored 

RSTUSRPRF  DEV(TAP01) USRPRF(*ALL) OUTPUT(*OUTFILE)
  OUTFILE(PRFS92) OUTMBR(FOURQT *ADD)

This command restores all user profiles from the tape device TAP01. A list reporting information about user profiles restored and not restored is directed to the output file PRFS92. The output is received in the member FOURQT as an addition to existing information in the member.

Error messages for RSTUSRPRF

*ESCAPE Messages

CPD3774
USRPRF(*ALL) required when MAIL(*YES) specified.
CPF2206
User needs authority to do requested function on object.
CPF370C
Not authorized to ALWOBJDIF parameter.
CPF3709
Tape devices do not support same densities.
CPF3727
Duplicate device &1 specified on device name list.
CPF3728
Device &1 specified with other devices.
CPF3733
&2 &1 in &3 previously damaged.
CPF3738
Device &1 used for save or restore is damaged.
CPF3743
File cannot be restored, displayed, or listed.
CPF3748
Object information for library &1 damaged.
CPF376B
File &1 not found.
CPF3767
Device &1 not found.
CPF3768
Device &1 not valid for command.
CPF3775
Not all user profiles or authority objects restored.
CPF3780
Specified file for library &1 not found.
CPF3782
File &1 in &2 not a save file.
CPF3785
Not all subsystems ended.
CPF3793
Machine storage limit reached.
CPF3794
Save or restore operation ended unsuccessfully.
CPF3796
Storage limit exceeded for user profile &4.
CPF380C
Library &1 not restored.
CPF3812
Save file &1 in &2 in use.
CPF908A
Requester &1 not enrolled.
CPF9812
File &1 in library &2 not found.
CPF9814
Device &1 not found.
CPF9833
*CURASPGRP or *ASPGRPPRI specified and thread has no ASP group.End of change
CPFB8ED
Device description &1 not correct for operation.End of change