Domain: | SYSTEM-TUNING |
Privileges: | TSOS |
Function
The /START-DAB-CACHING command is used to create DAB cache areas . The buffered database can be selected automatically by AutoDAB (specification of AREA=*BY-SYSTEM) or manually (specification of AREA=*FILE(...)).
The exact DAB method of operation can be specified for each cache area separately as follows:
selecting the data areas to be served
selecting the cache area with regard to storage type (MM) and size of the cache (CACHE-SIZE)
defining the cache area ID (CACHE-ID)
defining the caching mode (read, write or read/write cache)
defining the size of cache segments (4, 8, 16 or 32 KB)
defining the data backup level with or without defining threshold-controlled saving to disk
implicitly defining the caching technique via the CACHE-SIZE operand (displacement according to LRU or resident buffering)
defining the location of the cache area and its management data (resident below or non-resident above the minimum main memory size)
defining whether data on shared pubsets is to be served as well.
/START-DAB-CACHING command is restricted to a maximum of 4096 characters (including blanks and comments).The changeable attributes of a configured DAB cache area can be modified dynamically using the /MODIFY-DAB-CACHING command (see "MODIFY-DAB-CACHING Modify parameters of DAB cache area dynamically").
Format
START-DAB-CACHING | Alias: SRDABC | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
AREA = *BY-SYSTEM / *FILE(...)
Assigns data areas either automatically or manually at file level.
AREA = *BY-SYSTEM(...)
Assignment is made based on pubset/private disks. AutoDAB selects the files to be served on these volumes.
PUBSET = *NO / list-poss(100): <cat-id>
Specifies the pubsets/volume sets to be served with automatic caching by DAB.
PUBSET = *NO
No pubsets are to be served. The pubsets must be added to the data area with /MODIFY-DAB-CACHING.
PUBSET = list-poss(100): <cat-id>
Specifies the pubsets/volume sets whose files are to be served by DAB. The catalog IDs are to be specified (up to 100).
PRIVATE-VOLUME = *NO / list-poss(100): <vsn>
Specifies the private disks to be served with automatic caching by DAB.
PRIVATE-VOLUME = *NO
No private disks are to be served. Specification of PUBSET is then mandatory.
PRIVATE-VOLUME = list-poss(100): <vsn>
Specifies the private disks whose files are to be served by AutoDAB. The VSNs of the private disks (up to 100) containing the files are to be specified.
AREA = *FILE(...)
Assigns data areas at file level.
FILE-AREA = *NO
No file specified. The files must be added to the data area with /MODIFY-DAB-CACHING.
FILE-AREA = list-poss(16): <filename 1..54 without-vers>
The files specified here are to be served by DAB immediately. Up to 16 files may be specified. Further files can, however, be added to the data area using /MODIFY-DAB-CACHING.
CACHE-SIZE =
Defines the size of the cache area.
CACHE-SIZE = <integer 1..8388608>(...)
Size of the cache area which is to be used for buffering the data areas identified by the AREA operand.
DIMENSION = *KILOBYTE / *MEGABYTE
Determines whether the size of the cache area is specified in KB or MB.
The more memory used in the main memory cache medium for caching, the less memory there is available for paging activities. A rise in the paging rate reduces the performance gain for DAB and should therefore be avoided.The value should be a multiple of 32 KB. If it is not, DAB rounds it down to the next lowest multiple of 32. The allocation for key and management data is added to this value.The value of <integer> must be smaller than 7/8 of the main memory which is still available for paging, or the installation-specific value must be adjusted.
CACHE-SIZE = *BY-FILE
The size of the cache area depends on the data areas specified with the FILE-AREA operand.
CACHE-SIZE=*BY-FILE is only permitted if the data areas to be served are specified via the FILE-AREA operand. Any expansion of the disk storage allocation for these files effected while they are being served by DAB automatically expands the associated cache area.
CACHE-ID = *STD / <name 1..32>
Defines an identifier for the cache area.
CACHE-ID = *STD
Default value: BUFFER#iii (iii = lowest internal DAB number not yet assigned.)
CACHE-ID = <name 1..32>
Identifier assigned to the new cache area. <name> must not contain any special character other than ’#’ , ’@’ and ’$’ and must start with a letter.
CACHING-MODE = *READ / *WRITE / *READ-WRITE / *BY-CACHE-MEDIUM
Defines the caching mode to be used.
CACHING-MODE = *READ
Caching mode is read.
CACHING-MODE = *WRITE
Caching mode is write.
CACHING-MODE = *READ-WRITE
Caching mode is read/write.
CACHING-MODE = *BY-CACHE-MEDIUM
The setting for read or read/write caching is dependent on the data area specification.
Manual caching at file level (specification AREA=*FILE):
The READ caching mode is set.Automatic caching (specification AREA=*BY-SYSTEM):
The READ caching mode is set for permanent files and the READ-WRITE caching mode isi set for temporary files. Temporary files are saved to disk when they are closed to ensure failsafe caching.
CACHE-MEDIUM = *MAIN-MEMORY(...)
The cache area is to be set up in main memory.
CACHE-SEGMENT-SIZE = *32 / *4 / *8 / *16
Defines the size of segments in the new cache area in KB. The operand is ignored for cache areas with automatic caching (AREA=*BY-SYSTEM).
MEMORY = *STD / *ANY / *BELOW-MIN-MEM-SIZE / *ABOVE-MIN-MEM-SIZE
Defines the system in which dynamic main memory reconfiguration is possible, and the location of the cache area and its management data.
On systems on which no main memory reconfiguration is possible, the operand values *ANY / *BELOW-MIN-MEM-SIZE / *ABOVE-MIN-MEM-SIZE are equivalent to each other; but sizes may be changed in the event of memory saturation. No size adjustment takes place with *STD.
MEMORY = *STD
The cache area and its management data are (as in earlier DAB versions) created as resident below the minimum main memory size. The size of the cache area must comply with the following formula when it is created:CACHE-SIZE ≤ 7/8 * (P - 5) MB
where P specifies (in MB):
the size of the pageable main memory in the system when no main memory reconfiguration is possible
the size of the pageable main memory below the minimum main memory size when main memory reconfiguration is possible
MEMORY = *ANY
The cache area and its management data are (preferably) created above and below the minimum main memory size.
When the main memory is reconfigured or the minimum main memory size is increased, the size of the cache areas is also adjusted. If necessary, the size of the cache areas is reduced to 0. The main memory size of a system can thus be handled flexibly.
The size of the cache area must comply with the following formula when it is created:CACHE-SIZE ≤ 7/8 * (P - 64) MB
where P specifies (in MB) the size of the pageable main memory in the system.
MEMORY = *ABOVE-MIN-MEM-SIZE
The cache area and its management data are created only in the size which is possible above the minimum main memory size.
When the main memory is reconfigured or the minimum main memory size is increased, the size of the cache areas is also adjusted.
The size of the cache area must comply with the following formula when it is created:CACHE-SIZE ≤ 7/8 * (P - 64) MB
where P specifies (in MB) the size of the pageable main memory above the minimum main memory size.
If there is no pageable main memory above the minimum main memory size, the cache area is created with the size 0. When the main memory is then enlarged later, it will be expanded to the size specified in the CACHE-SIZE operand.
MEMORY = *BELOW-MIN-MEM-SIZE
The cache area and its management data are created as resident below the minimum main memory size.
The size of the cache area must comply with the following formula:CACHE-SIZE ≤ 7/8 * (P - 64) MB
where P specifies (in MB):
the size of the pageable main memory in the system when no main memory reconfiguration is possible
the size of the pageable main memory below the minimum main memory size when main memory reconfiguration is possible
When a higher value is specified for the cache size in the CACHE-SIZE operand, a cache size in accordance with the formula above is selected. If the minimum main memory size is increased later, the size of the cache area is increased to the desired cache size in accordance with the formula above.
In the case of main memory saturation, the cache size is automatically reduced. When the main memory saturation has been resolved, the cache size is increased again.
FORCE-OUT = *AT-LOW-FILLING / *AT-HIGH-FILLING / *NO
Specifies whether save runs are to be triggered by a threshold value. This operand is
relevant only with caching modes WRITE, READ-WRITE or BY-CACHE-MEDIUM (see
“Notes”, point 4). The operand is irrelevant for cache areas with automatic
caching (AREA=*BY-SYSTEM) (see "Automatic FORCE-OUT correction" (Automatic caching (AutoDAB))).
FORCE-OUT = *AT-LOW-FILLING
Threshold-controlled save runs are to be performed to keep the number of cache segments not saved to disk at any one time as small as possible. This specification triggers saving whenever 25% of the cache is filled with write data not yet saved to disk.
FORCE-OUT = *AT-HIGH-FILLING
Save runs for this cache area are to be restricted to the number required to ensure there are always enough segments available for caching. This specification triggers saving whenever 75% of the cache is filled with write data not yet saved to disk.
FORCE-OUT = *NO
No threshold-controlled save runs are to be performed to transfer data from this cache area to disk. Data transfer to disk is not performed until the cache area is released by means of the /STOP-DAB-CACHING command.
SHARED-DISK-SUPPORT = *NO / *YES
Determines whether data areas on disks used as shared pubsets are to be supported as well with AREA=*FILE (see Notes 6 and 7). This applies to read mode only.
SHARED-DISK-SUPPORT = *NO
No data area is to be served that is located on a disk operated as a shared pubset when DAB starts service for the first time.
SHARED-DISK-SUPPORT = *YES
A disk data area is to be served even if the disk is operated as a shared pubset the next time DAB starts service.
Return codes
| (SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
| 0 | CMD0001 | No error | |
| 0 | NDB0021 | No error. Cache area created with reduced size. | |
| 1 | CMD0202 | Syntax or semantic error in command | |
| 32 | CMD0221 | Internal SDF error | |
| 64 | CMD0216 | Required privilege missing | |
| 64 | NDB0005 | No authorization to invoke the command | |
| 64 | NDB0010 | Wrong syntax file version | |
| 64 | NDB0012 | DMS error | |
| 64 | NDB0013 | Multiple file specification | |
| 64 | NDB0016 | Cache memory bottleneck | |
| 64 | NDB0017 | Memory bottleneck (cache or management data) or system failure | |
| 64 | NDB0018 | Cache ID already defined | |
| 64 | NDB0025 | Volume not allocated | |
| 64 | NDB0026 | File not cataloged | |
| 64 | NDB0027 | Tape file or migrated file | |
| 64 | NDB0028 | File/volume already being served | |
| 64 | NDB0032 | File on PFA pubset cannot be served with /START-DAB- CACHING | |
| 64 | NDB0034 | File on key disk cannot be added to the cache area without keys | |
| 64 | NDB0036 | CACHE-SIZE=*BY-FILE permissible only in conjunction with file specification | |
| 64 | NDB0065 | /STOP-SUBSYSTEM is active | |
| 64 | NDB0066 | No default cache ID available | |
| 64 | NDB0071 | File cannot be cached because it is encrypted and the cache is a write cache | |
| 64 | NDB0072 | Unknown user ID | |
| 64 | NDB0080 | Automatic caching of data in the home pubset is not permissible in a write or read/write cache | |
| 64 | NDB0098 | Pubset not imported locally | |
| 64 | NDB0100 | Pubset already being served | |
| 64 | NDB0101 | More than one SM pubset specified for (RD)WR caching | |
| 64 | NDB0102 | Volume is not a private disk | |
| 64 | NDB0103 | File catalog cannot be served due to error | |
| 64 | NDB0106 | Neither pubset nor private disk specified for AREA=*BY- SYSTEM | |
| 64 | NDB0107 | Pubset specified more than once | |
| 64 | NDB0110 | SM pubset does not contain a cacheable volume set | |
| 64 | NDB0162 | Processing of a pubset was aborted when a particular volume was accessed | |
| 64 | NDB0163 | Processing of a pubset was aborted when a volume was accessed | |
| 64 | NDB0164 | Processing of a volume was aborted when this volume was accessed | |
| 64 | NDB0165 | Processing of a pubset was aborted when a particular volume was accessed. It is not known how processing was concluded | |
| 64 | NDB0166 | Processing of a pubset was aborted when a volume was accessed. It is not known how processing was concluded | |
| 64 | NDB0167 | Processing of a volume was aborted when this volume was accessed. It is not known how processing was concluded | |
| 64 | NDB0177 | The configuration of a cache area cannot be modified during main memory reconfiguration | |
| 65 | CMD2241 | Subsystem not available | |
| 128 | CMD2280 | Saturation problem |
Examples
Serving several pubsets in the MM cache medium with automatic file and caching mode selection.
/START-DAB-CACHING AREA=*BY-SYSTEM(PUBSET=(CAM4,RATS), - / CACHE-SIZE=100(*MEGABYTE), - / CACHE-MEDIUM=*MAIN-MEMORY(MEMORY=*ABOVE-MIN-MEM-SIZE), - / CACHING-MODE=*BY-CACHE-MEDIUM % NDB0021 /START-DAB-CACHING COMMAND ACCEPTED. THE DAB CACHE BUFFER 'BUFFER#001' WAS INSTALLED WITH 66 MB (INSTEAD OF THE TARGET SIZE OF 100 MB) FOR THE FOLLOWING FILES/PUBSETS: % F I L E / P U B S E T % -------------------------------------------------------------------- % :CAM4: (SYSTEM-CONTROLLED) % :RATS: (SYSTEM-CONTROLLED)
Serving the TSOSCAT file catalog of the RATS pubset with MM cache medium in read mode.
with a fixed cache size of 1 Mbyte
/START-DAB-CACHING AREA=*FILE(FILE-AREA=:RATS:TSOSCAT), - / CACHE-SIZE=1(DIMENSION=*MEGABYTE), - / CACHE-MEDIUM=*MAIN-MEMORY,CACHING-MODE=*READ % NDB0020 /START-DAB-CACHING COMMAND ACCEPTED. THE DAB CACHE BUFFER 'BUFFER#001' WAS INSTALLED WITH 1 MB FOR THE FOLLOWING FILES/PUBSETS: % F I L E / P U B S E T % ----------------------------------------------------------------- % :RATS:$TSOS.TSOSCAT
with a variable cache size in “resident buffering” mode. The served data area is buffered completely in the cache.
/START-DAB-CACHING AREA=*FILE(FILE-AREA=:RATS:TSOSCAT), - / CACHE-SIZE=*BY-FILE,CACHE-MEDIUM=*MAIN-MEMORY, - / CACHING-MODE=*READ % NDB0020 /START-DAB-CACHING COMMAND ACCEPTED. THE DAB CACHE BUFFER 'BUFFER#001' WAS INSTALLED WITH 16416 KB FOR THE FOLLOWING FILES/PUBSETS: % F I L E / P U B S E T % ----------------------------------------------------------------- % :RATS:$TSOS.TSOSCAT
Sample application for CACHE-MEDIUM=*MAIN-MEMORY(MEMORY=*ABOVE-MIN-MEM-SIZE)
Preparing a standby system under VM2000 which, if necessary, is to take over the load of a productive system (before the productive system is started):
Set the system’s minimum main memory size and current main memory size to the same minimum size to ensure that the requirement of the standby system and the requirement for resident memory are covered when the productive load is taken over.
Import the pubsets which are to be buffered after the load has been taken over.
Configure the cache areas with
/START-DAB-CACHING ...,CACHE-MEDIUM= *MAIN-MEMORY(MEMORY=*ABOVE-MIN-MEM-SIZE). The cache areas will be assigned the current size 0.In
/START-DAB-CACHINGalso specify the pubsets (AutoDAB) or files (FILE-AREA cache) which are to be buffered.Export the pubsets which are to be buffered after the load has been taken over.
When the load has been taken over, increase the size of the main memory. The cache areas will be extended accordingly.
As an alternative to b), d) and e) you can add the pubsets and files with /MODIFY-DAB-CACHING after the load has been taken over. Preparation of the standby system is then independent of the productive system run.
Notes
Dynamic modification of a DAB cache area is only possible with the
/MODIFY-DAB-CACHINGcommand. Repeated/START-DAB-CACHINGcommands with the same CACHE-ID value are permissible only if a/STOP-DAB-CACHINGcommand with the same CACHE-ID was executed in between.A
/START-DAB-CACHINGcommand is not accepted for further processing unless all disks on which data areas to be served are allocated and do not belong to a pubset that is buffered with DAB using PFA.Notes on the CACHE-MEDIUM = *MAIN-MEMORY(MEMORY=...) operand:
Cache areas with MEMORY=*ANY/*BELOW-MIN-MEM-SIZE/*ABOVE-MIN-MEM-SIZE only make sense in systems in which main memory reconfiguration is possible, e.g. under VM2000.
Creating cache areas above the minimum main memory size
(MEMORY=*ANY/*ABOVE-MIN-MEM-SIZE) enables the minimum main memory size of the (VM2000) system to be kept low. This permits the main memory of a (standby) guest system under VM2000 to be reduced during ongoing operation when the load is low and increased when the load increases.In the case of cache areas with MEMORY=*ANY/*BELOW-MIN-MEM-SIZE/*ABOVE-MIN-MEM-SIZE it can occur that the cache area is not created using the size specified in the CACHE-SIZE operand, but is operated with a smaller size, the current one. The current size is always less than or equal to the specified size.
The reason is that at the time the cache area was created not enough space was available in the main memory or that the DAB cache was decreased in size owing to a memory reduction (in the case of MEMORY=*ABOVE-MIN-MEM-SIZE/*ANY) or memory saturation (MEMORY=*ANY/*BELOW-MIN-MEM-SIZE/*ABOVE-MIN-MEM-SIZE). DAB specifies the current size of the cache area. After every implicit change, the current size is logged on the console with the message NDB0052 for cache areas whose size has been reduced. As in the case of a memory reduction a cache area with MEMORY= *ANY/*ABOVE-MIN-MEM-SIZE must in all cases first be completely detached and reattached after the memory reduction, it is possible that the old cache size will be attained once more. This is logged on the console with the message NDB0176.
The current (reduced) size of the cache area can be changed using the
/MODIFY-DAB-CACHINGcommand, see "MODIFY-DAB-CACHING Modify parameters of DAB cache area dynamically".When DAB caches with MEMORY=*ANY are used, performance can occasionally be impaired if the location of this cache memory needs to be changed in the main memory. This can occur in the following cases:
The cache memory could not be created immediately in the preferred area in the main memory because pages could not be displaced to the auxiliary memory quickly enough or the main memory was occupied by other cache areas with MEMORY=*ANY/*ABOVE-MIN-MEM-SIZE.
The cache memory must be displaced owing to resident memory requirements.
In the case of cache areas in the main memory with MEMORY=*ANY/*ABOVE-MIN-MEM-SIZE, before main memory reduction takes place or before the minimum main memory size is increased, the entire cache area is first reduced to 0.
After the main memory has been reduced or the minimum main memory size has been increased, the size of these cache areas is recalculated and reduced by the relevant percentage.
Example: A main memory reduction of 20% also leads to the size of the cache areas being reduced by 20%. The same effect occurs when the main memory area above the minimum main memory size is reduced by increasing the minimum main memory size by 20%.When the main memory is expanded (again), the size of the cache areas is also increased proportionately up to the size specified in
/START-or/MODIFY-DAB-CACHING.When the memory size is insufficient, cache areas in the main memory with MEMORY=*BELOW-MIN-MEM-SIZE are created with a size which is less than that specified. When the minimum main memory size is increased, such cache areas are increased proportionately up to the size specified in
/START-or/MODIFY-DAB-CACHING.In the case of main memory saturation, DAB reduces the size of the caches areas with MEMORY=*ANY/*BELOW-MIN-MEM-SIZE/ *ABOVE-MIN-MEM-SIZE proportionately. The size is increased correspondingly when memory saturation is reduced.
The new current size of the cache areas is logged on the console with the message NDB0052.
When cache areas with MEMORY=*STD or cache areas from earlier DAB versions are to be converted to cache areas with MEMORY=*ANY/*BELOW-MIN-MEM-SIZE/*ABOVE-MIN-MEM-SIZE, the system should be assigned a minimum main memory size which is adapted to the sizes of the cache areas.FORCE-OUT operand
Whether FORCE-OUT=*AT-HIGH-FILLING or FORCE-OUT=*AT-LOW-FILLING is advisable depends on various factors. With *AT-HIGH-FILLING, the load on the I/O system is lower than with *AT-LOW-FILLING. On the other hand, the fact that 75% of the cache is filled with data may result in a cache overflow if a large amount of write data has to be handled at a time.
FORCE-OUT=*AT-LOW-FILLING, on the other hand, may result in superfluous save operations which increase the I/O system load.
With write caching, a check should be performed to determine whether cache behavior is satisfactory with FORCE-OUT=*AT-HIGH-FILLING. In the event of cache overflows, FORCE-OUT=*AT-LOW-FILLING should be used instead.
FORCE-OUT=*AT-LOW-FILLING should always be used with read/write caching. FORCE-OUT=*NO is recommended for resident buffering.With automatic caching, any incorrect setting of the FORCE-OUT operand is corrected (see also section "Automatic caching (AutoDAB)").
When an SM pubset is to be buffered in a write or read/write cache, the SM pubset must already have been specified with
/START-DAB-CACHING. It cannot be added retroactively with/MODIFY-DAB-CACHING. No further SF or SM pubset is permitted in this cache area.Caching shared pubsets
Automatic caching
The SHARED-DISK-SUPPORT operand is irrelevant for automatically selected cache areas (AREA=*BY-SYSTEM). DAB takes over control for caching data on shared volumes in this case and ensures data consistency by means of the following measures:
Data areas on these volumes are only served with read caching. Caching is only enabled if the caching mode of the cache area concerned explicitly specifies read caching.
Read caching a file on such a volume is not accepted if the file is processed in a mode which allows it to be updated in parallel by another system.
Non-automatic caching
Using local system caches to serve data areas extending beyond a given system (e.g. files on shared pubsets) is generally problematic. Using non-automatic DAB for such data areas is not advisable unless access to the areas served by DAB is reliably restricted to read-only access for all sharers. The following should therefore be noted when specifying the SHARED-DISK-SUPPORT operand:
Data areas located on a disk operated in shared disk allocation mode are not served if the associated cache area is used as read/write or write cache.
The SHARED-DISK-SUPPORT operand is evaluated during the
/START-DAB-CACHINGcommand processing. DAB detects and processes any subsequently modified allocation mode.
The decision as to whether file-specific data areas (AREA=*FILE) on shared volumes are served depends on the parameter specifications defined by the user for a cache area. This results in the following differences when caching such volumes:
If a shared volume is served from different cache areas it is possible that its subareas are served by one cache area and not served by the others.
Since the allocation state of a volume can change frequently during serving by a cache area it is possible that a data area is alternately buffered or not buffered.