Save to Application Exit Program
1 | Operation type | Input | Binary(4) |
2 | Operation status | Output | Binary(4) |
3 | Save data | Input | PTR(SPP) |
4 | Length of save data | Input | Binary(4) |
5 | Save bytes read | Output | Binary(4) |
6 | Qualified user space name | Input | Char(20) |
7 | User space format name | Input | Char(8) |
The Save to Application exit program enables an application program to receive the save records that are generated by a save-to-save-file operation using the Save to Application (QaneSava) API.
The API calls the exit program once to start the transfer sequence, multiple times to transfer each block of save records, and once to end the transfer sequence.
The API passes to the exit program the operation type, the save data, the length of the save data, the qualified name of the user space and the format name of the user space.
The exit program must return the number of save bytes read, 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 read and store the save records in the order presented, without modification, for the objects to be successfully restored.
Authorities and Locks
See Save to Application (QaneSava) 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 save records transfer.2 Transfer
The exit program must use this operation type to transfer (copy, store, and so forth) a block of save records.3 End
The exit program must use this operation type to end the save records transfer.4 Abnormal end
The exit program must use this operation type to prematurely end the save 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 save operation before any save records are transferred.
Operation type 2 (transfer) is issued multiple times during the save operation as each block of save records becomes available. The exit program must read the entire block of save records.
Operation type 3 (end) is issued only once at the end of the save operation after all save records are transferred.
Operation type 4 (abnormal end) is issued only once following operation types 1 (start) or 2 (transfer), under abnormal conditions to prematurely end save records transfer. These conditions are:
- The API detects an error with the system save 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.
- Save data
- INPUT; PTR(SPP)
A pointer to a block of save records. This parameter is passed only on operation type 2 (transfer).
- Length of save 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 the block of save records.
- Save bytes read
- 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), the exit program must return a value that indicates the number of save record bytes successfully read. The API abnormally ends the transfer sequence if the returned value does not equal the length of save data.
- Qualified user space name
- INPUT; CHAR(20)
The qualified user space name specified by the application on the call to the Save to Application (QaneSava) 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 Save to Application API. For the format of the structure, see SVRS0100 Format in Save to Application (QaneSava) 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 prevent infinite looping conditions.
Exit program introduced: V4R3
[ Back to top | Backup and Recovery APIs | APIs by category ]