Restore Object List (QSRRSTO) API

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.

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

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

Valid Keys

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

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:

Defer ID. An identifier that specifies to defer the restore of objects that depend on other objects that are not yet available. To complete the restore of 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 can be logical files or SQL materialized query tables (MQTs). A deferred logical file is not created until the restore is complete. A deferred MQT is created, but until the restore is complete, any functions performed on the MQT that require access to the based-on files will fail.

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:

1. The deferred object is restored to the same library from which it was saved.
2. 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:

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:

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:

1. This key applies only to user objects of the *MODULE, *PGM, *SRVPGM, and *SQLPKG object types.
2. An object must have creation data (either observable or unobservable) to be converted.
3. 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.

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:

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.

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:

Option. Which objects are restored. The default is 1. The possible values are:

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

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:

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:

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:

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:

Restore to library. The name of the library to which objects are restored. The default is *SAVLIB. The possible values are:

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

Save 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:

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

Note:

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

The possible value is:

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:

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.

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:

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

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

Field Descriptions

Device name. The name of the device used for the restore operation. The possible values for each element of the array are:

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

Field Descriptions

File name. The name of the file being restored. The possible values are:

Member. The name of the member to restore. The possible values are:

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.

Reserved. An ignored field.

Force Object Conversion Key Format

Field Descriptions

Convert during restore. Whether objects should be converted on the restore operation. The possible values are:

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

Object Information Key Format

Field Descriptions

Object name. The name of the object that is to be restored. The possible values are:

Object type. The type of the object that is to be restored. The possible values are:

Omit Library Key Format

Field Descriptions

Library name. The name of the library containing the objects to omit. The possible values are:

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

Field Descriptions

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:

Object type. The type of the object that is to be omitted. The possible values are:

Output Member Key Format

Field Descriptions

Output member name. The name of the file member that receives the output. The possible values are:

Saved Library Key Format

Field Descriptions

Library name. The name of the library containing the objects. The possible values are:

Number in array. The number of libraries used during the restore operation. The possible values are 1 through 300.

Spooled File Data Key Format

Field Descriptions

Length of spooled file data header. The length of the spooled file data header information. The possible values are:

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:

Spooled File Selection List Entry Format

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:

Length of spooled file selection list entry. The length of the spooled file selection list entry information. The possible values are:

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:

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.

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:

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:

Qualified job name. The name of the job that owns the spooled file. The qualified job name has three parts:

Spooled file name. The name of the spooled file.

Spooled file number. The unique number of the spooled file. The possible values are:

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.

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:

The date and time must be specified in the format CYYMMDDHHMMSS:

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:

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:

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:

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:

Length of spooled file attributes. The length of the spooled file data attributes information. The possible values are:

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:

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:

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:

The date and time must be specified in the format CYYMMDDHHMMSS:

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:

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:

New Attributes Format

This is the format of new attributes to be assigned to the selected spooled files.

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:

Length of new attributes. The length of the new attributes information. The possible values are:

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:

Restore existing spooled file. Whether to restore a spooled file that already exists on the system. The default is 0. The possible values are:

Volume Identifier Format

Field Descriptions

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:

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/*'
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: This key does not have to be explicitly specified. The default may be taken to satisfy this dependency.

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.

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

[ Back to top | Backup and Recovery APIs | APIs by category ]