Restore from Application Exit Program
1 | Operation type | Input | Binary(4) |
2 | Operation status | Output | Binary(4) |
3 | Restore data | Input | PTR(SPP) |
4 | Length of restore data | Input | Binary(4) |
5 | Restore bytes written | Output | Binary(4) |
6 | Qualified user space name | Input | Char(20) |
7 | User space format name | Input | Char(8) |
The Restore from Application exit program enables an application program to provide the restore records that are required for a restore-from-save-file operation using the Restore from Application (QaneRsta) API.
The API calls the exit program once to start the transfer sequence, multiple times to transfer each block of restore records, and once to end the transfer sequence.
The API passes to the exit program the operation type, the number of restore record bytes required, the qualified name of the user space and the format name of the user space.
The exit program must return the restore data, the number of the restore record bytes retrieved, and status on the success or failure of the requested operation.
At any time following the initial call, the API could call the exit program that requires an abnormal end to the transfer sequence.
Restrictions
The exit program must provide the restore records in the order the records were saved, without modification, for the objects to be successfully restored.
Authorities and Locks
See Restore from Application (QaneRsta) API.
Required Parameter Group
- Operation type
- INPUT; BINARY(4)
The type of operation that the exit program is required to run.
1 Start
The exit program must use this operation type to prepare for the restore records transfer.2 Transfer
The exit program must use this operation type to transfer (retrieve, write, and so forth) a block of restore records.3 End
The exit program must use this operation type to end the restore records transfer.4 Abnormal end
The exit program must use this operation type to prematurely end the restore records transfer.Normal-operation-type order is 1 (start), 2 (transfer), 2 (transfer), ..., 2 (transfer), 3 (end).
Operation type 1 (start) is issued only once at the beginning of the restore operation before any restore records are transferred.
Operation type 2 (transfer) is issued multiple times during the restore operation as each block of restore records is required. The exit program must provide as many restore record bytes as requested, with the exception of the last block, which may not be of sufficient length.
Operation type 3 (end) is issued only once at the end of the restore operation after all restore records are transferred. The exit program must be able to handle the condition where this operation type is issued before all restore records are transferred. The exit program must handle this operation sequence as a normal condition and end the transfer sequence normally.
Operation type 4 (abnormal end) is issued only once following operation types 1 (start) or 2 (transfer), under abnormal conditions to prematurely end restore records transfer. These conditions are:
- The API detects an error with the system restore operation.
- The exit program returns an operation status of 1 (error).
- Operation status
- OUTPUT; BINARY(4)
The ending status of the requested operation.
0 Good
The exit program must return this status value to indicate successful completion of the operation.1 Error
The exit program must return this status value to indicate unsuccessful completion of the operation.2 Complete
The exit program must use this status value instead of a status value of 0 (good)., when the last byte of the restore records has been retrieved. This indicates successful completion of operation type 2 (transfer).
- Restore data
- INPUT; PTR(SPP)
A pointer to a block of restore records. The parameter is passed only on operation type 2 (transfer).
- Length of restore data
- INPUT; BINARY(4)
For operation types 1 (start), 3 (end), and 4 (abnormal end), this value is zero.
For operation type 2 (transfer), this is the length of restore data being requested.
- Restore bytes written
- OUTPUT; BINARY(4)
For operation types 1 (start), 3 (end), and 4 (abnormal end), this value must be set to zero.
For operation type 2 (transfer), this value must be set to the actual number of restore record bytes returned. This value must never exceed the value passed in the length of restore data parameter.
- Qualified user space name
- INPUT; CHAR(20)
The qualified user space name that is specified by the application on the call to the Restore from Application (QaneRsta) API. 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.
- User space format name
- INPUT; CHAR(8)
The user space format name that is specified by the application on the call to the Restore from Application API. For the format of the structure, see SVRS0100 Format in Restore from Application (QaneRsta) API. The exit program uses the length of application data field to determine if the structure contains application data, and the offset to application data field to locate this information.
Coding Guidelines
Applications should consider the following when coding the exit program:
- The program should only return an exception for the requested operation if
there has been a failure in the operation. If the program signals an escape
message to the API, the system assumes there is a failure. A diagnostic message
is returned to the calling program.
- The program must clean up any locks that it acquires.
- The program must handle all potential error conditions associated with its
own operations (be fault tolerant).
- The program must avoid infinite looping conditions.
Exit program introduced: V4R3
[ Back to top | Backup and Recovery APIs | APIs by category ]