SDUMP/SDUMPX
The SDUMP and SDUMPX macros provide a dump of virtual storage, which contains user data and system data.
The dump output is written either into a dump library or onto SYSLST, depending on the current setting of the SYSDUMP/SYSDUMPC option. The High Level Assembler is required to compile the macros.
The SDUMP macro causes address ranges in your current address space to be dumped. Whereas the SDUMPX macro also provides for storage ranges in address spaces or data spaces to which addressability via an ALET or via an STOKEN exists.
If the program is running in primary ASC (address space control) mode, either SDUMP or SDUMPX can be used. If the program runs in access register (AR) mode, the SDUMPX macro must be used. SDUMPX provides all of the functions of SDUMP, but generates code and addresses that are appropriate for AR mode.
If you are in access register (AR) mode, issue the SYSSTATE ASCENV=AR macro before you issue the SDUMPX macro to tell SDUMPX to generate code appropriate for AR mode.
The SDUMP macro cannot dump data space storage. To dump data space storage, SDUMPX is to be used instead by including either the LISTD or SUMLSTL operand.
When SDUMPX is entered, the specified parameter list and all areas to which the list points must be in the current address space of your partition.
Format
Requirements for the caller
- AMODE:
- 24 or 31
- RMODE:
- 24 or ANY
- ASC Mode:
- Primary or AR (access register)
Parameters
- HDR='dump-title'
- Specifies the title or header to be used for the dump. The title
must be from 1 to 100 characters, which are enclosed in quotes. Note: The header is displayed only if the dump is routed to SYSLST (OPTION NOSYSDMP). If the dump is routed to a dump sublibrary, the header is not displayed; you can, however, inspect it using the SELECT DUMP SYMPTOMS function of Info/Analysis.
- HDRAD=dump-title-addr
- Specifies the address of the title to be used for the dump. The dump title field consists of a 1-byte length field, followed by the specified title. The length field specifies the length of the title, excluding the length byte itself. The macro accepts a length value of 1 to 100. See note in the HDR parameter description.
- STORAGE=(startaddr,endaddr,...)
- Specifies the start and end address of the virtual storage area
to be dumped. One or more pairs of start and end addresses can be
specified. The list must contain an even number of addresses, and
each address must occupy one fullword. For example:
STORAGE=(startaddr,endaddr,startaddr,endaddr) - LIST=listaddr
- Specifies a list of start and end addresses of the storage to be dumped. 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 that contains the last ending address of the list must be set to 1; all other high-order bits must be set to 0.
- LISTD=listaddr
- Specifies a list of start and end addresses - qualified by STOKENs
(space tokens) - of the areas to be included in the dump. Specify
the STOKENs and address ranges as follows:
───────────────── 4 bytes ────────────────→
Length of the list
First STOKEN (8 bytes)
Number of ranges to be dumped in this STOKEN
Range 1 starting address
Range 1 ending address
Range 2 starting address
Range 2 ending address
⋮
Last STOKEN (8 bytes)
Number of ranges to be dumped in this STOKEN
Range 1 starting address
Range 1 ending address
Range n starting address
Range n ending address
The first fullword of the list contains the number of bytes (including the first word) in the list. STOKEN refers to any address or data space.
- LIST64=listaddr
- Specifies a list of start and end addresses of areas that are
qualified by an STOKEN (space token) of the area to be included in
the dump. Specify the STOKEN and address ranges as follows:
───────────────── 8 bytes ────────────────→
Length of the list (4 bytes)
First STOKEN
Number of ranges to be dumped (4 bytes)
Range 1 starting address
Range 1 ending address
⋮
Range n starting address
Range n ending address
The first fullword of the list contains the number of bytes (including the first word) in the list. STOKEN refers to the current primary address space, otherwise no dump is taken.Note: Currently only output to SYSLST is supported. - SUMLIST=listaddr
- Specifies a list of start and end addresses of areas to be included in the dump. 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 that contains the last ending address of the list must be set to 1; all other high-order bits must be set to 0.
- SUMLSTL=listaddr
- Specifies a list of start and end addresses - qualified by ALETs
(Access List Entry Tokens) - of areas to be included in the dump.
Specify the ALETs and address ranges as follows:
───────────────── 4 bytes ────────────────→
Length of the list
First ALET (4 bytes)
Number of ranges to be dumped in this ALET
Range 1 starting address
Range 1 ending address
Range 2 starting address
Range 2 ending address
⋮
Last ALET (4 bytes)
Number of ranges to be dumped in this ALET
Range 1 starting address
Range 1 ending address
Range n starting address
Range n ending address
The first fullword of the list contains the number of bytes (including the first word) in the list. ALET refers to entries in either a DU-AL or a PASN-AL associated with any address or data space that the caller has addressability to.
- TYPE=FAILRC
- Specifies that the macro is to return a reason code together with the return code in register 15. The reason code explains why the dump failed. This is also the default, if the TYPE operand is omitted.
- MF=L | (E,listaddr)
- L specifies the list form of the macro, which generates a control program parameter list that
can be used by the execute form of the macro. In the list form, only A-type
addresses can be used; RX-type addresses and registers cannot be used.
E specifies the execute form of the macro, which uses the parameter list that is generated by the list form of the macro. listaddr specifies the address of the parameter list.
If the MF operand is omitted, the standard form of the macro is used, which is for programs that are not reenterable or that do not change values in the parameter list.
Return Codes in Register 15
- 0
- A complete dump was taken.
- 4
- A partial dump was taken.
- 8
- The system was unable to take a dump.
For return code 8, a reason code is supplied in bits 16-23 of register 15. The reason code explains why the dump failed.
The reason codes are as follows:
| Reason Code | Meaning |
|---|---|
| 15 | The parameter list address is zero. |
| 16 | Invalid parameter list options - invalid dump type. |
| 18 | Invalid address range specified: conflicting begin and end addresses. |
| 19 | Invalid user data specified - header is not correct. |
| 1B | Invalid STORAGE list or LISTD. |
| 1D | The size of the storage areas to be dumped plus the control information for a dump library member exceeds 2GB, which is the maximum size of a dump library member. |
| 1E | Invalid address space or data space. |
| 20 | STOKEN does not refer to primary space. |
| 2A | The caller-supplied storage list is inaccessible. |
| 2B | The user header data is inaccessible. |
| 2E | The caller-supplied SUMLIST is inaccessible. |
| 33 | Out of space limits. |
| 34 | The caller-supplied STOKEN and range list in LISTD is inaccessible. |
| 35 | The caller-supplied ALET and range list in SUMLSTL is inaccessible. |
| E0 | SYSLST is not available. |
| E1 | Dump library is full - part of dump is on SYSLST. |
| E2 | Dump library is not defined - dump is on SYSLST. |
| E3 | Dump library is in error - dump is on SYSLST. |
| E4 | Getvis Failure |
| E5 | No dump due to JCL/Macro options |