Description

The requirements for the caller with BRANCH=NO are:

The requirements for the caller with BRANCH=YES are:

• To run in 64-bit addressing mode, issue the SYSSTATE AMODE64 variable set to 'YES' prior to invoking SDUMPX.
• For AR mode callers:
  • Issue the SYSSTATE ASCENV=AR macro before SDUMPX. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
  • The parameter list address must be qualified by an ALET of zero.
• To generate reentrant code, code the list and execute forms of the SDUMPX macro. Because the execute form of the macro is dependent on the length determined by the list form, the list form must appear before the execute form in a reentrant program.
  Callers can determine the length of the parameter list by using the following programming technique to calculate the amount of storage needed for only those options specified for the SDUMPX macro:

  SDMPXBEG SDUMPX SDATA=(SUM),SUMLIST=SLIST,MF=L
  SDMPXEND EQU   *
  SDMPXLEN DC    A(SDMPXEND-SDMPXBEG)

• The TCBOWNS option defaults to using a PLISTVER=3 sized parameter list for the standard and execute forms, so ensure that a parameter on the list version of the macro results in a PLISTVER=3 sized area.

Callers that issue SDUMPX with BRANCH=YES must include the CVT mapping macro.

1. The parameter list and all non-register notation keyword address parameters must reside in 31-bit addressable virtual storage, including for invokers that are executing in 64-bit addressing mode.

   Note: This restriction applies to macro keyword values that address the invoker-specified SDUMPX control information. For certain parameters, the content of the virtual storage addressed by a runtime keyword value may include virtual storage addresses above 2 gigabytes. For example, the LIST64 parameter must address a storage location residing in 31-bit addressable virtual storage, but the list content at that storage location may, in turn, address 64-bit addressable virtual storage.
2. The areas associated with the following parameters must be in common storage which must not be freed until the data capture for the dump is complete:
   • DSPLIST (when the area exceeds 512 bytes)
   • JOBLIST
   • PROBDESC
   • REMOTE
   • SUMLSTA (for BRANCH=NO invocations)

Before issuing the SDUMPX macro, the caller does not have to place any information into an access register (AR).

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

None.

The standard form of the SDUMPX macro is written as follows:

The parameters are explained as follows:

,ASID=ASID addr

,ASIDLST=list addr

Specifies the address of a halfword or a list of halfwords containing the hexadecimal address space identifier of an address space to be dumped. If register notation is used, the low-order halfword of the register contains the address space identifier of the address space to be dumped. If both parameters are omitted, the primary address space is dumped. If 0 is specified for the address space identifier, a dump is scheduled for the home address space of the issuer of the SDUMPX macro. No private area storage is included in the dump for the specified address space if either of the following events occurred:

• No SDATA parameters were specified that apply to the private area of the requested address space.
• The CHNGDUMP operator command was used to set an overriding parameter in the system dump options list that limits SVC dumps to areas outside of the private area.

The ASID list can contain a maximum of 15 address space identifiers. The high-order bit of the halfword containing the last identifier of the list must be set to 1, and all other high-order bits must be set to 0.

If the combined address spaces from the following exceed 15, the system dumps the first 15.

• Specified by the ASID or ASIDLST parameter
• Associated with the jobs specified in the JOBLIST parameter
• Associated with each data space specified in the DSPLIST, LISTD, or LIST64 parameter when the data space was created by a DSPSERV CREATE macro with SCOPE=SINGLE
• Associated with the address ranges specified in the LISTD or LIST64 parameter

Wildcards used in the parameters can result in multiple address spaces.

,BRANCH=NO

,BRANCH=YES

Specifies that a branch entry is to be used for interfacing with SVC dump to schedule a dump (YES), or that an SVC instruction is to be generated for interfacing with SVC dump (NO).

For BRANCH=YES, MVS produces a scheduled (asynchronous) SVC dump. For BRANCH=NO, the parameters you code to identify storage determine whether MVS produces a scheduled or synchronous SVC dump. MVS produces a scheduled dump when you code BRANCH=NO with one or more of the following:

• ASID=asid addr
• ASIDLST
• JOBLIST
• LISTA
• LISTD=list addr, when the STOKEN represents either an address space other than the primary address space, or a SCOPE=SINGLE data space owned by a program that is not running in the primary address space
• LIST64=list addr, when the STOKEN represents either an address space other than the primary address space, or a SCOPE=SINGLE data space owned by a program that is not running in the primary address space
• SUBPLST=subpool id list addr, when the list of address spaces with associated subpool IDs contains at least one address space other than the primary address space.
• TYPE=XMEM or TYPE=XMEME

You might make different design decisions for your program based on the type of dump MVS produces. See z/OS MVS Programming: Authorized Assembler Services Guide for guidance about designing your program to handle each type of dump.

If BRANCH=YES is specified and the caller has not specified at least one of the following keywords: ASID, ASIDLST, JOBLIST, TYPE=XMEM, TYPE=XMEME, or LISTA, the dump is scheduled to the home address space.

Routines that issue SDUMPX with BRANCH=YES must provide a 72-byte save area pointed to by register 13, and must include the CVT mapping macro.

For BRANCH=YES entry by reentrant recovery routines, SDUMPX processing moves the data supplied by the following parameters to a system area:

• HDR
• HDRAD
• ID
• IDAD
• ASIDLST
• STORAGE
• LIST
• LISTA
• SUBPLST
• KEYLIST

This enables the recovery routine to free its storage on return from SDUMPX although the dump has not completed.

,BUFFER=NO

,BUFFER=YES

Specifies that the contents of a 4096 byte SQA buffer is (YES) or is not (NO) reserved and used by the caller before SDUMP processing was invoked. Callers who specify BUFFER=YES on the SDUMPX macro must have reserved it for usage and properly initialized it before the SVC dump processing is invoked. If the caller is using the buffer to dump data that might change before normal SVC dump processing can dump it, the caller should instead consider using the SUMDUMP option of the SDATA parameter and one of the SUMLIST related parameters to dump that data. SUMDUMP provides far greater capacity for data capture.

The SQA buffer is pointed to by the CVTSDBF field of the Communications Vector Table (CVT). To reserve the SQA buffer area, use the compare and swap (CS) instruction to serialize the setting of the high-order bit of the CVTSDBF field. Setting of that bit prevents any other SDUMP requests from being processed. It essentially indicates the beginning of SVC dump processing, and only one SVC dump can be active in the system at a time. If the CS fails to set the bit on (B'1'), the buffer is already in use; processing should neither attempt to use the buffer, nor issue the SDUMPX request. If the bit was successfully set to B'1' by the CS instruction, the caller must also set the ASCBSDBF bit of the home address space ASCB (Address Space Control Block) using a CS instruction. When both operations were successful, the caller can place data into the buffer and issue the SDUMPX request. If the caller sets either bit, and then fails to invoke SDUMPX, it must reset the bit(s) that it set (resetting the ASCBSDBF bit first, then the CVTSDBF high order bit). If the home address space of the caller terminates after the setting of the ASCBSDBF bit, or once SVC dump processing has begun, SVC dump processing will reset both bits appropriately.

When the dump is being processed by IPCS, the contents of the SQA buffer is accessible for BUFFER=YES dumps by using the IPCS LIST 0 DOMAIN(SDUMPBUFFER) LENGTH(4096) command.

,DCB=dcb addr

Specifies the address of a previously opened data control block (DCB) for the data set that is to contain the dump. If this parameter is omitted, one of the SYS1.DUMP data sets is used. When you specify the DCB parameter, the dump contains data from only the requestor's home address space. The DCB must be addressable from the home address space. The control blocks built by OPEN must also be addressable from the home address space. The DCB must support EXCP. You must specify the following parameters on the DCB macro: RECFM=FB, LRECL=4160, and BLKSIZE=4160.

The DCB must reference device types supported by SVC dump. Eligible device types are unlabeled 9-track 2400-series tape devices (or tape devices compatible with the 2400-series) and any direct access devices supported by the system that have a track size of at least 4160 bytes. (4160 bytes equals 1 SVC dump output record.) SVC dump does not support secondary extents on DCB data sets.

