All IEASDUMP.QUERY exits that are defined receive control when
another system in the sysplex requests an SVC dump on this system
using:
- An SDUMPX macro with a REMOTE parameter and with or without a
PROBDESC parameter.
- A DUMP command with a REMOTE parameter and with a PROBDESC parameter.
The IEASDUMP.QUERY exit on the local system,
which is the system requesting the dumps, also receives control if
PROBDESC=SYSDLOCL is specified and if the local system is included
in the systems specified by SYSLIST or GRPLIST through the REMOTE
parameter.
The IEASDUMP.QUERY exit receives control before the system obtains
the areas to be dumped. The exit receives control in one of the following
address spaces:
- In the address space represented by the STOKEN
parameter, if STOKEN was specified on the CSVDYNEX REQUEST=ADD
macro that installed the routine.
- In the address space represented by the job specified
in the JOBNAME parameter, if JOBNAME was specified on the CSVDYNEX
REQUEST=ADD macro. If several jobs have the specified job name, the
exit gets control in only one of the address spaces, unless another
of those address spaces is also identified by the STOKEN on another
of the CSVDYNEX REQUEST=ADD macros. For example:
- CSVDYNEX REQUEST=ADD for exit R1 and with STOKEN=x, which is for
ASID 002F.
- CSVDYNEX REQUEST=ADD for exit R2 and with JOBNAME=J. Both ASID
002E and 002F are for the job named J.
Exit R1 gets control only in ASID 002F. Exit R2 gets control
in both ASID 002E and 002F. However, if R1 had not been associated
with this exit, R2 would get control only in ASID 002E. To best limit
the address spaces in which the exit will run, use STOKEN rather than
JOBNAME.
- In address space ASID 0001 and in the address
spaces of any other IEASDUMP.QUERY exits, based on their STOKEN and
JOBNAME values, if neither STOKEN nor JOBNAME was specified.
IBM® recommends that you specify
an STOKEN parameter for an IEASDUMP.QUERY exit.. To obtain the STOKEN
for the home address space, issue an ALESERV macro with an EXTRACTH
parameter. To obtain the STOKEN for ASID 0001:
- Issue the macro LOCASCB ASID==H'1' to locate the address
space control block (ASCB) for ASID 0001. (The two equal signs are
needed.)
- Use the ASCBASSB field in the ASCB to locate the address space
secondary block (ASSB) for ASID 0001.
- Obtain the STOKEN for ASID 0001 from the ASSBSTKN field of the
ASSB.
The IEASDUMP.QUERY exit decides if its system should write an SVC
dump. The IEASDUMP.QUERY exit returns control with a return code
to indicate the actions to be taken.
If the return code indicates that a dump should be written, the
exit can add areas to be dumped, specifying them in the area mapped
by the IHASDMSE mapping macro. For example:
- Address spaces, specified in an area mapped by DSECT SDMSE_ASIDLST.
When used, place the address of this area in SDMSE_OUTPUT_ASIDLST_ADDR.
- Storage ranges, specified in an area mapped by DSECT SDMSE_STORAGE.
When used, place the address of this area in SDMSE_OUTPUT_STORAGE_ADDR.
- Jobs, specified in an area mapped by DSECT SDMSE_JOBLIST. When
used, place the address of this area in SDMSE_OUTPUT_JOBLIST_ADDR.
- Data spaces, specified in an area mapped by DSECT SDMSE_DSPLIST.
When used, place the address of this area in SDMSE_OUTPUT_DSPLIST_ADDR.
- Subpools, specified in an area mapped by DSECT SDMSE_SUBPLST.
When used, place the address of this area in SDMSE_OUTPUT_SUBPLST_ADDR.
- Keys for the subpools, specified in an area mapped by DSECT SDMSE_KEYLIST.
When used, place the address of this area in SDMSE_OUTPUT_KEYLIST_ADDR.
- SDATA options, specified in the SDMSE_SDATA_OPTIONS fields.
The exit can place data to be dumped in a 4096-byte workarea supplied
by the system; the address of the workarea is in the SDMSE_INPUT_WORKARE_ADDR
field. If the exit requires more storage, the exit should request
it with a GETMAIN or STORAGE OBTAIN macro and describe it as follows:
- Its address in the SDMSE_OUTPUT_WORKAREA_ADDR field.
- Its length in the SDMSE_OUTPUT_WORKAREA_LENGTH field.
- Its subpool in the SDMSE_OUTPUT_WORKAREA_SUBPOOL field.
- Its key in the SDMSE_OUTPUT_WORKAREA_KEY field. Make sure that
the key is in bits 0-3 of the 8-bit field. For example, if using
key 1, set the field to X'10'.
Upon return from the routine, the system releases the storage described
by these fields.
Code the IEASDUMP.QUERY exit to be reentrant.
Immediate and Deferred Local Dump:
For the local system that requests the dumps, you can obtain two related
dumps: an immediate dump containing current problem data and a deferred
dump containing areas added by the IEASDUMP exits.
Specify the immediate and deferred dumps as follows:
- Specify the local system in SYSLIST or GRPLIST through the REMOTE
parameter of the DUMP command or SDUMPX macro. You can specify the
local system explicitly or with wildcards. For example, an * indicates
all systems. SY? indicates the local system if it is named, for example,
SY1.
- Specify SYSDCOND and SYSDLOCL keys on the PROBDESC parameter of
the DUMP command or in the PROBDESC area for the SDUMPX macro.
When you specify the preceding for four systems, SY1, SY2, SY3,
and SY4, with SY1 as the system requesting the dumps, the results
are:
- An SVC dump is requested on SY1.
- SY1 requests dumps on SY2, SY3, and SY4, and also on SY1.
- On SY2, SY3, and SY4, dump processing begins. If any IEASDUMP.QUERY
exit returns 0, a dump is written for the system.
- On SY1, dump processing also begins. If any IEASDUMP.QUERY exit
returns 0, a dump is written.
The total dumps requested are five, two on system SY1 and one each
on systems SY2, SY3, and SY4.