RSTDLO

RSTDLO (Restore Document Library Object)

RSTDLO Command syntax diagram

Purpose

The Restore Document Library Object (RSTDLO) command restores documents, folders, and distribution objects (mail).
This command can be used to restore the documents and folders if the document was or was not freed by the Save Document Library Object (SAVDLO) command, or to restore documents and folders that were deleted by the Delete Document Library Object (DLTDLO) command.
Restoring a document either replaces the existing document content and control information if the document exists on the system, or it adds new document content and control information if the document does not exist.
For a filed document (electronic mail or a document stored in the document library), the document and folder name of the document object on the media must be the same as the document name and folder name of the document on the system, unless the document is renamed and put in a different folder during the restore operation.

Note: Folder names must match exactly for restored folders. All objects that are not in use are restored from the folder on the media or in the save file to the existing folder. Restoring a folder creates a new folder object if the folder does not exist and adds to this new folder all objects saved with the folder on the media or in the save file. If the folder exists, any document or folder objects that do not exist within it are created. The existing documents are replaced with the version from the media.

For a filed document restored on the system whose owner is not known to the system or is not enrolled in the system distribution directory, the user profile of the default owner (QDFTOWN) becomes the owner of the document or folder.
The creation date of a document does not change if the document exists. If the document does not exist, the creation date is set to the date on which the document is created.
The security does not change if a document or folder exists on the system where it is to be restored. If the document or folder does not exist, public authority, authorization list, and personal status are restored; however, all other private document and folder authorities are not restored. These authorities must be established again by the owner.
If a document is restored that had a mail log entry when it was saved, the mail log entry is restored if the distribution tracking object exists on the system. If the distribution tracking object does not exist on the system, a message is sent saying that the document was restored without a mail log entry.
If this command ends abnormally, objects are left on the system in an unknown state and cannot be found in a library. This can happen if a power failure occurs when this command is run. The Reclaim Storage (RCLSTG) command can be used to clean up the auxiliary storage and delete most of those objects from the system; however, unknown mail objects are not cleaned up with the RCLSTG command.
When a set of documents and folders are restored, all documents and folders in the set must exist in the same diskette, tape, optical volume, or save file.
If a document exists in more than one tape or diskette file, the user can control which document is restored by specifying the media file using the sequence number (tape) or label (tape or diskette) parameter. If more than one version of the document exists, the SAVDATE and SAVTIME parameters can also be used to select the correct document.
When text search services are on the system and the user restores a document library object, the text search index for the object is restored.

Restrictions

This command is shipped with public *EXCLUDE authority.

To use this command, have *SAVSYS or *ALLOBJ special authority or be enrolled in the system distribution directory.

This command cannot be run when RCLDLO DLO(*ALL) is running because RCLDLO requires exclusive use of internal objects.

When saving or restoring to an existing database file using the OUTFILE parameter, the user must have execute authority to the output file library.

Required Parameters

DLO

Specifies the document library objects to be restored.
*ALL: All documents, folders, and distribution objects (mail) that are saved on the media and meet the values specified on the SAVFLR parameter are restored.
*MAIL: All distribution objects and documents that were referred to by a mail log are restored.
*SYSOBJNAM: The documents with the system object names specified in the SYSOBJNAM parameter are restored.
document-name: Specify the user-assigned names of the documents to be restored. Up to 12 characters can be specified for the name; up to 300 document names can be specified. All documents named must be in the folder specified on the SAVFLR parameter.

DEV

Specifies the name of the device to be used to restore the document library objects. The device name must be known on the system by a device description.
*SAVF: The document library objects are restored from a save file.
diskette-device-name: Specify the name of the diskette device to be used to restore the document library objects.
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 for the restore operation.
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

SAVFLR

Specifies the name of the folder on the media from which the documents and folders are restored.
*ANY: All document library objects that meet the values specified on the DLO parameter are restored, regardless of the folders (if any) from which they were saved. This value is valid only if *ALL, *MAIL, or *SYSOBJNAM is specified on the DLO parameter.
*NONE: The documents to be restored were saved as documents without folders.

Note: *NONE is valid only when DLO(*ALL) is specified.

saved-folder-name: Specify the name of the saved folder from which documents or folders are to be restored. Up to 63 characters can be specified for the folder name. When DLO(*ALL) is specified, up to 300 folder names can be specified. The name of a saved folder must be specified when DLO(document-name) is specified.

RENAME

Specifies the new user-assigned name for the restored document.
*SAME: The documents being restored have the same user-assigned names that they have on the media.
new-document-name: Specify the new document names that the documents have after they are restored. Up to 300 user-assigned names can be specified for documents being restored.

RSTFLR

Specifies the name of the folder in which the folders and documents to be restored will be placed. The name can be any fully-qualified folder name up to 63 characters. The folder named is not required to exist if DLO(*ALL) is specified and the media contains the folder specified on the SAVFLR parameter.
*SAME: The documents to be restored are placed into the same folder from which they were saved.
restore-folder-name: Specify the name of the folder in which the restored documents and folders are to be placed.