SVC dump does not close the dump data set. Use the CLOSE macro to close the data set and cause an end-of-file mark or a tape mark to be placed after the dump data. SVC dump sets up the DCB so that CLOSE works correctly and positions the end-of-file mark or tape mark at the correct place on the data set. For tape data sets, you can write a tape mark to separate multiple dumps without using the CLOSE macro.

Because it is the caller's responsibility to close the dump data set and the data set may be closed only after all the data has been written to it, the caller needs to receive notification when the dump writing phase is complete. Therefore, if you specify the DCB parameter with the ECB parameter, the system posts the ECB at the completion of the dump writing phase, no matter what has been specified on the ECB parameter. The ECB parameter is required when a DCB is provided for scheduled dumps. If an ECB is not provided with the DCB for a synchronous dump, SVC dump returns to the caller at the completion of the dump writing phase. See z/OS MVS Programming: Authorized Assembler Services Guide for descriptions of scheduled and synchronous dumps.

,DSPLIST=list addr

Specifies the address of an area that identifies the data space information to be dumped. Hiperspaces are not supported so they will not be dumped. If the area exceeds 512 bytes, the area must be in common storage and the caller must not free the area until data capture for the dump is completed. For an asynchronous dump, use the ECB or SRB parameter to be notified when data capture is completed or use the SUSPEND parameter to suspend other processing until data capture is completed. For a synchronous dump (only one address space and its data spaces involved), you do not need to worry about freeing the area too soon because the system does not return control to the caller until data capture is completed. Additionally, the number of data spaces that can be handled is limited to 256. If wildcard specifications are used, only the first 256 data spaces that match can be dumped. Also, each data space reduces the number of LISTD entries available by one. If register notation is used, the register contains the address of the area. If the parameter is omitted, data spaces are not dumped.

The area consists of:

• A 4-byte header, which indicates the total length of the area. The length includes the four bytes of the header.

  If the length is less than four bytes, the system ignores the DSPLIST parameter.

• One or more 16-byte data space identifiers for data spaces to be included in the dump. An identifier is an ASID or jobname in the left 8 bytes and the data space name in the right 8 bytes:

  ASID

  An 8-byte field containing an explicit hexadecimal address space identifier in bytes 7 and 8. Bytes 1 through 6 must be hexadecimal zeros.

  jobname

  A 1 to 8 character job name left-justified in the 8-byte field. Pad it on the right with blanks, if needed. The job name can be specified with wildcards. See Wildcards.

  data space name

  The 1 to 8 character name associated with the data space at its creation. Left justified in the 8-byte field. Padded on the right with blanks if needed. The data space name can be specified with wildcards. See Wildcards.

See the ASID parameter for the limit on address spaces that can be specified.

,ECB=(ecb addr[,[CAPTURE|WRITE][,TCBOWNS]])

Specifies how the system should synchronize your program with dump processing. Note that these interfaces will not be driven if the call to SDUMPX results in an initial non-zero return code. When the initial return code is zero, the return code for capturing the data is available as documented when the TYPE=FAILRC parameter is used.

ECB specifies that the system should post the event control block (ECB) indicated by ecb addr. If an A-type address is specified, ecb addr specifies the address of a fullword containing the address of an ECB that is posted on completion of a scheduled dump. If a register operand is used, the register must contain the actual address of the ECB. If this parameter is omitted, the caller is not notified of the dump completion. The fullword and the ECB must be addressable from the home address space. The fullword address that points to the ECB must be a 24-bit or 31-bit address.

For ECB=ecb addr and ECB=(ecb addr,CAPTURE), the system posts the ECB at the completion of the capture phase, unless the DCB parameter was also specified. When both the DCB and ECB parameters are specified, CAPTURE is ignored. So for that case, and for ECB=(ecb addr,WRITE), the system posts the ECB at the completion of the writing phase. If the capture phase is not successful, the system posts the ECB at the completion of SVC dump processing. Include the TYPE=FAILRC parameter in order to receive a return code and reason code at dump completion.

The storage for the supplied ECB must always be available for SVC dump processing to post. Once the ECB has been posted, the storage may be explicitly freed. There are two recovery scenarios where the ECB storage may be freed before SVC dump processing can post it. One is when the requestor's address space terminates. The other relates to task termination when the TCBOWNS option of the ECB parameter is specified. This indicates to SDUMP processing that the task requesting the SDUMP owns the ECB storage. Otherwise, the ECB should be in ELSQA/LSQA or common storage, and its availability managed appropriately.

HDR=‘dump title’

HDRAD=dump title addr

Specifies the title or address of the title to be used for the dump. If HDR is specified, the title must be 1-100 characters enclosed in apostrophes, although the apostrophes do not appear in the actual title. If HDRAD is specified, the first byte at the indicated address specifies the length of the title in bytes.

If the length of the title is greater than 100, SVC dump issues an abend with a completion code of X'233', reason code X'14', then returns to the caller with a return code of 8. If the length of the title is zero, SVC dump continues processing as if the HDR or HDRAD parameter was not specified.

If these keywords are specified with BRANCH=YES or ASID/ASIDLST (that is, to cause a scheduled dump), the system moves the title to SVC dump storage before it returns control to the caller. There is no requirement to synchronize with the completion of the dump.

,ID='identifier'

,IDAD=identifier addr

Specifies an identifier that is included in the dump message IEA911E or IEA611I, which is issued at the completion of the dump. The identifier must be from one to 50 printable characters. If ID is specified, the identifier must be enclosed in apostrophes, although the apostrophes do not appear in the actual identifier. If IDAD is specified, the first byte at the indicated address specifies the length of the identifier in bytes. If the length of the identifier is greater than 50, SVC dump issues an abend with a completion code of X'233', reason code X'8C', then returns to the caller with a return code of 8. If the length of the identifier is zero, SVC dump continues processing as if the ID or IDAD parameter was not specified.

,INTOKEN=token addr

Specifies the address of a 32-byte area that contains an incident token previously built by an IEAINTKN macro. If register notation is used, the register contains the address of the area.

The system associates the token with the SVC dump on this system and with any SVC dumps requested by the REMOTE parameter on other sysplex systems. If the parameter is omitted, the system generates an incident token.

,JOBLIST=list addr

Specifies the address of an area that identifies jobs to be dumped. If register notation is used, the register contains the address of the area. If the parameter is omitted, the current job is dumped.

The area, which must be in common storage and should never be larger than 124 bytes (8 bytes × 15 entries + 4-byte header), consists of:

• A 4-byte header, which indicates the total length of the area. The length includes the 4 bytes of the header.

  If the area exceeds 256 bytes, the caller must not free the area until data capture for the dump is completed. For an asynchronous dump, use an ECB or SRB parameter to be notified when data capture is complete or use a SUSPEND parameter to suspend other processing until data capture is completed. (For a synchronous dump on the local system, you do not have to worry about freeing the area too soon because the system does not return control to the caller until processing completes.)

  If the length is less than 4 bytes, the system ignores the JOBLIST parameter.

• One or more 8-character job names for jobs to be included in the dump. Left justify each name in its 8-character field; pad it on the right with blanks, if needed. A job name can be specified with wildcards. See Wildcards.

You can specify a maximum of 15 job names. See the ASID parameter for the limit on address spaces that can be specified.

,KEYLIST=storage key list addr

Specifies the address of a list of storage keys associated with the virtual storage to be dumped. If the key of a subpool specified in SUBPLST does not match a key in this list, the data in the subpool is not dumped. SUBPLST must be specified if the KEYLIST option is used. If you do not specify KEYLIST, all storage (regardless of key) associated with the requested subpools is included in the dump. Therefore, if you want to dump the storage corresponding to all 16 keys, do not specify this parameter.

The list contains one-byte entries and starts on a halfword boundary. The first byte indicates the length of the list (including this byte). The list has a maximum length of 16 bytes so that up to 15 keys can be specified. Specify each key in the left-most four bits of each byte, except the length byte.

,LIST=(strt addr,end addr)

,LISTA=list addr

,LISTD=list addr

,LIST64=listaddr

Specifies one of the following lists:

