IBM Z Machine Instructions
Part Three - Challenge #14


The challenge exposes you to IBM Z Assembler. Learning to be an assembler programmer takes significant time and repetition.

Learning assembler is harder than learning other programming languages.
The reason is that assembler requires the programmer to learn about the machine specific:

  • Assembler instructions
  • Assembler directives
  • Assembler macros
  • Hardware architecture

IBM Z Assembler coding and debugging requires:

  • Decimal/Hexadecimal conversion
  • Hexadecimal arithmetic applied to memory addressibility
  • Binary format representation and binary arithmetic such as two's complement

There are employers that want and need technicians with IBM Z Assembler skills.
  A humorous youtube video related to the above statement follows:
  "The code I write runs on the mainframe."

A deceptively simple assembler program will be used and explained. The deceptively simple assembler program includes many technical elements of IBM Z Assembler.

Figure 1. is assembler source code. Outlined in red are the assembler instruction mnemonics responsible for "standard linkage", a way in which data and control are passed from the calling program to this called program.

The first red outline is an assembler coding technique to save register content of the program that gives execution control to this assembler program. One exception is the USING statement which is an assembler directive as is the END statement at the bottom.

The second red outline restores register content of the program that gave control to this assembler program.

The third red outline gives control back to the program that originally gave control to this assembler program.
Figure 1.
Figure 2. is the same assembler source code. Outlined in red are the assembler instruction mnemonics to be executed. This is the program body which is only 3 assembler mnemonics (LH, A, ST) and 1 assembler macro (WTO).
Figure 2.
Figure 3. is the same assembler source code. Outlined in red are the assembler program declared storage areas (DC - Define Constant).
Figure 3.
  1. Compile assembler program source code
    tso submit 'zos.public.jcl(ch14)'

  2. Screen shots of the compile output follow focusing on machine instructions and assembler mnemonics.

    Figure 4. Outlined in red on the right side are the assembler mnemonics.
    Outlined in red on the left side are the corresponding machine instructions.
    An example is the left side x'90' that is the machine instruction for assembler mnemonic STM on the right side.
    Figure 4.
  3. Screen shots of the compile output follow focusing on program instruction memory address locations.

  4. Figure 5. Outlined in red on the left side are the program relative address locations.
    Relative address locations range from x'00000' to x'00009E' which is also the length of the program, CH14.
    Figure 5.
  5. Screen shots of the compile output follow focusing on assembler directives and macros.

  6. Figure 6. Outlined in red are assembler directives (CSECT, USING, END).
    Also, outlined in red is an assembler macro (WTO).
    Outlined in red 16+ to 22+ are statements included in the program as a result of the macro.
    Assembler macros are reusable code.
    Figure 6.
  7. Screen shots of the compile output follow focusing on assembler program defined storage areas.

  8. Figure 7. Outlined in red are assembler program defined storage areas (DC - Define Constant).
    Each storage area has an address location and a label.
    The assembler mnemonics can use either labels or relative address locations of storage areas. Writing an assembler program using labels is much easier. The compiler translates the labels into relative address locations.
    Figure 7.
  9. Screen shots of how to use the TSO TEST facility.

  10. Figure 8. A TSO facility (TEST) is available to view program execution.
    TEST can list program execution registers and storage locations.
    Use the TEST facility on the executable program (CH14) as follows:

    Get a TSO Ready prompt by terminating the ISPF session.


    Start the TSO TEST facility as shown below - replacing Z99999 with your ID

    Figure 8.

    In the above display - observe the following:

    • list +0 length(158) displays relative address location +0 for a length of 158 which is the machine instructions and storage areas in the program.
        The program length is x'9E' which is equivalent to decimal 158.
        As mentioned before, the need to convert between hexadecimal and decimal is required because of instances where a value is decimal when the operating system is working in hexadecimal.
      Hexadecimal/Decimal Converter - try converting x'9E' to a decimal value
    • The hexadecimal values between +0 and +9E map directly to the compile object code (machine instructions) in Figure 7.
    • list 0r:15r displays the content of the 16 program execution registers, 0-15.
        TEST initializes registers 2 through 12 with X'FFFFFFFF' to allow you to see register content changes during the program execution.
  11. Try what you see in Figure 10. below using TSO TEST facility to:
  12.    List instruction located at +0, the beginning of program execution
       List instruction located at +14
       List storage area located at +92 for a length of decimal 7
       List storage area located at +92 for a length of decimal 7 in character format

    Figure 10.
  13. The TEST facility program has control at the moment and register 15 contains an address where CH14 program is loaded in memory.
    Try what you see in Figure 11. to:
  14.    Ask where (the address location) is program CH14
       List of all registers which includes register 15 with the address of program CH14 to be loaded for execution
    NOTE: Enter end to exit the TSO test facility

    Figure 11.
  15. The TEST facility program can set break points to stop program execution for the purpose of listing registers and storage address content at that point in time of the program execution. Reference Figure 5. as you proceed through this preparation exercise. Try what you see in Figure 12. below to:
    • Set break points at specific the program execution address locations
    • List of all registers at each break point
    • The first go loads and begins to execute CH14
    • at +14 is LH 3,HALFCON where the result will be to load register 3 with value from storage location HALFCON
    • The stop at +18 shows register 3 changed as a result of go to continue with execution of machine instruction at +14.
    • HALFCON is DC H'32'. However, HALFCON storage address (+90) shows x'20' - one those hex/dec conversion things
    • at +18 is A 3,FULLCON where the result will be to ADD to register 3 the value from storage location FULLCON
    • The stop at +1C shows register 3 changed as a result of go to continue with execution of machine instruction at +18.
    • FULLCON value is -1. Adding x'20' to -1 resulted in x'1F'
          * Where FULLCON at +88 is a hexadecimal full binary word x'FFFFFFFF'
          * Confused-normal-it is two's complement arithmetic.
          * Understanding is not necessary to complete the challenge
          * If you want to understand, start with following youtube
            "Two's Complement Explained"
    • While at +1C, list content at storage address +8C, associate with label HEXCON.
          * Instruction ST 3,HEXCON is at +1C, waiting to be executed on next go at bottom of Figure 12.

    Figure 12.
  16. Figure 13. below is at the beginning of +20 in CH14 program execution
    • The assembler code ST 3,HEXCON located at +1C was executed.
    • The content at +8C, HEXCON was changed from x'0000FD38' to x'0000001F'.
    • The assembler ST instruction stores content of register 3 into storage memory location at +8C, HEXCON

    • Figure 13.
    • END terminates TSO TEST facility execution returning to TSO Ready.


