Top ten ways to shoot yourself in the foot in S/390 Assembler

1. Modifying a base register
   
   Typically this happens when you are adding a new feature to an old program. You jump in and cut&paste a routine from another program and suddenly you've shot-yourself-in-the-foot. For example:

       USING csect,R12,R11,R10
       ...
       ...
       BAS   R10,do_something
       

   You'll get a S0C1, S0C4 or some other nasties.
   
   
2. Using the wrong branching code or extended mnemonic
   
   Some S/390 machine instructions change the condition code and later code must act correctly based on the condition. The assembler does not have a PARM='DOWHATIMEAN'. For example, you've decided that you'd rather be testing a flag byte instead of a value byte.

   Buried somewhere in your program is: TM field,value BE here

   but you needed this code: TM field,value BO here

   
   
   
3. L vs LA
   
   Two rules to understand:
   • Using a "L" instruction when you need the "LA" instruction will cause you untold grief.
   • Using a "LA" instruction when you need the "L" instruction will cause you untold grief.
   
   Thanks to Roland Schiradin for sending me the suggestion about L vs. LA.
   
   
4. Linking a non-Reentrant program Reentrant
   
   You have a program that's been running for years and it starts S0C4ing out of the blue. One thing to check is if it has been linked Reentrant but doesn't follow the rules of reentrancy. This will only byte bite you if the load library is APF-authorized. Reentrant program that reside in APF authorized libraries get loaded into key zero storage. Attempts to modify key zero storage by unauthorized programs result in... a nice user-friendly S0C4.
   
   
5. Specifing immediate character instead of literal
   
   There are a few machine instructions that take operands that are easily miscoded and overlooked. For example, let's say you coded CLC FLAG,C'1' when you meant CLC FLAG,=C'1'. Your program will assemble with a RC=0 but will not execute as expected.
   
   Looking at the generated OPCODEs, you can see the difference:

   Loc Object Code Addr1 Addr2 Stmt Source Statement 000000 00000 00011 1 MYCSECT CSECT , R:F 00000 2 USING *,R15 3 * 000000 D500 F00C 00F1 0000C 000F1 4 CLC FLAG,C'1' 5 * 000006 D500 F00C F010 0000C 00010 6 CLC FLAG,=C'1' 7 * 00000C F1 8 FLAG DC C'1' 9 * 000010 10 LTORG , 000010 F1 11 =C'1'

   I'd like to thank Gilbert Saint-flour for sending me this suggestion.
   
   
6. Register operands on Macros may be specified incorrectly
   
   You may shoot-yourself-in-the-foot by assuming that the register operand you've specified on a Macro was specified correctly. Many times you will need to look at the expansion of the Macro to see if what you intended was actually used by the Macro.
   
   Bob Shannon sent me this example:

   This is what was intented: LA R6,32 length for obtain STORAGE OBTAIN,LENGTH=(6),ADDR=(7),LOC=ANY + CNOP 0,4 + B IHB0001B .BRANCH AROUND DATA +IHB0001F DC BL1'00000000' .FLAGS @D5C + DC AL1(0*16) .KEY + DC AL1(0) .SUBPOOL + DC BL1'00110010' .FLAGS +IHB0001B DS 0F + LR 0,6 .STORAGE LENGTH + L 15,IHB0001F .CONTROL INFORMATION + L 14,16(0,0) .CVT ADDRESS + L 14,772(14,0) .ADDR SYST LINKAGE TABLE + L 14,160(14,0) .OBTAIN LX/EX FOR OBTAIN + PC 0(14) .PC TO STORAGE RTN + LR 7,1 .SAVE ADDR OF STORAGE

   This STORAGE OBTAIN is incorrect and gets 6 bytes and not 32: LA R6,32 length for obtain STORAGE OBTAIN,LENGTH=6,ADDR=(7),LOC=ANY + CNOP 0,4 + B IHB0002B .BRANCH AROUND DATA +IHB0002L DC A(6) .STORAGE LENGTH +IHB0002F DC BL1'00000000' .FLAGS @D5C + DC AL1(0*16) .KEY + DC AL1(0) .SUBPOOL + DC BL1'00110010' .FLAGS +IHB0002B DS 0F + L 0,IHB0002L .STORAGE LENGTH + L 15,IHB0002F .CONTROL INFORMATION + L 14,16(0,0) .CVT ADDRESS + L 14,772(14,0) .ADDR SYST LINKAGE TABLE + L 14,160(14,0) .OBTAIN LX/EX FOR OBTAIN + PC 0(14) .PC TO STORAGE RTN + LR 7,1 .SAVE ADDR OF STORAGE

   In this case, the only way to find the error was to check the expansion of the Macro to see how it used the LENGTH= operand.
   
   