• A list of starting and ending addresses (LIST)
• A list of ASIDs and storage ranges (LISTA)
• A list of address ranges, qualified by STOKENs, of areas to be included in the SVC dump (LISTD)
• A list of virtual storage address ranges, qualified by STOKENs, of areas to be included in the dump (LIST64)

Each starting address must be less than its corresponding ending address.

LIST

When LIST is specified, the list must contain an even number of addresses, and each address must occupy one fullword. In the list, the high-order bit of the fullword containing the last ending address of the list must be set to 1; all other high-order bits must be set to 0.

LISTA

When LISTA is specified, the first fullword of the storage list contains the number of bytes (including the first word) in the list. LISTA specifies a list of ASIDs and storage ranges, as follows:

Note: If LISTA or SUBPLST is specified for a scheduled dump request and if the list does not exceed 484 bytes in size, SVC dump will move the list to SVC dump storage. The caller can free or reuse this space on return from SVC dump. No synchronization with SVC dump completion is required. If the list exceeds 484 bytes, SVC dump will not move the list and synchronization with SVC dump completion is required.

LISTD

When LISTD is specified, the first fullword of the list contains the number of bytes (including the first word) in the list. The list can be up to 5124 bytes (for a possible 256 single range entries). The number of entries processed will be fewer than 256, if either data spaces are requested using the DSPLIST parameter, or multiple ranges are specified for an STOKEN. For LISTD, specify the STOKENs and address ranges as follows:

STOKEN refers to any address/data space. SVC dump does not dump data space storage that has not been referenced.

LISTD causes a scheduled dump when the caller performs one of the following actions:

• Requests a SCOPE=SINGLE data space that is owned by a task in an address space other than the caller's primary address space.
• Requests an address space other than the primary

See the ASID parameter for the limit on address spaces that can be specified.

Dumps on other systems in a sysplex: If the SDUMPX macro specifies SDRMT_IDCON_STORAGE_COPY in the area specified by the REMOTE parameter, the dumps requested by REMOTE contain areas specified by LISTD on this macro; the dumps do not contain areas specified by LIST and LISTA. If an STOKEN is all zeros in the area specified by the REMOTE parameter, the dumps include the indicated address range within all address spaces included in the dump.

If the LISTD area exceeds 484 bytes, only the data requested in the first 484 bytes is included in the dumps requested by REMOTE.

LIST64

Specifies a storage location describing a list of STOKEN-qualified virtual storage address ranges to be included in the dump.

The address ranges are described with 64-bit starting and ending addresses and may refer to any address space virtual storage, including virtual storage above the 2 gigabyte bar and any data space storage.

The LIST64 parameter is mutually exclusive with the LISTD parameter.

When LIST64=list addr is specified, the first fullword of the storage list contains the number of bytes, including the first word, in the list.

SDUMPX behavior for the LIST64 keyword is the same as LISTD behavior when REMOTE is also specified. Prior releases will ignore 64-bit addresses in a remote list.

The LIST64 storage list format is exactly analogous to the LISTD storage list format, and the STOKENs and address ranges as follows:

• A range's ending address must be greater than its starting address for each specified range.
• The ending address for any data space range cannot exceed X'000000007FFFFFFF'.
• If any STOKEN in the list describes a SCOPE=SINGLE data space, or is for an address space other than the SDUMPX invoker's primary address space, then a scheduled dump is performed.

See the ASID parameter for the limit on the number of differing address spaces that can own virtual storage included in the dump.

,PLISTVER=1

,PLISTVER=2

,PLISTVER=3

Specifies the length of the parameter list used:

• For PLISTVER=1, the length is up to 112 bytes.
• For PLISTVER=2, the length is 128 bytes.
• For PLISTVER=3, the length is 184 bytes.

Defaults are as follows:

• When you specify SYMREC, ID, IDAD, PSWREGS, SDATA=DEFS, SDATA=NODEFS, or SDATA=IO, the default is PLISTVER=2.
• When you specify STRLIST, REMOTE, INTOKEN, PROBDESC, JOBLIST, DSPLIST, LIST64, SUMLIST64, or ECB=(*,*,TCBOWNS), the default is PLISTVER=3.
• For other specifications, the default is PLISTVER=1.

Note: When the TCBOWNS option is specified for the ECB parameter of the EXECUTE form of the macro, use PLISTVER=3 when specifying MF=L to generate a 184-byte parameter list.

,PROBDESC=area addr

Specifies the address of an area that contains information describing the problem. If register notation is used, the register contains the address of the area.

The area can be passed to any SVC dump, but is primarily intended for dumps requested by the REMOTE parameter. When a dump is requested through REMOTE, the system being dumped calls an IEASDUMP.QUERY routine. The routine uses the area to determine if its system should be dumped and, if so, what storage areas should be added to the dump.

The area is mapped by the IHASDPD mapping macro and must be in common storage. The area consists of:

• A 4-byte header, which indicates the total length of the area. The length includes the 4 bytes of the header.
• Key, length, data entries. Each entry consists of:

  Key

  An 8-byte key, which you can use to identify the application or the problem or both. You might use the key field, for example, to contain a 3-byte identifier for the application and a 5-byte area for application information.

  The key corresponds to the SDPD_KLD_KEY field in the IHASDPD mapping macro. The key must not begin with A through I or SYS; these are reserved for IBM use. IBM-supplied values for key are:

  • SYSDCOND: Suppresses a dump on another system in a sysplex if the other system does not have an IEASDUMP.QUERY routine or if no IEASDUMP.QUERY routine returns a code of 0.
  • SYSDLOCL: Requests a second, deferred dump of the local system, if the area for the REMOTE parameter specifies the local system. The deferred dump contains areas added by IEASDUMP.QUERY, IEASDUMP.GLOBAL, and IEASDUMP.LOCAL exit routines, if any routines had been associated with those exits.

  Length

  A 2-byte field that gives the length of the data portion. The length does not include the length of this field itself or of the key field. A length of zero is valid.

  Data

  The data portion, which consists of the number of bytes specified in the preceding field. You can place in the data portion any information you desire in any format.

If the area exceeds 1024 bytes, the caller must not free the area until data capture for the dump is completed. For an asynchronous dump, use an ECB or SRB parameter to be notified when data capture is complete or use a SUSPEND parameter to suspend other processing until data capture is completed. (For a synchronous dump on the local system, you do not have to worry about freeing the area too soon because the system does not return control to the caller until processing completes.) If the area exceeds 32,768 bytes, the system places in the dump only the first 32,768 bytes.

If the length is less than 4 bytes, the system ignores the PROBDESC parameter.

,PSWREGS=list addr

Specifies a PSW or register area to be passed to SVC dump. This area may contain a PSW, control registers 3 and 4, all the general purpose registers (GPRs), and all access registers (ARs). When PSWREGS is specified, SVC dump includes the following information in the summary dump portion of the dump:

• The PSWREGS parameter list.
• If the PSW is provided, 4K of storage before and 4K after the PSW address from the primary address space.
• 4K of storage before and 4K of storage after each of the GPRs from the primary and secondary address spaces.
• If the ARs are provided, they qualify the addresses of the area that includes the 4K of storage before and 4K of storage after each of the GPRs. GPRs will be used to locate storage; ARs (if provided along with a PSW in AR mode) will be used to identify the source address space or data space.

Notes:

1. If the control registers are provided, they will be used to determine the primary and secondary address spaces. If no control registers are provided, then the storage will be dumped from the caller's primary and secondary address spaces.
2. The content of the storage location specified by PSWREGS parameter can include both the high-order and low-order halves of the GPRs.

The PSWREGS parameter allows programs running in a non-abend environment, where there is no SDWA, to request SVC dump and dump suppression services similar to those available in an abend environment, where an SDWA is present.

The parameter list for the PSWREGS parameter must reside in the address space currently addressable by SVC dump. The caller must provide at least the length and the mask field. Each bit in the mask refers to a data area.

• If a mask bit is set, SVC dump expects that the data area and the appropriate size in the length field to be supplied.
• If a mask bit is off , but any lower-order mask bit is on, the corresponding storage area must still be included in the parameter list, and the total length specified must match the entire area. For instance, if only general purpose registers are specified. Set bit 3 on, store the register values starting at X'14' into the parameter list, and set the total length to 84 (64 + 8 + 8 + 2 + 2). This total length is the same whether or not the user wants to supply PSW or control registers 3 and 4 information.

