Save to Application Exit Program

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

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. The value for this parameter currently is 1 048 832 bytes for all but the last operation, which may be less.

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