Storage definitions, dumps and program checks

Defining storage: DC and DS

DC (define constant) reserves storage and gives it an initial value. DS (define storage) reserves storage without a value. Both take a type that sets the format, alignment and default length.

Types map directly onto COBOL: C is PIC X, F and H are binary COMP fields, P is COMP-3. Reading a copybook and its assembler equivalent side by side is a good way to learn both.

CSECT, DSECT and USING

These are assembler instructions: directions to the assembler rather than machine instructions. A CSECT (control section) is a block of code and data that becomes part of an object module; the binder combines CSECTs into a load module or program object. A DSECT (dummy section) describes a layout without allocating any storage: it is a template laid over storage that belongs to someone else, such as a parameter area or a control block.

PARMMAP  DSECT
PCUSTNO  DS    CL10
PAMOUNT  DS    PL6
PSTATUS  DS    CL1
DATECHK  CSECT
*        ... entry logic ...
         L     2,0(,1)          R2 = address of first parameter
         USING PARMMAP,2        lay the map over it
         CLI   PSTATUS,C'A'
         BNE   NOTACTV
         DROP  2

Once USING PARMMAP,2 is in effect, the assembler turns PSTATUS into displacement 16 from R2. The DSECT is the assembler equivalent of a COBOL LINKAGE SECTION item.

Macros are different again: named pieces of source that expand into instructions. IBM supplies system macros such as SAVE, RETURN, WTO (write to operator) and STORAGE (obtain or release storage), and many sites keep their own macro libraries. The listing shows the expanded instructions, which is what actually runs.

The PSW

The Program Status Word (PSW) is the processor's record of its current state. In z/Architecture it is 128 bits. It holds, among other things, the address of the next instruction, the condition code, the addressing mode, the storage protection key and whether the program is in problem (application) or supervisor state.

Program checks

When an instruction cannot complete, the hardware raises a program interruption with an interruption code. z/OS turns an unhandled one into a system abend of the form 0Cx.

Reading assembler in a dump

1. Find the PSW at the time of the error and the instruction length code (ILC), 2, 4 or 6.
2. In most cases the PSW points to the instruction after the failing one. Subtract the ILC to find the failing instruction.
3. Find the module's entry point address (the dump or Language Environment report usually names it). Failing address minus entry point gives the offset.
4. Look up that offset in the assembler listing (or the COBOL listing with an offset map) to find the source statement.
5. Decode the operands and check the registers they use. A base register containing zero or rubbish explains most S0C4s.

COMPLETION CODE  SYSTEM = 0C4  REASON = 00000004
PSW AT ENTRY TO ABEND  078D1000 8002A1B6  ILC 6  INTC 0004
MODULE DATECHK  ENTRY POINT 0002A000
GR 0-3   00000000 0002A3F0 00000000 0002B110

Here the PSW address is X'2A1B6' (the leading 8 is the 31-bit mode bit). The ILC is 6, so the failing instruction is at X'2A1B0', offset X'1B0' in DATECHK: an SS instruction such as MVC. R2 is zero, and the listing shows that instruction addresses a parameter through R2. The calling program passed no parameter.

Interactive dump analysis on z/OS is done with IPCS for SVC and SYSMDUMP dumps, while SYSUDUMP and Language Environment CEEDUMP output is formatted text. Vendor tools such as IBM Fault Analyzer, BMC AMI and Broadcom products automate much of this, but they assume you understand the steps above.