The following describes the expected length of the entire parameter list relative to the highest bit set in the mask:

• If bit 5 is set (indicating that the high halves of the general purpose registers are included in the PSW/register area), the length must be 212 bytes, even if bit 3 is the only other bit set.
• If bit 4 is set (indicating ARs are included), the length must be 148.
• If bit 3 is set (GPRs are included), the length must be 84.
• If bit 2 is set (CRs are included), the length must be 20.
• If bit 1 is set (PSW is included), the length must be 12.
• If none of the bits are to be set ('nothing' is indicated), the length must be 4.

Table 1 describes the PSWREGS parameter list.

Table 1. PSWREGS parameter list

Offset (in hex)	Length	Field description
00	2	The total length of the PSWREGS parameter list
02	2	Bit mask describing data areas included in the PSW/register area
	1... ....	Bit 1: On - The PSW is included in the PSW/register area
	.1.. ....	Bit 2: On - Control registers 3 and 4 are included in the PSW/register area
	..1. ....	Bit 3: On - General purpose registers are included in the PSW/register area
	...1 ....	Bit 4: On - ARs are included in the PSW/register area.
	.... 1...	Bit 5: On - High halves of general purpose registers are included in the PSW/register area.
		Bits 6 - 16: Initialize these bits to zero.
04	8	PSW: Data only supplied if the PSW mask bit is set
0C	8	Control registers 3 and 4: Data only supplied if mask bit is set.
14	64	General purpose registers 0 - 15: Data only supplied if mask bit is set.
54	64	ARs 0 - 15: Data only supplied if mask bit is set.
94	64	High halves of general purpose registers 0 - 15: Data only supplied if mask bit is set

In addition to dumping virtual storage areas around the general purpose registers using 31-bit addresses, if the high order register halves are also specified then SDUMP will also dump the anologous virtual storage areas addressed by the resulting 64-bit register contained addresses using the same guidelines for dumping areas in the primary, secondary, home and access register qualified storage locations.

,QUIESCE=YES

,QUIESCE=NO

Specifies that the system is to be set nondispatchable until the contents of the SQA and the CSA are dumped (YES), or that the system is to be left dispatchable (NO). If the SDATA parameter does not specify SQA or CSA, the QUIESCE=YES request is ignored.

Notes:

1. Summary dumps (SUMDUMP) for branch entries (BRANCH=YES) always cause the system to be set nondispatchable until the summary dump is written.
2. A Q=YES|NO setting for the CHNGDUMP command overrides this parameter. For the use of the CHNGDUMP command, see z/OS MVS System Commands.

,REMOTE=area addr

Specifies the address of an area that identifies other systems in the sysplex to be dumped by this SDUMPX macro. If register notation is used, the register contains the address of the area. If the parameter is omitted, only the current system is dumped.

The area is mapped by the IHASDRMT mapping macro and must be in common storage. Through IHASDRMT, you can identify the systems to be dumped and specify the content of the dumps on individual systems. The area consists of:

• A 4-byte header, which indicates the total length of the area. The length includes the 4 bytes of the header.
• ID, length, contents entries. Each entry consists of:

  ID

  A 2-byte field, whose value identifies the type of the contents. The values are declared by the constants with names beginning with SDRMT_IDCON in the IHASDRMT mapping.

  Length

  A 2-byte field that gives the length of the contents portion. The length includes the 2 bytes of this length field and the 2 bytes of the ID field.

  Contents

  A variable field that gives the contents identified in the ID field. The contents you can specify are the system names, job names, XCF group and member names, data space names, address space identifiers, SDATA options, storage ranges, subpools, and keys. Within the contents, you can specify items explicitly or, for the following, use wildcards.

  • System name
  • Job name
  • XCF group name
  • XCF member name
  • Data space name and its qualifying job name

  See Wildcards.

If the area exceeds 1024 bytes, the caller must not free the area until data capture for the dump is completed. For an asynchronous dump, use an ECB or SRB parameter to be notified when data capture is complete or use a SUSPEND parameter to suspend other processing until data capture is completed. (For a synchronous dump on the local system, you do not have to worry about freeing the area too soon because the system does not return control to the caller until processing completes.)

If the length of the area is less than 4 bytes, the system ignores the REMOTE parameter. If the length of any of its entries is less than 4 bytes, the dump request returns with an error return code.

The dumps requested through REMOTE are affected by other parameters on the SDUMPX macro: LISTD, SDATA, ASIDLST, JOBLIST, DSPLIST, SUBPLST, and KEYLIST; you can specify that the values of these parameters be copied for the dumps requested through REMOTE. The dumps requested through REMOTE do not contain information for the LIST and LISTA parameters.

,SDATA=(sdata options)

Specifies the system is to dump the following:

Option

Data to be Dumped

ALLNUC

The DAT-ON and DAT-OFF nuclei. The read-only (page-protected) area of the nucleus and the DAT-OFF nucleus is not included in the dump unless this keyword is specified.

ALLPSA

All of the prefixed storage areas (PSAs) in the system.

COUPLE

Cross-system coupling facility (XCF) information

CSA

Dumps the following storage:

• The CSA and ECSA subpools (subpools 227, 228, 231, and 241)

  Only those obtained pages that have something stored into them are dumped. The dump does not include pages of storage that are in a freshly-obtained state.

• Virtual storage for 64-bit addressable memory objects created using one of the following services:
  • IARV64 REQUEST=GETCOMMON,DUMP=LIKECSA
  • IARCP64 COMMON=YES,DUMP=LIKECSA
  • IARST64 COMMON=YES,TYPE=PAGEABLE

GRSQ

Global resource serialization control blocks.

HCSAByASID

High virtual CSA storage that is owned by the ASIDs for which SDUMP captures data. See the ASID parameter for details about the ASIDs that are dumped.

Attention: When this option is specified alone, it might result in the inclusion of none of the above the bar CSA storage in the dump.

The following table describes how HCSAByASID, HCSANoOwner, and HCSASysOwner affect the CSA storage that is captured in an SVC dump:

HCSANoOwner

High virtual CSA storage for which the owner has ended.

Attention: When this option is specified alone, it might result in the inclusion of none of the above the bar CSA storage in the dump.

HCSASysOwner

High virtual CSA storage that belongs to the SYSTEM.

Attention: When this option is specified alone, it might result in the inclusion of none of the above the bar CSA storage in the dump.

Table 2. Effects on the CSA storage captured in an SVC dump

Specified SDATA option or options	CSA storage that is included in the dump
CSA	All above the bar and below the bar CSA storage
CSA, HCSAByASID, HCSANoOwner, HCSASysOwner	All below the bar CSA storage, high virtual CSA storage that is owned by the ASIDs that are included in the dump, high virtual CSA storage for which the owner has ended, and high virtual CSA storage that belongs to the SYSTEM. The dump does not include high virtual CSA storage that is owned by the ASIDs that are excluded from the dump.
HCSAByASID, HCSANoOwner, HCSASysOwner	All high virtual CSA storage that is owned by the ASIDs that are included in the dump, high virtual CSA storage for which the owner has ended, and high virtual CSA storage that belongs to the SYSTEM No below the bar CSA storage is included in the dump.
(Neither CSA nor any of the HCSAxxxx options)	None of the CSA storage is included in the dump.

LPA

The active link pack area modules and SVCs for each address space being dumped.

LSQA

Dumps the following storage:

• The LSQA and ELSQA for each address space being dumped (subpools 203-205, 213-215, 223-225, 233-235, and 253-255)
• Virtual storage for 64-bit addressable memory objects created using one of the following services:
  • IARV64 REQUEST=GETSTOR,DUMP=LIKELSQA
  • IARCP64 COMMON=NO,DUMP=LIKELSQA
  • IARST64 COMMON=NO

NOALLPSA

NOALL

The PSA for one processor is dumped. This is either the processor at the time of the error or the processor at the time of the dump.

NOSQA

