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 tape, optical volume, or save file.

If a document exists in more than one tape file, the user can control which document is restored by specifying the media file using the sequence number or label 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 no public authority (*EXCLUDE).
• You must have save system (*SAVSYS) or all object (*ALLOBJ) special authority or be enrolled in the system distribution directory to run this command.
• 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, you must have execute (*EXECUTE) authority to the library where the output database file is located.

Parameters

Keyword	Description	Choices	Notes
DLO	Document library object	Single values: *ALL, *SYSOBJNAM, *MAIL Other values (up to 300 repetitions): Character value	Required, Positional 1
SAVFLR	Saved folder	Single values: *ANY, *NONE Other values (up to 300 repetitions): Character value	Optional
RENAME	New object name	Single values: *SAME Other values (up to 300 repetitions): Character value	Optional
RSTFLR	Restore into folder	Character value, *SAME	Optional
DEV	Device	Single values: *SAVF Other values (up to 4 repetitions): Name	Required, Positional 2
SYSOBJNAM	System object name	Values (up to 300 repetitions): Name, *NONE	Optional
VOL	Volume identifier	Single values: *MOUNTED Other values (up to 75 repetitions): Character value	Optional
SEQNBR	Sequence number	Single values: *SEARCH Other values: Element list	Optional
	Element 1: Beginning sequence number	1-16777215
	Element 2: Ending sequence number	1-16777215, *ONLY
ENDOPT	End of media option	*REWIND, *LEAVE, *UNLOAD	Optional
LABEL	Label	Character value, *GEN	Optional
SAVF	Save file	Qualified object name	Optional
	Qualifier 1: Save file	Name
	Qualifier 2: Library	Name, *LIBL, *CURLIB
OPTFILE	Optical file	Path name, *	Optional
NEWOBJ	Object name generation	*SAME, *NEW	Optional
SAVDATE	Date when saved	Date	Optional
SAVTIME	Time when saved	Time	Optional
ALWOBJDIF	Allow object differences	*NONE, *ALL	Optional
SAVASP	Saved from ASP number	1-32, *ANY	Optional
RSTASP	Restore to ASP number	1-32, *SAVASP	Optional
OUTPUT	Output	*NONE, *PRINT, *OUTFILE	Optional
OUTFILE	File to receive output	Qualified object name	Optional
	Qualifier 1: File to receive output	Name
	Qualifier 2: Library	Name, *LIBL, *CURLIB
OUTMBR	Output member options	Element list	Optional
	Element 1: Member to receive output	Name, *FIRST
	Element 2: Replace or add records	*REPLACE, *ADD

Top

Document library object (DLO)

Specifies the document library objects to be restored.

This is a required parameter.

Single values

*ALL

All documents, folders, and distribution objects (mail) that are saved on media and meet the criteria specified for the Saved folder (SAVFLR) parameter are restored.

*MAIL

All distribution objects and documents that were referred to by a mail log are restored.

*SYSOBJNAM

All documents with the system object names specified for the System object name (SYSOBJNAM) parameter are restored.

Other values (up to 300 repetitions)

document-name

Specify the user-assigned names of the documents to be restored. All documents named must be in the folder specified for the SAVFLR parameter.

Saved folder (SAVFLR)

Specifies the name of the folder on the media from which the documents and folders are restored.

Single values

*ANY

