Example of using a linkage assist routine

Figure 1 shows a “before” and “after” situation involving modules USER1 and USER2. USER1 invokes USER2 by using a LOAD and BALR sequence. The “before” part of the figure shows USER1 and USER2 residing below 16 megabytes and lists the changes necessary if USER2 moves above 16 megabytes. USER1 does not change.

The “after” part of the figure shows how things look after USER2 moves above 16 megabytes. Note that USER2 is now called USER3 and the newly created linkage assist routine has taken the name USER2.

The figure continues with a coding example that shows all three routines after the move.

Figure 1. Example of a Linkage Assist Routine

USER1 (This module will not change):

*  USER MODULE USER1 CALLS MODULE USER2                          00000100
USER1    CSECT                                                   00000200
BEGIN    SAVE   (14,12),,*  (SAVE REGISTER CONTENT, ETC.)        00000300
*  ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA (NORMAL          00000400
*  ENTRY CODING)                                                 00000500
           .
           .
*  ISSUE LOAD FOR MODULE USER2                                   00000700
         LOAD   EP=USER2    ISSUE LOAD FOR MODULE "USER2"        00000800
*  The LOAD macro returns a
*  pointer-defined value.  However, because module USER1
*  has not been changed and executes in AMODE 24, the
*  pointer-defined value has no effect on the BALR
*  instruction used to branch to module USER2.
         ST     0,EPUSER2   PRESERVE ENTRY POINT                 00000900
           .
*  MAIN PROCESS BEGINS                                           00001000
PROCESS  DS     0H                                               00001100
           .
           .
           .
           .
           .
           .
*  PREPARE TO GO TO MODULE USER2                                 00002000
         L      15,EPUSER2  LOAD ENTRY POINT                     00002100
         BALR   14,15                                            00002200
           .
           .
           .
           .
         TM                 TEST FOR END                         00003000
         BC     PROCESS     CONTINUE IN LOOP                     00003100
           .
         DELETE EP=USER2
         L      13,4(13)
         RETURN (14,12),T,RC=0  MODULE USER1 COMPLETED           00005000
EPUSER2  DC     F'0'       ADDRESS OF ENTRY POINT TO USER2       00007000
         END    BEGIN                                            00007100

USER2 (Original application module):

*  USER MODULE USER2 (INVOKED FREQUENTLY FROM USER1)             00000100
USER2    CSECT                                                   00000200
         SAVE   (14,12),,*  SAVE REGISTER CONTENT, ETC.          00000300
*  ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA (NORMAL          00000400
*  ENTRY CODING)
           .
           .
           .
           .
           .
         L      13,4(13)
         RETURN (14,12),T,RC=0  MODULE USER2 COMPLETED           00008100
         END                                                     00008200

USER2 (New linkage assist routine):

* THIS IS A NEW LINKAGE ASSIST ROUTINE                            0000100
* (IT WAS NAMED USER2 SO THAT MODULE USER1 WOULD NOT              0000200
*  HAVE TO BE CHANGED)                                            0000300
USER2    CSECT                                                    0000400
USER2    AMODE  24                                                0000500
USER2    RMODE  24                                                0000600
         SAVE   (14,12),,*  (SAVE REGISTER CONTENT, ETC.)         0000700
*  ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA (NORMAL           0000800
*  ENTRY CODING)
           .
* FIRST TIME LOGIC, PERFORMED ON INITIAL ENTRY ONLY,              0002000
* (AFTER INITIAL ENTRY, BRANCH TO PROCESS (SHOWN BELOW))          0002100
           .
         GETMAIN         NEW REGISTER SAVE AREA                   0003000
           .
         LOAD   EP=USER3                                          0004000
*  USER2 LOADS USER3 BUT DOES NOT DELETE IT.  USER2 CANNOT
*  DELETE USER3 BECAUSE USER2 DOES NOT KNOW WHICH OF ITS USES
*  OF USER3 IS THE LAST ONE.
         ST     0,EPUSER3   PRESERVE POINTER DEFINED VALUE        0004100
           .
* PROCESS  (PREPARE FOR ENTRY TO PROCESSING MODULE)               0005000
           .
         (FOR EXAMPLE, VALIDITY CHECK REGISTER CONTENTS)
           .
           .
* PRESERVE AMODE FOR USE DURING RETURN SEQUENCE                   0007000
         LA     1,XRETURN           SET RETURN ADDRESS            0008000
         BSM    1,0                 PRESERVE CURRENT AMODE        0008100
         ST     1,XSAVE             PRESERVE ADDRESS              0008200
         L      15,EPUSER3          LOAD POINTER DEFINED VALUE    0009000
* GO TO MODULE USER3                                              0009100
         BASSM  14,15               TO PROCESSING MODULE          0009200
* RESTORE AMODE THAT WAS IN EFFECT                                0009300
         L      1,XSAVE             LOAD POINTER DEFINED VALUE    0009400
         BSM    0,1                 SET ADDRESSING MODE           0009500
XRETURN  DS     0H                                                0009600
         L      13,4(13)
           .
         RETURN (14,12),T,RC=0      MODULE USER2 HAS COMPLETED    0010000
EPUSER3  DC     F'0'                POINTER DEFINED VALUE         0010100
XSAVE    DC     F'0'                ORIGINAL AMODE AT ENTRY       0010200
         END                                                      0010500
_________________________________________________________________________

Statements 8000 through 8200: These instructions preserve the AMODE in effect at the time of entry into module USER2.
Statement 9200: This use of the BASSM instruction:
- Causes the USER3 module to be entered in the specified AMODE (AMODE 31 in this example). This occurs because the LOAD macro returns a pointer-defined value that contains the entry point of the loaded routine, and the specified AMODE of the module.
- Puts a pointer-defined value for use as the return address into Register 14.
Statement 9400: Module USER3 returns to this point.
Statement 9500: Module USER2 re-establishes the AMODE that was in effect at the time the BASSM instruction was issued (STATEMENT 9200).

USER3 (New application module):

*  MODULE USER3    (PERFORMS FUNCTIONS OF OLD MODULE USER2)      00000100
USER3    CSECT                                                   00000200
USER3    AMODE  31                                               00000300
USER3    RMODE  ANY                                              00000400
         SAVE   (14,12),,*  (SAVE REGISTER CONTENT, ETC.)        00000500
*  ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA                  00000600
           .
           .
           .
           .
           .
           .
*  RESTORE REGISTERS AND RETURN                                  00008000
           .
         RETURN (14,12),T,RC=0                                   00008100
         END                                                     00008200
_________________________________________________________________________

Statements 300 and 400 establish the AMODE and RMODE values for this module. Unless they are over-ridden by linkage editor PARM values or MODE control statements, these are the values that will be placed in the PDS for this module.
Statement 8100 returns to the invoking module.