Important fields in the SDWA
The following figure summarizes some of the key fields in the SDWA.
Note that certain fields are in an extension of the SDWA called SDWARC1,
which is a different DSECT. Here is how to access SDWARC1:
- SDWAXPAD in the SDWA contains the address of SDWAPTRS.
- SDWAPTRS is a DSECT which contains SDWASRVP.
- SDWASRVP contains the address of SDWARC1.
- SDWACRC
- SDWAARER
- SDWAARSV
- SDWACID
- SDWASC
- SDWAMLVL
- SDWARRL
- Field Name
- Use
- SDWAPARM
- For ESTAEX, if the ESTAEX was established by a routine running
in AMODE 64, the 8-byte area contains the address of the parameter
area you specified on the PARAM parameter of the ESTAEX macro. Otherwise,
the first four bytes of this 8-byte area contain the address of the
parameter area and the next four bytes contain the ALET for the parameter
area.
For routines defined by the IEAARR macro, if the IEAARR was issued in AMODE 64, the 8-byte area contains the 64-bit address of the parameter area specified on the ARRPARMPTR64 parameter of IEAARR. Otherwise, this field contains the address of an 8-byte area. The first word of this area contains the address of the parameter area you specified on the ARRPARAMPTR parameter of IEAARR and the second word does not contain interface information.
See Setting up, passing, and accessing the parameter area for details on the parameter area passed by recovery routines.
- SDWACMPC
- This 3-byte field contains the completion code that existed when the system gave control to the recovery routine. The recovery routine can change the completion code by issuing the SETRP macro with the COMPCOD parameter. The system completion code appears in the first twelve bits, and the user completion code appears in the second twelve bits.
- SDWARPIV
- This bit tells the recovery routine that the registers and PSW at the time of error are not available. When this bit is on, the contents of SDWAGRSV, SDWAG64, SDWAARER, and SDWAEC1 are unpredictable.
- SDWACRC
- This 4-byte field contains the reason code associated with the
completion code in SDWACMPC. The reason code is set through the REASON
parameter of the CALLRTM or ABEND macro, and is valid only when bit
SDWARCF is on. The recovery routine may change this reason code by
specifying a new value for the REASON parameter of the SETRP macro. Note: This reason code is not the same as the return code that programs may set in GPR 15 before they issue the CALLRTM or ABEND macro.
- SDWARCF
- If on, this bit indicates that SDWACRC contains a reason code.
- SDWAGRSV
- This field contains the contents of the general purpose registers (GPRs) 0-15 as they were at the time of the error.
- SDWAARER
- This field contains the contents of the access registers (ARs) 0-15 as they were at the time of the error.
- SDWAEC1
- This field contains the PSW that existed at the time of the error.
- SDWAEC2
- The contents of this field vary according to the type of recovery
routine:
- For ESTAE-type recovery routines (except for ESTAI routines): If a program establishes an ESTAE routine, and subsequently performs a stacking operation while running under the same RB as when it established the ESTAE routine, SDWAEC2 contains the PSW from the linkage stack entry immediately following the entry that was current when the ESTAE routine was established. Otherwise, SDWAEC2 contains the current RBOPSW from the RB that activated the recovery routine, and the PSW is the one from the time of the last interruption of that RB that occurred while the RB was unlocked and enabled. Bit SDWAINTF in SDWAXFLG indicates whether the contents of SDWAEC2 are from the linkage stack (SDWAINTF is 1) or from an RB (SDWAINTF is 0).
- For an ESTAI routine, this field contains zero.
- For an FRR, the field contains the PSW used to give control to the FRR.
- SDWASRSV
- The contents of this field vary according to the type of recovery
routine:
- For ESTAE-type recovery routines (except for ESTAI routines):
If a program establishes an ESTAE routine, and subsequently performs
a stacking operation while running under the same RB as when it established
the ESTAE routine, SDWASRSV contains GPRs 0-15 from the linkage stack
entry immediately following the entry that was current when the ESTAE
routine was established. Otherwise, SDWASRSV contains GPRs 0-15 from
the RB that activated the recovery routine, and the GPRs are the same
as they were at the time of the last interruption of that RB that
occurred while the RB was unlocked and enabled. Bit SDWAINTF in SDWAXFLG
indicates whether the contents of SDWASRSV are from the linkage stack
(SDWAINTF is 1) or from an RB (SDWAINTF is 0). Note: SDWASRSV is not available for ESTAE-type recovery routines running in AMODE 64. SDWAG64 is used for retry instead of SDWASRSV when RETREGS=64 is specified with SETRP.
- For an ESTAI routine, this field contains zeros.
- For an FRR, this field has the same contents as SDWAGRSV.
If the recovery routine requests a retry, the system might use the contents of this field to load the GPRs for the retry routine. See the RETREGS parameter description in the SETRP macro in z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO for details. To change the contents of the GPRs for the retry routine, you must make the changes to SDWASRSV and then issue SETRP with RETREGS=YES. You can update the registers directly or with the RUB parameter on SETRP.
- For ESTAE-type recovery routines (except for ESTAI routines):
If a program establishes an ESTAE routine, and subsequently performs
a stacking operation while running under the same RB as when it established
the ESTAE routine, SDWASRSV contains GPRs 0-15 from the linkage stack
entry immediately following the entry that was current when the ESTAE
routine was established. Otherwise, SDWASRSV contains GPRs 0-15 from
the RB that activated the recovery routine, and the GPRs are the same
as they were at the time of the last interruption of that RB that
occurred while the RB was unlocked and enabled. Bit SDWAINTF in SDWAXFLG
indicates whether the contents of SDWASRSV are from the linkage stack
(SDWAINTF is 1) or from an RB (SDWAINTF is 0).
- SDWAARSV
- The contents of this field depend on the type of recovery routine:
- For ESTAE-type recovery routines (except for ESTAI routines): If a program establishes an ESTAE routine, and subsequently performs a stacking operation while running under the same RB as when it established the ESTAE routine, SDWAARSV contains ARs 0-15 from the linkage stack entry immediately following the entry that was current when the ESTAE routine was established. Otherwise, SDWAARSV contains ARs 0-15 from the RB that activated the recovery routine, and the ARs are the same as they were at the time of the last interruption of that RB that occurred while the RB was unlocked and enabled. Bit SDWAINTF in SDWAXFLG indicates whether the contents of SDWAARSV are from the linkage stack (SDWAINTF is 1) or from an RB (SDWAINTF is 0).
- For an ESTAI routine, this field contains zeros.
- For an FRR, this field has the same contents as SDWAARER.
If the recovery routine requests a retry, the system might use the contents of this field to load the ARs for the retry routine. See the RETREGS parameter description in the SETRP macro in z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO for details. To change the contents of the ARs for the retry routine, you must make the changes in SDWAARSV, and then issue SETRP with RETREGS=YES.
- SDWASPID
- This field contains the subpool ID of the storage used to obtain the SDWA, for use whenever the retry routine is responsible for freeing the SDWA.
- SDWALNTH
- This field contains the length, in bytes, of this SDWA, the SDWA extensions, and the variable recording area, for use whenever the retry routine is responsible for freeing the SDWA. (This allows the retry routine to free the extensions along with the SDWA.)
- SDWACOMU
- The recovery routines can use this 8-byte field to communicate
with each other when percolation occurs. The system copies this field
from one SDWA to the next on all percolations. When the field contains
all zeros, either no information is passed or the system has not been
able to pass the information. Note: Using this field, FRRs can pass information to ESTAE-type recovery routines.
- SDWATRAN
- This field contains one of the following if a translation exception
occurred:
- The valid translation exception address if the SDWATEAV bit is 1.
- The ASID of the address space in which the translation exception occurred if the SDWATEIV bit is 1.
If both the SDWATEAV and SDWATEIV bits are 0, ignore the SDWATRAN field.
- SDWATEAR
- For translation exceptions that occur in AR mode, this 1-byte field identifies the number of the AR that the program was using when the translation exception occurred.
- SDWACLUP
- If on, this bit indicates that the recovery routine cannot retry.
- SDWAPERC
- If on, this bit indicates that a recovery routine of the same type has already percolated for this error. This bit is valid only between similar types of recovery routines; an FRR can tell if an FRR has percolated, and an ESTAE-type recovery routine can tell if an ESTAE-type recovery routine has percolated.
- SDWAEAS
- If on, this bit indicates that a previous recovery routine provided sufficient diagnostic information pertaining to this error. The recovery routine providing the information is responsible for setting the bit. If the recovery routine issues SDUMPX (or SDUMP), the system sets the bit automatically.
- SDWACID
- The recovery routine can use this 5-byte field to provide the component ID of the component involved in the error.
- SDWASC
- The recovery routine can use this 23-byte field to provide the name of the component and a description of the function or subfunction involved in the error.
- SDWAMLVL
- The recovery routine can use this 16-byte field to indicate the level of the module involved in the error. The first 8 bytes contains the date (SDWAMDAT) and the second 8 bytes contains the version (SDWAMVRS).
- SDWARRL
- The recovery routine can use this 8-byte field to indicate the recovery routine's entry point label.
- SDWALCL
- If on, this bit indicates that the system is entering an FRR in LOCAL restricted mode.
- SDWALSLV
- The recovery routine can use this 2-byte field to control the linkage stack state upon retry. See Linkage stack at time of retry for additional information.
- SDWAG64
- When running in z/Architecture® mode, this field contains the full 64-bit contents of the general purpose registers at the time of error. It also contains the 64-bit registers to be used for retry if you specify RETREGS=64 on the SETRP macro or turn on the SDWAUPRG and SDWAUP64 bits.
- SDWATXG64
- When bits SDWAPCHK and SDWAPTX2 are on, indicating that the program interrupt occurred while within transactional execution, this field contains the full 64-bit contents of the general purpose registers that result from the transaction abort.
- SDWATXPSW16
- When bits SDWAPCHK and SDWAPTX2 are on, this field contains the 16-byte PSW that results from the transaction abort.