Restore Object (QsrRestore) API

The Restore Object (QsrRestore) API restores a copy of one or more objects that can be used in the integrated file system.

Authorities and Locks

User Space

User Space Authority

*USE

User Space Library Authority

*EXECUTE

User Space Lock

*EXCLRD

Objects to Be Restored, Created Parent Directories, Devices, and Output

Locking

See the Backup and Recovery book for information on object locking for the Restore Object (RST) command.

Authority

In the iSeries Security Reference book, see the Appendix about authorities required for the Restore Object (RST) command.

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The user space that is to hold all the information for the restore operation. The first 10 characters contain the user space name. The second 10 characters contain the name of the library where the user space is located. See User space format for the format of the information in the user space.

You can use the following special values for the library name. It should be noted, however, that the library name that is actually used is not passed back to the user. Care should be taken when you use these special values to avoid unexpected results.

*CURLIB	The job's current library is used to locate the user space. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list is used to locate the user space.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter

User Space Format

The following defines the format for the information in the user space. For detailed descriptions of the fields in the user space format, see Field Descriptions.

If the length of the data is longer than the key identifier's data length, the data will be truncated at the right. No message will be issued.

If the specified data length is shorter than the key field's defined data length, an error message is returned for binary fields. If the field is a character field, the data is padded with blanks and an error message will not be returned.

Note: This does not apply to keys that allow a list of values to be specified. In these cases, the amount of data read is based on the specified number of entries in the list.

If keys are duplicated in the user space, only the last value for a given key is used for the restore operation.

Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.

Field Descriptions

Data. The data used to specify the value for the given key.

Key. The parameter of the Restore Object (RST) command to specify. See Valid Keys for the list of valid keys.

Offset to first record. The offset from the beginning of the user space to the first variable length record.

Offset to next record. The offset from the beginning of the user space to the next variable length record.

Number of variable length records. The number of variable length records that are passed in the user space. The valid range is from 2 through 19.

Reserved. This field should contain x'00's.

Valid Keys

The following table lists the valid keys for the key field area of the variable length record. For detailed descriptions of the keys, see the Field Descriptions.

Some messages for this API refer to parameters and values of the Restore Object (RST) command. This table can also be used to locate the key names that correspond to the RST command parameters. The field descriptions contain, in addition to detailed descriptions, the corresponding parameter values.

The object path name key and the device path name key are required keys. The other keys are optional.

Key	Type	Field	RST Command Parameter
1	CHAR(*)	Device path name	DEV
2	CHAR(*)	Object path name	OBJ
3	CHAR(1)	Directory subtree	SUBTREE
4	CHAR(1)	System	SYSTEM
5	CHAR(7)	Save date	SAVDATE
6	CHAR(8)	Save time	SAVTIME
7	CHAR(1)	Option	OPTION
8	CHAR(*)	Allow object differences	ALWOBJDIF
9	CHAR(2)	Force object conversion	FRCOBJCVN
10	CHAR(*)	Volume identifier	VOL
11	CHAR(*)	Label	LABEL
12	BINARY(4)	Sequence number	SEQNBR
13	CHAR(1)	End of media option	ENDOPT
14	CHAR(*)	Optical file	OPTFILE
15	CHAR(*)	Output	OUTPUT, INFTYPE
16	CHAR(*)	Object ID	OBJID
17	CHAR(*)	Name pattern	PATTERN
18	CHAR(1)	Create parent directories	CRTPRNDIR
19	CHAR(10)	Parent directory owner	PRNDIROWN

Field Descriptions

The values shown in parentheses are the corresponding values for the RST command parameters.

Allow object differences. Whether differences are allowed between the saved object and the restored object. The differences include:

Number in array. The number of allow object difference values. The possible values are:

Allow object difference. Whether differences are allowed between the saved object and the restored object. The differences include:

• Authorization list: The saved object had an authorization list, and either the object exists on the system but does not have the same authorization list, or the object does not exist and it is being restored to a different system than the save system.

  Note: This key has no effect when the saved object did not have an authorization list. If the object exists, it is restored with the authorization list of the existing object. If it does not exist, it is restored with no authorization list.

• Ownership: The owner of an object on the system is different than the owner of an object from the save operation.
• Primary group: The primary group of an object on the system is different from the primary group of an object from the save operation.

The default is 0. The possible values are:

