The term “program linkage” or simply “linkage” encompasses all
the techniques required to make separately assembled control sections work
cooperatively. This includes transfers
of execution between control sections as well as the communication of data
between control sections or programs.
To facilitate program linkage, IBM developed a series of rules called
“Linkage Conventions” which specify the responsibilities of the cooperating
programs. We will call the main program
the “calling program” and the subroutine it calls the “called program”. Each type of program has it own conventions.
The Calling Program’s Conventions
1) Register 13 should contain the address of a “Save Area”. The save area is a contiguous collection of
18 fullwords that is used as a storage area for the registers. Since there are only 16 registers which must
be shared by all programs, the calling program must provide the address of its
save area in register 13. Subsequently,
the called program stores the contents of the registers in this area before
continuing execution.
2) Register 15 should contain the entry point address of the called
program. Since the entry point is not
in the calling program, we must use a “virtual” address constant in order to
reference the entry point. For example,
suppose the entry point in the called program is the CSECT name “SUBPROG”. Then the following instruction would load
register 15 properly.
L R15,=V(SUBPROG)
When the assembler processes
the virtual address constant, it recognizes that the symbol SUBPROG is not part
of the current control section. As a
result it assembles a fullword containing zeros for the virtual address. When the linkage editor combines the calling
and called subprograms, the fullword is filled in with the correct runtime
address of SUBPROG. Only “external”
symbols can be used for entry points into a control section. Control section names are automatically
external. Other symbols can be declared
external using the EXTRN directive.
3) When passing variables from the main program to the subprogram,
the address of each variable we wish to pass becomes an entry in a list of
consecutive fullword addresses. The
address of the list is placed in register 1.
Assume we want to pass variables X, Y, and Z. The following code will create the address list and initialize
register 1.
LA R1,=A(X,Y,Z)
The following diagram
illustrates the structure which is created by the above command. We assume the
following declarations.
X DC
CL3’ABC’
Y DC
CL2’PQ’
Z DC
CL4’DEFG’
Notice that only one item of
data is passed - the address of the
list of addresses. You must use
register 1 to find all the variables which are passed.
4) Register 14 should be initialized with the “return” address. This is the address to which the called
program will transfer control when it has completed execution. The following instruction will accomplish
this.
BASR R14,R15
BASR stores
the address of the instruction following the BASR in register 14, and branches to the address in register
15. In this way, control is transferred
to the subprogram.
The Called Program’s Conventions
1) The called program must save the current values of the registers
in the caller’s save area. Since the
caller has placed the address of the save area in register 13, the following
code will save the registers.
STM R14,R12,12(R13)
Notice that the explicit
address 12(R13) means that R14 is stored in the fourth fullword in the save
area ( 12 bytes off R13 ). You should also note that all the registers are
stored except R13. Register 13 contains
the address of the save area and must be stored in an area that belongs in the
called program.
The format of the save area
is listed below. We assume a sequence
of program calls: Program “A” calls
Program “B”, and Program “B” calls Program “C”. The save area in the diagram is for Program “B”.
2) The contents of register 13 ( the address of the caller’s save
area ) must be stored in the second fullword of the called program’s save
area. This can be done using the
following instruction.
ST R13,SAVE+4
Notice that “SAVE” refers to
the save area in the called program.
“SAVE+4” becomes a “backwards pointer” to the previous save area. This is illustrated below.
Additionally, the called
program can store the address of its own save area in the calling program’s
save area in the third word (SAVE+8).
This last technique is usually omitted and will not be used in this
topic.
3) Like the calling program, R13 should contain the address of the
program’s save area. This is
accomplished with the same instruction used in the main program.
LA R13,SAVE
4) Register 1 can be used to access any variables that are passed
from the main program. For example,
suppose X, Y, and Z are passed as parameters as described in step 3 of the “The
Calling Program’s Conventions”. Assume
that Y is defined as CL2 in the main program, and YSUB is defined as CL2 in the
subprogram. The data in Y can be copied
to YSUB as follows.
L R8,4(R0,R1) LOAD THE
2ND ADDRESS CONSTANT
MVC YSUB,0(R8) R8 POINTS
AT Y IN THE MAIN
The technique of copying a
variable to the subprogram and working with the copy is called “Pass by
Value”. An alternative would be to work
directly with Y in the main program.
This technique is called “Pass by Reference”. Either technique is acceptable according to the linkage conventions. “Pass by Value” provides protection for the
main program from “side effects” generated by the subprogram.
5) At the end of the subprogram the called program must restore the
registers to the values that were stored in the save area. The following code will restore the
registers.
L R13,SAVE+4
LM R14,R12,12(R13)
6) The called program should initialize register 15 with a return
code value to indicate the results of the subprogram. Generally, return codes are multiples of four - 0, 4, 8, ...
where 0 indicates success, 4 is a warning, and all the other codes indicate
that errors have occurred. The
following command will initialize register 15 with a small ( < 4096 ) return
code.
LA R15,8 SET RETURN CODE TO 8
7) The subprogram can return to the caller by branching to the
return address that was stored in register 14 by the caller.
BR R14
The following code illustrates a calling and called program side
by side.
MAIN CSECT SUB
CSECT
STM R14,R12,12(13) STM R14,R12,12(R13)
BASR R12,R0 BASR
R12,R0
USING *,R12
USING *,R12
ST R13,SAVE+4 ST
R13,SAVE+4
LA R13,SAVE LA
R13,SAVE
... ...
LA R1,=A(X,Y,Z) L R8,0(R0,R1)
L R15,=V(SUB) MVC
XSUB,0(R8)
BASR R14,R15 L
R8,4(R0,R1)
...
MVC YSUB,0(R8)
EXIT EQU
*
L R8,8(R0,R1)
L R13,SAVE+4 MVC
ZSUB,0(R8)
LM R14,R12,12(R13) ...
LA R15,0
EXIT EQU *
BR R14 L R13,SAVE+4
... LM R14,R12,12(R13)
X DS
CL4
LA R15,0
... BR R14
Y DS
CL2
XSUB DS CL4
Z DS
F
YSUB DS CL2
SAVE DS
18F
ZSUB DS F
END MAIN
SAVE DS 18F
END SUB
1. Each program you write should follow the calling program’s
conventions as well as the called program’s conventions. The operating system treats each main
program you write as a subprogram and so even a main program behaves as a
subprogram. On the other hand, each
subprogram you write may call other programs either explicitly or by requesting
services from the operating system.
Write each program as if it is one link in a chain of program
calls.
