DA - Mainframe Disassembler in REXX

JAMZ icon

FUNCTION

This will disassemble mainframe executables that are represented in printable hex.

The DA REXX procedure disassembles the AMBLIST output (or indeed any printable hex) that you are currently editing with ISPF/EDIT.

The DAB REXX procedure does the same thing but does not use ISPF/EDIT, so it can be run in TSO, batch, or even on Linux or Windows.

This can be very handy for mainframe sites that have somehow lost the source code to an important executable. All you need to do is run DA or DAB against the output from an AMBLIST module listing of the executable. It is an iterative process, but at the end of the day you will have an assembler source file that, when assembled, should recreate the executable load module.

PREREQUISITES

To run DA or DAB on z/OS there are no prerequisites
To run DAB on Linux or windows, you will need to install a REXX interpreter such as:
1. Regina REXX (http://regina-rexx.sourceforge.net)
2. Open Object REXX (http://www.oorexx.org/)
On Linux, there is usually a REXX package that you can install using your package manager. On Ubuntu you can install it by issuing:
```
sudo apt install regina-rexx
```
The interpreter can then be invoked in a command window by issuing, for example:
```
rexx dab.rex input.hex output.asm
```

OVERVIEW

DA is the interactive version of the disassembler and DAB is the batch version.

The interactive version uses ISPF/EDIT and is generally more convenient to use on z/OS. DAB can be run in TSO or batch and, because it does not use ISPF/EDIT, it can also be run on Linux and Windows.

DA

If DA is invoked outside of the ISPF editor then it will generate and edit an AMBLIST job that you can submit to produce a module listing that can be read by the DA macro. For example, the following command will generate JCL to list module IEFBR14:

TSO DA SYS1.LPALIB(IEFBR14)
If DA is invoked in an ISPF edit session with the TEST option, for example:

DA (TEST

...then an assembler source file is generated containing one valid assembler statement for each instruction. This can be assembled into a load module, printed with AMBLIST and used to check that DA can disassemble all instructions correctly.
If DA is invoked in an ISPF edit session with the ASM option, for example:

DA (ASM

...then JCL to assemble the file being edited is generated.
If DA is invoked in an ISPF edit session with no options, for example:

DA

...then it will disassemble the file being edited and edit the temporary dataset created as a result.
If DA is invoked with hex on the command line then that hex will be disassembled, for example:

DA 58100010 07FE

DAB

DAB can be run in batch, for example:

//        EXEC PGM=IKJEFT01
//SYSEXEC   DD DISP=SHR,DSN=SYS1.MY.EXECLIB
//IN        DD DISP=SHR,DSN=SYS1.MY.AMBLIST.OUTPUT
//OUT       DD DISP=SHR,DSN=SYS1.MY.ASM(MEM)
//SYSTSIN   DD *
TSO DAB DD:IN DD:OUT
/*

DAB can be run in TSO (but DA is more convenient), for example:

TSO DAB sys1.my.amblist.output sys1.my.asm(mem)
DAB can be run on Linux and Windows once you have downloaded the AMBLIST output, for example:

rexx dab.rex my.amblist.output my.asm

WORKFLOW

Disassembly is usually an iterative process:

Run DA on the AMBLIST output. This will help to identify which areas are data and which are code.

If you see a comment in the output like <-- TODO (not code) it means that the disassembler was in CODE parsing mode but detected an invalid instruction. You should insert a dot (.) to switch the disassembler into DATA parsing mode at that point, and then insert a comma (,) to revert to CODE mode at the end of that block of data.
Mark the beginning of areas known to be code with a comma (,) and those known to be data with a dot (.).

Remember: Comma-for-Code, Dot-for-Data.

Run DA again until no TODO comments are seen.
Optionally, tag the AMBLIST output. There is much more detail on tagging in the USAGE section below.

Tags are strings enclosed in parentheses and can be used as follows:
- You can mark data areas as having particular data types.
  
  For example:
  
  (F) 00000010 (H) 00220023 (X) 0102(P)19365C (B)8F
  
  Generates:
```
         DC    F'16'
         DC    H'34'
         DC    H'35'
         DC    XL2'0102'
         DC    PL3'19365'
         DC    B'10001111'
```
- You can assign a label at an offset into the code.
  
  For example:
  
  18CF(myLabel)47F0C010
  
  Generates:
```
         LR    R12,R15
myLabel  B     16(,R12)
```
- You can explicitly assign a label to a code offset:
  
  For example:
  
  (myLabel=2,myData=6)18CF47F0C010.1234
  
  Generates:
```
         LR    R12,R15
myLabel  B     16(,R12)
myData   DC    XL2'1234'
```
- You can specify and/or drop a base register for the subsequent code.
  
  For example: (R12)18CF47F0C002(R12=) Generates:
```
         USING *,R12
         LR    R12,R15
L2       B     L2
         DROP  R12
```
- You can specify a base register for a named DSECT.
  
  This is very powerful because it causes a DSECT to be built containing fields for each displacement off that base register that is referenced by the code. The name of each field is derived from the displacement. For example:
  
  (R13=>WA)5810D010 5010D044 (R13=)
  
  ...where (R13=>WA) means "R13 points to a DSECT called WA" and (R13=) means "Drop R13", generates:
```
          USING WA,R13
          L     R1,WA_10
          ST    R1,WA_44
          DROP  R13
 WA       DSECT
          DS    XL16
 WA_10    DS    XL4
          DS    XL48
 WA_44    DS    XL4
```
- You can do some other useful things as described in the TAGS section below.
Assemble the disassembled source file.

You may see some assembly error messages like:

** ASMA044E Undefined symbol - L12C

...which is easily resolved by going back to the AMBLIST output and inserting a "." (for data) at offset +12C. That will create the missing label (L12C) at that offset.

Rerun DA and reassemble the output until all assembly errors are resolved.

EXAMPLE

Some samples of input and output files can be found in the /samples folder of this repository.

A sample input file (with DA markup highlighted) is:

<pre> A7F4000E . C7C5E3C3 D4C44040 F2F0F2F0 61F1F061 F2F140F1 F67AF5F5 , 90ECD00C 18CF (R12=0) 1841 (R4=>PLIST 'Parameter List') 47F0C030 (F) 0000004C 00000012 , 5800C028 58F0C02C 58E00010 58EE0304 58EE00A0 B218E000 12FFA774 006C50D0 10045010 D00818D1 (R13=>WA 'Work Area') 1244A784 005D9180 4008A7E4 00594180 D0484110 C1305081 00009201 10089200 10090A28 5880D048 58708000 58104008 50701000 58704000 92007000 58704004 D7FF7000 70005870 80041277 A784002F 58904000 95447004 A7740006 92C69000 A7F40012 95407004 A7740006 92D79000 A7F4000A 95047004 A7740015 92E29000 A7F40002 4850700E 06501255 A744000B 58904004 D2009000 70104450 C0ECA7F4 00021117 41008004 0A224110 00051111 41008004 11000A22 A7F40006 41F0000C A7F40003 1FFF58D0 D00458E0 D00C980C D01407FE (''). 00000000 00000000 00000000 00000000 </pre>

The meaning of the inserted markup is:

Markup | Meaning ------ | ------- . | Decodes the following hex as data. The data type is automatic (i.e. it is guessed based on the alignment and the content) , | Decodes the following hex as code (R12=0)| Declares that R12 points to offset 0 (emits a USING statement for R12) (R4=>PLIST 'Parameter List')|Declares that R4 points to a DSECT called PLIST, and emits a section heading 'Parameter List' before the DSECT definition. Subsequent storage references based on R4 will be added to the DSECT. (F) | Decodes the following hex as data (the type is explicitly declared as fullword) (R13=>WA 'Work Area')|Declares that R13 points to a DSECT called WA, and emits a section heading 'Work Area' before the DSECT definition. Subsequent storage references based on R13 will be added to the DSECT. (''). | Emits an empty comment and decodes the following hex as data. The data type remains as fullwords unless you reset it with '/'

The result of disassembling this input is:

@        START
*Label   Op    Operands                Comment                                                     Location Hex          Format

***********************************************************************
*                                                                     *
*                               GETCMD                                *
*                                                                     *
***********************************************************************

         ORG   @+X'00000000'

GETCMD   J     L1C                                                                                 00000000 A7F4000E     RIc
         DC    CL24'GETCMD  2020/10/21 16:55'                                                      00000004

L1C      STM   R14,R12,12(R13)         Store Multiple (32)                                         0000001C 90ECD00C     RSA    60 (,F)
         LR    R12,R15                 Load (32)

Da

Install / Use

README