0	No differences are allowed between the saved object and the restored object. If 0 is specified for the allow object difference field, 1 must be specified for the number in array field. (*NONE) If an object already exists on the system with a different owner or primary group than the saved object, the object is not restored. If the saved object had an authorization list and the object exists on the system but does not have the same authorization list, the object is not restored. If the saved object had an authorization list and the object does not exist and it is being restored to a different system than the save system, the object is restored, but it is not linked to the authorization list, and the public authority is set to *EXCLUDE.
1	All differences are allowed between the saved object and the restored object. If 1 is specified for the allow object difference field, 1 must be specified for the number in array field. (*ALL) If an object already exists on the system with a different owner or primary group than the saved object, the object is restored with the existing values. If the saved object had an authorization list and the object exists on the system but does not have the same authorization list, the object is restored with the authorization list of the existing object. If the saved object had an authorization list and the object does not exist and it is being restored to a different system than the save system, the object is restored and it is linked to the authorization list. If the authorization list does not exist, the public authority of the object is set to *EXCLUDE.
2	Authorization list differences are allowed. (*AUTL) If the saved object had an authorization list and the object exists on the system but does not have the same authorization list, the object is restored with the authorization list of the existing object. If the saved object had an authorization list and the object does not exist and it is being restored to a different system than the save system, the object is restored and it is linked to the authorization list. If the authorization list does not exist, the public authority of the object is set to *EXCLUDE.
3	Ownership differences are allowed. (*OWNER) If an object already exists on the system with a different owner than the saved object, the object is restored with the existing value.
4	Primary group differences are allowed. (*PGP) If an object already exists on the system with a different primary group than the saved object, the object is restored with the existing value.

Create parent directories. Whether parent directories of objects being restored should be created if they do not exist. For example, if object '/a/b/c/file1' is being restored then directories '/a', '/a/b' and '/a/b/c' must exist. This key only applies to "root" (/), QOpenSys and user-defined file systems, it will be ignored for all other file systems. The default is 0. The possible values are:

Note: Other than owner, the parent directory attributes will be set as though the Create Directory (CRTDIR) command had been used to create the parent directory without changing any of the command defaults (the defaults are with respect to the defaults on the shipped command and do not reflect changes that have been made to the command default values).

Device path name. The path name of the device from which the objects are restored.

Device path name. The path name of the device used for the restore operation. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The possible value is:

device-path-name

The path name of the media definition, media library device, optical device, save file, or tape device used to restore the objects. If a media definition, media library device, optical device, or save file path name is specified, it must be the only element in the array. For information about creating and using a media definition, see the Backup and Recovery book and the Create Media Definition (QSRCRTMD, QsrCreateMediaDefinition) API.

Number in array. The number of devices used during the restore operation. The possible value is:

Offset to first device path name. The offset from the beginning of the user space to the first device path name in the list. The possible value is:

Offset to next device path name. The offset from the beginning of the user space to the next device path name in the list. The possible value is:

Reserved. Reserved. The possible value is:

Directory subtree. Whether the directory subtrees are included in the restore operation. The default is 1. The possible values are:

End of media option. The operation that is performed automatically on the tape or optical volume after the restore operation ends. If more than one volume is used, this key applies only to the last volume used; all other volumes are unloaded when the end of the volume is reached. The default is 0.

Note: This parameter is valid only if a tape or optical device name is specified. For optical devices, 2 is the only value supported; 0 and 1 are ignored.

The possible values are:

Force object conversion. Whether to convert user objects to the format required for use in the current version of the operating system.

Note: If an object needs to be converted, but is not converted during the restore operation, the object is automatically converted the first time it is used.

Force conversion. Whether objects should be converted on the restore operation. The default is 2. The possible values are:

Objects to convert. Which objects should be converted on the restore operation. The default is 2. The possible values are:

Object ID. Whether the object ID of the restored object will be the object ID of the object from the save media, the object ID of the object that exists on the system prior to the restore, or a new object ID generated by the system if the object does not exist on the system prior to the restore. The default is 0. The possible values are:

Label. The file identifier of the media to be used for the restore operation. The default is *SEARCH. The possible values are:

Name pattern. Specifies a pattern to be used to include or omit objects.

Number in array. The number of pattern names. The possible value is:

Pattern name. Specifies a pattern name. The possible value is:

Offset to first pattern name. The offset from the beginning of the user space to the first pattern name. The possible value is:

Offset to next pattern name. The offset from the beginning of the user space to the next pattern name in the list. The possible value is:

Option. Whether names that match the pattern should be included or omitted from the restore operation.

Note: The subtree key specifies whether the subtrees are included or omitted.

The possible values are:

Reserved Reserved. The possible value is:

