gtps4m12 | System Generation |
Pool file record addresses are obtained by issuing a get file storage (GFS) type macro. The application program may then store data in the record referenced by the given file address for whatever period of time is appropriate. A file address for a pool record is returned to the system through the use of a release file storage (RFS) type macro.
Pool file storage is managed through the use of pool directories built by offline programs and assigned to online system residency by special programs invoked in an initial system restart. There are several types of file pools based upon the attributes of:
The various types of pools may be considered as system record types.
Each type of pool is allocated some maximum number of records (usually a very large number). The base addresses of the various pool types are identified in the SYCON macro which is generated by FCTBG, and are held in keypoints during online execution for the use of the get file storage macros. The space required for the pools is accounted for in the FACE table.
Rather than maintain a unique space consuming a file address for each record, the system maintains a bit indicator in a pool directory. Each record within a pool type is indicated with a bit (for example, 0 or 1). The relative position of a bit within a directory determines an ordinal number within a pool type, shown in Figure 16. Upon a request for file storage, the GFS macro interpreter scans the directory for a 1. Upon a match, the relative position number within the directory is used as an ordinal number and the bit is switched to zero. A release file storage macro interpreter switches the availability bit of a short term pool record back to a one. In the case of a release, a FARF address must be converted into a relative bit position in a directory.
FARF address references in the pool area are generated by the get file storage facility. The resulting address is passed to the requesting program. This is the address to be referenced as a parameter of the FIND and FILE macro requests. The FIND and FILE macro interpreters perform the additional translation necessary to obtain the physical module number by using the FACE Table. Therefore, pool addresses, as well as fixed file addresses are independent of a change to online disk pack hardware addresses (for example, the system operator may have a need to bind a symbolic module number to different hardware addresses during online system activity).
Figure 16. Sample File Pool Directory
File pool records are classified according to the attributes of size, duplication, and length of intended use. The 10 basic pool types are:
Small, long-term record pool (SLT)
Small, short-term record pool (SST)
Small, long-term duplicate record pool (SDP)
Large, long-term record pool (LLT)
Large, short-term record pool (LST)
Large, long-term duplicate record pool (LDP)
4K, long-term record pool (4LT)
4K, short-term record pool (4ST)
4K, long-term duplicate record pool (4DP)
4K, long-term duplicate FARF6 record pool (4D6)
All pool records are duplicated in a completely duplicated file system. Only long-term pool records may be duplicated in a partially duplicated file system.
Pool records are not loaded like fixed records since the pool records are only used during execution of the online system. However, the directories which control the use of this area are loaded in the fixed file area by the online directory generation programs.
The recommended way to acquire pool addresses is by use of the GETFC macro, supplying the desired pool record ID only. The system then determines from the record ID attribute table (RIAT) the pool type and size (small, large, or 4K) required. The next available pool record of the requested type is assigned to the operational program. The program must then record the address of the record in order to later find the data it has inserted in it. Duplicates are obtained in the same manner as duplicated fixed file data records. (See TPF General Macros for more information about the GETFC macro.)
After fixed file requirements and their location on file have been determined, the remaining file space is available for assignment of file pool storage.
The considerations that should be taken into account in the assignment of file area for pool usage are:
The file pool ratio dispensing facility is provided to dispense addresses according to predetermined ratios for any basic pool type using several sections of the pool (for example, SST pool sections). When a pool section is selected, its ratio factor (that is, a number of addresses) is used to determine how many addresses will be dispensed from that section before selecting the next scheduled ratio. This facility thus allows the dispensing of addresses to be spread across several different device types.
A file pool storage record address may be obtained by executing one of the GFS macros for a large (LLT, LST, LDP), small (SLT, SST, SDP), or 4K (4LT, 4ST, 4DP, 4D6) record. The 10 basic file pools may be split across more than 1 (maximum of 4) storage device types. Each split is called a pool section. See TPF General Macros for a description of the GETLC, GETSC, and GETFC macros.
File pool ratio dispensing is an optional function selected by the operation of the online system function ZGFSP.
For each pool type there are ten sets; each set consists of 2 bytes. In each set, the first byte (a binary counter) contains the number of addresses (up to 100) to be dispensed before selecting the next set. The second byte contains the pool record code check (RCC). Unused sets should be set to zero. Only those devices specified by the RCC in the sets will participate in the ratio dispensing. The schedule is updated as a push-up list with the selected item placed at the bottom of the schedule. This results in a continuous rotation of the dispensing schedule.
The RCC is defined in the CZ1GF macro for various device type basic pool
sections. The assignments for DEVA pool sections are listed in Table 4.
Table 4. DEVA Pool Section Assignments
#SLTA EQU 4 | Small, long-term |
#SSTA EQU 8 | Small, short-term |
#SDPA EQU 12 | Small, duplicated |
#LLTA EQU 16 | Large, long-term |
#LSTA EQU 20 | Large, short-term |
#LDPA EQU 24 | Large, duplicated |
#4LTA EQU 28 | 4K, long-term |
#4STA EQU 32 | 4K, short-term |
#4DPA EQU 36 | 4K, duplicated |
#4D6A EQU 148 | 4K, long-term duplicated FARF6 |
The CZ1GF macro also contains similar equates for DEVB, DEVC and DEVD when the last character of the label is the device type.
When a depleted pool section is selected for address dispensing, and an alternate compatible pool section is used, a fallback situation is said to exist.
Selection of alternate pool sections for fallback processing is done based upon either a user-specified (primary), or a predefined default (secondary) fallback schedule. Secondary fallback is predefined by system design and system initialization.
The get/return file pool program (CCSONP CSECT) controls fallback pool selection for depleted pool sections. The Pool Cycle-Up Program initializes file pool fallback schedules as described previously.
If no fallback schedule has been specified or if all pool sections of a fallback schedule are depleted, system error number 000011 occurs unless the schedule pertains to a short-term basic pool type. For this latter case, long-term or duplicate pool sections are designated in the Pool Management Global Table by the Pool Cycle-Up Program as secondary short-term fallback schedules.
The fallback schedules in the Pool Descriptor Record contain record code check (RCC) characters which are assigned uniquely to each pool section. These equates are converted by the Pool Cycle-Up Program to indices, which are then used to select the respective pool sections for fallback.
Each pool type schedule consists of 6 bytes showing the order (left-to-right) in which to fall back to another pool section when all addresses of the pool section have been depleted.
Each byte contains the RCC for the device's pool type. The first byte in the fallback schedule must contain the RCC for the basic device type. Any unused bytes must be set to zeros (null entry). The last valid RCC, after depletion, will cause fallback to the first RCC specified in the schedule.
Any long-term pools not specified in the primary schedule will not have fallback capability. Short-term pools always automatically fallback to equivalent long-term pools when there are no more short-term addresses and no primary fallback schedule is specified. However, when primary fallback schedules are implemented, only short-term pools should be specified for fallback of a short-term pool.
In the coding of the fallback schedules, the null entries have no effect on efficiency, since the fallback schedules are used only when a pool section is depleted. Normally, this will not occur very often.
Specifying the characteristics of pool storage areas on direct access storage devices is accomplished via the SIP RAMFIL statement. A separate RAMFIL statement is required for each pool interval. The sequence of the RAMFIL statements determines the sequence of the record groups on file storage.
The following are the SIP RAMFIL parameters relating to pool intervals:
The SIP ONLFIL macro parameter NAMDEVx is used to change the four-character DASD device name (3350, 3380, 3390) which is used by the pool programs to any four-character name specified by the user. Renaming is required when two device types are identical (DEVICEA = 3380, DEVICEB = 3380) and may optionally be used to change the standard names (3350, 3380, and so on).
File pools residing on DASD devices have their options hard coded in keypoint record 9 (CTK9). After system generation and cycle up, these options may be displayed and altered via the miscellaneous file pool functions system operator command ZGFSP.
Directory records are created for file pools by the pool maintenance program.
Pool directory records reside in the fixed file area of the database. The user must provide SIP RAMFIL statements to allocate file space for these records. Pool directories require record type #SONRI (see data macro CY3DR).
Use the following formula to help determine the minimum number of pool directories for each pool section:
(2 × set size × number of processors) + 1
Users who are required to update one or more of the equate macros in order to generate their system properly should be aware of two cases of when and how to do so. For macros like CZ1GF, which are not generated by SIP, the macro should be updated/modified prior to the execution of SIP stage I. On the other hand for macros like SYCON, which is generated by the FACE table generator (FCTBG) the user should allow FCTBG to actually create its version of the macro and then the user should update/modify that version of the macro. It is very important that this updating take place prior to the assembly of any programs which call/use the macro in SIP jobs. The alternative is to allow SIP to complete Stage II and then to do the updates/modifications and then to reassemble and relink the affected modules.