The system queue area is not dumped.

NOSUMDUMP

NOSUM

A summary dump is not included in the SVC dump.

NUC

The non-page-protected areas of the DAT-ON nucleus. (The ALLNUC parameter must be specified to obtain the entire nucleus, including the page-protected areas of the DAT-ON nucleus and the DAT-OFF nucleus.)

PSA

The PSA for one processor is dumped. This is either the processor at the time of the error or the processor at the time of the dump.

RGN

Dumps the following storage:

• The allocated pages in the private area of each address space being dumped. This includes the following areas:

  Subpools	Storage
  0-127, 129-132, 229, 230, 240, 244, 249, 250-252	All storage allocated to these subpools
  203-205, 213-215, 223-225, 233-235, 253-255	All storage allocated to the LSQA and ELSQA
  236, 237	All storage allocated to the SWA and ESWA

  Only those obtained pages that have something stored into them are dumped. The dump does not include pages of storage that are in a freshly-obtained state. This reduces the number of page faults that occur during SVC dump processing, decreases the time required to take a dump, and reduces the size of the dump.

• Virtual storage for 64-bit user region memory objects created using the following services:
  • IARV64 REQUEST=GETSTOR,DUMP=LIKERGN
  • IARV64 REQUEST=GETSTOR,SVCDUMPRGN=YES
  • IARCP64 COMMON=NO,DUMP=LIKERGN
  • IARST64 COMMON=NO
• Data-in-virtual (DIV) pages are dumped when they have been changed since the last DIV macro (that specified the SAVE service) executed. DIV pages that have not been changed, are considered to be in a freshly-obtained state.

SERVERS

Client-related data in address spaces and dataspaces other than the client's should be added to the dump via IEASDUMP.SERVERS exit invocations. Note that this will convert synchronous dumps to asynchronous dumps.

SQA

Dumps the following storage:

• The SQA and ESQA subpools (226, 239, 245, 247, and 248)

  Only those obtained pages that have something stored into them are dumped. The dump does not include pages of storage that are in a freshly-obtained state.

• Virtual storage for 64-bit addressable memory objects created using one of the following services:
  • IARV64 REQUEST=GETCOMMON,DUMP=LIKESQA
  • IARCP64 COMMON=YES,DUMP=LIKESQA
  • IARST64 COMMON=YES,TYPE=FIXED
  • IARST64 COMMON=YES,TYPE=DREF

SUMDUMP

SUM

A summary dump is to be included with the SVC dump output. The trace table is included in the non-summary portion of the dump if this option is specified or used as a default.

The type of summary dump depends on how you specify the BRANCH and SUSPEND parameters:

• If you specify BRANCH=YES and SUSPEND=NO, you get a disabled summary dump.
• If you specify BRANCH=YES and SUSPEND=YES, you get a suspend summary dump.
• If you specify BRANCH=NO, you get an enabled summary dump.

For a description of the dump contents, see z/OS MVS Diagnosis: Tools and Service Aids.

SWA

The scheduler work area subpools for each address space being dumped (subpools 236 and 237). This includes all storage allocated above and below 16 megabytes.

TRT

The system trace table, the GTF trace records, and master trace data if these types of traces are active

XESDATA

Cross-system extended services (XES) information.

DEFAULTS

DEFS

The following default SDATA options are included in the SVC dump:

• ALLPSA
• SQA
• SUMDUMP
• IO
• Any default SDATA options specified by the CHNGDUMP command when CHNGDUMP is in ADD mode.

Notes:

1. DEFAULTS is not required. All SVC dumps include the default SDATA options unless NODEFAULTS is specified.
2. DEFAULTS and NODEFAULTS are mutually exclusive.

NODEFAULTS

NODEFS

The SDATA defaults are NOT included in the SVC dump. Specifying NODEFAULTS reduces the size of an SVC dump by excluding the following default SDATA options:

• ALLPSA
• SQA
• SUMDUMP
• IO
• Any default SDATA options specified by the CHNGDUMP command when CHNGDUMP is in ADD mode.

If a data area relating to an SDATA option is required in the dump, the programmer can code that SDATA option on the SDUMPX macro invocation. All keywords and SDATA options are valid when NODEFS is coded.

If you specify NODEFAULTS, the dump still contains some default system areas that are included in all dumps.

IO

The IO data areas are included in the SVC dump.

,SRB=(srb addr)

,SRB=(srb addr,CAPTURE)

,SRB=(srb addr,WRITE)

Specifies how the system should synchronize your program with dump processing. Note that these interfaces will not be driven if the call to SDUMPX results in a non-zero return code.

SRB specifies that the system should schedule the service request block (SRB) indicated by srb addr. For SRB=srb addr and SRB=(srb addr,CAPTURE), the system schedules the SRB at the completion of the capture phase unless you have also specified the DCB parameter. If you specify both the DCB and SRB parameters, the system schedules the SRB at the completion of the writing phase, no matter what has been specified on the SRB parameter. For SRB=(srb addr,WRITE), the system schedules the SRB at the completion of the dump writing phase. If the capture phase is not successful, the system schedules the SRB at the completion of SVC dump processing.

When the caller builds the SRB, the caller may pass the address of a status area in the SRBPARM field. This status area, SDSTATUS, is mapped by IHASDST. SVC dump passes information about the dump to the SRB routine by means of this status area. If SVC dump schedules the SRB at the completion of the capture phase, the name of the dump data set is not passed to the caller.

,STORAGE=(strt addr,end addr)

Specifies one or more pairs of starting and ending addresses. Each starting address must be less than its corresponding ending address.

When STORAGE is specified, the list must contain an even number of addresses, and each address must occupy one fullword. In the list, the high-order bit of the fullword containing the last ending address of the list must be set to 1. All other high-order bits must be set to 0.

,STRLIST=structure list addr

Specifies the address of an area that contains a dump parameter list. The list can contain lists of structures, ranges, and options to be dumped from a Coupling facility. Use the IHABLDP macro to build this list for input to SDUMPX. If any structure specified is not accessible or not eligible to be dumped, a partial dump occurs.

The size of the structure list can range from a minimum of 72 bytes to a maximum of 8K.

,SUBPLST=subpool id list address

Specifies a list of ASIDs with associated subpool ids corresponding to subpools of virtual storage that are to be included in the SVC dump.

The first fullword of the list contains the number of bytes (including the first word) in the list. The list can contain a maximum of 200 bytes consisting of unique ASIDs and subpool IDs. If the list contains duplicate ASIDs or subpool IDs, the length can exceed 200 bytes because SDUMPX stores the unique subpool IDs in a 200-byte work area.

The structure of the list for each ASID follows:

• The first word contains the ASID in bits 0-15 and the number of subpools associated with this ASID (n) in bits 16-31. If 0 is specified as the ASID, the caller's home ASID is used.
• The next n halfwords contain the subpool IDs (right justified) corresponding to the virtual storage to be included in the SVC dump. The manner in which these subpools are dumped depends on whether they are private or common area subpools.
  • If a private area subpool (related to a TCB) is specified, all virtual storage associated with this subpool, for all TCBs in the specified address space, is dumped.
  • If a common area subpool is specified, all of the virtual storage allocated in the subpool is dumped.

SVC dump does not dump all the obtained storage in an address space if the SUBPLST list keyword for private subpools is coded. This reduces the number of page faults that occur during SVC dump processing and the time required to take a dump. It also reduces the size of dumps on tape or DASD.

For storage that is not related to data-in-virtual, only obtained pages that have something stored into them are dumped. This eliminates the pages of storage that are in a freshly obtained state.

For storage that is related to data-in-virtual, only pages that are in central storage are dumped, as well as pages that have been changed since the last data-in-virtual SAVE operation.

Notes:

1. SVC dump ignores unassigned subpool IDs and ASIDs.
2. If an invalid subpool or ASID (ASID greater than ASVTMAXU) is specified, the caller receives a 233 ABEND and SDUMP processing terminates the dump.
3. If all ASIDs specified in SUBPLST are the current ASID, SUBPLST does not force a scheduled dump. However, if any of the ASIDs are different, a scheduled (or asynchronous) dump results.
4. SDUMPX callers executing in key 0 and supervisor state, who request storage from subpool 0 via GETMAIN obtain that storage from subpool 252 instead. Therefore, when these callers want to dump this storage, they must specify subpool 252 rather than subpool 0.

