Restore Object List (QSRRSTO) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Restore Object List (QSRRSTO) API restores a list of objects or spooled files specified by the user. The list of objects, as well as any additional information needed for the restore operation, is specified by the user in a user space.
Authorities and Locks
- User Space
-
- User Space Authority
- *USE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *SHRNUP
- Objects to Be Restored
The following authorities are needed if the user does not have save system (*SAVSYS) special authority. To allow any object differences or to restore private authorities, you need all object (*ALLOBJ) special authority. To specify a defer ID, you need *SAVSYS special authority. -
- Object Authority
- *OBJEXIST
- Library Authority
- *EXECUTE, *READ, and *ADD
- Object Lock
- *EXCL
- Library Lock
- *SHRUPD
- Spooled Files to Be Restored
If the user has save system (*SAVSYS) special authority, the following authorities are not needed. -
- Output Queue Authority
- *OBJEXIST
- Output Queue Library Authority
- *EXECUTE
- Output Queue Lock
- *EXCLRD
Note: Additional authority may be needed to change spooled file attributes. See New Attributes Format for more information.
- Devices
-
- Save File Authority
- *USE
- Save File Library Authority
- *EXECUTE
- Save File Lock
- *EXCLRD
- Tape or Optical Authority
- *USE
- Tape or Optical Lock
- *EXCL
- Media Library Device Lock
- *SHRUPD
- Media Definition Authority
- *USE
- Media Definition Library Authority
- *EXECUTE
- Media Definition Lock
- *EXCLRD
- Auxiliary Storage Pool (ASP)
- *USE
- Output Files
-
- Output File Lock
- *SHRRD
- If the output file does not exist:
-
- Output File Library Authority
- *READ and *ADD
- If the output file exists and a new member will be added:
-
- Output File Authority
- *OBJMGT, *OBJOPR, and *ADD
- Output File Library Authority
- *EXECUTE and *ADD
- If the output file exists and an existing member will be appended:
-
- Output File Authority
- *OBJMGT and *ADD
- Output File Library Authority
- *EXECUTE
- If the output file exists and an existing member will be replaced:
-
- Output File Authority
- *OBJMGT, *OBJOPR, *ADD, and *DLT
- Output File Library Authority
- *EXECUTE
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 using 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 |
| Note: These fields repeat for each variable length record. | |||
| BINARY(4) | Length of variable length record | ||
| BINARY(4) | Key | ||
| BINARY(4) | Length of data | ||
| CHAR(*) | Data | ||
If you specify a data length that is longer than the key field's defined data length, the data is truncated at the right. No error message is returned.
If you specify a data length that 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.
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.
It is recommended, but not required, to align each variable length record on a 4-byte boundary. That is, you should make the length of each variable length record a multiple of 4, even if the data length is not a multiple of 4.
Field Descriptions
Data. The data used to specify the value for the given key.Key. The parameter of the Restore Object (RSTOBJ) command to specify. See Valid Keys for the list of valid keys.
Length of data. The length of the data used to specify the value for the given parameter.
Length of variable length record. The length of the 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 32.
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 Field Descriptions.Some messages for this API refer to parameters and values of the Restore Object (RSTOBJ) command. This table can also be used to locate the key names that correspond to the RSTOBJ command parameters. The field descriptions contain, in addition to detailed descriptions, the corresponding parameter values.
The library key and the device key are required keys. The other keys are optional.
| Key | Type | Field | RSTOBJ Command Parameter |
|---|---|---|---|
| 1 | CHAR(*) | Object information | OBJ, OBJTYPE |
| 2 | CHAR(*) | Saved library | SAVLIB |
| 3 | CHAR(*) | Device | DEV |
| 4 | CHAR(20) | Save file | SAVF |
| 6 | CHAR(*) | Volume identifier | VOL |
| 7 | BINARY(4) | Sequence number | SEQNBR |
| 8 | CHAR(*) | Label | LABEL |
| 10 | CHAR(1) | End of media option | ENDOPT |
| 17 | CHAR(*) | File member | FILEMBR |
| 23 | CHAR(1) | Output | OUTPUT |
| 24 | CHAR(20) | Qualified output file | OUTFILE |
| 25 | CHAR(11) | Output member | OUTMBR |
| 26 | CHAR(1) | Type of output information | INFTYPE |
| 27 | CHAR(*) | Optical file | OPTFILE |
| 29 | CHAR(*) | Omit libraries | OMITLIB |
| 30 | CHAR(*) | Omit object information | OMITOBJ |
| 31 | CHAR(20) | Media definition | MEDDFN |
| 35 | CHAR(*) | Spooled file data | SPLFDTA |
| 36 | CHAR(1) | Option | OPTION |
| 37 | CHAR(1) | Database member option | MBROPT |
| 38 | CHAR(7) | Save date | SAVDATE |
| 39 | CHAR(6) | Save time | SAVTIME |
| 40 | CHAR(*) | Allow object differences | ALWOBJDIF |
| 41 | CHAR(2) | Force object conversion | FRCOBJCVN |
| 42 | CHAR(10) | Restore to library | RSTLIB |
| 43 | CHAR(10) | Restore to ASP device | RSTASPDEV |
| 44 | BINARY(4) | Restore to ASP number | RSTASP |
| 47 | CHAR(1) | Private authorities | PVTAUT |
| 48 | CHAR(10) | Defer ID | DFRID |
| 49 | CHAR(32) | Starting position in file | POSITION |
| 50 | CHAR(1) | Start journaling | STRJRN |
| 51 | CHAR(*) | Object selection list | SELECT |
Field Descriptions
The values shown in parentheses are the corresponding values for the RSTOBJ command parameters.
Allow object differences. Whether differences are allowed between the saved objects and the restored objects. The default is a single value of 0. For the format of this key, see Allow Object Differences Key Format.
Database member option. Which members are restored for database files that exist on the system. The default is 4. The possible values are:
| 1 | All the members in the saved file are restored. (*ALL) |
| 2 | Only the members in the saved file that do not exist in the current version of the file on the system are restored. (*NEW) |
| 3 | Only the members in the saved file that do exist in the current version of the file on the system are restored. (*OLD) |
| 4 | The saved members are restored if the list of the members where they exist match, member for member, the lists of the current system version. (*MATCH) |
Defer ID. An identifier that specifies to defer the restore or the start journal requests for objects that depend on other objects that are not yet available. To complete the restore or start journal requests for deferred objects, restore the objects that they depend on, and specify the same defer ID. If any objects remain deferred when the other objects are available, use the Restore Deferred Objects (RSTDFROBJ) command, and specify the same defer ID. This key allows you to restore all objects in a set of libraries when the libraries with dependent objects are restored before the libraries with the objects they depend on.
Deferred objects include:
- Logical files when based-on files are missing. A deferred logical file does not exist on the system until the restore is complete.
- SQL materialized query tables (MQTs) when based-on files are missing. A deferred MQT exists on the system, but any functions that are performed on the MQT that require access to the based-on files will fail.
- Start journal requests for file (*FILE), data area (*DTAARA), data queue (*DTAQ), and library (*LIB) objects when journals are missing. When deferred objects are processed, journaling is started if the journals are available.
Note: If the following conditions are true, the restore of a deferred object may be completed automatically when the objects it depends on are restored:
- The deferred object is restored to the same library from which it was saved.
- The same defer ID is specified for the restore operations for both the deferred object and the objects it depends on.
The default is *NONE. The possible values are:
| *NONE | Objects will not be deferred if they depend on other objects that are not available. |
| Name | An identifier to defer the restore of objects that depend on other objects that are not yet available. You need save system (*SAVSYS) special authority to specify a name. |
Device. The names of the devices used for the restore operation. The device must already be known on the system by a device description. For the format of this key, see Device Key Format.
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) |
File member. A list of the database files and their members that are to be restored. Each database file specified here must also be specified in the list of objects to be restored. If this key is not specified, the default of *ALL will be used for both the file name and the member name. For the format of this key, see File Member Key Format.
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, when the objects are restored. The default is 2 (*SYSVAL). For the format of this key, see Force Object Conversion Key Format.
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.
Label. The name that identifies the data file on the tape. Although the label key is defined as CHAR(*), the maximum length of a label is currently 17. If the length of data field is specified as more than 17, the label is truncated such that only the first 17 characters are used. The default is *SAVLIB.
| *SAVLIB | The file label is the name of the library specified for the saved library key. |
| Data file identifier | The data file identifier of the data file used. This option is valid only for a single-library restore operation. |
Media definition. The name and library of the media definition that identifies the devices and media used to contain the restored data. 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. The first 10 characters contain the media definition name; the second 10 characters contain the library in which the media definition is located.
You can use these special values for the library name:
| *CURLIB | The job's current library is used to locate the media definition. If no library is specified as the current library for the job, the QGPL library is used. |
| *LIBL | The library list. |
Object information. A list of the name and type of the objects to be restored. If *ALL is specified for the object name and object type, the list cannot contain other entries. The default for both the object name and the object type is *ALL. For the format of this key, see Object Information Key Format.
Object selection list. A list of the selection criteria for the objects to be restored. You can select from the objects specified for the object information and saved library keys. For the format of this field, see Object Selection List Format.
Omit libraries. A list of the libraries to be omitted from the restore operation. The default is *NONE. For the format of this key, see Omit Library Key Format.
Omit object information. A list of the name and type of the objects and library to be omitted from the restore operation. If *ALL is specified for the object name and object type, the list cannot contain other entries. The default for both the object name and the object type is *ALL. For the format of this key, see Omit Object Information Key Format.
Optical file. The name that identifies the file on the optical volume. Although the optical file is defined as CHAR(*), the maximum length of an optical file name is currently 256 characters. If the length of data field is specified as more than 256 characters, the name is truncated such that only the first 256 characters are used. The default is '*'. The possible values are:
| '*' | The system generates an optical file name in the root directory of the optical volume. |
| 'Optical-directory-path-name/*' | The system generates an optical file name in the specified directory of the optical volume. |
| 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. Which objects are restored. The default is 1. The possible values are:
| 1 | All the objects in the saved library are restored. (*ALL) |
| 2 | Only the objects in the saved library that do not exist in the current version of the library on the system are restored. (*NEW) |
| 3 | Only the objects in the saved library that do exist in the current version of the library on the system are restored. (*OLD) |
| 4 | Only the objects in the saved library that do exist in the current version of the library on the system with their storage freed are restored. (*FREE) |
Output. Whether a list of information about the restored objects is created. The default is 0. The possible values are:
| 0 | No output listing is created. (*NONE) |
| 1 | The output is printed with the job's spooled output. (*PRINT) |
| 2 | The output is directed to the database file specified with the output file key. (*OUTFILE) |
Output member. The name of the database file member used to save the object information. This field also determines whether to replace or add the data if the member already exists. The defaults are *FIRST for the output member name field and 0 for the option field. For the format of this key, see Output Member Key Format.
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) |
Qualified output file. The qualified name of the database file to which the information about the objects is directed. This key is required only if the output key is set to 2. The first 10 characters contain the output file name; the second 10 characters contain the output file library. The possible values for output file library are:
| *CURLIB | The job's current library is used to locate the output file. 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 output file. |
| Library name | The name of the library where the output file is located. |
Restore to ASP device. The name of the auxiliary storage pool (ASP) device to which objects are restored. The default is *SAVASPDEV. The possible values are:
| *SAVASPDEV | The data is restored to the independent ASP from which it was saved. |
| ASP device name | The name of the independent ASP where the data will be restored. |
Restore to ASP number. The number of the auxiliary storage pool (ASP) to which objects are restored. The default is 0. The possible values are:
| 0 | The data is restored to the ASP from which it was saved. (*SAVASP) |
| 1-32 | The number of the ASP where the data will be restored. |
Restore to library. The name of the library to which objects are restored. The default is *SAVLIB. The possible values are:
| *SAVLIB | The data is restored to library from which it was saved. |
| Library name | The name of the library where the data will be restored. |
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 file. The name and library of the save file that contains the saved data. The first 10 characters contain the save file name; the second 10 characters contain the library where the save file is located.
You can use these special values for the library name:
| *CURLIB | The job's current library is used to locate the save file. If no library is specified as the current library for the job, the QGPL library is used. |
| *LIBL | The library list. |
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:
|
Saved library. A list of libraries that contain the saved objects. If more than one library is specified, *ALL must be the only object name specified (object information key) and the device cannot be *SAVF. For the format of this key, see Saved Library Key Format.
Sequence number. The sequence number to use for the restore operation when tape is used. The default is -1. The possible values are:
| -1 | The restore operation searches the tape volume for the file to be restored. (*SEARCH) |
| 1-16777215 | The sequence number of the file to be used for the restore operation. |
Spooled file data. A description of spooled file data to be restored. The default is new spooled file data; for each output queue that is restored, spooled file data that was saved with the output queue is restored, if it does not already exist on the system. For the format of this key, see Spooled File Data Key Format.
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.
Type of output information. The type of information that is printed or directed to the output database file. The default is 0. The possible values are:
| 0 | The list contains an entry for each object requested to be restored. (*OBJ) |
| 2 | The list contains an entry for each object, database file member, and spooled file requested to be restored. (*MBR) |
Volume identifier. The volume identifiers of the tape volumes or optical volumes from which the object data is to be restored. The volume identifiers must be entered in the order in which the data was saved. The default is *MOUNTED. For the format of this field, see Volume Identifier Format.
Allow Object Differences Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number in array |
| Note: This field repeats for each allow object difference value. | |||
| CHAR(1) | Allow object difference | ||
Field Descriptions
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.
- File level id: The creation date and time of the database file on the system does not match the creation date and time of the file that was saved.
- Member level id: The creation date and time of the database file member on the system does not match the creation date and time of the member that was saved.
- 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 than the primary group of an object from the save operation.
Note: To specify any value other than 0, you need all object (*ALLOBJ) special authority.
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 file level id, member level id, 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. If a database file already exists on the system with a different file level id than the saved object, the existing file is renamed and the saved version of the file is restored If a database file already exists on the system with a different member level id than the saved object, the existing member is renamed and the saved version of the member is restored |
| 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. |
| 5 | File level id and member level id
differences are allowed. (*FILELVL)
If a physical file already exists on the system with a different file level id or member level id than the saved object, but it has the same format level id as the saved object, the data is restored to the existing file. |
| 6 | All differences are allowed between the saved
object and the restored object. If 6 is specified for the allow object
difference field, 1 must be specified for the number in array field. (*COMPATIBLE)
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. If a physical file already exists on the system with a different file level id or member level id than the saved object, but it has the same format level id as the saved object, the data is restored to the existing file. |
Number in array. The number of allow object difference values. The possible values are 1 through 4.
Device Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: This field repeats for each device name. | |||
| CHAR(10) | Device name | ||
Field Descriptions
Device name. The name of the device used for the restore operation. The possible values for each element of the array are:
| *SAVF | The restore operation is done using the save file specified by the save file key. If specified, it must be the only element in the array. |
| *MEDDFN | The restore operation is done by using the devices and media that are identified in the media definition, which is specified by the media definition key. If specified, it must be the only element in the array. |
| Media library device name | The name of the media library device used for the restore operation. If specified, it must be the only element in the array. |
| Optical device name | The name of the optical device used for the restore operation. If specified, it must be the only element in the array. |
| Tape device name | The name of the tape device used for the restore operation. A maximum of four tape devices may be used. They must be specified in the order in which they should be used. |
Number in array. The number of devices to be used during the restore operation. The possible values are 1 through 4.
File Member Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: These fields repeat for each file. | |||
| CHAR(10) | File name | ||
| BINARY(4) | Number of members< | ||
| Note: This field repeats for each member associated with the given file. | |||
| CHAR(10) | Member | ||
Field Descriptions
File name. The name of the file being restored. The possible values are:
| *ALL | The list of member names that follow this value applies to all files indicated in the list of objects to restore. If *ALL is specified for the file name, it must be the only file name in the list. |
| Database file name | The name of the database file from which the listed members are restored. |
Member. The name of the member to restore. The possible values are:
| *ALL | All members are restored from the specified file. If *ALL is specified for member name, it must be the only member name for that file. |
| *NONE | No members are restored from the specified file. Only the file description is restored. |
| Member name | The name of the member to restore. It may be either a simple name or a generic name. |
Number in array. The number of file and member structures used during the restore operation. The possible values are 1 through 50.
Number of members. The number of member names for the given file name. Possible values are 1 through 50.
Force Object Conversion Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Convert during restore |
| 1 | 1 | CHAR(1) | Objects to convert |
Field Descriptions
Convert during restore. Whether objects should be converted on the restore operation. 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 Information Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: These fields repeat for each object name. | |||
| CHAR(10) | Object name | ||
| CHAR(10) | Object type | ||
Field Descriptions
Number in array. The number of objects that are specified for this key. There is no limit for the number in array field. The total amount of information in the user space, however, cannot exceed 16MB.Object name. The name of the object that is to be restored. The possible values are:
| *ALL | All the objects in the specified libraries, depending on the values specified for object type |
| Object name | Either a simple name or a generic name |
Object type. The type of the object that is to be restored. The possible values are:
| *ALL | All objects with the specified object name that are valid types for the RSTOBJ command on the current release of the system. |
| Object type | A valid type for the RSTOBJ command on the current release of the system |
Object Selection List Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| BINARY(4) | Offset to first object selection list entry | ||
| Note: These fields repeat for each object selection list entry. | |||
| BINARY(4) | Length of object selection list entry | ||
| BINARY(4) | Offset to next object selection list entry | ||
| BINARY(4) | Include or omit | ||
| CHAR(10) | Object name | ||
| CHAR(10) | Library name | ||
| CHAR(10) | Object type | ||
| CHAR(10) | Object attribute | ||
| CHAR(10) | File member | ||
Field Descriptions
File member. The database file members to select. If *ALL is specified, the selected objects are included or omitted. If any value other than *ALL is specified, the File member key cannot be specified. The selected objects are included, even if the objects are not database files. If the objects selected are database files, the file members selected are included or omitted. The default value is *ALL. The possible values are:
| *ALL | All file members are selected. For an *OMIT specification, the selected file or object is also omitted. |
| *ALLMBR | All file members are selected. For an *OMIT specification, the selected file or object is included and all file members are omitted. |
| Member name | Either a simple name or a generic name The selected file or object is included even if it does not contain the specified members. |
Include or omit. Whether the objects selected by this entry are included or omitted from the restore operation. Omit takes precedence over include. The possible values are:
| 0 | Objects that match all of the values specified in the selection list entry are omitted from the restore operation. |
| 1 | Objects that match all of the values specified in the selection list entry are included in the restore operation, unless another entry omits them. |
Length of object selection list entry. The length of the object selection list entry information. The possible values are:
| 22 | The selection list entry ends with the object name field. |
| 32 | The selection list entry ends with the library name field. |
| 42 | The selection list entry ends with the object type field. |
| 52 | The selection list entry ends with the object attribute field. |
| 62 | The selection list entry ends with the file member field. |
Library name. The name of the library that contains the objects. The default value is *ALL. The possible values are:
| *ALL | All library names specified for the library key are selected. |
| Library name | Either a simple name or a generic name |
Object attribute. The attribute of the object that is to be restored. The default value is *ALL. The possible values are:
| *ALL | All object attributes are selected. |
| *BLANK | Objects with no attribute value are selected. |
| Object attribute | Either a simple or a generic attribute value |
Object name. The name of the object that is to be restored. The possible values are:
| *ALL | All objects specified for the object information key are selected. |
| Object name | Either a simple name or a generic name |
Object type. The type of the object that is to be restored. The default value is *ALL. The possible values are:
| *ALL | All objects specified for the object information key are selected. |
| Object type | A valid type for the RSTOBJ command on the current release of the system |
Offset to first object selection list entry. The offset from the start of the user space to the first object selection list entry.
Offset to next object selection list entry. The offset from the start of the user space to the next object selection list entry. The value must be 0 for the last entry in the list.
Omit Library Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: This field repeats for each library name. | |||
| CHAR(10) | Library name | ||
Field Descriptions
Library name. The name of the library containing the objects to omit. The possible values are:
| *NONE | No libraries are excluded from the restore operation. |
| Library name | Either a simple or generic library name |
Number in array. The number of libraries to omit from the restore operation. The possible values are 1 through 300.
Omit Object Information Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: These fields repeat for each object name. | |||
| CHAR(10) | Object name | ||
| CHAR(10) | Library name | ||
| CHAR(10) | Object type | ||
Field Descriptions
Library name. The name of the library that is to be omitted. The possible values are:| *ALL | All the libraries, depending on the values specified for object and object type |
| Library name | Either a simple name or a generic name |
Number in array. The number of values that are specified for this key. The possible values are 1 through 300.
Object name. The name of the object that is to be omitted. The possible values are:
| *ALL | All the objects in the specified libraries, depending on the values specified for object type |
| Object name | Either a simple name or a generic name |
Object type. The type of the object that is to be omitted. The possible values are:
| *ALL | All objects with the specified object name that are valid types for the RSTOBJ command on the current release of the system |
| Object type | A valid type for the RSTOBJ command on the current release of the system |
Output Member Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| CHAR(10) | Output member name | ||
| CHAR(1) | Option | ||
Field Descriptions
Option. An indicator of whether to add to or replace the existing member. The possible values are:| 0 | The existing records in the specified database file member are replaced by the new records. (*REPLACE) |
| 1 | The new records are added to the existing information in the database file member. (*ADD) |
Output member name. The name of the file member that receives the output. The possible values are:
| *FIRST | The first member in the file is used and receives the output. |
| Member name | If the member does not exist, the system creates it. |
Saved Library Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: This field repeats for each library name. | |||
| CHAR(10) | Library name | ||
Field Descriptions
Library name. The name of the library containing the objects. The possible values are:
| *ANY | Restores objects from the first version of all saved libraries found on the tape beginning with the sequence number specified for the sequence number key, or restores objects from all saved libraries found on the optical media in the directory specified for the optical file key. |
| *SELECT | The libraries identified in the object selection list key are restored. Only one library can be specified in the selection criteria when restoring from a save file. Special value *SPLF cannot be specified in the selection criteria. |
| *SPLF | Spooled file data that was saved with the QSRSAVO API with library name *SPLF specified is to be restored. If this value is specified, it must be the only element in the array, the spooled file data key must be specified, and *ALL must be specified for the object name and object type. |
| Library name | Either a simple or generic library name |
Number in array. The number of libraries used during the restore operation. The possible values are 1 through 300.
Spooled File Data Key Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Spooled file data |
| 4 | 4 | BINARY(4) | Length of spooled file data header |
| 8 | 8 | BINARY(4) | Offset to spooled file selection list |
Field Descriptions
Length of spooled file data header. The length of the spooled file data header information. The possible values are:
| 8 | The header information ends with the length field. |
| 12 | The header information ends with the offset to selection list field. |
Offset to spooled file selection list. The offset from the start of the user space to the first spooled file selection list entry. See Spooled File Selection List Entry Format. The default is 0. If the value of the spooled file data field is 2, the value of this field must be greater than 0. Otherwise, the value must be 0.
Spooled file data. Whether to save spooled file data and attributes. The default is 3. The possible values are:
| 0 | No spooled file data is restored. (*NONE) |
| 2 | Selected spooled file data is restored. The offset to selection list field must be specified. |
| 3 | For each output queue that is restored, spooled file data that was saved with the output queue is restored, if it does not already exist on the system. (*NEW) |
Spooled File Selection List Entry Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of spooled file selection list entry |
| 4 | 4 | BINARY(4) | Offset to next spooled file selection list entry |
| 8 | 8 | BINARY(4) | Include or omit |
| 12 | C | BINARY(4) | Selection criteria format |
| 16 | 10 | BINARY(4) | Offset to selection criteria |
| 20 | 14 | BINARY(4) | Offset to new attributes |
Field Descriptions
Include or omit. Whether the spooled files selected by this entry are included or omitted from the save operation. Omit takes precedence over include. The possible values are:
| 0 | Spooled files that match all of the values specified in the selection criteria are omitted from the restore operation. |
| 1 | Spooled files that match all of the values specified in the selection criteria are included in the restore operation, unless another entry omits them. At least one entry must have this value. |
Length of spooled file selection list entry. The length of the spooled file selection list entry information. The possible values are:
| 20 | The selection list entry ends with the offset to selection criteria field. |
| 24 | The selection list entry ends with the offset to new attributes field. |
Offset to new attributes. The offset from the start of the user space to the new attributes for the spooled files included by this selection list entry. The value must be 0 if the Include or omit field value is 0. For the format of the new attributes, see New Attributes Format.
Offset to next spooled file selection list entry. The offset from the start of the user space to the next spooled file selection list entry. The value must be 0 for the last entry in the list.
Offset to selection criteria. The offset from the start of the user space to the selection criteria.
Selection criteria format. The format of the spooled file selection criteria. The possible values are:
| 1 | The selection criteria is specified by the Spooled File ID Format. This format identifies exactly one spooled file. |
| 2 | The selection criteria is specified by the Spooled File Attributes Format. This format identifies any number of spooled files. |
Spooled File ID Format
This is the format of the spooled file selection criteria when a value of 1 is specified for the selection criteria format field. The criteria specified must uniquely identify a single spooled file.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of Spooled file ID |
| 4 | 4 | CHAR(26) | Qualified job name |
| 30 | 1E | CHAR(10) | Spooled file name |
| 40 | 28 | BINARY(4) | Spooled file number |
| 44 | 2C | CHAR(8) | Job system name |
| 52 | 34 | CHAR(7) | Creation date |
| 59 | 3B | CHAR(6) | Creation time |
Field Descriptions
Creation date and time. The date and time the spooled file was created. The date and time must be specified in the format CYYMMDDHHMMSS:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
Job system name. The name of the system where the job that created the spooled file ran.
Length of spooled file ID. The length of the spooled file ID information. The possible values are:
| 65 | The spooled file ID ends with the creation time field. |
Qualified job name. The name of the job that owns the spooled file. The qualified job name has three parts:
| Job name | CHAR(10) | A specific job name. |
| User name | CHAR(10) | A specific user profile name. |
| Job number | CHAR(6) | A specific job number. |
Spooled file name. The name of the spooled file.
Spooled file number. The unique number of the spooled file. The possible values are:
| 1-999999 | The number of the spooled file for the specified qualified job name and spooled file name. |
Spooled File Attributes Format
This is the format of the spooled file selection criteria when a value of 2 is specified for the selection criteria format field.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of spooled file attributes |
| 4 | 4 | CHAR(20) | Qualified output queue |
| 24 | 18 | CHAR(10) | Spooled file name |
| 34 | 22 | CHAR(10) | Job name |
| 44 | 2C | CHAR(10) | User name |
| 54 | 36 | CHAR(6) | Job number |
| 60 | 3C | CHAR(10) | User-specified data |
| 70 | 46 | CHAR(8) | Job system name |
| 78 | 4E | CHAR(10) | Form type |
| 88 | 58 | CHAR(13) | Starting creation date and time |
| 101 | 65 | CHAR(13) | Ending creation date and time |
Field Descriptions
Ending creation date and time. Spooled files with a creation date and time less than or equal to this date and time are selected. The default is *ALL. The following special value is allowed:
| *ALL | Ending creation date and time are not used to select spooled files. |
The date and time must be specified in the format CYYMMDDHHMMSS:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
Form type. Spooled files with this form type are selected. Either a specific value or generic value may be specified. The default is *ALL. The following special values are allowed:
| *ALL | Spooled files with any form type are selected. |
| *STD | Spooled files that specify the standard form type are selected. |
Job name. Spooled files owned by this job are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special value is allowed:
| *ALL | Spooled files owned by any job are selected. |
Job number. Spooled files owned by a job with this job number are selected. If a job number is specified, then a specific job name and a specific user name must also be specified. The default is *ALL. The following special value is allowed:
| *ALL | Spooled files owned by a job with any job number are selected. |
Job system name. Spooled files owned by a job on this system are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special values are allowed:
| *ALL | Spooled files owned on any system are selected. |
| *CURRENT | Spooled files owned by a job on the current system are selected. |
Length of spooled file attributes. The length of the spooled file data attributes information. The possible values are:
| 24 | The spooled file attributes end with the qualified output queue field. |
| 34 | The spooled file attributes end with the spooled file name field. |
| 44 | The spooled file attributes end with the job name field. |
| 54 | The spooled file attributes end with the user name field. |
| 60 | The spooled file attributes end with the job number field. |
| 70 | The spooled file attributes end with the user-specified data field. |
| 78 | The spooled file attributes end with the job system name field. |
| 88 | The spooled file attributes end with the form type field. |
| 101 | The spooled file attributes end with the starting creation date and time field. |
| 114 | The spooled file attributes end with the ending creation date and time field. |
Qualified output queue. Spooled files on this output queue are selected, if they were saved with the data selected by the saved library and object information keys. The qualified output queue has two parts:
| Object name | CHAR(10). A specific or generic
output queue name or the following special value:
|
||||||
| Library name | CHAR(10). A specific or generic
library name, or one of the following special values:
|
Spooled file name. Spooled files with this name are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special value is allowed:
| *ALL | Spooled files with any name are selected. |
Starting creation date and time. Spooled files with a creation date and time greater than or equal to this date and time are selected. The default is *ALL. The following special value is allowed:
| *ALL | Starting creation date and time are not used to select spooled files. |
The date and time must be specified in the format CYYMMDDHHMMSS:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
User name. Spooled files owned by this user are selected. Either a specific name or generic name may be specified. The default is *ALL. The following special value is allowed:
| *ALL | Spooled files with any user are selected. |
User-specified data. Spooled files with this user-specified data value are selected. Either a specific value or generic value may be specified. The default is *ALL. The following special value is allowed:
| *ALL | Spooled files with any user-specified data value are selected. |
New Attributes Format
This is the format of new attributes to be assigned to the selected spooled files.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of new attributes |
| 4 | 4 | BINARY(4) | Expiration days |
| 8 | 8 | CHAR(20) | Qualified output queue |
| 28 | 1C | BINARY(4) | Restore existing spooled file |
Field Descriptions
Expiration days. The number of days from the start of the operation when the selected spooled files will expire. The default is 0.
Note: The user needs additional authority to use any value other than 0. The default value of 0 will be used for any spooled files which the user is not authorized to change. The user is authorized to change the expiration date of a spooled file if any of the following conditions are met.
- The user owns the spooled file.
- The user has spool control (*SPLCTL) special authority.
- The user has job control (*JOBCTL) special authority, and the output queue to which the spooled file is being restored is specified as OPRCTL(*YES).
- The user owns the output queue to which the spooled file is being restored, and the output queue is specified as AUTCHK(*OWNER).
- The user has read, add, and delete authorities to the output queue to which the spooled file is being restored, and the output queue is specified as AUTCHK(*DTAAUT).
The possible values are:
| -1 | The expiration date for the selected spooled files will be set to *NONE (no expiration date). |
| 0 | The saved expiration date for the selected spooled files will be used. If a saved expiration date has already passed, a value of -1 will be used. |
| 1-366 | The expiration date for the selected spooled files will set to the number of days specified past the date that the restore operation begins. |
Length of new attributes. The length of the new attributes information. The possible values are:
| 8 | The new attributes end with the expiration days field. |
| 28 | The new attributes end with the qualified output queue field. |
| 32 | The new attributes end with the restore existing spooled file field. |
Qualified output queue. Spooled files are restored to this output queue, if it is found in the ASP specified for the restore to ASP device key or the restore to ASP number key. The default is *SAME. The qualified output queue has two parts:
| Object name | CHAR(10). A specific output queue name
or the following special value:
|
||||
| Library name | CHAR(10). A specific library name,
or blanks when the object name is *SAME,
or one of the following special values:
|
Restore existing spooled file. Whether to restore a spooled file that already exists on the system. The default is 0. The possible values are:
| 0 | A spooled file that already exists on the system is not restored. |
| 1 | If a spooled file already exists on the system, a duplicate copy of the spooled file is restored to the specified output queue with a new creation date and time. |
Volume Identifier Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Number in array | ||
| Note: These fields repeat for each volume identifier. | |||
| BINARY(4) | Length of volume identifier | ||
| CHAR(*) | Volume identifier | ||
Field Descriptions
Length of volume identifier. The character length of the identifier of the volume. The possible value is:| 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. If the volume identifier is *MOUNTED, this value must be 8. If the volume identifier is *SAVVOL, this value must be 7. |
Number in array. The number of volume identifiers used during the restore operation. The possible values are 1 through 75.
Volume identifier. The identifier of a volume. The possible values are:
| *MOUNTED | The volume currently placed in the device is used. If *MOUNTED is specified, it must be the only value specified. This value cannot be specified for an optical media library device. *MOUNTED cannot be specified for a tape media library device unless a category is set with the Set Tape Category (SETTAPCGY) command. |
| *SAVVOL | The system, by using the save or restore history information, determines which volumes contain the most recently saved version of the objects. If *SAVVOL is specified, it must be the only value specified. The history information contains only the first 6 characters of any volume name. If the name of an optical volume exceeds 6 characters, you should not use this value. |
| Volume identifier | The identifier of a volume. |
Dependencies between Keys
The following two tables list the dependencies between the different keys. If the dependency holds only for 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 |
|---|---|
| More than one library name, Generic library name, or Library name = *ANY |
Object name = *ALL Device <> *SAVF Restore library = *SAVLIB1 Label = *SAVLIB1 Optical file = '*'1 or 'directory/*' |
| Object selection list< | |
| Device = tape device | Volume identifier 1 Sequence number 1 Label 1 End of media option 1 |
| Device = optical device | Volume identifier Optical file 1 |
| Device = media definition | Media definition |
| Output = 1 | Type of output information = 01 |
| Output = 2 | Output file Output member 1 Type of output information 1 |
| Save time | Save date |
| Volume identifier = *SAVVOL | Label = *SAVLIB1 |
| Library name = *SPLF | Object name = *ALL1 Object type = *ALL1 Spooled file data = 2 |
| Spooled file data = 2 | Object name = *ALL1 Object type = *ALL1 Library name = *SPLF or Object type = *OUTQ Library name <> *SPLF |
| Starting position in file | Sequence number <> -1 |
Notes:
|
|
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 |
|---|---|
| Save file | Volume identifier Sequence number Label End of media option Optical file Media definition |
| Media definition | Volume identifier Sequence number Optical file |
| Tape, optical, or media definition for the device |
Save file |
| Output = 0 | Output file Output member Type of output information |
| Optical file | Label Sequence number |
| Allow object differences = 1 | Database member option = 0 |
| Volume identifier = *SAVVOL | Sequence number |
| Database member option = 0 | File member |
| Restore ASP | Restore ASP device name |
Relationship to RSTOBJ Command
Because of the relationship between the QSRRSTO API and the RSTOBJ command, the following situations should be noted:
- Message text: Several messages produced by this API refer to parameters or values of the RSTOBJ command. 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 RSTOBJ, not QSRRSTO.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF222E E | &1 special authority is required. |
| 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. |
| CPFB8ED E | Device description &1 not correct for operation. |
API introduced: V5R4
[ Back to top | Backup and Recovery APIs | APIs by category ]