Symptoms provided by a recovery routine

DAE attempts to construct a unique symptom string using specific data that your recovery routine can provide in the SDWA or through a symptom record. For an SVC dump, or a Transaction dump, the symptom record is passed in the SDUMPX or IEATDUMP macro. For a SYSMDUMP, place the symptom record in the ABDUMP symptom area.

To provide symptoms for an SVC dump, do one or more of the following in a recovery routine:

Place data in the SDWA, which is mapped by the IHASDWA mapping macro.
In an authorized program, provide a symptom record through a SYMREC parameter on the SDUMPX or SDUMP macro. The symptom record is built using SYMRBLD and mapped by the ADSR mapping macro.
In an authorized or unauthorized program, provide a symptom record through a SYMREC parameter on the IEATDUMP macro. The symptom record is built using SYMRBLD and mapped by the ADSR mapping macro.
Use a VRADATA macro to place information in the SDWA variable recording area (VRA), which is mapped by the IHAVRA mapping macro. The VRA is used:
- To supply additional symptoms for the symptom string.
- To provide secondary symptoms that give problem data not given in the SDWA; for example, the identity of the caller of a service.
Use VRADATA when the standard symptom data is insufficient to determine if a dump for the program is a duplicate.

For information about coding the VRADATA macro to add data to the SDWA, see z/OS MVS Programming: Assembler Services Reference IAR-XCT. For more information about symptom records, see Reporting symptom records (SYMRBLD and SYMREC macros). For more information about recovery routines, see Writing recovery routines.

VRADATA macro: Use the VRAREQ key to tell DAE that the symptom is required and the VRAOPT key to tell DAE that the symptom is optional.

A VRADATA macro with VRAREQ adds a symptom following the two required symptoms (see the previous table). For example, to add a symptom, in this case the name of a data set, and to define the symptom as required:

VRADATA KEY=VRAREQ,DATA=TAG1,LEN=L'TAG1
VRADATA KEY=VRADSN,DATA=MYDSN,LEN=L'MYDSN
⋮
TAG1   DC  AL2(VRADSN)
MYDSN  DC  C'DEPT27.PAYROLL'

A VRADATA macro with VRAOPT adds an optional symptom following the optional symptoms (see the previous table). For example, to add an optional symptom with the data at the address in register 5, and to define the symptom as optional:

LA  R5,VRAOPTKEY
VRADATA KEY=VRAOPT,LEN=2,DATA=(5)
VRADAYA KEY=VRACA,DATA=PGMCALLR
⋮
VRAOPTKEY DC AL2(VRACA)
PGMCALLR  DS  A

If the symptom is to be the caller's address, the data pointed to would consist of X'003C', which represents the key VRACA.

See z/OS MVS Diagnosis: Reference for the VRADATA keys.

Required symptom data: The recovery routine must provide the following minimum data to enable dump suppression by DAE:

SDWA Field	Data	Example
SDWAMODN	Failing module name	IEAVTCXX
SDWACSCT	Failing CSECT name	IEAVTC22
SDWACID	Product or component identifier	SCDMP
SDWACIB	Component identifier base	5655
SDWAREXN	Recovery routine name	IEAVTC2R
SDWASC	Subcomponent or module subfunction	RSM-PGFIX

To obtain the failing module name, the failing CSECT name, and the recovery module name, the recovery routine can set up a RECPARM parameter list and specify it on a SETRP macro. For information, see the RECPARM parameter of the SETRP macro in z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO.

Correct module and CSECT names: Obtaining the correct module and CSECT names may be difficult, especially when the PSW does not point within the program areas. Problems can also occur when the program uses the following:

User exits: When the program calls a user exit, which in turn invokes system services, such as getting a lock, the recovery routine often cannot identify the exit as the failing module and CSECT. To avoid this problem, the program should save the name of the user exit, so that the recovery routine can use the saved name.
Common recovery routines: The program should maintain footprints or require that all modules using a common recovery routine update a common parameter list with the name of the current module, CSECT, subfunction, and so on. The recovery routine can obtain data from the common parameter list when filling in the SDWA.

Symptoms: When you provide symptom information, select each symptom carefully. If a symptom is too precise, no other failure will have that symptom; if the symptom is too general, many failures will have the same symptom. For example, do not use addresses as symptoms; instead, use names of modules and components.

DAE accumulates up to 20 specified required and optional symptoms and up to 20 additional symptoms, if specified. The maximum string length is 150, so that not all of the additional symptoms may appear in the string. A recovery routine can change the minimum number of symptoms and the minimum string lengths that DAE is to use for symptom matching for a particular dump. To make these changes, code the following VRADATA macro keys in the recovery routine:

The VRAMINSC key controls the minimum number of symptoms.
The VRAMINSL key controls the minimum string length.

Control of suppression: When the ADYSETxx parmlib member being used by the installation contains SUPPRESS, a recovery routine must indicate that enough data is available to suppress a duplicate dump. To indicate to DAE that the SDWA contains enough data, set the VRADAE indicator in the SDWA variable recording area by issuing the following:

VRADATA KEY=VRADAE

If the recovery routine cannot provide enough data in the SDWA suppression, the recovery routine should indicate that its dump is not eligible for suppression, even when the ADYSETxx member contains SUPPRESSALL. The routine should set the VRANODAE indicator by issuing the following:

VRADATA KEY=VRANODAE

The VRANODAE key is useful for error environments that generate identical symptoms but represent different problems.