Passing control

You may use two standard methods for passing control to another control section and providing for return of control. One is an extension of the method used to pass control without a return, and requires a V-type address constant and a branch, a branch and link, or a branch and save instruction provided both programs execute in the same addressing mode. If the addressing mode changes, use a branch and save and set mode instruction. The other method uses the CALL macro to provide a parameter list and establish the entry and return addresses. With either method, you must identify the entry point by an ENTRY instruction in the called control section if the entry name is not the same as the control section CSECT name. Figure 1 and Figure 2 illustrate the two methods of passing control; in each example, assume that register 13 already contains the address of a new save area.

Figure 1 also shows the use of an inline parameter list and an answer area. The address of the external entry point is loaded into register 15 in the usual manner. A branch and link instruction is then used to branch around the parameter list and to load register 1 with the address of the parameter list. An inline parameter list, such as the one shown in Figure 1, is convenient when you are debugging because the parameters involved are located in the listing (or the dump) at the point they are used, instead of at the end of the listing or dump. Note that the high-order bit of the last address parameter (ANSWERAD) is set to 1 to indicate the end of the list. The area pointed to by the address in the ANSWERAD parameter is an area to be used by the called control section to pass parameters back to the calling control section. This is a possible method to use when a called control section must pass parameters back to the calling control section. Parameters are passed back in this manner so that no additional registers are involved. The area used in this example is twelve words. The size of the area for any specific application depends on the requirements of the two control sections involved.

Figure 1. Passing Control With Return

          .
          .
          L      15,NEXTADDR          Entry address in register 15
          CNOP   0,4
          BAL    1,GOOUT              Parameter list address in register 1
PARMLIST  DS     0A                   Start of parameter list
DCBADDRS  DC     A(INDCB)             Input DCB address
          DC     A(OUTDCB)            Output DCB address
ANSWERAD  DC     A(AREA+X'80000000')  Answer area address with
                                      high-order bit on
NEXTADDR  DC     V(NEXT)              Address of entry point
GOOUT     BALR   14,15                Pass control; register 14 contains
                                      return address and current AMODE
RETURNPT  ...
AREA      DC     12F'0'               Answer area from NEXT

Note: This example assumes that you are passing control to a program that executes in the same addressing mode as your program. See Linkage considerations for information on how to handle branches between programs that execute in different addressing modes.

Figure 2. Passing Control With CALL

           CALL     NEXT,(INDCB,OUTDCB,AREA),VL
RETURNPT   ...
AREA       DC       12F'0'

Note: If you are using the CALL macro to pass control to a program that executes in a different addressing mode, you must include the LINKINST=BASSM parameter.

The CALL macro in Figure 2 provides the same functions as the instructions in Figure 1. When the CALL macro is expanded, the parameters cause the following results:

NEXT - A V-type address constant is created for NEXT, and the address is loaded into register 15.
(INDCB,OUTDCB,AREA) - A-type address constants are created for the three parameters coded within parentheses, and the address of the first A-type address constant is placed in register 1.
VL - The high-order bit of the last A-type address constant is set to 1.

Control is passed to NEXT using a branch and link instruction. (Optionally, you can specify either a BASR or BASSM instruction, with the LINKINST= parameter.) The address of the instruction following the CALL macro is loaded into register 14 before control is passed.

In addition to the results described above, the V-type address constant generated by the CALL macro requires the load module with the entry point NEXT to be link edited into the same load module as the control section containing the CALL macro. The z/OS MVS Program Management: User's Guide and Reference and z/OS MVS Program Management: Advanced Facilitiespublications tell more about this service.

The parameter list constructed from the CALL macro in Figure 2, contains only A-type address constants. A variation on this type of parameter list results from the following coding:

CALL   NEXT,(INDCB,(6),(7)),VL

In the above CALL macro, two of the parameters to be passed are coded as registers rather than symbolic addresses. The expansion of this macro again results in a three-word parameter list; in this example, however, the expansion also contains instructions that store the contents of registers 6 and 7 in the second and third words, respectively, of the parameter list. The high-order bit in the third word is set to 1 after register 7 is stored. You can specify as many address parameters as you need, and you can use symbolic addresses or register contents as you see fit.