,SUMLIST=(strt addr,end addr)

,SUMLSTA=list addr

,SUMLSTL=list addr

,SUMLIST64=list addr

Specifies one of the following:

• A list of starting and ending addresses of areas to be included in a summary dump (SUMLIST).
• A combined list of ASIDs and storage ranges (SUMLSTA).
• A list of address ranges, qualified by ALETs, of areas to be included in a summary dump (SUMLSTL).
• A list of virtual address ranges, qualified by ALETs or STOKENs, of areas to be included in a summary dump (SUMLIST64).

SUMDUMP must be specified as an SDATA parameter and each starting address must be less than its corresponding ending address.

SUMLIST: For SUMLIST, the storage list must contain an even number of addresses, and each address must occupy one fullword. In the list, the high-order bit of the fullword containing the last ending address of the list must be set to 1, and all other high-order bits must be set to 0.

SUMLSTA: For SUMLSTA, the first fullword of the list contains the number of bytes (including the first word) in the list. The list must be in common storage for SDUMPX BRANCH=NO invocations. SUMLSTA specifies a list of ASIDs and storage ranges as follows:

Restriction: The maximum number of ASIDs that the combined ASID, ASIDLST, JOBLIST, LISTA, TYPE=XMEM, TYPE=XMEME, and SUBPLST parameters can specify is fifteen.

Note: There is no restriction on the number of ASIDs that the SUMLSTA can specify.

When BRANCH=YES and SUSPEND=NO are also specified, the list must be addressable using the addressability established when SVC dump was entered. The lists themselves and all ranges specified must reference paged-in data. Paged-out data is not dumped by summary dump.

When BRANCH=YES and SUSPEND=YES are also specified, the lists must be addressable using the addressability established when SVC dump was entered. The lists and referenced data can either be in paged in or paged out areas. The maximum amount of summary dump data with this type of dump is 8M.

When BRANCH=NO is also specified, the lists must be addressable in all address spaces in which the dump will be taken (those address spaces specified by ASID, ASIDLST, JOBLIST, LISTA, or TYPE=XMEM, TYPE=XMEME, or SUBPLST), which typically means that the list must be in common storage. Synchronization with the capture phase via the SRB or ECB option is also required, as you cannot free the storage containing these lists until the capture phase is completed. The lists and referenced data can be in paged-in or paged-out areas. The maximum amount of summary dump data possible with this type of dump is dependent only on the size of the dump data set.

Each ASID specified with SUMLSTA must represent a valid, swapped-in address space in order for the data to be dumped.

Programming Notes: The total number of distinct ASIDs that can be specified by ASID, ASIDLST, JOBLIST, LISTA, TYPE=XMEM, TYPE=XMEME, and SUBPLST is fifteen. If more than fifteen are requested, only the first fifteen are processed. There is no restriction on the number of ASIDs specified by the SUMLSTA parameter, nor do SUMLSTA ASIDs contribute toward the fifteen ASID limit.

SUMLSTL: For SUMLSTL, the first fullword of the list contains the number of bytes (including the first word) in the list. Specify the ALETs and address ranges as follows:

ALET refers to entries in either a DU-AL or a PASN-AL, and associated with any address/data space that the caller has addressability to. SVC dump does not dump data space storage that has not been referenced.

SUMLIST64=list addr

Specifies a storage location describing a list of virtual storage address ranges, qualified by STOKEN or ALET, to be included in the dump.

The address ranges are described with 64-bit starting and ending addresses and may refer to any address space virtual storage, including virtual storage above the 2 gigabyte bar and any data space storage.

The SUMLIST64 parameter is mutually exclusive with the SUMLSTL parameter.

When SUMLIST64=list addris specified, the first fullword of the storage list contains the number of bytes, including the first word, in the list.

The SUMLIST64 storage list format is essentially analogous to the SUMLSTL storage list format, and the STOKENs or ALETs and the address ranges can be specified as follows:

• The flags field contains one byte of bit indicators.
• A flags value of X'80' indicates the STOKEN/ALET field contains a STOKEN.
• A value of X'40' indicates the STOKEN/ALET field contains an ALET.
  Note: The ALET must be right-aligned in the 8-byte field (placed into the last 4 bytes).
• The only values supported in the flags field are X'80' and X'40'.
• The ending address for any data space range cannot exceed hexadecimal '000000007FFFFFFF'.

The STOKEN/ALET field is specified as follows:

If a STOKEN is specified, the address of data space represented by the stoken must be addressable via PASN access list.

SUMLIST64 may only be specified in conjunction with SDATA=SUMDUMP.

,SUSPEND=NO

,SUSPEND=YES

Specifies that a suspend summary dump is requested (YES) or not requested (NO). SUSPEND=YES must be used together with the BRANCH=YES and SDATA=SUMDUMP parameters. This keyword should be used by routines that can experience page faults but that want to save dump information in a virtual storage buffer.

In z/OS® V1R7 and later releases, when SUSPEND=YES is specified with SDATA=TRT, dumping of the trace table prior to suspend summary dump processing is initiated. Prior releases did this in the opposite order, risking the loss of valuable system trace table entries.

Applications that request the recording of a significant amount of data during suspend summary dump processing can budget their requests using field SMEWVSPC. SMEWVSPC is formally supported in z/OS V1R7 to indicate the capacity of the suspend summary dump buffer.

,SYMREC=symrec addr

Specifies the address of a valid symptom record for DAE to use for dump suppression. DAE suppresses the SVC dump if the primary symptom string found in the symptom record matches previously known symptoms, and, suppression has been enabled by the installation.

The caller must build the symptom record and fill in at least the ‘SR’ identifier and the primary symptom string, which should uniquely identify the error.

SVC dump issues an abend with a completion code of X'233', reason code X'9C', then returns to the caller with a return code of 8 if the symptom record identifier is not ‘SR’, if the offset and length of the primary symptom string are not initialized, or if the first byte of the symptom record and the last byte of the secondary symptom string are not addressable.

SVC dump does not include the symptom record in the dump. The caller can use the SUMLIST keyword to include the symptom record in the dump.

See the dump analysis and elimination (DAE) section in z/OS MVS Programming: Authorized Assembler Services Guide for more information on symptom strings and how to build them.

The ADSR macro maps the symptom record. See z/OS MVS Data Areas in the z/OS Internet library for a macro mapping of the ADSR.

,TYPE=XMEM

,TYPE=XMEME

,TYPE=NOLOCAL

,TYPE=FAILRC

Specifies that the caller's cross memory mode determines the address spaces to dump (XMEM or XMEME) or that the caller cannot allow SDUMPX to obtain a local lock (NOLOCAL) or that SVC dump should return a reason code with the return code to the DUMP command processor when the requested dump was not taken (FAILRC).

XMEM

Requests SVC dump to use the caller's cross memory mode at the time the SDUMPX macro is executed.

XMEME

Requests SVC dump to use the caller's cross memory mode at the time of the error for which the dump is being taken.

See the ASID, ASIDLST, or JOBLIST descriptions for the default behavior if TYPE=XMEM or TYPE=XMEME is not specified.

The home address space is dumped for both keywords. The relevant primary and secondary address spaces are also dumped if they are unique. If a cross memory local lock was held, the address space whose local lock is held is also dumped.

NOLOCAL

Indicates that the caller is in an environment where SDUMPX cannot hold a local lock. This option has meaning only when BRANCH=YES is specified and the caller is enabled and unlocked (for example, the caller has an enabled unlocked task FRR established or is in SRB or cross memory mode).

FAILRC

Requests that the caller receive special information from SVC dump whenever the dump fails. Some information is already placed in SDWASDRC as a result of the SVC dump failure. When the caller receives control again after a dump failure (return code 8) and the caller has specified TYPE=FAILRC, the reason code is combined with the return code and passed to the caller in either register 15 or the ECB, or through the IHASDST mapping macro if the SRBPARM area was provided for an SRB. The reason code is in bits 16-23; the return code is in bits 24-31. When the return code is in the ECB, the POST flag is set on. SDUMPX passes back a return code in register 15 and places the reason code in the SDWA. The reason code explains why the dump failed.

