Restore Object (QsrRestore) API
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Error code | I/O | Char(*) |
Service Program Name: QSRLIB01
Default Public Authority: *USE
Threadsafe: No
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 Save-while-active object locking rules in the Backing up your system topic collection for information about object locking for the Restore Object (RST) command.
- Authority
- See Authority required for objects used by commands in the Security reference topic collection for 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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of variable length records |
| 4 | 4 | BINARY(4) | Offset to first record |
| 8 | 8 | CHAR(8) | Reserved |
| Note: These fields repeat for each variable length record. | |||
| BINARY(4) | Key | ||
| BINARY(4) | Offset to next record | ||
| CHAR(8) | Reserved | ||
| CHAR(*) | Data | ||
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 23.
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 |
| 20 | CHAR(1) | Rebuild mounted file system | RBDMFS |
| 21 | CHAR(1) | Private authorities | PVTAUT |
| 22 | CHAR(32) | Starting position in file | POSITION |
| 23 |
CHAR(1) | Start journaling | STRJRN |
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:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: This field repeats for each allow object difference value. | |||
| CHAR(1) | Allow object difference | ||
Number in array. The number of allow object difference values. The possible values are:
| 1-3 | The number of allow object difference values. |
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:
| 0 | Parent directories will not be created if they do not exist. Diagnostic message CPD375B will be sent and the object will not be restored. (*NO) |
| 1 | The restore will create parent directories if they do not exist. The directories created by the restore will have *EXCLUDE public authority and will be owned by the user profile specified using key 19 - Parent directory owner. (*YES) |
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| BINARY(4) | Offset to first device path name | ||
| Note: These fields repeat for each device name. | |||
| BINARY(4) | Offset to next device path name | ||
| CHAR(12) | Reserved | ||
| CHAR(*) | Device path name | ||
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 about 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 Saving to multiple devices to reduce your save window in the Backing up your system topic collection and Create Media Definition (QSRCRTMD, QsrCreateMediaDefinition) API. |
Number in array. The number of devices used during the restore operation. The possible value is:
| 1-4 | The number of devices used during the restore operation. |
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:
| n | The offset from the beginning of the user space to the first device path name in the list. |
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:
| n | The offset from the beginning of the user space to the next device path name in the list. If the current device path name is the last device path name in the array, this value should be 0. |
Reserved. Reserved. The possible value is:
| x'00' | This field should contain x'00's. |
Directory subtree. Whether the directory subtrees are included in the restore operation. The default is 1. The possible values are:
| 0 | No subtrees are included in the restore operation. If a directory matches the object name pattern specified, the objects in the directory are included. If the directory has subdirectories, neither the subdirectories nor the objects in the subdirectories are included. (*NONE) |
| 1 | The entire subtree of each directory that matches the object name pattern is included. The subtree includes all subdirectories and the objects within those subdirectories. (*ALL) |
| 2 | The objects in the first level of each directory that matches the object name pattern are included. The subdirectories of each matching directory are included, but the objects in the subdirectories are not included. (*DIR) |
| 3 | Only the objects that exactly match the object name pattern are included. If the object name pattern specifies a directory, objects in the directory are not included. (*OBJ) |
| 4 | The objects that match the object name pattern are processed along with the storage for related objects. Objects that are saved using this value can only be restored using SUBTREE(*STG). (*STG) |
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:
| 0 | The tape is automatically rewound, but not unloaded, after the operation ends. (*REWIND) |
| 1 | The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive. (*LEAVE) |
| 2 | The tape is automatically rewound and unloaded after the operation ends. Some optical devices eject the volume after the operation ends. (*UNLOAD) |
Force object conversion. Whether to convert user objects to the format required for use in the current version of the operating system or to be compatible with the current machine.
Notes:
- This key applies only to user objects of the *MODULE, *PGM, *SRVPGM, and *SQLPKG object types.
- An object must have creation data (either observable or unobservable) to be converted.
- If an object needs to be converted (because it is formatted for an earlier version of the operating system or is incompatible with the current machine), but is not converted during this restore operation, the object is automatically converted the first time it is used.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| CHAR(1) | Force conversion | ||
| CHAR(1) | Objects to convert | ||
Force conversion. Whether objects should be converted on the restore operation. The default is 2. The possible values are:
| 0 | The objects are not converted during the restore
operation. (*NO)
Note: If this value is specified, then the QFRCCVNRST system value must have a value of either 0 or 1. |
| 1 | The objects are converted during the restore
operation. (*YES)
Notes:
|
| 2 | The objects are converted based on the value of the QFRCCVNRST system value. (*SYSVAL) |
Objects to convert. Which objects should be converted on the restore operation. The default is 2. The possible values are:
| 1 | All objects are converted regardless of their current format and machine compatibility. Even if the objects are compatible and in the current format, they are converted again. However, if the objects do not have all creation data (either observable or unobservable), the objects cannot be converted and are not restored. (*ALL) |
| 2 | The objects are converted only if they require conversion to be used by the current operating system or to be compatible with the current machine. If the objects do not have all creation data (either observable or unobservable), the objects cannot be converted and are not restored. (*RQD) |
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:
| 0 | The restored object will have the object ID it had when it was saved. (*SAVED) |
| 1 | The restored object may have a new object ID generated by the system. If the object is being restored as a new object, a new object ID will be given to the restored object. If an object with the same name as the object from the media already exists on the system, the object ID of the restored object will be the same as the object ID of the object on the system before the restore. (*SYS) |
Label. The file identifier of the media to be used for the restore operation. The default is *SEARCH. The possible values are:
| *SEARCH | The file label for which to search is determined by the system. |
| file-identifier | The identifier (maximum of 17 characters) of the tape file used for the restore operation. |
Name pattern. Specifies a pattern to be used to include or omit objects.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| BINARY(4) | Offset to first pattern name | ||
| Note: These fields repeat for each pattern name. | |||
| BINARY(4) | Offset to next pattern name | ||
| CHAR(1) | Option | ||
| CHAR(11) | Reserved | ||
| CHAR(*) | Pattern name | ||
Number in array. The number of pattern names. The possible value is:
| 1-n | The number of pattern names. |
Pattern name. Specifies a pattern name. The possible value is:
| pattern-name | The object name or pattern that can match many names. |
Offset to first pattern name. The offset from the beginning of the user space to the first pattern name. The possible value is:
| n | The offset from the beginning of the user space to the first pattern name. |
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:
| n | The offset from the beginning of the user space to the next pattern name in the list. If the current pattern name is the last pattern in the array, this value should be 0. |
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:
| 0 | All objects which are included by the OBJ parameter are included in the restore except those objects which match the PATTERN parameter. This value overrides objects that are included with option 1 and is intended to be used to omit a subset of a previously selected patterns. (*OMIT) |
| 1 | Only objects which are included by the OBJ parameter and match the PATTERN parameter are included in the restore, unless overridden by an omit specification. (*INCLUDE) |
Reserved Reserved. The possible value is:
| x'00' | This field should contain x'00's. |
Object path name. The path name of the object to restore. You can specify a pattern for this path name.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| BINARY(4) | Offset to first object path name | ||
| Note: These fields repeat for each object path name. | |||
| BINARY(4) | Offset to next object | ||
| BINARY(4) | Offset to new object path name | ||
| CHAR(1) | Option | ||
| CHAR(7) | Reserved | ||
| CHAR(*) | Object path name | ||
| CHAR(*) | New 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 about this structure, see Path name format. The possible value is:
| path-name | The path name with which to restore the object. If a pattern is specified for the object path name field, the new path name must be an existing directory in which to restore any objects that match the pattern. If an object name is specified in the object path name field, each component in the new path name must exist with the exception of the last component. If the object described in the last component does not exist, it will be restored as new. |
Number in array. The number of object path names to be restored. The possible value is:
| 1-300 | The number of object path names to be restored. |
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 about this structure, see Path name format. The possible value is:
| path-name | The path name or pattern that can match many names. If 0 is specified for the new name option, each component in the path name must exist with the exception of the last component. The name in the last component is restored as new if it does not exist. |
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:
| n | The offset from the beginning of the user space to the first object path name. |
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:
| 0 | There is not a new object path name. The object will be restored to the same name with which it was saved. |
| n | The offset from the beginning of the user space to the new object path name. |
Offset to next object. The offset from the beginning of the user space to the next object in the list. The possible value is:
| n | The offset from the beginning of the user space to the next object in the list. If the current object is the last object in the array, this value should be 0. |
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:
| 0 | The objects that match the object name pattern are not restored. This value overrides the objects that are included with option 1 and is intended to be used to omit a subset of a previously selected pattern. (*OMIT) |
| 1 | The objects that match the object name pattern are restored, unless overridden by an omit specification. (*INCLUDE) |
Reserved Reserved. The possible value is:
| x'00' | This field should contain x'00's. |
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 about this structure, see Path name format. The default is '*'. The possible values are:
| '*' | 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 | The path name of the optical file that is used for the restore operation, beginning with the root directory of the volume. |
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:
| 0 | All of the specified objects are restored, whether or not they already exist on the system. (*ALL) |
| 1 | Objects are restored only if they do not already exist on the system. (*NEW) |
| 2 | Objects are restored only if they already exist on the system. (*OLD) |
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| CHAR(1) | Option | ||
| CHAR(1) | Type of output information | ||
| CHAR(14) | Reserved | ||
| CHAR(*) | Output path name | ||
Option. Whether a list of information about the restored objects is created. The default is 0. The possible values are:
| 0 | No output is created. (*NONE) |
| 1 | The output is printed with the job's spooled output. (*PRINT) |
| 2 | The output is directed to an existing stream file or user space specified by the output path name. |
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 about this structure, see Path name format. The possible value is:
| path-name | The path name of the existing stream file or user space to which the output of the command is directed. |
Reserved Reserved. The possible value is:
| x'00' | This field should contain x'00's. |
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:
| 0 | The file will contain information about the command, and an entry for each directory. (*SUMMARY) |
| 1 | The file will contain information about the command, an entry for each directory, and an entry for each object that was not successfully restored. (*ERR) |
| 2 | The file will contain information about the command, an entry for each directory, an entry for each object that was successfully restored, and an entry for each object that was not successfully restored. (*ALL) |
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) |
Private authorities. Whether to restore private authorities for the objects that are restored. The default is 0. The possible values are:
| 0 | No private authorities are restored. (*NO) |
| 1 | Private authorities are restored with the objects. Objects will be restored only from save operations that specified that private authorities should be saved with the objects. To specify this value, you need all object (*ALLOBJ) special authority. (*YES) |
Rebuild mounted file system. Which mounted file systems should be rebuilt during the restore.
Note: You must have save system (*SAVSYS) or all object (*ALLOBJ) special authority to specify a value other than *NONE for this parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: These fields repeat for each rebuild mounted file system value. | |||
| CHAR(1) | Rebuild mounted file system | ||
Number in array. The number of rebuild mounted file system values. The possible value is 1.
Rebuild mounted file system. Which mounted file systems should be rebuilt during the restore. The default is 0. The possible values are:
| 0 | Mounted file systems will not be rebuilt during the restore. Objects that were saved from a mounted file system will be restored to the file system that contains the directory being restored into. (*NONE) |
| 1 | Mounted user-defined file systems will be
rebuilt during the restore. A user-defined file system will be created
if it does not exist and then will be mounted over the same directory
it was mounted over during the save.
If a user-defined file system is created during the restore, the attributes will be set based on the saved user-defined file system including any user-defined file system specific attributes such as 'Case sensitivity' or 'Default file format'. If the user-defined file system exists before the restore, no attributes will be changed. If there is an error creating or mounting a user-defined file system, none of the objects that were saved from the mounted user-defined file system will be restored. (*UDFS) Note:If it does not exist before the restore, the directory that is being mounted over will be created with attributes and authorities copied from the directory being restored into. This could cause problems when the user-defined file system is unmounted and then remounted, if the authorities are not sufficient to allow the mount to occur. |
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:
| date | The date the objects were saved, in the format
CYYMMDD:
|
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:
- This key is valid only if the save date key is specified.
- This key is ignored when the sequence number key is specified.
The possible value is:
| time | The time the objects were saved in the format
HHMMSS:
|
Sequence number. The tape file sequence number to be used. The default is -1. The possible values are:
| -1 | The tape volume is searched for the next file that contains any of the specified objects. (*SEARCH) |
| 1-16777215 | The sequence number of the file. |
Start journaling. Whether to start journaling for new objects
that are restored. Note: Journal information that was saved will be restored
for new objects whether journaling is started or not.
Journaling will not be changed for existing objects.
The default is 1. The possible values are:
| 0 | Journaling will not be started for the objects that are restored. (*NO) |
| 1 | Journaling will be started for new objects that were being journaled when they were saved. (*YES) |
Starting position in file. The position in the tape file at which to start searching for the data to restore. Specifying a value may improve the performance of the restore operation if you only want to restore data that is far from the beginning of the tape file. The starting position of each object was returned in the output of the save operation. This field must contain 32 hexadecimal characters (0-9 and A-F). The default value is a string of character zeros, which starts searching for the data to restore at the beginning of the tape file.
System. Whether to process objects that exist on the local system or remote systems. The default is 0. The possible values are:
| 0 | Only local objects are processed. (*LCL) |
| 1 | Only remote objects are processed. (*RMT) |
| 2 | Both local and remote objects are processed. (*ALL) |
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| BINARY(4) | Length of each volume identifier | ||
| BINARY(4) | Offset to first volume identifier | ||
| Note: These fields repeat for each volume identifier | |||
| BINARY(4) | Offset to next volume identifier | ||
| CHAR(*) | Volume identifier | ||
Length of each volume identifier. The character length of each of the volume identifiers. The possible value follows:
| n | The size of a single volume identifier. The maximum size of a tape volume identifier is 6 characters. The maximum size of an optical volume identifier is 32 characters. If a volume identifier larger than the maximum size is entered for this key, it is truncated to the maximum size. |
Number in array. The number of volume identifiers that are used during the restore operation. The default is 0. The possible values are:
| 0 | The volume currently placed in the device is
used. If 0 is specified for a tape media library device, volume identifiers
must be supplied by using the Tape Management exit program during the save or
restore operation. If 0 is specified, the length of each volume identifier
value is ignored. (*MOUNTED)
Note: This value cannot be specified for an optical media library device. |
| 1-75 | The number of volume identifiers used during the restore operation. |
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:
| n | The offset from the beginning of the user space to the first volume identifier in the list. |
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:
| n | The offset from the beginning of the user space to the next volume identifier in the list. If the current volume identifier is the last volume identifier in the array, this value should be 0. |
Volume identifier. The volume identifiers of one or more volumes to be used. The possible value is:
| Volume identifier | The volume identifiers of one or more volumes to be used. |
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.
| If you specify... | ...must be specified |
|---|---|
| Device = optical library device | Volume identifier |
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
| Message ID | Error Message Text |
|---|---|
| CPF0001 E | Error found on &1 command. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3700 E | All CPF37xx messages could be signalled. xx is from 01 to FF. |
| CPF3800 E | All CPF38xx messages could be signalled. xx is from 01 to FF. |
| CPF3C31 E | Object type &1 is not valid. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C83 E | Key &1 not allowed with value specified for key &2. |
| CPF3C84 E | Key &1 required with value specified for key &2. |
| CPF3C85 E | Value for key &1 not allowed with value for key &2. |
| CPF3C86 E | Required key &1 not specified. |
| CPF3C87 E | Key &1 allows one value with special value. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF5729 E | Not able to allocate object &1. |
| CPF9800 E | All CPF98xx messages could be signaled. xx is from 01 to FF. |
| CPF9999 E | Function check. &1 unmonitored by &2 at statement &5, instruction &3. |
API introduced: V4R3
[ Back to top | Backup and Recovery APIs | APIs by category ]