All document library objects that meet the values specified for the Document library object (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 for the DLO parameter.

*NONE

All documents that were saved as documents not in any folder are restored. *NONE is valid for documents only and is valid only when *ALL is specified for the DLO parameter.

Other values (up to 300 repetitions)

folder-name

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

New object name (RENAME)

Specifies the new user-assigned name for the restored document.

Single values

*SAME

The documents are restored with the names they had when they were saved.

Other values (up to 300 repetitions)

document-name

Specify the new user-assigned names that the documents have after being restored. When document names are specified for the Document library object (DLO) parameter, a maximum of 300 user-assigned names can be specified for documents being restored.

Restore into folder (RSTFLR)

Specifies the name of the folder in which the restored folders and documents to be restored will be placed. The folder must exist on the system or when *ALL is specified for the Document library object (DLO) parameter, the saved folder must exist on the media.

*SAME

The folders and documents to be restored are placed into the same folder from which they were saved.

folder-name

Specify the name of the folder where the restored documents and folders are to be placed.

Device (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.

This is a required parameter.

Single values

*SAVF

The restore operation is done using the save file specified for the Save file (SAVF) parameter.

Other values

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 a virtual tape device is used, it must be the only device specified. If you are using more than one tape device (up to a maximum of four), specify the names of the devices in the order in which they are used. When more than one tape volume is to be restored, using more than one tape device permits one tape volume to be rewound while another tape device processes the next tape volume.

System object name (SYSOBJNAM)

Specifies the system object names of the documents to be restored if *SYSOBJNAM is specified for the Document library object (DLO) parameter.

Single values

*NONE

A system object name is not specified.

Other values (up to 300 repetitions)

system-object-name

Specify the system object names of the documents to be restored.

Volume identifier (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.

Single values

*MOUNTED

The objects are restored from the volumes placed in the device specified for the Device (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.

Other values (up to 75 repetitions)

character-value

Specify the identifiers of one or more volumes in the order in which they are placed in a device and used to restore the data.

Sequence number (SEQNBR)

Specifies the sequence numbers of the tape files used for the restore operation.

Note:When restoring document library objects (DLOs) from more than one auxiliary storage pool (ASP), a beginning and ending sequence number must be specified. The beginning and ending sequence numbers were shown in the completion message for the SAVDLO command used to create the tape media files. Or use the Display Tape (DSPTAP) command to find the sequence numbers of the QDOC and QDOCnnnn files, where nnnn is the ASP number.

Single values

*SEARCH

The tape is searched for the first data file with an identifier matching the Label (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 the ENDOPT(*LEAVE) operation), the search begins with the first data file on the volume.

Element 1: Beginning sequence number

1-16777215

Specify the sequence number of the first file used for the restore operation.

Element 2: Ending sequence number

*ONLY

The ending sequence number is the same as the starting sequence number.

1-16777215

Specify the sequence number of the last file used for the restore operation.

End of media option (ENDOPT)

Specifies the operation that is automatically done 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 for 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 (LABEL)

Specifies the file label used to find the file that was written onto the media during the save operation.

*GEN

The system generates the default name of the file label for which to search.

character-value

Specify the file label of the file that contains the document library objects to be restored. A maximum of 17 alphanumeric characters can be used.

Save file (SAVF)

Specifies the save file used to restore the data.

Note: A value must be specified for this parameter if *SAVF is specified for the Device (DEV) parameter.

Qualifier 1: Save file

name

Specify the name of save file to be used.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the thread is used to locate the save file. If no current library entry exists in the library list, the QGPL library is used.

name

Specify the name of the library where the save file is located.

Optical file (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 "Object naming rules" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

*

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.

Object name generation (NEWOBJ)

Specifies whether a new library-assigned name and system object name are generated for the folders and documents that are restored.

*SAME

The library-assigned name and system object name do not change.

*NEW

A new library-assigned name and system object name are generated for each document or folder that is restored.

Date when saved (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 specified 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.

Time when saved (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. Specify 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 the Time when saved (SAVTIME) parameter is not specified, the version of the document library objects to be restored will be the first version found on the volume or the first version found with the specified file label.

This parameter is valid only if the Date when saved (SAVDATE) parameter is specified also.

Allow object differences (ALWOBJDIF)

Specifies whether the following differences encountered during a restore operation are allowed.

• Ownership--the owner of the object on the system is different than the owner of the object from the save operation.
• System object name--the system object name on the system does not match the system object name on the media.
• Authorization list linking--the object is being restored to a system different from 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, you need all object (*ALLOBJ) authority.

*NONE

None of the differences described above are 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 of the differences described above are allowed for the restore operation. An informational message is sent, and the object is restored.

Notes:

• If the owners of the object do not match, the object is restored, but it will keep the ownership and authorities of the object on the system before the restore operation.
• If *ALL is specified on this parameter, *NEW cannot be specified for the Object name generation (NEWOBJ) parameter.
• If you are 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.

Saved from ASP number (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.

Note:When restoring document library objects (DLOs) from more than one ASP, the sequence number (SEQNBR) parameter must be specified.

1-32

Specify the number of the ASP from which documents and folders are restored.

Restore to ASP number (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.

1-32

Specify the number of the ASP in which restored documents and folders are placed.

Output (OUTPUT)

Specifies whether a listing that shows information about the status of the objects 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.

*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 for the File to receive output (OUTFILE) parameter.

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

File to receive output (OUTFILE)

Specifies the qualified name of the database file to which the information about the object is directed when *OUTFILE is specified for the Output (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.

Qualifier 1: File to receive output

name

Specify the name of the database file to which output from the command is directed. If this file does not exist, it is created in the specified library.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the thread is used to locate the file. If no library is specified as the current library for the job, the QGPL library is used.

name

Specify the name of the library to be searched.

Output member options (OUTMBR)

Specifies the name of the database file member to which the output is directed when *OUTFILE is specified for the Output (OUTPUT) parameter.

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 for the File to receive output (OUTFILE) parameter.

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, you can add records to the end of the existing member or clear the existing member and add the records.

Element 2: Replace or add records

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

Examples

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(TAP01)  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

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