,UTOKEN=list addr

Specifies the address of an area that identifies the user token information to use to collect the high virtual storage. To include these memory objects in an SVC dump, it is required that they were created using 64-bit storage services with a user token and no dumpable attributes. If the area exceeds 512 bytes, the area must reside in common storage and the caller must not free the area until data capture for the dump completes. For an asynchronous dump, use the ECB or SRB parameter so that you are notified when data capture completes. Alternatively, use the SUSPEND parameter to suspend other processing until data capture completes. For a synchronous dump where only one address space and its data spaces are involved, do not worry about freeing the storage so soon because the system does not return control to the caller until data capture completes.

A maximum of 256 user token entries are processed by DUMPSRV and the rest are ignored. If register notation is used, the register contains the address of the area. UTOKEN SVC dump processing captures only those 64-bit memory objects that were created with a memory or user token and no dumpable attributes, meaning that either DUMP=NO or SVCDUMPRGN=NO is specified on the 64-bit storage service.

The area consists of:

• A 8-byte header, which indicates the length of the area. The first 4 bytes contain the area length followed by 4 reserved bytes. If the value in the length field is less than 20, the system ignores the UTOKEN parameter.
• One or more 12-byte user token identifiers for the high virtual storage that is included in the dump. An identifier is an ASID, STORAGE_TYPE indicator and a double word user token.

  ASID

  A 2 byte field that contains an explicit hexadecimal address space identifier. ASID is ignored for common storage user tokens. If an ASID is zero for the region entry, matching high virtual region storage for all dumping ASIDs for the supplied user token are included in the dump.

  STORAGE_TYPE

  A 1 byte character that indicates storage type:

  • 'C' or 'c' represents HV common storage
  • 'R' or 'r' represents HV region (private) storage

  If STORAGE_TYPE and ASID are omitted for an entry, matching high virtual common as well as high virtual region storage for the supplied user token is included in the dump. If STORAGE_TYPE is omitted but an ASID is specified for an entry, the dump includes matching high virtual common storage as well as high virtual region storage for the specified ASID for the supplied user token.

  USERTOKEN

  An 8 byte hexadecimal user token that was either supplied or returned when the associated 64-bit storage service was used to create the memory object. If an ASID or STORAGE_TYPE value is specified but the user token is omitted, then the UTOKEN entry is ignored.

Provide usertoken information as formatted in the following chart to ensure that the desired storage is not excluded from the dump.

4 byte length + 4 reserved bytes
2 byte ASID for usertoken_1 +1 byte storage type + 1 byte RSVD
8 bytes usertoken_1
2 byte ASID for usertoken_2 +1 byte storage type + 1 byte RSVD
8 bytes usertoken_2
...
2 byte ASID for usertoken_n +1 byte storage type + 1 byte RSVD
8 bytes usertoken_n

With the introduction of 64-bit storage, SVC dump enhanced its existing processing to dump high virtual storage when the associated SDATA option was specified. For example, when SDATA=CSA was specified, all storage with the DUMP=LIKECSA dumping attribute was automatically included in the dump. This was done to reduce the complexity of a large SDUMP interface or parameter list. However, with the increase in 64-bit exploitation, this approach resulted in larger than desired SVC dumps because more storage was dumped than was needed for diagnosing problems. Now that SDUMPX supports the UTOKEN parameter, applications have a simpler mechanism for dumping sections of high virtual storage without having to manage lists or addresses.

IBM strongly recommends that you exploit the memory token (MOTKN= or USERTKN=) support that is available for 64-bit storage services when memory objects are created. While you can associate memory tokens with memory objects that might have other dumpable attributes, using a memory token as the exclusive dumpable attribute (MOTKN|USERTKN and DUMP=NO or SVCDUMPRGN=NO) for memory objects offers an advantage. Applications can control what is dumped without the need to track address ranges that are supplied to SDUMPX using a LIST64 parameter. You can also make the storage dumpable without associating it with a particular storage characteristic or larger dumpable attribute regions like SVCDUMPRGN=YES areas. As exploitation increases, there is little, if any, need for installations to use the HCSAxxxx CHNGDUMP options to grossly filter what storage is captured for a dump.

While not required, there are also potential advantages to using one or more different tokens with different diagnostic characteristics for storage. For example, some dumps might need only global and trace data, while others might need local data tables. It is recommended to use one or more different tokens for common and region storage areas that you need to dump, because you need to create separate usertoken entries for these tokens. This will reduce the search time in storage manager when looking for matching storage areas.

The following tables identify return codes and reason codes, tell what each means, and recommend actions that you should take.

If BRANCH=NO was specified and no ASIDs other than the current ASID were requested, register 15 contains one of the following hexadecimal return codes when control is returned at the completion of the capture phase:

If BRANCH=YES or any ASID other than the current ASID was requested, register 15 contains one of the following hexadecimal return codes when control is returned after the system has scheduled the dump:

If ECB=(ecb addr), ECB=(ecb addr,CAPTURE), SRB=(srb addr), or SRB=(srb addr,CAPTURE), was specified and the DCB parameter was not specified, the system also returns one of following hexadecimal codes in the ECB or SRB at the completion of the capture phase:

If ECB=(ecb addr,WRITE) or SRB=(srb addr,WRITE) was specified, or if any of the options on the ECB or SRB parameters were specified along with the DCB parameter, the system also returns one of the following hexadecimal codes in the ECB or SRB at the completion of the dump writing phase:

The reason codes are as follows:

Table 7. Reason codes for return code 08

