How control is returned

In the discussion of the return under Analyzing the return, it was indicated that the control section returning control must restore the contents of registers 2-14. Because these are the same registers reloaded when control is passed without a return, refer to the discussion under “Passing Control without Return” for detailed information and examples. The contents of registers 0 and 1 do not have to be restored.

Register 15 can contain a return code when control is returned. As indicated previously, a return code should be a multiple of four with a return code of zero indicating a normal return. The return codes other than zero that you use can have any meaning, as long as the control section receiving the return codes is aware of that meaning.

The return address is the address originally passed in register 14; you should always return control to that address. If an addressing mode switch is not involved, you can either use a branch instruction such as BR 14, or you can use the RETURN macro. An example of each of these methods of returning control is discussed in the following paragraphs. If an addressing mode switch is involved, you can use a BSM 0,14 instruction to return control. See Figure 1 for an example that uses the BSM instruction to return control.

Figure 1 shows a portion of a control section used to analyze input data cards and to check for an out-of-tolerance condition. Each time an out-of-tolerance condition is found, in addition to some corrective action, one is added to the one-byte value at the address STATUSBY. After the last data card is analyzed, this control section returns to the calling control section, which bases its next action on the number of out-of-tolerance conditions encountered. The coding shown in Figure 1 loads register 14 with the return address. The contents of register 15 are set to zero, and the value at the address STATUSBY (the number of errors) is placed in the low-order eight bits of the register. The contents of register 15 are shifted to the left two places to make the value a multiple of four. Registers 2-12 are reloaded, and control is returned to the address in register 14.

Figure 1. Establishing a Return Code

         .
         .
         L     13,4(13)      Load address of previous save area
         L     14,12(13)     Load return address
         SR    15,15         Set register 15 to zero
         IC    15,STATUSBY   Load number of errors
         SLA   15,2          Set return code to multiple of 4
         LM    2,12,28(13)   Reload registers 2-12
         BR    14            Return
         .
         .
STATUSBY DC    X'00'

Note: This example assumes that you are returning to a program with the same AMODE. If not, use the BSM instruction to transfer control.

The RETURN macro saves coding time. The expansion of the RETURN macro provides instructions that restore a designated range of registers, load a return code in register 15, and branch to the address in register 14. If T is specified, the RETURN macro flags the save area used by the returning control section (that is, the save area supplied by the calling routine). It does this by setting the low-order bit of word four of the save area to one after the registers have been restored. The flag indicates that the control section that used the save area has returned to the calling control section. The flag is useful when tracing the flow of your program in a dump. For a complete record of program flow, a separate save area must be provided by each control section each time control is passed.

You must restore the contents of register 13 before issuing the RETURN macro. Code the registers to be reloaded in the same order as they would have been designated for a load-multiple (LM) instruction. You can load register 15 with the return code before you write the RETURN macro, you can specify the return code in the RETURN macro, or you can reload register 15 from the save area.

The coding shown in Figure 2 provides the same result as the coding shown in Figure 1. Registers 13 and 14 are reloaded, and the return code is loaded in register 15. The RETURN macro reloads registers 2-12 and passes control to the address in register 14. The save area used is not flagged. The RC=(15) parameter indicates that register 15 already contains the return code, and the contents of register 15 are not to be altered.

Figure 2. Using the RETURN Macro

         .
         .
         L        13,4(13)        Restore save area address
         L        14,12(13)       Return address in register 14
         SR       15,15           Zero register 15
         IC       15,STATUSBY     Load number of errors
         SLA      15,2            Set return code to multiple of 4
         RETURN   (2,12),RC=(15)  Reload registers and return
         .
         .
STATUSBY DC       X'00'

Note: You cannot use the RETURN macro to pass control to a program that executes in a different addressing mode.

Figure 3 illustrates another use of the RETURN macro. The correct save area address is again established, and then the RETURN macro is issued. In this example, registers 14 and 0-12 are reloaded, a return code of 8 is placed in register 15, the save area is flagged, and control is returned. Specifying a return code overrides the request to restore register 15 even though register 15 is within the designated range of registers.

Figure 3. RETURN Macro with Flag

        .
        .
        L        13,4(13)
        RETURN   (14,12),T,RC=8