gtpi1m5zSystem Installation Support Reference

Programming Considerations

This section contains programming considerations for defining and using global areas.

Defining Addressability to Globals

This section contains programming considerations for defining global areas.

Global Records

When defining a new global, you must decide which global area the new global should be addressed from. A global record can reside in GL1, GL2, or GL3, but it is addressed from a directory slot in GL1 or GL3. To address the new global record from GL1's directory, you must label one of the 56 doubleword slots in the GL0BA macro. The tag on the 8-byte field then points to the GL1 directory slot for the new global record. To address the global record from GL3's directory, you must update the GL0BY macro in a similar manner. If either GL0BA or GL0BY is updated, then the GLOBZ macro, which allows application programs to access the global area, must also be updated. The GLOBZ macro must be updated because it contains a list of global records addressed by GL0BY and GL0BA, and the directory tag for the new GL3 or GL1 global record must be added to that list.

Another consideration is the degree of storage protection desired for the new global. The GL1 and GL3 areas both have protection keys different from that assigned to E-type programs and require the use of GLMOD and FILKW (or KEYRC) macros to change from one key to another. The GL2 area, on the other hand, has the same protection key as E-type programs and can be directly addressed without special macros.

Addressing extended globals presents no special problems: the GL1 directory is used to address records stored in extended GL1 or GL2; the GL3 directory is used to address records stored in extended GL2 or GL3. The chief consideration is that programs written to access extended globals must be allocated to run in 31-bit mode or must switch to 31-bit mode by using MODEC MODE=31.

See Loading Globals for more information about allocating a new global record and creating an input data set used for the pilot tape.

Global Fields

Whether a global field is to be SSU common or unique determines in which global area the global field should be defined. SSU unique fields should be defined only in the GL1 area. SSU user common fields must reside in the GL3 area.

Global Fields in Global Area 1

To address GL1 records and fields, the GLOBZ macro must be used with the REGR option. This invokes macro GLOB which, in turn, invokes macros GL0BA, GL0BB, GL0BC, GL0BD, GL0BE, GL0BF, and GL0BG.

The following summarizes the result of these macro calls:

  1. Besides calling the other macros, GLOB declares storage for the GL1 directory and for the global blocks. GLOB includes the following code:
     @GLOBA   DS    56D        DEFINE THE AREA FOR 56 SLOTS
     @GLOBB   DS    132D            X'84'         1056   BYTES
     @GLOBC   DS    132D            X'84'         1056   BYTES
     @GLOBD   DS    9D              X'09'         72     BYTES
     @GLOBE   DS    8D              X'08'         64     BYTES
     @GLOBF   DS    17D             X'11'         136    BYTES
     @GLOBG   DS    3D              X'03'         24     BYTES
              GL0BA                 DIRECTORY AREA
              GL0BB                 NON-KEYPOINTABLE MISC FIELDS
              GL0BC                 KEYPOINTABLE MISC FIELDS
              GL0BD                 F/Q NON-KEYPOINTABLE FIELDS
              GL0BE                 F/Q KEYPOINTABLE FIELDS
              GL0BF                 EXPANSION FOR NON-KEYPOINTABLE
              GL0BG                 EXPANSION FOR KEYPOINTABLE
     
    
  2. The GL0BA macro maps the GL1 directory. Storage is declared for 56 doubleword slots. Each slot to which a global will be loaded should have a label. The GL0BA DSECT must not address more directory slots than are declared in the @GLOBA DS instruction.
  3. The amount of storage GLOB declares for each global block must be greater than or equal to the amount of storage defined in each DSECT. In the preceding example, the sum of all the global fields defined in GL0BD must be less than or equal to 72 bytes.
  4. The sum of the storage declared by GLOB must not exceed 4KB, since the directory and global blocks are all addressed from one base register.
  5. The amount of storage declared for each global block must exactly match the number of doublewords that will be loaded into that area (see Number of Doublewords under GOA List Entry).

To define addressability to a new global field in GL1, you must modify one of GL1's global field DSECTs: GL0BB, GL0BC, GL0BD, GL0BE, GL0BF, or GL0BG. If the DSECT is modified to declare additional storage, then GLOB must be updated to declare additional storage.

Global Fields in Global Area 3

To address GL3 records and fields, the GLOBZ macro must be used with the REGS or REGC option. GLOBZ calls GL0BY, which in turn calls GL0BP and GL0BQ. GL0BY includes the following code:

 @GL0BY   DS    68D        DEFINE THE AREA FOR 68 SLOTS
 @GL0BP   DS    132D            X'84'         1056   BYTES
 @GL0BQ   DS    132D            X'84'         1056   BYTES
          GL0BP                 NON-KEYPOINTABLE TPF GLOBAL
          GL0BQ                 KEYPOINTABLE TPF GLOBAL
 

GL3 is very similar to GL1:

  1. GL0BY declares storage and addresses for the GL3 directory and the global blocks.
  2. The directory has exactly 68 doubleword slots declared.
  3. GL0BP and GL0BQ macros address the global blocks. As in GL1, the amount of storage addressed by GL0BP and GL0BQ must not exceed the number of doublewords declared by GL0BY.
  4. The amount of storage declared for each global block must exactly match the number of doublewords that will be loaded into that area (see Number of Double Words in GOA List Entry).
  5. The sum of storage GL0BY declares for the directory and the global blocks must not exceed 4KB.

To define addressability to a new global field in GL3, you must modify either GL0BP or GL0BQ. As in GL1, if the amount of storage added to GL0BP or GL0BQ causes the DSECT to exceed the amount declared by GL0BY, GL0BY must be updated. For new global fields in GL3, the GLOBZ macro must also be updated. The tag for the new global field must be added to the list of subsystem user common fields in the beginning of the GLOBZ macro.

Keypointable Global Records

A global record can be keypointed if it is addressed from one of the first 48 slots of the GL1 directory or from one of the first 64 slots of the GL3 directory. The KEYUC macro should contain an entry for each of the 48 slots in GL1. The GLOUC macro should have an entry for each of the 64 slots in GL3. Global fields are considered keypointable if they reside in a keypointable global record. How to designate a global as keypointable is described under Attribute Byte in GOA List Entry.

Global Area Requirements of the Control Program

GL1 contains not only fields for application use but also fields required by the system itself. Examples are @MAXCL and @MAXBK, which are used in creating output messages. @MAXCL is a 2-byte field that contains the maximum line length for a standard CRT display, usually 64 characters. @MAXBK is a 2-byte field that contains the maximum number of characters allowed in one message block, the maximum being 342 characters per block.

A typical application field is @SWITCH, which is tested during cycling up or down to determine whether any running utility programs should be halted.

GL0BD, GL0BE, and GL0BF do not contain any fields required by the system. Usually, those fields are in GL0BP and GL0BQ.

Required System Data Resident in GL0BP

The GL0BP data macro contains the following fields used by RLCH (chain release routine) and DBR (database reorganization):