IBM Z Mainframe Assembler
Part Three - Challenge #13

Background:

The challenge exposes you to IBM Z Assembler Language

Some large companies need programmers that understand assembler language.

These technical positions pay well and lead to promotions in the technical ranks.

Familiarity with IBM Z assembler on a resume is a major attention getter for securing an interview.

You can say you have familiarity with IBM Z assembler as a result of completing the challenge.

Do not let the technical details in the challenge scare you away.

By the end of the challenge you will realize you are capable of beginning to understand the technical details of how computer software works.


Learning to be an assembler programmer takes significant time and repetition.

Learning assembler is more difficult than learning other programming languages.

Assembler requires a programmer to learn about:

  • Assembler mnemonics
  • Machine 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

A benefit of understanding assembler is the ability to debug complex system problems by reading system dumps.

Only a small number of developers and system programmer are proficient with assembler.
However, those familiar with assembler possess a deeper understanding of the operating system technology and ability to write high performance code.

A humorous youtube video related to the above statement follows:
  "The code I write runs on the mainframe."


A few comments about what you are about to learn
  • The majority of IBM Z jobs and careers do NOT require proficiency with IBM Z assembler
  • Large enterprise management requested assembler exposure in the Master the Mainframe contest
  • Past Master the Mainframe participants have careers working directly with assembler in IBM Z enterprises
  • The challenge will not be as difficult as you might imagine
  • The challenge instructions enable you to successfully interpret requested changes to the ASMPGM code
  • Assembler is not for everyone
  • Assembler requires near obsessive attention to the smallest details
  • Assembler proficiency enables a capability to debug complex system problems
  • Large enterprises have assembler routines for critical high volume, high frequency processing requiring highest possible performance - someone must understand and support those assembler programs
  • The challenge exposes you to the details of assembler because:

      * Some of you just might learn you enjoy dealing with the details of assembler

      * If you are one of these people with an affinity for assembler, a job is waiting for you
        You need to let employers know you enjoy the details of IBM Z assembler
        and want to grow your assembler proficiency

      * If you are NOT one of these people with an affinity for assembler, you will be exposed to
       the hidden details behind all computer operating systems and higher level programming languages

Preparation

A relatively simple assembler program will be used and explained.

Each computer architecture has machine instructions unique to the architecture. All computer languages supported by the architecture must be translated into the unique machine instructions of the underlying computer architecture. Each computer architecture has an assembly language which includes mnemonics that are assembled into machine instructions understood by the computer. Compilers and interpreters translate supported computer languages into the unique machine instructions understood by the hosting computer.

Computer processing memory is used to load and store the machine instructions and data for processing. The operating system keeps track of processing memory locations using addresses where some of the memory is free, some of the memory has machine instructions, and some of the memory has data.

Higher level languages such as C/C++, Java, COBOL, etc. were created to make programming the computer easier by hiding the complexity of the underlying machine instructions, addressable memory, and registers. Registers are at the top of the memory hierarchy, and provide the fastest way to access data.

IBM Z mainframe computer architecture, z/Architecture, is Complex Instruction Set Computing, CISC.

The assembler code that follows is explained in greater detail using the assembly compile output.

Figure 1. is assembler source code.

Outlined in red is assembler code responsible for "standard linkage",
a technique for passing data and processing control from a caller program to a called program.

Read the comments to the right of the assembler mnemonics.
Figure 1.
Figure 2. is the same assembler source code.

Assembler mnemonics to be executed, the program body.
Figure 2.
Figure 3. is the same assembler source code.

Assembler code defining program constants, data in processing memory storage.
Figure 3.
Figure 4. is the same assembler source code.

Assembler code restoring caller program registers and returning control to the caller program.
Figure 4.

Challenge:

Compile assembler program
  1. edit Z#####.SOURCE
  2. select a new member name
    s asmpgm
  3. copy 'zos.mtm2018.public.source(asmpgm)'
  4. submit
  5. jump to SDSF and verify the assembler program compile was successful
    =sd ; st

Review of assembler compile details

SDSF review of output for ASMPGM, DDNAME SYSPRINT and ProcStep C, should match the following images.

