HLASM - BAL = Branch And Link

The opcode of the BAL instruction is X'45'.

Usage

Branch to a subroutine - within a CSECT - and pass the return address.

Arguments

Register into which the return address will be passed.
Destination address (in index, base, displacement format).

Function

The processor places the address of the byte following the BAL instruction (which is both the next sequential instruction address and the expected return address) in the first register.
It branches to the destination address.
The condition code does not change.

Special Cases

None.

Related Instructions

BALR branches to an address that is specified in a register.
BCR is the preferred return instruction.
BAS is preferred over BAL.
BASSM branches to another routine that may need to be called in a different Amode.

Hardware

All hardware supports the BAL instruction.

Remarks

It is common practice to use register R15 for passing the return address, although other conventions are used as well.
The PSW's Amode setting determines how many bits are used for the return and destination addresses.
Subroutines are typically used for the following reasons:
1. When a section of code is required in multiple places.
2. When a section of code may be difficult to follow, and it's desired to keep it's logic separate from the routine within which it's used.
Subroutines within the addressable area of a CSECT are generally invoked using BAL (or BAS).
Subroutines in another program, in another CSECT, or past the end of common addressability generally are invoked using BALR or BASR.
Use of BAL is discouraged. Use BAS instead.
In Amode 24 the generated return address contains 8 high-order bits with additional PSW fields. This is usually regarded as garbage. The high-order bit of the 32-bit register may be set to one, which may cause problems if the called program returns with a BSM instead of one of the BCR instructions (typically BR instruction).

Examples

         YREGS                         * Define register names
         ...
* This contrived routine reads a file and copies the first record,
* and all non-blank records after it. It can be invoked by the instruction:
*        BAL   R14,COPYRTN
*
* Register usage:
* R2 = record pointer
* R9 = return address from subroutine
* R14= return address from copy routine
*
COPYRTN  ST    R14,RET_ADR             * Save our return address
         BAL   R9,READ                 * Go read the first record
LOOP     MVC   LINE,0(R2)              * move data to print line.
         BAL   R9,WRITE                * and go run the print routine.
SKIP     BAL   R9,READ                 * Go get the next record.
         CLC   SPACES,0(R2)            * Is the record blank?
         BNE   LOOP                    * no, go write it.
         B     SKIP                    * yes, just read the next.
*
* End-of-file: return to invoker
ALLDONE  L     R14,RET_ADR             * Retrieve return address
         BR    R14                     * and return
*
READ     READ  INPUT                   * Read a record.
         LR    R2,R1                   * Put record addr into reg-2
         BR    R9                      * and return.
*
WRITE    PUT   OUTPUT,LINE             * write current line,
         BR    R9                      * and return.
*
spaces   DC    CL80' '                 * Use to see if the input rec is blank.
LINE     DC    CL80' '                 * Print line.
*
INPUT    DCB   DDNAME=INFILE,DSORG=PS,DEVD=DA,EODAD=ALLDONE
OUTPUT   DCB   DDNAME=NEWFILE,DSORG=PA,DEVD=DA,LRECL=80,RECFM=FB
*

To the Opcodes Overview.
To the English Homepage for Hlasm.com.
To the General Homepage for Bixoft and Hlasm.com.

This site is a member of WebRing. You are invited to browse the list of mainframe-loving sites.		Dinos are not dead. They are alive and well and living in data centers all around you. They speak in tongues and work strange magics with computers. Beware the dino! And just in case you're waiting for the final demise of these dino's: remember that dinos ruled the world for 155-million years!
Dinos and other anachronisms [ Join Now \| Ring Hub \| Random \| << Prev \| Next >> ]

Below you find the logo of our sponsor and logos of the web-standards that this page adheres to.