Hexadecimal reason code	Meaning and action
0	Meaning: SVC dump processing could not be serialized. Action: None
1	Meaning: An SVC dump was successfully started. Action: None
2	Meaning: An SVC dump was suppressed because the capture phase of another SVC dump was in progress. Action: Wait until the dump in progress has been captured (as identified by message IEA794I) and reissue SDUMPX.
3	Meaning: An SVC dump was suppressed by a request by the installation (for example: DUMP=NO at IPL or CHNGDUMP SET,NODUMP). Action: Issue CHNGDUMP SET,SDUMP or CHNGDUMP RESET,SDUMP and reissue SDUMPX.
4	Meaning: An SVC dump was suppressed by a SLIP NODUMP command. Action: Delete SLIP trap with SLIP DEL command and reissue SDUMPX.
5	Meaning: An SVC dump was suppressed because a SYS1.DUMP data set was not available. Action: If MSGTIME expired, increase MSGTIME limit with CD SET,SDUMP,MSGTIME= command. Make a dump dataset available via the DUMPDS ADD,DSN= and/or DUMPDS CLEAR,DSN= commands and reissue SDUMPX.
6	Meaning: An SVC dump was suppressed because an I/O error occurred during the initialization of the SYS1.DUMP data set. Action: Reissue SDUMPX.
8	Meaning: An SVC dump was suppressed because an SRB could not be scheduled to activate the dump tasks in the requested address spaces. Action: None
9	Meaning: An SVC dump was suppressed because a terminating error occurred in SVC dump before the first dump record was written. Action: Reissue SDUMPX.
A	Meaning: An SVC dump was actually started, but because the status stop SRB condition was detected, no notification can be returned to the application when the dump completes, regardless of the SRB or ECB parameter settings. Action: None
B	Meaning: An SVC dump was suppressed by DAE. Action: None.
C	Meaning: The DUMPSRV primary task is unavailable to process SVC dumps. Action: DUMPSRV may be restarting after processing a CANCEL request. Try reissuing the SDUMPX at a later time. If the condition persists, notify the system programmer that DUMPSRV is unavailable and that they may require IBM assistance to get it restarted.
15	Meaning: The parameter list address is zero. Action: Supply a parameter list address in register 1 and reissue SDUMPX.
16	Meaning: The parameter list is not a valid SVC or SNAP parameter list. Action: Provide the address of a valid SVC dump parameter list in register 1 and reissue SDUMPX.
17	Meaning: The caller-supplied data set is not supported. Action: Supply a dataset with LRECL >= 4160 open with EXCP on a device supported by SVC dump (or use a system dump dataset) and reissue SDUMPX.
18	Meaning: The start address is greater than or equal to the end address in a storage list. For the LIST, STORAGE and SUMLIST parameters, ensure that the high-order bit of the last ending address is set to 1. For the LISTA, LISTD, LIST64, SUMLSTA, SUMLSTL and SUMLIST64 parameters, ensure that the length of the list or the number of ranges was specified correctly. Action: Correct the address range that is not valid and reissue SDUMPX.
19	Meaning: The caller-supplied header is longer than 100 characters. Action: Supply a shorter header and reissue SDUMPX.
1A	Meaning: The caller requested a 4K buffer, but did not reserve it. Action: Consider converting the SDUMP invocation to generate a summary dump instead of using the BUFFER=YES parameter. Otherwise, refer to the information for the BUFFER=YES parameter in the SDUMPX macro description and reissue the SDUMPX after the correction is made.
1B	Meaning: A storage list overlaps the 4K buffer. Action: Move the storage list so that it does not overlap the SVC dump 4K buffer pointed to by CVTSDBF. Reissue SDUMPX.
1C	Meaning: The caller-supplied DCB is not valid. Action: Make sure DCB is open, does not overlap 4K buffer, and represents a tape or DASD dataset, then reissue SDUMPX.
1E	Meaning: An ASID in the ASID list is syntactically not valid. Action: Supply a valid ASID (<= ASVTMAXU) and reissue SDUMPX.
22	Meaning: The 4K buffer was requested with an SVC dump already in progress. Action: Wait until the dump in progress has been captured and reissue SDUMPX.
25	Meaning: A subpool ID that was not valid was specified in the subpool list. Action: Supply a valid subpool id (<= 255) and reissue SDUMPX.
28	Meaning: Part of the parameter list is inaccessible. Action: Make sure the parameter list is addressable from the caller's current address space. Reissue SDUMPX.
29	Meaning: The caller-supplied DCB is inaccessible. Action: Make sure the DCB is addressable from the caller's current address space. Reissue SDUMPX.
2A	Meaning: The caller-supplied storage list is inaccessible. Action: Make sure the storage list addressable from the caller's current address space. Reissue SDUMPX.
2B	Meaning: The caller-supplied header data is inaccessible. Action: Make sure the header is addressable from the caller's current address space. Reissue SDUMPX.
2C	Meaning: The caller-supplied ECB is inaccessible. Action: Make sure the ECB is addressable from the caller's current address space. Reissue SDUMPX.
2D	Meaning: The caller's ASID list is inaccessible. Action: Make sure the ASID list is addressable from the caller's current address space. Reissue SDUMPX.
2E	Meaning: The caller's SUMLIST/SUMLSTA is inaccessible. Action: Make sure the SUMLIST/SUMLSTA is addressable from the caller's current address space. Reissue SDUMPX.
2F	Meaning: The caller's SUBPLST list is inaccessible. Action: Make sure the SUBPLST is addressable from the caller's current address space. Reissue SDUMPX.
30	Meaning: The caller's KEYLIST is inaccessible. Action: Make sure the KEYLIST is addressable from the caller's current address space. Reissue SDUMPX.
31	Meaning: Copies of the SLIP register and PSW are inaccessible. Action: None
32	Meaning: The caller-supplied SRB is inaccessible. Action: Make sure the SRB is addressable from the caller's current address space. Reissue SDUMPX.
33	Meaning: The version number in the parameter list is not valid. Action: Supply a parameter list with a valid version number and reissue SDUMPX.
34	Meaning: The caller's LISTD or LIST64 is inaccessible. Action: Make sure the LISTD or LIST64 is addressable from the caller's current address space. Reissue SDUMPX.
35	Meaning: The caller's SUMLSTL or SUMLIST64 is inaccessible. Action: Make sure the SUMLSTL or SUMLIST64 is addressable from the caller's current address space. Reissue SDUMPX.
36	Meaning: The parameter list contains conflicting parameters. Action: Remove the conflicting parameters (for example, both ECB and SRB specified) and reissue SDUMPX.
37	Meaning: The ID is longer than 50 characters. Action: Supply a shorter ID and reissue SDUMPX.
38	Meaning: The ID is not addressable. Action: Make sure the ID is addressable from the caller's current address space. Reissue SDUMPX.
39	Meaning: The PSWREGS area is an incorrect length. Action: Correct the length of the PSWREGS area and reissue SDUMPX.
3A	Meaning: The PSWREGS area is not addressable. Action: Make sure the PSWREGS area is addressable from the caller's current address space. Reissue SDUMPX.
3B	Meaning: The symptom record is not valid. Action: Supply a valid symptom record and reissue SDUMPX.
3C	Meaning: The symptom record is not addressable. Action: Make sure the symptom record is addressable from the caller's current address space. Reissue SDUMPX.
3D	Meaning: The DEB for the caller-supplied DCB is inaccessible. Action: Make sure the DEB for the caller-supplied DCB is addressable from the caller's current address space. Reissue SDUMPX.
3E	Meaning: SVC dump is already using the maximum amount of virtual storage (as determined by the installation, using the MAXSPACE parameter on the CHNGDUMP command) to process other dumps. Action: Make a dump dataset available via the DUMPDS ADD,DSN= or DUMPDS CLEAR,DSN= command, reply DELETE to an outstanding IEA793A message, or increase the amount of virtual storage that SDUMPX is allowed to use via the CHNGDUMP SET,SDUMP,MAXSPACE= command, then reissue SDUMPX.
3F	Meaning: The caller-supplied STRLIST area is inaccessible. Action: Make sure the STRLIST area is addressable from the caller's current address space. Reissue SDUMPX.
40	Meaning: The caller-supplied INTOKEN area is inaccessible. Action: Make sure the INTOKEN area is addressable from the caller's current address space. Reissue SDUMPX.
41	Meaning: The caller-supplied REMOTE area is inaccessible. Action: Make sure the REMOTE area is addressable from the caller's current address space. Reissue SDUMPX.
42	Meaning: The caller-supplied PROBDESC area is inaccessible. Action: Make sure the PROBDESC area is addressable from the caller's current address space. Reissue SDUMPX.
43	Meaning: The caller-supplied JOBLIST area is inaccessible. Action: Make sure the JOBLIST area is addressable from the caller's current address space. Reissue SDUMPX.
44	Meaning: The caller-supplied DSPLIST area is inaccessible. Action: Make sure the DSPLIST area is addressable from the caller's current address space. Reissue SDUMPX.
45	Meaning: The caller-supplied REMOTE area is not valid. The length of a field in the REMOTE area is specified as less than 4 bytes. Note that, if the length of the entire REMOTE area is less than 4 bytes, the REMOTE parameter is ignored. Action: Correct the lengths specified in the area mapped by the IEASDRMT macro. Reissue SDUMPX.
46	Meaning: SVC dump processing was informed that its threshold for using storage resources has been exceeded. If the threshold was exceeded while an SVC dump was in progress, that processing will be stopped and the resulting dump will be truncated. Also, as long as the threshold is exceeded, no new dumps will be allowed to start. If the DUMPSRV address space is the largest consumer of storage resources, then either captured SVC dumps are not being written to DASD quickly enough, or the size of the current dump request is considerable and can not be contained. Action: Ensure that enough DASD resources are available for accommodating the captured SVC dumps. Because other applications might be using the storage resources, more might be required. When a storage shortage has been detected, the shortage must be relieved before new SVC dump requests are honored. See the system programmer response for message IRA201E to determine how to relieve the shortage. Then re-drive the SVC dump. You can use the AUXMGMT and MAXSPACE parameters of the CHNGDUMP SET command to manage the use of virtual and auxiliary storage by SVC dump processing. See z/OS MVS System Commands for more details about the CHNGDUMP command.
47	Meaning: A LIST64 range exceeds 2 gigabyte addressability in an ESA environment. Action: Remove the ranges from the LIST64 parameter that exceeds 2 gigabyte addressability. Then reissue the SDUMPX macro.