Object path name. The path name of the object to restore. You can specify a pattern for this path name.

New path name. The new path name of the object. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The possible value is:

Number in array. The number of object path names to be restored. The possible value is:

Object path name. The path names of the objects saved on the media. Directory abbreviations (for example, the current directory) are expanded with their current values, not with the values they had at the time of the save operation. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The possible value is:

Offset to first object path name. The offset from the beginning of the user space to the first object path name. The possible value is:

Offset to new object path name. The offset from the beginning of the user space to the new object path name. The possible values are:

Offset to next object. The offset from the beginning of the user space to the next object in the list. The possible value is:

Option. Whether names that match the pattern should be included or omitted from the restore operation. Note that in determining whether the name matches a pattern, relative name patterns are always treated as relative to the current working directory.

Note: The subtree key specifies whether the subtrees are included or omitted.

The possible values are:

Reserved Reserved. The possible value is:

Optical file. The path name of the optical file that is used for the restore operation. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The default is '*'. The possible values are:

Option. Whether to restore objects that already exist on the system or to restore objects that do not already exist on the system. The default is 0. The possible values are:

Output. Whether a list of information about the restored objects is created. The information can be directed to a spooled file, a stream file, or a user space.

Option. Whether a list of information about the restored objects is created. The default is 0. The possible values are:

Output path name. The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, Path name format. The possible value is:

Reserved Reserved. The possible value is:

Type of output information. The type of information that should be directed to the spooled file, stream file, or user space specified for the output key. The possible values are:

Parent directory owner. The name of an existing user profile that will own parent directories that are created by the restore. This key only applies to "root" (/), QOpenSys and user-defined file systems, it will be ignored for all other file systems.. The default is *PARENT. The possible values are:

*PARENT	The owner of the parent directory being created by the restore will be copied from the directory it is being created into. (*PARENT)
name	Specify a user profile to be the owner of any parent directories that are created by the restore. (name)

Save date. The date the objects were saved. If the most recently saved version is the one being restored, or if multiple saved versions reside on the media, specify the date that identifies which version of the objects to restore. If this key is not specified, the restored version of the objects is the first version found. The possible value is:

Save time. The time the objects were saved. If this key is not specified, the version of the objects to be restored is the first version on the volume.

Note:

1. This key is valid only if the save date key is specified.
2. This key is ignored when the sequence number key is specified.

The possible value is:

Sequence number. The tape file sequence number to be used. The default is -1. The possible values are:

System. Whether to process objects that exist on the local system or remote systems. The default is 0. The possible values are:

Volume identifier. The volume identifiers of the volumes, or the cartridge identifier of a tape in a tape media library device, from which data is to be restored. The volumes must be placed in the device in the order specified on this key. After all specified volumes are filled, the restore operation continues on whatever volumes are mounted on the device.

Length of each volume identifier. The character length of each of the volume identifiers. The possible value follows:

Number in array. The number of volume identifiers that are used during the restore operation. The default is 0. The possible values are:

Offset to first volume identifier The offset from the beginning of the user space to the first volume identifier in the list. The possible value is:

Offset to next volume identifier The offset from the beginning of the user space to the next object volume identifier in the list. The possible value is:

Volume identifier. The volume identifiers of one or more volumes to be used. The possible value is:

Dependencies between Keys

The following two tables list the dependencies between the different keys. If the dependency pertains only to a certain value, then that value is also shown (key = n, where n is the value). Otherwise, if the dependency is true for all values of the key, then only the name of the key is given.

The following table lists the conditions where specifying a certain key forces the use of another key.

The following table lists the conditions where specifying a certain key excludes the user from using another key or a particular value of that key.

If you specify...	...cannot be specified
Create parent directories = 0	Parent directory owner
Device = media definition	Optical file Sequence number Volume identifier
Device = optical device	Label Sequence number
Device = save file	End of media option Label Optical file Sequence number Volume identifier
Device = tape device	Optical file

Relationship to RST Command

Because of the relationship between the QsrRestore API and the RST command, the following situations should be noted:

• Message text: Several messages produced by this API refer to parameters or values of the RST command (for example, *SEARCH). To determine which key a given parameter corresponds to, see Valid Keys. To determine which key value a given parameter value corresponds to, see Field Descriptions.
• Command type: The command type listed for the API on headings of displays and print files is QsrRestore for integrated file system objects. If QsrRestore is used to restore objects in libraries or document library objects (DLOs), the generated output indicates that the corresponding library or DLO command generated the media.

Error Messages