SYSOBJNAM

Specifies the system object name of the documents to be restored. This parameter is valid only when DLO(*SYSOBJNAM) is specified.
*NONE: A system object name is not specified.
system-object-name: Specify the 10-character system object names of the documents to be restored. A maximum of 300 names can be specified.

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.
*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.

Note: This value cannot be specified when using an optical media library device.

volume-identifier: Specify the identifiers of one or more volumes in the order they are placed in the device and used to restore the objects.

SEQNBR

Specifies the tape sequence numbers used for the restore operation. This parameter is valid for tape only.
*SEARCH: The tape is searched for the first data file with an identifier matching the LABEL parameter value and with contents of a minimum of one of the specified document library objects. If the last operation on the device specified ENDOPT(*LEAVE) (that is, the tape is positioned at the location at which the last operation ended), the file search begins with the first data file beyond the current tape position. If ENDOPT(*LEAVE) was not specified on the last operation (or if the tape has been rewound since an ENDOPT(*LEAVE) operation), the search begins with the first data file on the volume.

Note: If a folder is contained in more than one file or on more than one tape, a message is sent indicating that the folder may not have been fully restored. To restore the rest of the folder, run the RSTDLO command again specifying the next sequence number.

Element 1: Beginning Sequence Number
Specifies the sequence number of the first file to be used for the restore operation.
Element 2: Ending Sequence Number
*ONLY: The ending sequence number is the same as the beginning sequence number.
ending-sequence-number: Specify the sequence number of the last file used for the restore operation. 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.

LABEL

Specifies the file label that is used to find the file that was written to the media during the save operation.
*GEN: The system generates the default name of the file label for which to search.
data-file-identifier: Specify the media data file identifier, which includes up to 17 alphanumeric characters, of the file that contains the documents and folders to be restored.

SAVF

Specifies the qualified name of the save file that contains the saved document library objects to be restored.
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 save file from which to restore DLOs.

NEWOBJ

Specifies whether a new library-assigned name is created for the folder or document being restored.
*SAME: The library-assigned name is restored to the name used when the document library objects were saved.
*NEW: A new library-assigned name is created for each document or folder being restored. If *NEW is specified on this parameter, then ALWOBJDIF(*ALL) cannot be specified.

SAVDATE

Specifies the date on which the document library objects were saved. If more than one version of the document library objects exist on the media, use this parameter to identify which version of the document library objects to restore. The date must be expressed in the job date format; if separators are used, the value must be enclosed in apostrophes. If the SAVDATE parameter is not specified, the version of the documents and folders to be restored will be the first version found on the volume or the version found with the specified file label.

SAVTIME

Specifies the time when the document library objects were saved. If more than one version of the document library objects exist on the media with the same value for the date saved, use this parameter to identify which version of the document library objects to restore. Express the time as a 6-digit value, in the format hours, minutes, seconds (hhmmss). If separators are used, the value must be enclosed in apostrophes ('hh:mm:ss'). If a volume identifier is specified, but SAVTIME is not specified, the version of the document library objects to be restored will be the first version found on the volume or the version found with the specified file label.
This parameter is valid only if SAVDATE is also specified.

ALWOBJDIF

Specifies whether the following differences encountered during the RSTDLO operation are allowed:

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 system object name on the system does not match the system object name on the tape or diskette being restored.

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

The ALWOBJDIF parameter can be used to allow an object to be restored whose owner or object name on the system is different than on the media used for the restore operation. By specifying the *ALL special value, an object with a different name is restored to the name on the media, while an object with a different owner keeps the owner name from the system instead of the media.

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

*NONE: The differences described above are not allowed on the restore operation. For authorization list cases, the object is restored, but the object is not linked to the authorization list, and public authority is set to *EXCLUDE. For other cases, a diagnostic message is sent for the object, and the object is not restored.
*ALL: All the differences described above are allowed for the restore operation. The object is restored.

Notes

If the owners of the object do not match, the object is restored, but it keeps the ownership and authorities of the object on the system before the restore operation.

If the primary groups of the object do not match, the object is restored, but it keeps the primary group of the object on the system before the restore operation.

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

If *ALL is specified on this parameter, then NEWOBJ(*NEW) cannot be specified.

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. If the authorization list does not exist on the new system, a message that includes the name of the missing list is issued.

SAVASP

Specifies the number of the auxiliary storage pool (ASP) on media from which saved documents and folders are to be restored.
*ANY: The documents and folders saved in any ASP are restored.
auxiliary-storage-pool-number: Specify the number of the ASP from which documents and folders are restored.

RSTASP

Specifies the number of the auxiliary storage pool (ASP) on media in which restored documents and folders are to be placed.
*SAVASP: The documents and folders are placed in the same ASP from which they were saved.
auxiliary-storage-pool-number: Specify the number of the ASP in which restored documents and folders are placed.

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.
*PRINT: The output is printed with the job's spooled output.
*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 QAOJRSTO in QSYS with the format name QOJRST 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.
'optical-file-path-name': Specify the path name of the optical file.