Observe the following in the image below:
  • Loc - abbreviation for location, program location column
  • Object Code - machine instructions column. commonly called op codes
  • Addr1 - memory address location column
  • Addr2 - memory address location column
  • Stmt - line numbers associated with each line of code
  • Source Statement - assembler code labels, mnemonics, and mnemonic operands
  • Stmt 2 is the first assembler code line where -
    Loc 00000 represents the beginning location
    Addr1 00000 Addr2 000FD represents the starting and ending location of the program in hexadecimal
       -- effectively the program length in bytes - x'FD' or 253 decimal
     ASMPGM is a user chosen label
     CSECT is an assembler directive declaring a Control Section
  • Stmt 3, 4, 5 are comments
  • Stmt 6 to 11 show user selected label names equated (EQU) to computer register numbers

Below is assembler code frequently reused for "standard linkage",
store the location and register content of the caller program to return control when done.

Stmt 18 includes assember mnemonic B, a branch.
  The operand is SETUP, a program label, a quick way to resolve addressable location in memory.

The left of Stmt 18 has an op code that begins with 47, which is the op code for mnemonic B, branch.

Stmt 18 Addr2 is 00014.
  Observe Loc 00014, Stmt 22, is label SETUP with more assembler code to execute.

While the explanation below is elaborate, it is just preparation for you to see these changes happen at breakpoints during program execution later in the challenge.

The program body includes -

  • Stmt 34, op code beginning with x'58', L, Load register 2 with characters 'Begin'
  • Stmt 35, op code beginning with x'41', LA, Load Address register 2 with address of 'Begin' address location
      You will see the register content difference between the 2 instructions later.
      You will might notice the Addr2 is 000F8 memory address location for 'Begin'
    =C'Begin' resulted in assembler assigning a memory address location for characters Begin
  • Stmt 37, op code beginning with x'1B', is mnemonic SR, subtract register 2 from itself
  • Stmt 38, op code beginning with x'58', is mnemonic L, load 4 into register 2
  • Stmt 39, op code beginning with x'58', is mnemonic L, load 1 into register 3
  • Stmt 42, op code beginning with x'5A', is mnemonic A, add 1 to register 3
  • Stmt 43, op code beginning with x'46', is mnemonic BCT, decrement register 2 by 1 and branch to the label loop until register 2 is zero
  • Stmt 45, op code beginning with x'48', is mnemonic LH, load halfword into register with content of memory location assigned to HALFCON label
  • Stmt 46, op code beginning with x'5A', is mnemonic A, add memory location assigned to FULLCON label into register 3
  • Stmt 47, op code beginning with x'50', is mnemonic ST, store register 3 in memory location of HEXCON

Below is commonly reused code for 'standard linkage', restoring the caller program registers.

Observe Stmt 56 with 'WTO'
  Left is blank - no op code, no operands, and no addresses
  WTO, abbreviation for Write To Operator, is an assembler macro
  The text following WTO is written to the system log

Below observe Stmt 58 to 64 with a '+' following the statement number
  58 to 64 is the WTO macro expanded code

Observe Stmt 65 with op code beginning with x'07' associated with mnemonic BR, branch
  The address location represented by label RETREG is register 14
  where register 14 contains the address location of the caller program.
  So, the execution result is a branch to an address location of the caller program.

Below is assembler defined constants with assembly assigned addressable memory locations

The op code area is content at the addressable memory location when the program starts execution.

A few observations -

  • Label SAVEAREA at location 98 into the program is 18 full words in length
  • Label FULLCON at location EO into the program is 1 full word in length
  • Label HEXCON at location E4 into the program is a hexadecimal length of 4.
  • Label HALFCON at location E8 into the program is a half word where of decimal value H'32'
      but inspection of the stored value in memory is x'20'
  • Program body included =F'4', =F'1', and =C'Begin',
      where the = resulted in the assembly to machine code assigning addressable locations
      for the values at the end of the executable program, F0, F4, and F8, respectively.
Calculator to convert between hexadecimal and decimal (if you need it)

Use TSO TEST facility to understand assembler program execution