7. Rob Scott sent me this one:
   1. Program uses R2 as a base or linkage register
   2. You add a TRT instruction to the code
   This program will function fine until the TRT returns a non-zero value (eg fails the TRT) - R2 will now be overwritten by the TRT instruction and now you 'branch to the car-park' (0C4).
   
   
8. Reserved for future items. Send email to dave@planetmvs.com.

Ways to avoid "Shooting yourself in the foot"

• Use the options of the HLASM
  
  Advances in the assembler itself has helped:
  
  • HLASM's PARM='MXREF' - Prior to the SLAC mods and the HLASM, the assembler didn't report on which library in the //SYSLIB concatenation a macro was resolved from. In many cases your assembly //SYSLIB concatenation order causes a problem. See the HLASM tips entry Resolving macro problems with the HLASM.
  • HLASM's PARM='RXREF' - The Register Cross Reference was added in HLASM V1.3. Before, you could only find references in the XREF output for equates like R0, R1, R2, etc and other references in macros might not be found.
  
  
  
• Use the HILITE feature of the ISPF editor
  
  The HILITE feature of the ISPF editor was added in ISPF version 4. It changes the text of your edit data based on the type of edit file. This feature can be used to find programming errors.
  
  For example, our security adminstrators aren't assembler programmers. They do have to maintain an assembler source file for the SDSF parameters. One day I got a call that they were stumped: they added a new userid to the source file, it assembled with RC=0 but the user couldn't access SDSF. I went into ISPF view on the source, turned on the HILITE option, did a find on the failing userid and it visually jumped out at me that he had left off a trailing comma on a line with a continuation:

  ROCKGRPS ISFNTBL PAGE,1,PLANT,1,JAGGER,1,RICHARDS,1 X LENNON,1,MCCART,1

  When the comma was added to the line, you get the intended result:

  ROCKGRPS ISFNTBL PAGE,1,PLANT,1,JAGGER,1,RICHARDS,1, X LENNON,1,MCCART,1

  "Thinking" always slows you down. Use the HILITE option to cut down on having to think!.
  
  
• Avoid writing new code!
  
  You should develop general purpose subroutines which can be easily used in new programs you write.
  
  There's an old joke about OS/2: There was only one OS/2 program ever written, the first one. The rest were just cut and paste.

Ways to make debugging easier

