Improved TPF/DF error checking

TPFUG_Req_Number: DF08191F
ORIGIN DATE: December 21, 2007
REQUIREMENT ABSTRACT : Provide the ability for an application to determine the success or reason for failure of any TPFDF call with a single check.


REQUIREMENT DESCRIPTION :

• As the TPFDF product provides increased functionality, error determination is increasing complex and requires a more detailed understanding of the order in which the TPFDF product identifies and sets error conditions. The introduction of LLR support in particular means that SW00RTN can be set to zero despite errors that mean a READ into a buffer actually failed (e.g. invalid buffer address, buffer too small, or replace in progress set in SW00RT3). This increased complexity exposes applications to greater risk of inaccurately identifying the result of a TPFDF call with resulting logic and possible database integrity errors.
• A mechanism is required for both assembler (SPM and non-SPM) and C/C++ applications to determine the overall outcome of any TPFDF call without them having to have knowledge of the order in which error conditions are flagged inside of the TPFDF product code. This is required to provide a consistent and accurate means of determining the overall result.
• The success or reason for failure of the TPFDF should be recorded by the TPFDF product code, based on the call made.
• Each result condition should have its own unique value to allow an application to 'switch' on its value without having to manipulate bit settings. Equates/enumeration should be provided to each possible result value (for assembler SPM and non-SPM support is required)
• The current conditions that should be considered success/failure conditions are:
o TPFDF call was successful
o Serious error
o Index Error
o Lrec not found/add unique failed
o EOF
o LIST definition error
o Buffer address error using BAM
o Buffer size error using BAM
o Replace in progress on BAM read of LLR
• Since the following conditions are secondary checks that an application would only check if it had a specific need to do so, they should not be part of the success/failure conditions:
o Which specific 'serious' error is set in SW00RTN/SW00RT3
o File is now empty - SW00RT2 bit 5 following a delete with EMPTYCHECK
o The number of errors for FULLFILE processing (SW00RT1)
o Successfully located lrec is LLR (no BAM errors or no BAM) is LLR.
• Currently assistance is provided for assembler SPM and C/C++ applications to check for all the secondary error checks listed except for specific types of serious errors. SW00SR equates should be provided to provide the same assistance to non-SPM assembler applications.



CRITICAL SUCCESS FACTORS

Applications which use ERROR=/ERRORA= must not require reassembly to support the new error checking method. None of the existing SW00RTx byte definitions should change.


ALTERNATIVE SOLUTIONS

N/A

SOLUTION CONSIDERATIONS (required)

Use a new public SW00SR field that contains a unique value to identify all success/failure conditions that can occur.
Use a new private SW00SR field that contains a unique value to identify all success/failure conditions that can occur and provide an API to obtain that SW00SR value.