TSO TEST facility is used to execute a program with the added capable to stop the program execution at chosen address locations to inspect changes in registers and changes in other address locations in the program.

The TSO Ready prompt is required to use the TSO TEST facility.

If ISPF =x terminates both ISPF and automatically logs off TSO, stopping you from getting to the TSO Ready prompt, then revisit Part 2, challenge #01 instructions.

Once in the TSO Ready prompt, the commands below can be copied and pasted when instructed to enter the commands.

Consider opening a separate browser tab to view the ASMPGM compile output (seen above in the section
'Review of assembler compile details') as you study how the assembler program works using the TSO TEST facility.

  1. test 'z#####.load(asmpgm)'
      --- you must replace z##### with your ID
      Enter the above command to load your assembler program, ASMPGM, into the TEST facility

  2. listpsw
      Enter the above command to list the current address location of ASMPGM
      ASMPGM address location is under the INSTR ADDR column

  3. l 0r:15r
      Enter the above command to list the 'current' content of the 16 registers, 0-15
      Observe register 15 is the address of ASMPGM which will be executed shortly
      Register 14 is the address of TSO Ready environment which called TEST facility
      When TEST facility is ended, control is returned to the address in register 14

  4. l 11f00. length(256)
      Enter the above command to list the content starting at 'absolute' address location 11F00
      Observe the content is machine instructions and data from the compile output
      Example, the first byte, x'47' machine instruction (op code) was created by the branch, B mnemonic at Stmt 18

  5. l 11f00. length(256) c
      Enter the above command to list the content starting at 'absolute' address location 11F00 in character format
      Observe the literal text embedded in the assembler program
      The first instruction in the program was to branch around the literal "eye catchers" embedded in the executable program

  6. l +0 length(256)
      Enter the above command to list the content starting 'relative' address location 0
      Observe content is the same as listing 'absolute' address location starting at 11F00
      The program executable area can be referenced by either 'relative' or 'absolute' addressing

  7. at +14 (l 0r:15r)
      at +14 is Stmt 22 -- SETUP label and STM assembler mnemonic
      Stopping at +14 means the instruction at +14 is NOT executed until proceeding past +14 location
      Enter the above command to stop program execution at 'relative' address location 14, then
      - go to list content of all registers

  8. at +28 (l 0r:15r)
      at +28 is Stmt 34 -- L 2,=C'Begin' to load register 2 with content of character string 'Begin'
      Enter the above command to stop program execution at 'relative' address location 28, then
      - go to list content of all registers

  9. at +2C (l 2r)
      at +2C is Stmt 35 -- LA 2,=C'Begin' to load register 2 with address location of character string 'Begin'
      Enter the above command to stop program execution at 'relative' address location 2C, then
      - go to list content of register 2 which now contains the result of L 2,=C'Begin'

  10. at +30 (l 2r;l 11FF8. length(5) c)
      at +30 is Stmt 37 -- subtract register 2 from itself, SR 2,2, filling register 2 with zeroes
      Enter the above command to stop program execution at 'relative' address location 30, then
      - go to list content of register 2 containing result of LA 2,=C'Begin'
      Observe register 2 contains an 'absolute' address location, then the 'absolute' address location is listed
      The content of the 'absolute' address location is displayed

  11. at +32 (l 2r)
      at +32 is Stmt 38 -- load register 2 with the number 4, L 2,=F'4'
      Enter the above command to stop program execution at 'relative' address location 32, then
      - go to list content of register 2 containing zeros as a result of the previously executed SR 2,2

  12. at +36 (l 2r)
      at +36 is Stmt 39 -- load register 3 with the number 1, L 3,=F'1'
      Enter the above command to stop program execution at 'relative' address location 36, then
      - go to list content of register 2 which has result of L 2,=F'4'
      Observe register 2 changed from 0000000 to 0000004 as the result of L 2,=F'4'

  13. at +3A (l 2r:3r)
      at +3A is both Stmt 41 and Stmt 42 where:
      - Stmt 41 has label LOOP at the +3A Defined Storage location, LOOP DS 0H
      - Stmt 42 results in add 1 to register 3, A 3,=F'1'
      Enter the above command to stop program execution at 'relative' address location 3A, then
      - go to list content of registers 2 and 3
        where registers 2 equals 00000004 and register 3 equals 00000001 first time through the loop
      The program execution is designed to branch back to the +3A location,
        therefore, +3A location stopping point will be executed again

  14. at +3E (l 2r:3r)
      at +3E is Stmt 43 -- branch on count, BCT 2,LOOP
      Enter the above command to stop program execution at 'relative' address location 3E, then
      Each BCT execution results in decrement of register 2 by 1
      The result of BCT 2,LOOP is to branch to label LOOP at +3A until register 2 is zero
      The next stop is at +3A, storage address location of label LOOP adding 1 to register 3 until register 2 is zero
      - Enter the following commands to be executed when register 3 is zero, terminating the loop
        at +42
        at +46
        at +4A
        at +94

    go to list content of registers 2 and 3, then branch to LOOP
        Once register 2 is zero, then execution will stop at +42
          ** You will need to enter go numerous times to proceed with program execution

  15. When execution stops at +42, then
    l 2r:3r
       Register 2 and 3 show the final results of the loop
       Register 2 contains 00000000 as a result of BCT count decrement during each loop execution
       Register 3 contains 00000005 as a result of adding 1 during each loop execution
    l +e8
       Location +E8 has the content of HALFCON
       HALFCON is defined as a halfword, 'H', therefore the first 4 bytes, 0020 represents the halfword
    go to continue execution

  16. When execution stops at +46, then
      Stmt 45 -   STOP1   LH 3,HALFCON  was just executed
    l 3r
       Register 3 is a full word, therefore load halfword, 'LH', resulted in register 3 containing 00000020
    l +E0
       Content of value FULLCON is displayed, 'FFFFFFFF'
       However, the assembler Define Constant statement is DC F'-1'
       Why? FULLCON is an example of Two's Complement
       Two's Complement Explained
       For the purpose of computer arithmetic operation, FULLCON is -1
    go to continue execution

  17. When execution stops at +4A, then
      Stmt 46 -   STOP2   A 3,FULLCON  was just executed
    l 3r
        Register 3, 0000001F, is the result of adding x'20' to x'-1'
      Before continuing with program execution, list value of address location for HEXCON (+E4)
       l +E4
       Observe address location currently shows 00009ABC
    go to continue execution

  18. When execution stops at +94, then
      Stmt 47 -   STOP3   ST 3,HEXCON  was just executed
       ST 3,HEXCON stores the content of register 3 into address location HEXCON
    l 3r
       Register 3 still contains the result of the previous add operation unaltered by ST op code
    l +E4
       HEXCON address location was written over using the ST, Store, op code with content of Register 3
    go to continue execution

    The above go resulted in ASMPGM program termination returning control to caller TSO TEST facility
    Enter end to terminate TSO TEST facility, returning control to caller TSO

Return to ISPF by entering ISPF


Modify and re-compile ASMPGM assembler program

Edit z#####.source member name ASMPGM

  1. Use register 6 for all operations where register 2 was previously used
  2. Use register 7 for all operations where register 3 was previously used
  3. Initialize the register used to sum each add operation in the loop with a zero value
  4. Execute the loop 10 times adding 5 to the register being used to sum each add operation

Submit and verify results via SDSF and potentially using TSO TEST to see if ASMPGM is executing as you expected

Important: If you use TSO TEST to validate your ASMPGM is behaving as you expected, remember the register used to store the sum of the arithmetic add operation is in a hexadecimal value.


Action needed to get credit for the challenge

From ISPF command line, enter tso submit 'zos.public.jcl(p3ch13)'

The above JCL job copies your modified ASMPGM source code to P3.OUTPUT(#13)


If a person says to you, "It is not possible to Master the Mainframe by completing the contest". You can respond, "Well, I did learn it takes experience and repetition to truly Master the Mainframe. However, I also became familiar with the details of IBM Z assembler and modified assembler code during the contest."

Challenge #13 was a lot of work.

For your amusement - "I asked my manager about a mainframe you mentioned."

Next: Challenge #14