• Use standard OS eyecatchers
  
  Every executable CSECT should have a "standard OS eyecatcher" that includes the CSECT name and assembly date and time. See the 'SYS1.MACLIB(SAVE)' macro for an example of an IBM macro creating one. Basically:
  
  

  The first instruction of the CSECT should be a branch around the eyecatcher Followed by a length byte Then text of your choice

  A_EC B A_ECL(0,R15) Branch past EyeCatcher DC AL1(A_ECE-A_ECV) Length of Eyecatcher A_ECV DC C'CSECTA - &SYSDATC &SYSTIME - ' DC C'program description here' A_ECE EQU * DS 0H A_ECL EQU *-A_EC

  
  Not only can you easily verify load modules via ISPF browse, you also reap the benefit when viewing the "Save Area Trace" portion of the SYSUDUMP output (if you chain your Save Areas). For example, look at SAMPEC.TXT and the following output from the dump where I've highlighted the "standard OS eyecatcher":

   SAVE AREA TRACE
  
   PROCEEDING FORWARD FROM TCBFSA
  
   NAME=SAMPEC
   WAS ENTERED VIA LINK         AT EP CSECTA - 19990623 10.47 - Main CSECT in SAMPEC: Calls CSECTB
   SA   00005FA8  WD1 00000000   HSA 00000000   LSA 00006DDC   RET 80FD0310   EPA 00006D78   R0  FD000008
                  R1  00005FF8   R2  00000040   R3  009DB7D4   R4  009DB7B0   R5  009F9120   R6  009A5FF8
                  R7  FD000000   R8  009F9000   R9  009F93A0   R10 00000000   R11 009F9120   R12 00E62612
  
   NAME=SAMPEC
   WAS ENTERED VIA CALL         AT EP CSECTB - 19990623 10.47 - Calls CSECTC which has no eyecatcher
   SA   00006DDC  WD1 00000000   HSA 00005FA8   LSA 00006E94   RET 40006DD2   EPA 00006E28   R0  FD000008
                  R1  00005FF8   R2  00000040   R3  009DB7D4   R4  009DB7B0   R5  009F9120   R6  009A5FF8
                  R7  FD000000   R8  009F9000   R9  009F93A0   R10 00000000   R11 009F9120   R12 00006D78
  
   Note: the next entry is for CSECTC which does NOT have a Standard OS eyecatcher
         Notice how we are in the dark with no "AT EP yada yada yada" information!
  
   NAME=SAMPEC
   WAS ENTERED VIA CALL
   SA   00006E94  WD1 00000000   HSA 00006DDC   LSA 00006F0C   RET 40006E8E   EPA 00006EE0   R0  FD000008
                  R1  00005FF8   R2  00000040   R3  009DB7D4   R4  009DB7B0   R5  009F9120   R6  009A5FF8
                  R7  FD000000   R8  009F9000   R9  009F93A0   R10 00000000   R11 009F9120   R12 00006E28
  
   NAME=SAMPEC
   WAS ENTERED VIA CALL         AT EP CSECTD - 19990623 10.47 - We ABEND to show Save Area Trace
   SA   00006F0C  WD1 00000000   HSA 00006E94   LSA 00006FB8   RET 40006F02   EPA 00006F58   R0  FD000008
                  R1  00005FF8   R2  00000040   R3  009DB7D4   R4  009DB7B0   R5  009F9120   R6  009A5FF8
                  R7  FD000000   R8  009F9000   R9  009F93A0   R10 00000000   R11 009F9120   R12 00006EE0
   SA   00006FB8  WD1 00000000   HSA 00006F0C   LSA 00000000   RET 00000000   EPA 00000000   R0  00000000
                  R1  00000000   R2  00000000   R3  00000000   R4  00000000   R5  00000000   R6  00000000
                  R7  00000000   R8  00000000   R9  00000000   R10 00000000   R11 00000000   R12 00000000
  
   INTERRUPT AT 00006FB6
  
   PROCEEDING BACK VIA REG 13
  
   SA   00006FB8  WD1 00000000   HSA 00006F0C   LSA 00000000   RET 00000000   EPA 00000000   R0  00000000
                  R1  00000000   R2  00000000   R3  00000000   R4  00000000   R5  00000000   R6  00000000
                  R7  00000000   R8  00000000   R9  00000000   R10 00000000   R11 00000000   R12 00000000
  
   NAME=SAMPEC
   WAS ENTERED VIA CALL         AT EP CSECTD - 19990623 10.47 - We ABEND to show Save Area Trace
   SA   00006F0C  WD1 00000000   HSA 00006E94   LSA 00006FB8   RET 40006F02   EPA 00006F58   R0  FD000008
                  R1  00005FF8   R2  00000040   R3  009DB7D4   R4  009DB7B0   R5  009F9120   R6  009A5FF8
                  R7  FD000000   R8  009F9000   R9  009F93A0   R10 00000000   R11 009F9120   R12 00006EE0
  

  See how nice it is to have the Eyecatcher on CSECTA, CSECTB and CSECTD and the loss of information on CSECTC which doesn't have one.
  
  
• Use ID fields in storage
  
  If all of your GETMAIN'd storage, be it control blocks, data areas, buffers, whatever, has some type of ID field at the beginning and the end, your job will be a lot easier when you are looking at the storage in a dump format (SYSUDUMP, SYSABEND, IPCS, etc.).
  
  A well known database, I won't say it's name but its initials are IDMS, doesn't use ID fields on some of it's major control blocks like its CSA area. This saves storage but makes debugging harder.
  
  Here's an example of a data area that will be easy to verify in a dump:

  MYAREA      DSECT ,
  MYAREA_ID   DS    CL8'MYAREA'
  ...other fields here...
  MYAREA_END  DS    CL4'END '
  

• The Top 10 Ways to get screwed by the "C" programming language
• The Top 10 Ways to get screwed by the "Java" programming language