Coding for the Shared Virtual Area

Note: The description and the example shown in Figure 1 are primarily intended for a 24-bit environment. For the linkage conventions valid for a 31-bit environment, refer to Supported Addressing Modes, Data Spaces and Virtual Disks.

Besides accommodating the system directory list (SDL) and phases that are needed by the system, the shared virtual area (SVA) may contain user-written phases that can be used concurrently by more than one program. SVA phases must be re-enterable and relocatable; code that modifies itself will cause a protection check when executed from the SVA. This section presents some advice on coding phases to use SVA facilities and suggests some standards for base-register usage.

The basic assumptions for coding an SVA phase are:
  • The re-enterable code must not modify any storage within its own storage area. Therefore, the code must not contain DTFs, CCBs, or other control blocks that are modified during execution.
  • The phase can modify registers only if it saves and restores them for each user.
  • A user-specified work area (within the calling partition) must be provided for storing registers and for any storage modifications.
Suggested register conventions:
  • Use register 12 as the base register in both the main routine and the re-enterable code.
  • Use register 13 as base for the working storage area. It is the responsibility of the main routine to provide addressability to the work area by loading register 13; the re-enterable routine must not modify register 13. The easiest way to address the working storage area in the re-enterable code is by a DSECT that defines the fields of the work area and a USING dsectname,13. In this way symbolic addressing can be used.
  • Use CALL, SAVE, and RETURN macros. As register 13 is the base register, SAVE (14,12) and RETURN (14,12) result. Use register notation for CALL, for example, CALL (15) .... Before issuing the CALL, load register 15 with the transfer address. Register 14 will always contain the return address. The standard is thus established of register 15 for calling and register 14 for returning.
  • Switches, and other areas that may be modified, can be placed in the working storage area using base register 13.

Figure 1 illustrates the suggested conventions: MAINRTN is the main routine, SUBRTN is the SVA phase.

Figure 1. Example of Conventions for SVA Coding
 
 MAINRTN   CSECT
           BALR     12,0
           USING    *,12
           LA       13,SAVE
           LOAD     SUBRTN,WORKAREA       CANCELS IF SUBRTN NOT IN LIB
  *                                       LOADS SUBRTN INTO WORKAREA
  *                                       IF SUBRTN IS NOT IN SVA
           LR       15,1
           CALL     (15),(SWITCH,TECB,FIELDA,FIELDB,WORKAREA)
           .
           .
           EJO
  SAVE     DS       9D
  WORKAREA DS       200D                  SUBRTN IS LOADED HERE
  *                                       IF NOT IN SVA
  SWITCH   DC       XL1'00'
  TECB     DS       CL4
  FIELDA   DS       CL15
  FIELDB   DS       CL11
           END

  SUBRTN   CSECT                          MUST BE SEPARATE ASSEMBLY
           SAVE     (14,12)
           BALR     12,0
           USING    *,12
           USING    WORKAREA,6
           LM       2,6,0(1)
           MVC      0(15,4),DATA1
           MVC      0(11,5),DATA2
           CLI      0(2),X'FF'
           BE       EXIT
           SETIME   3,(3)                 SETIME ALTERS THE TECB
           WAIT     (3)
           .
           .
  EXIT     XI       0(2),X'FF'
           RETURN   (14,12)
  DATA1    DC       CL15'THIS IS FIELDA'
  DATA2    DC       CL11'THIS IS FIELDB'
           LTORG
  WORKAREA DSECT
  FIELDC   DS       3D
  FIELDD   DS       3D
           END