Restore from Application (QaneRsta) API

The Restore from Application (QaneRsta) API enables an application to provide the restore records that are required for a restore-from-save-file operation. The application defines the restore operation by specifying the type of restore command, and by providing the restore command parameters. The API calls an exit program to retrieve the restore records from the application instead of from the save file.

To use the API, the application must provide the following:

• A user space that contains the required input parameter group
• An exit program

When processing the restore command, the API does the following:

• Calls the exit program to indicate the start of the transfer sequence
• Submits the restore command for processing
• Calls the exit program repeatedly to transfer the restore records
• Calls the exit program to signal the end of the restore operation
• May call the exit program to force an abnormal end to the restore operation

The program that calls the API is suspended while the restore operation is being processed.

Restrictions

QTEMP should not be specified for the library name on the OUTFILE parameter because the restore command is submitted by a prestart job running in the QSYSWRK subsystem and not in the job that called the API. Locks should not be applied to restore objects that would conflict with locks applied by the restore operation running in the prestart job.

Objects can be restored by this API only if the objects were saved using the Save to Application (QaneSava) API, and only if the objects were saved from the current or an earlier release of the operating system.

The application must provide the restore records in the order presented, without modification, for the objects to be successfully restored.

Authorities and Locks

Exit Program Library Authority

*EXECUTE

Exit Program Authority

*EXECUTE

User Space Lock

*SHRNUP

User Space Library Authority

*USE

User Space Authority

*USE

Restore Command Library Authority

*EXECUTE

Restore Command Authorities

See the restore command

Restored Object Locks

See the Back up your server topic.

Restored Object Authorities

See Appendix D in the iSeries Security Reference book.

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The user space that contains all the control 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.

You can use the following special values for the library name:

*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 actual library that is used is returned in the status information. the user space.

The library list is used to locate the user space.

User space format name

INPUT; CHAR(8)

The format name for the input parameters that are contained in the user space. For the format of the structure, see SVRS0100 Format.

Status format name

INPUT; CHAR(8)

The format name for the status information returned on the API call. For the format of the structure, see SRST0100 Format.

Status information

OUTPUT; CHAR(*)

The status information returned on the API call.

Length of status information

INPUT; BINARY(4)

The length of the status information returned on the API call. The minimum length is 8 bytes.

Error code

I/O; CHAR(*)

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

SVRS0100 Format

This format defines the input parameter group for the API.

Field Descriptions

Application data. Information that the application wants passed to the exit program. The content of this information is defined by the application. This field could contain information specific to the object being saved (such as the object name, size, and so forth), or it could contain the qualified name of another object that contains this information.

Exit program library. The name of the library that contains the exit program called by the API. the exit program.

Exit program name. The name of the exit program that is called by the API. See Restore from Application exit program for additional details.

Length of application data. The length of the application data. This value is passed to the exit program. This value must be set to zero if there is no application data.

Length of restore command parameters. The length of the restore command parameters. The maximum allowable length is 32500 bytes for restore commands.

Length of structure. The length of this structure, from the start of the input parameters to the last byte of the application data.

Offset to application data. The byte offset from the beginning of the user space to the start of the application data. This value must be set to zero if there is no application data.

Offset to restore command parameters. The byte offset from the beginning of the user space to the start of the restore command parameters.

Restore command parameters. A character string that contains the restore command parameters or restore keys. These parameters are validated when the API submits the command for processing. Refer to the restore commands in the Control Language (CL) for detailed information about valid parameters. Refer to the Restore Object (QsrRestore) API or Restore Object List (QSRRSTO) API for detailed information about valid keys.

These additional restrictions apply to the restore command parameters when you use this API:

• The parameters must be consistent with the restore command type.
• The parameters must not include the restore command name.
• The parameters must be separated by at least one blank character.
• The Device (DEV) and Save file (SAVF) parameters must not be used. These parameters are provided by the API.
• The End of media option (ENDOPT), Label (LABEL), Media definition (MEDDFN), Optical file (OPTFILE), Sequence number (SEQNBR) and Volume identifier (VOL) parameters must not be used. These parameters are inconsistent with the save file operation provided by the API.
• Only single library names can be used with the SAVLIB or RSTLIB parameter.

The following examples illustrate the restore command parameters that are required for typical restore scenarios:

• Example 1: Restore command type 1 (RST)

  OBJ('/*') ('/QSYS.LIB' *OMIT)
  ('/QDLS.LIB' *OMIT)
  

  These parameters restore all objects that are not in libraries and that are not document library objects.

• Example 2: Restore command type 2 (RSTOBJ)

  OBJ(FILE*) SAVLIB(MYLIB) OBJTYPE(*FILE)
  SAVDATE(122297) RSTLIB(TMPLIB)
  

  These parameters restore all files with names that start with the characters FILE* to library TMPLIB that were saved from the library named MYLIB on 22 December 1997.

• Example 3: Restore command type 4 (RSTLIB)

  SAVLIB(JOE)
  

  These parameters restore the library named JOE.

These additional restrictions apply to the command parameters when you use the Restore Object (QsrRestore) API or Restore Object List (QSRRSTO) API.

• The keys specified must be consistent with restore from save file operations.
• The Device (DEV) and Save file (SAVF) keys must not be used. These keys are provided by this API.
• The End of media option (ENDOPT), Label (LABEL), Media definition (MEDDFN), Optical file (OPTFILE), Sequence number (SEQNBR) and Volume identifier (VOL) keys must not be used. These keys are inconsistent with the save file operation provided by the API.
• The starting offset for the keys is always 0 and not the offset of the restore command parameters.
• All integer values within the keys must be aligned on 4-byte boundaries.
• All pointers within the keys must be aligned on 16-byte boundaries.

Restore command type. The type of restore command that is to be processed.

1	Restore (RST) command
2	Restore Object (RSTOBJ) command
3	Restore Document Library Object (RSTDLO) command
4	Restore Library (RSTLIB) command
5	Restore Object (QsrRestore) API
6	Restore Object List (QSRRSTO) API
7	Restore System Information (RSTSYSINF) command

Target release.

An ignored field. Must be set to blanks.

SRST0100 Format

This format defines the status information that is returned on the API call.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Transfer time
12	C	BINARY(4)	Transfer block size
16	10	BINARY(4)	Transfer block multiplier
20	14	BINARY(4)	Last block size
24	18	CHAR(10)	User space library used
34	22	CHAR(2)	Reserved
36	24	BINARY(4)	Decimal transfer time

Field Descriptions

Bytes returned. The number of status information bytes returned. If the value specified in the length of status information parameter is larger than the specified status information structure, this value is set to the last byte of the returned information.

Bytes available. The number of status information bytes available for the specified status information format.

Decimal transfer time.The decimal portion of the transfer time in millionths of a second. If the value returned for Transfer time was 5 and the value returned for Decimal transfer time was 827352, then the total transfer time was 5.827352 seconds.

Reserved.This field is unused and will be returned with blanks.

Transfer block size. The number of bytes in the blocks transferred by the exit program.

Transfer block multiplier. The number of blocks successfully transferred by the exit program.

Last block size. The number of bytes in the last block transferred by the exit program.

The true transfer size of the operation is equal to the transfer block size multiplied by the transfer block multiplier plus the last block size.

Transfer time. The elapsed time, in seconds, that begins when the application calls the API, and ends when the API returns to the caller.

User space library used. The name of the user space library that is used in the API call.

Error Messages