Examples for RSTDLO
Example 1: Restoring Documents with System Object Names
RSTDLO DLO(*SYSOBJNAM) DEV(TAP01) SYSOBJNAM(HZ83B55219)

This command restores the document named HZ83B55219 from the tape unit TAP01.
Example 2: Restoring Documents from a Save Folder
RSTDLO DLO(A) DEV(diskette-device-name) SAVFLR(X)

This command restores the document named A from folder X.
Example 3: Restoring All Documents
RSTDLO DLO(*ALL) DEV(TAP01)

This command restores all documents and folders that are on the first tape file on tape unit TAP01.
Example 4: Restoring a Folder Saved from the System ASP to a User ASP
RSTDLO DLO(*ALL) FLR(Y) SAVASP(1) RSTASP(2)

This command restores folder Y, which was saved from ASP 1, to user ASP 2. Folder Y must be deleted from ASP 1 before it can be restored to ASP 2.
Example 5: Creating New Library-Assigned Name
RSTDLO DLO(*SYSOBJNAM) DEV(TAP01) SYSOBJNAM(HZ83B55219) NEWOBJ (*NEW)

This command restores document HZ83B55219 from tape unit TAP01 and gives it a new library-assigned name and a new system object name.
Example 6: Renaming Documents
RSTDLO DLO(A B) DEV(TAP01) SAVFLR(C) RENAME(Y Z) RSTFLR(X)

This command restores documents A and B from within folder C. Document A is renamed to Y and document B is renamed to Z. The command then puts them in folder X.
Example 7: Specifying Sequence Numbers
RSTDLO DLO(*ALL) DEV(tape-device-name) SAVFLR(A) SEQNBR(1 3) LABEL(*GEN)

This command restores all of folder A from tape files with the sequence numbers 1, 2, and 3, and the label QDOC or QDOCxxxx.
Example 8: Specifying Allowed Differences
RSTDLO DLO(A) DEV(TAP01) SAVFLR(X) ALWOBJDIF(*ALL)

This command restores document A from folder X. If document A in folder X exists on the system and the owner of the document on the system does not match the owner of the document being restored, the document is restored and the owner of the document on the system remains unchanged.
Example 9: Reporting Information about Objects Restored and Not Restored
RSTDLO DLO(*ALL) DEV(TAP01) OUTPUT(*OUTFILE) OUTFILE(INFO92) OUTMBR(FOURQT *ADD)

This command restores all documents and folders from the tape device TAP01. A list reporting information about objects restored and objects not restored is directed to the output file INFO92. The output is received in the member FOURQT as an addition to existing information in the member.
Error messages for RSTDLO
*ESCAPE Messages

CPF370C

Not authorized to ALWOBJDIF parameter.

CPF3718

Restore command not valid for file &1.

CPF3728

Device &1 specified with other devices.

CPF3767

Device &1 not found.

CPF3780

Specified file for library &1 not found.

CPF3782

File &1 in &2 not a save file.

CPF381B

No DLOs restored to ASP &1.

CPF3812

Save file &1 in &2 in use.

CPF384D

Save or restore operation not allowed on ASP &1.

CPF8AB5

ASP &5 is not configured.

CPF8A47

Internal system objects in use.

CPF90AF

RSTFLR value not allowed.

CPF90A4

RENAME value not allowed.

CPF90B4

&1 folders restored to system, &2 not restored.

CPF90CD

Not authorized to restore distributions.

CPF90CF

Search index data base is damaged.

CPF90E0

Not enough authority for ALWOBJDIF(*ALL).

CPF90E7

Document library objects not restored.

CPF9003

&1 document library objects restored. &10 not restored.

CPF905C

Error occurred trying to find a translation table.

CPF9050

Ending sequence number not valid.

CPF9069

User not permitted to restore into folder &1.

CPF908A

Requester &1 not enrolled.

CPF909B

&1 document library objects restored. &10 not restored.

CPF9412

List of folder names not allowed with DLO parameter.

CPF9810

Library &1 not found.

CPF9812

File &1 in library &2 not found.

CPF9820

Not authorized to use library &1.

CPF9822

Not authorized to file &1 in library &2.

CPF9825

Not authorized to device &1.

CPF9830

Cannot assign library &1.

CPF9831

Cannot assign device &1.

CPF9845

Error occurred while opening file &1.

CPF9846

Error while processing file &1 in library &2.

CPF9850

Override of printer file &1 not allowed.

CPF9851

Overflow value for file &1 in &2 too small.

CPF9860

Error occurred during output file processing.

CPF9899

Error occurred during processing of command.

OPT1498

Volume name list exhausted on device &1.

OPT1502

Attempted to process past the end of a multi-volume set.

OPT1605

Media or device error occurred.