Modify CH14 assembler program as instructed below.

  1. Edit hlq.SOURCE member name CH14
  2. Change the A 3,FULLCON assembler statement to a statement that will subtract register 2 from itself.
  3.   -- Note: Internet search "z assembler subtract register instruction" for the assembler syntax
  4. Change the ST 3,HEXCON assembler statement to store register 2 into HEXCON.
  5. Submit ; =sd; st and review CH14 output for successful compile and execution.
  6.   -- If compile and execution is successful, proceed to 5.
      -- If compile and execution is unsuccessful, then identify and correct the error
  7. Use TSO TEST to validate the successful assembler changes and debug as needed.
  8.   -- Subtract register instruction has a shorter instruction length than the add instruction
        ** Carefully review compile output for changes in program address locations
      -- Register 2 should be x'00000000'
      -- Storage location associated with label HEXCON, should be x'00000000'
  9. If register 2 is NOT x'00000000' or HEXCON is NOT x'00000000', then correct CH14 source code.
  10. If register 2 is x'00000000' and HEXCON is x'00000000', then
    submit 'zos.public.jcl(ch14x)'
  11.   -- JCL job ch14x writes output to hlq.P3.OUTPUT(#14)

Congratulations! You are most likely in a fraction of the contestants advancing to the last challenge in Part 3.
Completing all Part 3 challenges qualifies you to be among the group judged and selected as the Part 3 contest winners.
Best of luck with the final challenge.

Next: Challenge #15

The challenge idea is from an IBM professional manual, TSO/E Programming Guide.
The last chapter is presented in a tutorial form.
Chapter 17. A Tutorial Using the TEST Command