Restore from Application (QaneRsta) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | User space format name | Input | Char(8) |
| 3 | Status format name | Input | Char(8) |
| 4 | Status information | Output | Char(*) |
| 5 | Length of status information | Input | Binary(4) |
| 6 | Error code | I/O | Char(*) |
Service Program Name: QANESERV
Default Public Authority: *USE
Threadsafe: No
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 by 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.
Because the restore command is processed from within a prestart job the adopted authority of the thread using the Restore from Application (QaneRsta) API will not be available to the restore command. One way to give the prestart job more authority is to use the adopted authority to swap user profiles within the application before calling the Restore from Application (QaneRsta) API.
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 Backing up your
system topic collection.
- Restored Object Authorities
- See Authority required for objects used by commands in the Security reference topic collection.
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:
The library list is used to locate the user space.*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.
- 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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of structure |
| 4 | 4 | BINARY(4) | Offset to restore command parameters |
| 8 | 8 | BINARY(4) | Length of restore command parameters |
| 12 | C | BINARY(4) | Offset to application data |
| 16 | 10 | BINARY(4) | Length of application data |
| 20 | 14 | BINARY(4) | Restore command type |
| 24 | 18 | CHAR(10) | Exit program name |
| 34 | 22 | CHAR(10) | Exit program library |
| 44 | 2C | CHAR(8) | Target release |
| CHAR(*) | Restore command parameters | ||
| CHAR(*) | Application data | ||
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. See the restore commands in the Control language topic collection for detailed information about valid parameters. See 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
| Message ID | Error Message Text |
|---|---|
| CPF3700 E | All CPF37xx messages could be signalled. xx is from 01 to FF, excluding tape and diskette errors since the operation is a restore from a save file. |
| CPF3800 E | All CPF38xx messages could be signalled. xx is from 01 to FF, excluding tape and diskette errors since the operation is a restore from a save file. |
| CPF2115 E | Object &1 in &2 type *&3 damaged. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9800 E | All CPF98xx messages could be signaled. xx is from 01 to FF. |
| CPF9999 E | Function check. &1 unmonitored by &2 at statement &5, instruction &3. |
| CPFB8C0 E | Status information length for &1 API is not valid. |
| CPFB8C1 E | Unsupported value for &1 API. |
| CPFB8C2 E | Offset value for &1 API not valid. Reason &6. |
| CPFB8C3 E | Length value for &1 API not valid. Reason &6. |
| CPFB8C4 E | Unexpected condition with exit program for &1 API. Reason &6. |
| CPFB8C5 E | Parameter &2 specified more than once for API &1. |
| CPIB8C6 I | Trace data generated for API &1. |
| CPFB8C7 E | Unsupported value for &1 API. |
| CPFB8C8 E | Command syntax error detected by &1 API. |
| CPFB8C9 E | Command exception occurred using &1 API. |
| CPFB8CF E | Unexpected condition with &1 API. Reason &6. |
API introduced: V4R3
[ Back to top | Backup and Recovery APIs | APIs by category ]