Assembler Coding Techniques  Assembler Coding Examples http://www.simotime.com

Introduction
(Next) (Previous) (Table-of-Contents)

This suite of sample programs is written in IBM Mainframe Assembler. The programst will compile using Assembler/H or HLASM. This suite provides examples of some of the coding techniques that have been used by mainframe assembler programmers. They will run as MVS batch jobs on an IBM mainframe or as a project with Micro Focus Mainframe Express (MFE) running on a PC with Windows (refer to http://www.microfocus.com).

This programs may serve as a tutorial for programmers that are new to 370 assembler or as a reference for experienced programmers.

Examples of Coding Techniques
(Next) (Previous) (Table-of-Contents)

This section provides examples of specific coding techniques.

IEFBR14, A Very Small Program
(Next) (Previous) (Table-of-Contents)

On the mainframe files can be allocated, created or deleted using DD statements in JCL (Job Control Language). Also, JCL has a requirement that it must have a JOB statement and an EXEC statement. If a programmer simply wanted to create a file using a JCL member with a JOB statement and a DD statement it would cause an error. If the programmer added an EXEC statement the PGM keyword required a program name and this program would execute. Therefore, the need for a program that simply returned to the caller became a requirement. The first version of this program was two bytes (or x'07FE') and referred to as "the world's smallest program".

In the preceding example the BR OpCode is an extended mnemonic for the BCR (Branch on Condition Register) instruction. The BR mnemonic generates a BCR instruction that sets all the mask bits to 1's and this causes an unconditional branch to the address defined in Register 14.

Note: it is standard protocol for the calling program to provide a return address in register 14 .

If we take a closer look at the actual generated, two bytes of code (or x'07FE') the "07" is the opcode for the BCR instruction. The "F" of the "FE" byte is the mask for branching and since all bits are on it becomes an unconditional branch. The "E" of the "FE" byte specifies register 14.

It was not long before the first "bug" was reported. The "return code" was being set to a non-zero value and subsequent job steps that were dependent on the return code were failing. In a matter of minutes a fix was delivered and the size of the program doubled to four bytes (or x'1BFF07FE').

In the preceding example the SR OpCode is the mnemonic for the SR (Subtract Register) instruction. Therefore, subtracting the contents of register 15 from itself results in a zero value.

Note: it is standard protocol for register 15 to be used to store the return code value.

This new version has been running for years without any reported bugs. This is the story of " why and how " the program known as IEFBR14 was created.

First Time Logic
(Next) (Previous) (Table-of-Contents)

Sometimes an assembler routine is called many times and contains code segments that only need to be executed the first time the routine is called. The following is an example of the coding technique used to execute a segment of code the first time a routine is called.

This is a technique that is commonly used to perform first-time or one-time logic. The Branch Instruction is coded with a mask of zero and will never branch. It will fall through and execute the next sequential instruction. The first-time logic is inserted after the branch. A Move Immediate instruction is used to modify the Branch instruction to be an unconditional branch. The code following the branch will not execute again until a new copy of the program is loaded.

Note: This techniques was an acceptable practice many years ago because it was fast and only required eight bytes of memory. However, in today's world of structured programming it is no longer an accepted practice to use dynamic, self-modifying code.

Refer to the  First Time or One Time Logic  for more detail. To return to this point use the browser's "back" function.

Creating an EBCDIC Table
(Next) (Previous) (Table-of-Contents)

This is a rather esoteric coding technique for creating a sequential 256 byte table of the character set using a single instruction. The technique uses the addressing constant (ADCON) function of mainframe assembler. Let's take a look at how the 256AL1(*-TABLE) creates a 256 byte EBCDIC table. First, the AL1 says create a one byte ADCON. The value of 256 says repeat this creation process 256 time. Now the trick, the (*-TABLE) calculates the value of each of the 256, one byte ADCON's by taking the value of the current address (specified by the *) and subtracting the address of TABLE. For example, let's assume the table will be located at address x'00010000'. On the first ADCON creation the table address is x'00010000' and the current address is x'00010000' and the resulting ADCON is x'00'.

On the second iteration the address of the table is still x'00010000' but the current address is now x'00010001' and the resulting ADCON is x'01' This process keeps repeating itself for 256 times.

The preceding statement will generate the following.

Note: This technique may be considered as overly clever. For clarity it may be better to code as follows.

Refer to the  Table Routine in the Source Code  for more detail. To return to this point use the browser's "back" function.

Incrementing the Contents of a Register
(Next) (Previous) (Table-of-Contents)

This is a common coding technique used to increment the contents of a register. There are many ways to increase the contents of a register but this technique uses a single instruction and does not use any data items in memory.

The preceding Load Address (LA) instruction will load R3 with the value contained in R3 plus the displacement value or 1. Since the amount to increment the register is contained in the 3-byte displacement value of the LA instruction the register contents may be increased by a value of 1 through 4095 (i.e. x'001' through x'FFF'.

Refer to the  Incrementing Register Routine in the Source Code  for more detail. To return to this point use the browser's "back" function.

Decrementing the Contents of a Register
(Next) (Previous) (Table-of-Contents)

This is a common coding technique used to decrement the contents of a register. There are many ways to decrease the contents of a register but this technique uses a single instruction and does not use any data items in memory.

The preceding statement takes advantage of a unique characteristic of the Branch-on-Count-Register (BCTR) instruction. Normally the BCTR decrements the value in the register specified by operand-1 and when the content of the operand-1 register is non-zero a branch to the address specified in operand 2 is performed. There is one exception, if operand-2 is register zero then a branch is never executed. Therefore, the operand-1 register is decremented and a branch is never performed. In the preceding statement R3 will be decreased by a value of one and a branch is never performed.

Refer to the  Decrementing Register Routine in the Source Code  for more detail. To return to this point use the browser's "back" function.

Setting the High-Order Bit of a Register to ON
(Next) (Previous) (Table-of-Contents)

This is a common coding technique used to force the high order (left-most) bit of a register to an ON condition.

This technique uses the OR (O) instruction and in this example the value in memory of x'80000000' is OR'ed with the contents of register-3 and the result is placed in register-3. Therefore, if the contents of register-3 before the instruction is executed contains x'00000000' then after the preceding OR instruction is executed the contents of register-3 will equal x'80000000'.

The mainframe assembler has the capability to dynamically create literals. The =x'80000000' in the preceding statement will cause the compiler to generate the equivalent of the following instruction.

The literal pool for dynamically specified literals is generated at the end of the CSECT unless a LTORG statement is used. When a LTORG statement is used the literals created up to the point of the LTORG statement will be generated.

Refer to the  Set the High Order Bit ON  for more detail. To return to this point use the browser's "back" function.

Setting the High-Order Bit of a Register to OFF
(Next) (Previous) (Table-of-Contents)

This is a common coding technique used to force the high order (left-most) bit of a register to an OFF condition.

This technique uses the AND (N) instruction and in this example the value in memory of x'7FFFFFFF' is AND'ed with the contents of register-3 and the result is placed in register-3. Therefore, if the contents of register-3 before the instruction is executed contains x'FF010203' then after the preceding AND instruction is executed the contents of register-3 will equal x'7F010203'.

The mainframe assembler has the capability to dynamically create literals. The =x'7FFFFFFF' in the preceding statement will cause the compiler to generate the equivalent of the following instruction.

The literal pool for dynamically specified literals is generated at the end of the CSECT unless a LTORG statement is used. When a LTORG statement is used the literals created up to the point of the LTORG statement will be generated.

Refer to the  Set the High Order Bit OFF  for more detail. To return to this point use the browser's "back" function.

Initializing a Field to Spaces
(Next) (Previous) (Table-of-Contents)

This is a common coding technique used to initialize a field to spaces.

The preceding two statements take advantage of how the MOVE (MVC) instruction executes a move function. The first statement uses the Move Immediate (MVI) instruction to move a space to the first byte in the 80-byte field called DATA80. The MVC instruction performs the move byte-by-byte from left to right. By moving the value at the memory location of DATA80 to the memory location of DATA80+1 we move a space character to the next position in memory. Since the length of the MVC has been specified as 79 bytes this process will repeat resulting in the entire eighty bytes of DATA80 being initialized to spaces.

Refer to the  Initializing a Field to Spaces  for more detail. To return to this point use the browser's "back" function.

Swapping the Contents of Two Fields
(Next) (Previous) (Table-of-Contents)

The following takes advantage of the results of the eXClusive-OR instruction when executed multiple times. Notice the second eXClusive-OR has the fields reversed.

After executing the preceding three instructions the contents of WORKA16 and WORKZ16 will be swapped.

Refer to the  Swap Fields  for more detail. Use the browser "back" function to return to this point.

Setting/Testing the Return Code to Zero
(Next) (Previous) (Table-of-Contents)

This section describes how to set or test the value of the Return Code. Register 15 is used to pass the Return Code value between calling programs. Therefore, when you return to a COBOL program or a Job (JCL) and you want the Return Code to be Zero then you must place a value of Zero (x'00000000') into register 15.

There are a number of ways to place a value into register 15. The preceding two statements show how to set register 15 to zero. The first method is fast and simply subtracts register 15 from itself.

The second statement will also set register 15 to Zero by loading an address defined within the Load Address (LA) instruction into register 15. In the above example an address (or value) of Zero will be loaded into register 15.

The following statements show how to test register 15 for a Zero or non-Zero value.

The Load-and-Test-Register (LTR) instruction loads the value of a register into a register and sets the Condition Code (not Return-Code) based on whether or not the value of the targeted register is Zero. In this example register 15 is loaded with the contents of itself and therefore does not change. However, the Condition Code is set based on the content of register 15 being a Zero or non-Zero value.

The mnemonic branch (BNZ) instruction will branch to an abnormal termination routine if the value of register 15 is not Zero.

Refer to the  Set Return Code to Zero Logic  for more detail. To return to this point use the browser's "back" function.

The LTORG
(Next) (Previous) (Table-of-Contents)

The mainframe assembler has the capability to dynamically create literals within the coding of assembler statements by using the literal definition preceded by an equal sign. For example, =X'C1C1C1C1' or =C'AAAA' will cause a four byte area of memory to be allocated with the value of "AAAA".

The preceding is an example of the LTORG statement. The literal pool for dynamically specified literals is generated at the end of the CSECT unless a LTORG statement is used. When a LTORG statement is used the literals created up to the point of the LTORG statement will be generated.

The JCL Member
(Next) (Previous) (Table-of-Contents)

The following is the mainframe JCL (ASMTRXJ1.JCL) required to run the mainline program. The coding technique is used with the expectation the JCL would be used as a stand alone procedure. This will also run on the PC using Mainframe Express provided by Micro Focus.

//ASMTRXJ1 JOB SIMOTIME,ACCOUNT,CLASS=1,MSGCLASS=0,NOTIFY=CSIP1
//* *******************************************************************
//*                   This program is provided by:                    *
//*                    SimoTime Enterprises, LLC                      *
//*           (C) Copyright 1987-2010 All Rights Reserved             *
//*                                                                   *
//*             Web Site URL:   http://www.simotime.com               *
//*                   e-mail:   helpdesk@simotime.com                 *
//* *******************************************************************
//*
//* Text   - 370 Assembler, Assembler Coding Techniques
//* Author - SimoTime Enterprises
//* Date   - January 01, 1997
//*
//* This 370 Assembler program will show a few of the programming
//* techniques used by assembler programmers.
//*
//* This set of programs will run on a mainframe under MVS or on a
//* Personal Computer with Windows and Micro Focus Mainframe Express.
//*
//* The real value is in the animation of this program. You can
//* immediately see the results of each instruction execution. This
//* is a very effective way to become familiar with the 370
//* instruction set.
//*
//* *******************************************************************
//* Step   1 of 1  This is a single step job.
//*
//TRIXSTP1 EXEC PGM=ASMTRXA1
//STEPLIB  DD  DSN=SIMOTIME.DEMO.LOADLIB1,DISP=SHR
//*

Source Code for the Examples
(Next) (Previous) (Table-of-Contents)

This program (ASMTRXA1.MLC) does not provide much visual information when it is executed on the mainframe. The real value to this program is when it is animated using the 370 Assembler Option of Mainframe Express provided by MERANT. It is possible to watch the actual execution of each individual instruction and to immediately see the results.

ASMTRXA1 CSECT
***********************************************************************
*                    This program is provided by:                     *
*                     SimoTime Enterprises, LLC                       *
*            (C) Copyright 1987-2010 All Rights Reserved              *
*                                                                     *
*              Web Site URL:   http://www.simotime.com                *
*                    e-mail:   helpdesk@simotime.com                  *
***********************************************************************
*                                                                     *
* Created: 1993/06/01, Simmons                                        *
* Changed: 1993/06/01, Simmons, no changes to date...                 *
*                                                                     *
***********************************************************************
*                                                                     *
* Micro Focus Mainframe Express, version 2.5 or later with the        *
* the Assembler Option is required. This program provides a sample    *
* of some of the coding techniques used by assembler programmers.     *
* You can immediately see the results of each instruction execution.  *
* This is a very effective way to become familiar with how these      *
* techniques work.                                                    *
*                                                                     *
* Note: The comments on the EQU statements are HTML links.            *
*                                                                     *
***********************************************************************
*
         BALR  11,0              Prepare a base register
         USING *,11              Establish register as the base
*
***********************************************************************
* WTO to display the copyright information
*
         WTO   '* ASMTRXA1 Examples of Assembler Coding Tips  v03.01.24-
                http://www.simotime.com'
         LTR   R15,R15     IS REG-15 = ZERO...
         BNZ   ABEND4         IF NOT, ABEND...
*
         WTO   '* ASMTRXA1 Copyright 1987-2010  SimoTime Enterprises, L-
               LC   All Rights Reserved'
         LTR   R15,R15     IS REG-15 = ZERO...
         BNZ   ABEND4         IF NOT, ABEND...
*
         WTO   '* ASMTRXA1 is STARTING...'
*
ONETIME  EQU   *                 
***********************************************************************
* This is a technique that is commonly used to perform first-time or
* one-time logic. The Branch Instruction is coded with a mask of zero
* and will never branch. It will fall through and execute the next
* sequential instruction. The first-time logic is inserted after the
* branch. A Move Immediate instruction is used to modify the Branch
* instruction to be an unconditional branch. The code following the
* branch will not execute until a new copy of the program is loaded.
***********************************************************************
NOBRANCH BC    X'00',ONEJUMP     First time through is a no-op
         MVI   NOBRANCH+1,X'F0'  Change to unconditional branch
         B     NOBRANCH          First time logic, perform once
ONEJUMP  EQU   *
*
TABLERTN EQU   *                 
***********************************************************************
* This is how you create a 256 byte table of the EBCDIC character set
* in a single instruction. This is a rather esoteric technique.
* Also note the technique used to branch around the table
* without having to use a label.
***********************************************************************
         B     *+4+256         * BRANCH around the TABLE
TABLE    DC    256AL1(*-TABLE) * Create a 256 byte TABLE
*
INCRREGS EQU   *                 
***********************************************************************
* This is how you increment the contents of a register.               *
* The incrementing value may be 1-4095.                               *
***********************************************************************
         LA    R3,0            * Set R3 to ZERO          X'00000000'
         LA    R3,1(,R3)       * Increment REG-3 by 1    X'00000001'
         LA    R3,2(,R3)       * Increment REG-3 by 2    X'00000003'
         LA    R3,3(,R3)       * Increment REG-3 by 3    X'00000006'
*
DECRREGS EQU   *                 
***********************************************************************
* This is how you decrement the contents of a register.               *
* The decrementing value is limited to 1.                             *
* When the second operand points to register-0 then no branch.        *
***********************************************************************
         LA    R3,5            * SET R3 to FIVE         X'00000005'
         BCTR  R3,R0           * DECR OP-1, NO BRANCH   X'00000004'
         BCTR  R3,R0           * DECR OP-1, NO BRANCH   X'00000003'
         BCTR  R3,R0           * DECR OP-1, NO BRANCH   X'00000002'
*
BITON    EQU   *                 
***********************************************************************
* Set the high-order bit of a register to a ON condition.             *
***********************************************************************
         LA    R3,0            * Set R3 to ZERO
         O     R3,=X'80000000' * Set HIGH-ORDER BIT ON   X'80000000'
*
BITOFF   EQU   *                 
***********************************************************************
* Set the high-order bit of a register to a OFF condition.            *
***********************************************************************
         L     R3,=X'FF010203' * Set R3 to HEX FF010203
         N     R3,=X'7FFFFFFF' * Set HIGH-ORDER BIT OFF  X'7F010203'
*
INIT80   EQU   *                 
***********************************************************************
* Initialize an eighty byte field to spaces.                          *
***********************************************************************
         MVI   DATA80,X'40'         * Move a space to 1st position
         MVC   DATA80+1(79),DATA80  * Propagate space through field
*
SWAP16   EQU   *                 
***********************************************************************
* One of the unique results of doing three eXClusive OR instructions  *
* is the contents of the defined items are swapped.                   *
***********************************************************************
         MVC   WORKA16,A16           Move all A's to WORKA16
         MVC   WORKZ16,Z16           Move all Z's to WORKZ16
         XC    WORKA16(16),WORKZ16 * The next three exclusive-or
         XC    WORKZ16(16),WORKA16   instructions will swap WORKA16
         XC    WORKA16(16),WORKZ16   contents with WORKZ16 contents
*
RCTOZERO EQU   *                 
***********************************************************************
* Test the return-code (Register-15) for a zero value                 *
***********************************************************************
         MVC   WTODATA(8),=C'LTRTRICK'
         LA    R15,0           * Set R15 to Zero value
         LTR   R15,R15         * Load R15 with itself and test content
         BZ    *+8             * If zero, branch over next instruction
         B     ABEND08         * This instruction should never execute
*
***********************************************************************
* NORMAL END-OF-JOB                                                   *
* RETURN to the CALLING PROGRAM OR OPERATING SYSTEM                   *
***********************************************************************
         WTO   '* ASMTRXA1 is FINISHED...'
         SR    15,15           * Set RETURN-CODE to ZERO
         BR    14              * RETURN to CALLER
*
ABEND4   EQU   *
***********************************************************************
* ABENDING WITH RETURN-CODE OF 4                                      *
*
         WTO   '* ASMTRXA1 MLC, is ABENDING, RC=4...'
         RETURN (14,12),RC=4
*
*
ABEND08  EQU   *               * ABEND routine
***********************************************************************
* ABENDING WITH RETURN-CODE OF 8                                      *
* RETURN to the CALLING PROGRAM OR OPERATING SYSTEM                   *
***********************************************************************
         WTO   MF=(E,WTOBLOCK)
         LA    R15,8
         BR    14
WTOBLOCK DC    H'84'
         DC    XL2'0000'
WTODATA  DC    CL80'???????? ASMTRXA1 is ABENDING...'
***********************************************************************
* Define Constants and EQUates                                        *
***********************************************************************
         DS    0F            + Force alignment
DATA80   DC    80XL1'00'
*
         LTORG
*
R0       EQU   0
R1       EQU   1
R2       EQU   2
R3       EQU   3
R4       EQU   4
R5       EQU   5
R6       EQU   6
R7       EQU   7
R8       EQU   8
R9       EQU   9
R10      EQU   10
R11      EQU   11
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15
*
         DS    0F            + Force alignment
A16      DC    16CL1'A'
Z16      DC    16CL1'Z'
WORKA16  DC    16CL1'A'
WORKZ16  DC    16CL1'Z'

*
         END

Summary
(Next) (Previous) (Table-of-Contents)

The purpose of this document is to assist as a tutorial for new assembler programmers or as a quick reference for experienced programmers. The samples focus on the coding techniques of the individual instructions. As always, it is the programmer's responsibility to thoroughly test all programs.

Software Agreement and Disclaimer
(Next) (Previous) (Table-of-Contents)

Permission to use, copy, modify and distribute this software for any commercial purpose requires a fee to be paid to Simotime Enterprises. Once the fee is received by SimoTime the latest version of the software will be delivered and a license will be granted for use within an enterprise, provided the SimoTime copyright notice appear on all copies of the software. The SimoTime name or Logo may not be used in any advertising or publicity pertaining to the use of the software without the written permission of SimoTime Enterprises.

Permission to use, copy and modify this software for any non-commercial purpose and without fee is hereby granted, provided the SimoTime copyright notice appear on all copies of the software. The SimoTime name or Logo may not be used in any advertising or publicity pertaining to the use of the software without the written permission of SimoTime Enterprises.

SimoTime Enterprises makes no warranty or representations about the suitability of the software for any purpose. It is provided "AS IS" without any express or implied warranty, including the implied warranties of merchantability, fitness for a particular purpose and non-infringement. SimoTime Enterprises shall not be liable for any direct, indirect, special or consequential damages resulting from the loss of use, data or projects, whether in an action of contract or tort, arising out of or in connection with the use or performance of this software.

If you have any questions, suggestions or comments please call or send an e-mail to: helpdesk@simotime.com

Downloads and Links to Similar Pages
(Next) (Previous) (Table-of-Contents)

You may download this example at http://www.simotime.com/sim4dzip.htm#AsmCodingTechniques as a Z-Pack. The Z-Packs provide individual programming examples, documentation and test data files in a single package. The Z-Packs are usually in zip format to reduce the amount of time to download.

Please view the complete list of SimoTime Z-Pack Examples at http://www.simotime.com/sim4dzip.htm.

Note: You must be attached to the Internet to download a Z-Pack or view the list.

Check out  The Assembler Connection  for more examples of mainframe Assembler coding techniques and sample code.

Check out  The JCL Connection  for more mainframe JCL examples.

Check out  The SimoTime Library  for a wide range of topics for Programmers, Project Managers and Software Developers.

To review all the information available on this site start at  The SimoTime Home Page .

Comments or Suggestions
(Next) (Previous) (Table-of-Contents)

If you have any questions, suggestions or comments please call or send an e-mail to: helpdesk@simotime.com

About SimoTime Enterprises
(Next) (Previous) (Table-of-Contents)

Founded in 1987, SimoTime Enterprises is a privately owned company. We specialize in the creation and deployment of business applications using new or existing technologies and services. We have a team of individuals that understand the broad range of technologies being used in today's environments. This includes the smallest thin client using the Internet and the very large mainframe systems. There is more to making the Internet work for your company's business than just having a nice looking WEB site. It is about combining the latest technologies and existing technologies with practical business experience. It's about the business of doing business and looking good in the process. Quite often, to reach larger markets or provide a higher level of service to existing customers it requires the newer Internet technologies to work in a complementary manner with existing corporate mainframe systems. Whether you want to use the Internet to expand into new market segments or as a delivery vehicle for existing business functions simply give us a call or check the web site at http://www.simotime.com