Restore from Application Exit Program

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; CHAR(*)

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. The maximum length is 1 048 832 bytes.

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 the SVRS0100 Format in the 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.