IEASDUMP.QUERY dynamic exit processing

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.

Parent topic: IEASDUMP.QUERY dynamic exit