Domain: | SYSTEM-TUNING |
Privileges: | TSOS |
Function
The /MODIFY-DAB-CACHING command allows systems support to modify all of the main parameters of a DAB cache area dynamically.
The modified parameters include the cache size and the cache segment size, along with the data of file-specific cache areas (created with the command /START-DAB-CACHING AREA=*FILE/*BY-SYSTEM), the caching mode and the FORCE-OUT parameter.
Format
MODIFY-DAB-CACHING | Alias: MDDABC | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
CACHE-ID = <alphanum-name 1..32>
Identifier of the cache area to be modified.
CACHE-SIZE = *UNCHANGED / *EXTEND(...) / *REDUCE(...)
Defines the size of the cache area.
CACHE-SIZE = *UNCHANGED
The size of the cache area is not to be changed.
CACHE-SIZE = *EXTEND(...)
The cache area should be extended.
NEW-SIZE = <integer 1..8388608>(...)
Specifies the new size of the cache area.
The process of extending the cache area to the specified size is additive, all cache data already imported is retained.
In the case of cache areas in the main memory with MEMORY=*ANY/ *BELOW-MIN-MEM-SIZE/*ABOVE-MIN-MEM-SIZE (see /START-DAB-CACHING on "START-DAB-CACHING Create ADM-PFA DAB cache areas"), the size of the cache area set (desired) is increased. The current size is increased when the command is executed if the memory utilization permits this.
DIMENSION = *KILOBYTE / *MEGABYTE
Defines whether the cache area size is to be specified in KB or in MB.
CACHE-SIZE = *REDUCE(...)
The cache area is to be reduced.
NEW-SIZE = <integer 0..8388608>(...)
Specifies the new size of the cache area.
The following applies for cache areas with CACHING-MODE=*WRITE/*READ-WRITE:
Only cache data that is needed is saved to disk, thus helping reduce the cache area to the required size. As for all types of caching mode, the cache segments of the cache area are then disconnected. Caching in all of the other cache segments is not affected by this action.
In the case of cache areas in the main memory with MEMORY=*ANY/ *BELOW-MIN-MEM-SIZE/*ABOVE-MIN-MEM-SIZE (see /START-DAB-CACHING on "START-DAB-CACHING Create ADM-PFA DAB cache areas"), the size of the cache area set (desired) is decreased. The current size is decreased only if the newly set size is below the current size.
DIMENSION = *KILOBYTE / *MEGABYTE
Defines whether the cache area size is to be specified in KB or in MB.
CACHE-SEGMENT-SIZE = *UNCHANGED / *32 / *16 / *8 / *4
Specifies which cache segment size should be set.
Changing the previous cache segment size has no effect on cache areas with automatic caching (AutoDAB).
CACHE-SEGMENT-SIZE = *UNCHANGED
The cache segment size is not to be changed.
CACHE-SEGMENT-SIZE = *32 / *16 / *8 / *4
The cache segment size is to be changed to 32KB / 16KB / 8KB / 4KB.
AREA = *UNCHANGED / *ADD-FILE(...) / *REMOVE-FILE(...) / *RESET-FILE(...) /*ADD-PUBSET(...) / *REMOVE-PUBSET(...)
The data area of an file-specific cache area is to be changed.
In the case of a file-specific cache area (created with AREA=*FILE), individual files can be added to or removed from the cache.
In the case of an automatic cache area (created with AREA=*BY-SYSTEM), one or more files can be permanently added to or removed from the cache. It can also be specified that these files should be cached automatically again, i.e. depending on what AutoDAB decides.
In the case of an automatic cache area (configured with AREA=*BY-SYSTEM), a pubset can be permanently added to the cache or removed from it.
AREA = *UNCHANGED
The data area of the cache area is not to be changed.
AREA = *ADD-FILE(...)
The data area of the cache area is to be extended by one or more files. With AutoDAB, this file is cached without first being assessed by DAB.
FILE-NAME = <filename 1..54 without-vers>
Name of the file to be added to the specified cache area.
FILE-NAME = <partial-filename 2..53>
Only for automatic cache areas (created with AREA=*BY-SYSTEM):
Partially qualified file name for a file set which is to be added to the specified cache area.
AREA = *REMOVE-FILE(...)
The data area of the cache area is to be reduced by one or more files. The cache data is written to the disk(s) and invalidated in the cache.
FILE-NAME = <filename 1..54 without-vers>
Name of the file to be removed from the specified cache area.
FILE-NAME = <partial-filename 2..53>
Only for automatic cache areas (created with AREA=*BY-SYSTEM):
Partially qualified file name for a file set which is to be removed from the specified cache area.
AREA = *RESET-FILE(...)
Only for automatic cache areas (created with AREA=*BY-SYSTEM):
The data area of the automatic cache area is to be modified in such a manner for one or more files that these files are once more automatically cached, i.e. depending on what AutoDAB decides.
FILE-NAME = <filename 1..54 without-vers> / <partial-filename 2..53>
Name of the file or partially qualified file name for a file set which is once more to be cached automatically in the specified cache area.
AREA = *ADD-PUBSET(...)
Only for automatic cache areas (created with AREA=*BY-SYSTEM):
The database of the cache area is to be extended by one pubset.
PUBSET = <cat-id 1..4>
Name of the pubset which is to be added to the specified cache area.
AREA = *REMOVE-PUBSET(...)
Only for automatic cache areas (created with AREA=*BY-SYSTEM):
The database of the cache area is to be reduced by one pubset.
PUBSET = <cat-id 1..4>
Name of the pubset which is to be removed from the specified cache area.
CACHING-MODE = *UNCHANGED / *READ / *READ-WRITE / *WRITE / *BY-CACHE-MEDIUM
The caching mode of the cache area is to be changed.
There are two different “directions” to be considered when changing the caching mode:
When changing from *READ to *READ-WRITE/*WRITE/*BY-CACHE-MEDIUM, the imported read data is retained; in the future write data will also (or only in the case of *WRITE) be imported in the cache.
In the other direction (to *READ), data is written to the disk(s) without disk copy, only read data is then imported in the cache.
CACHING-MODE = *UNCHANGED
The caching mode is not changed.
CACHING-MODE = *READ
The cache area is to be changed to a read cache. Write data imported in the cache must be written to the disk(s).
CACHING-MODE = *READ-WRITE
The cache area is to be changed to a read/write cache.
CACHING-MODE = *WRITE
The cache area is to be changed to a write cache.
CACHING-MODE = *BY-CACHE-MEDIUM
The caching mode set is to depend on the file attributes (see the /START-DAB-CACHING command).
FORCE-OUT = *UNCHANGED / *AT-LOW-FILLING / *AT-HIGH-FILLING / *NO
The threshold for the asynchronous saving of cache data is to be changed. This determines if and when write data is to be written from the cache to the disk(s) (see the /START-DAB- CACHING command).
FORCE-OUT = *UNCHANGED
The threshold for the asynchronous saving of cache data is not to be changed.
FORCE-OUT = *AT-LOW-FILLING
The number of cache segments not saved to disk is to be kept to a minimum through threshold-controlled save runs. Saving is to be triggered as soon as 25% of the cache is filled with unsaved write data.
FORCE-OUT = *AT-HIGH-FILLING
For the cache segments of this cache area, only as many data savings as are required are to be carried out in order to have enough segments available for new cache imports. Saving is to be triggered as soon as 75% of the cache is filled with unsaved write data.
FORCE-OUT = *NO
The data of this cache area is not to be transferred to the disk in threshold-controlled save runs. The data is only transferred to the disk when the cache area is disconnected using the /STOP-DAB-CACHING command.
Return codes
| (SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
| 0 | CMD0001 | No error | |
| 32 | CMD0221 | Internal SDF error | |
| 64 | CMD0216 | Required privilege missing | |
| 64 | NDB0002 | Pubset with key disks cannot be added to the cache area without keys | |
| 64 | NDB0005 | No authorization to invoke command | |
| 64 | NDB0006 | Pubset cannot be added to file area cache | |
| 64 | NDB0010 | Wrong syntax file version | |
| 64 | NDB0012 | DMS error | |
| 64 | NDB0026 | File is not cataloged | |
| 64 | NDB0027 | File cannot be served because it is either a tape file, has been migrated by HSMS, is a file group, a work file for SO migration or a work file for SPACEOPT | |
| 64 | NDB0028 | File already served | |
| 64 | NDB0029 | Cache area could not be fully saved to disk | |
| 64 | NDB0034 | File on key disk cannot be added to the cache area without keys | |
| 64 | NDB0071 | No write caching is possible for the specified file because of file encryption | |
| 64 | NDB0072 | User ID of the specified file is unknown | |
| 64 | NDB0080 | Caching of home pubset data is not permissible in a write or read/write cache | |
| 64 | NDB0096 | The modification could not be performed either because of a memory bottleneck, a malfunction in cache destaging or an error in a function in BS2000 | |
| 64 | NDB0097 | The cache area is unknown, exists more than once or has been reconfigured | |
| 64 | NDB0098 | Pubset not imported locally | |
| 64 | NDB0100 | Pubset already being served | |
| 64 | NDB0101 | More than one SM pubset specified for read/write caching | |
| 64 | NDB0103 | File catalog cannot be served (error) | |
| 64 | NDB0110 | SM pubset does not contain a cacheable volume set | |
| 64 | NDB0111 | An ADD-FILE or REMOVE-FILE is not permissible for the cache area | |
| 64 | NDB0112 | The file is not located on an occupied disk volume | |
| 64 | NDB0113 | The cache size of cache areas with a dynamic cache size cannot be modified explicitly | |
| 64 | NDB0114 | Parameter error during extension: new size is smaller than or equal to the old size | |
| 64 | NDB0115 | Parameter error during reduction: new size is larger than or equal to the old size | |
| 64 | NDB0116 | Modification of the cache segment size is not possible with automatic caching | |
| 64 | NDB0117 | The size of a user PFA cache area for a shared pubset cannot be modified | |
| 64 | NDB0118 | Modification of the cache area to caching mode *WRITE/*READ-WRITE is not possible because files are being served on the home pubset | |
| 64 | NDB0119 | The command cannot be executed at present because another MODIFY-DAB-CACHING command is already being executed | |
| 64 | NDB0120 | Parameter error in the MODIFY-DAB-CACHING command: the file(s) is(are) not served from the specified cache area | |
| 64 | NDB0121 | A switchover of the caching mode is not permitted for a user PFA cache area | |
| 64 | NDB0124 | The new cache segment size is the same as the old cache segment size | |
| 64 | NDB0127 | The file cannot be served in the specified cache area | |
| 64 | NDB0129 | Modification of the cache segment size of a cache area without cache memory is not possible | |
| 64 | NDB0155 | Partial file names are not supported as no cache area with automatic caching exists | |
| 64 | NDB0156 | The RESET-FILE parameter is not supported for the specified cache area | |
| 64 | NDB0158 | The cache area has been reduced because of the lack of main memory | |
| 64 | NDB0159 | File cannot be added to the cache area owing to lack of main memory | |
| 64 | NDB0161 | Pubset cannot be removed from the cache area owing to pubset import | |
| 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 | 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 | NDB0168 | Parameter error: pubset to be removed is not served by DAB in the cache area | |
| 64 | NDB0169 | The maximum number of pubsets is already being served in the cache area | |
| 64 | NDB0170 | Parameter error: pubset to be added is not served by DAB in the cache area | |
| 64 | NDB0177 | The configuration of a cache area cannot be modified during main memory reconfiguration | |
| 64 | NDB0197 | Pubset cannot be added to the cache area owing to lack of main memory | |
| 65 | CMD2241 | DAB subsystem not loaded |
Notes
Handling files which correspond to the specification of different partially qualified file names
Specifying partially qualified file names in the AREA=*ADD-FILE(...)/REMOVE-FILE(...)/RESET-FILE(...) operand enables subsets of files to be created which differ from a specific superset of files.
If, for example, the files which begin with the partial name :<catid>:$TSOS.SYS. are not to be added to the automatic cache area, this is done using:/MODIFY-DAB-CACHING CACHE-ID=<cache-id>,AREA=*REMOVE-FILE(SYS.)On the other hand, files which begin with :<catid>:$TSOS.SYS.SDF. should always be cached. The following command ensures that these files are always cached:
/MODIFY-DAB-CACHING CACHE-ID=<cache-id>,AREA=*ADD-FILE(SYS.SDF.)In this case files which begin with :<catid>:$TSOS.SYS.<xyz>. where xyz <> SDF, are not cached. However, the commands must be issued in the specified order. If they were issued in reverse order, none of the files with :<catid>:$TSOS.SYS.SDF. would be cached.
Specifying a shorter prefix cancels all preceding specifications for longer, partially qualified or complete file names which begin with a prefix.
Renaming files
When a file which was added to the data area of the cache area with ADD-FILE or removed from it with REMOVE-FILE is renamed, it retains this attribute even after it has been renamed.
When a file which was added to the data area of the cache area with ADD-FILE or removed from it with REMOVE-FILE by specifying a partially qualified file name is renamed, it retains this attribute even after it has been renamed.
When a file which was added to the data area of the cache area with ADD-FILE or removed from it with REMOVE-FILE by specifying a partially qualified file name is renamed (in these cases the file loses this attribute), or if neither ADD-FILE nor REMOVE-FILE has been applied to it, it takes over the attribute regarding affiliation to the data area which applies for the new file name. If the file is given a new name which matches the previous specification for a partially qualified file name, it is added to the data area provided this partially qualified file name was specified in ADD-FILE. The same applies for removing files if the partially qualified file name was specified in REMOVE-FILE. Otherwise DAB decides on whether the file should be cached.
Modifying the cache segment size
When the cache segment size is modified in a file area cache, it can occur that the old cache size cannot be set again and the cache is continued with a reported smaller cache size.
Contending cache areas
The current size of a cache area in the main memory (MEMORY =*BELOW-MIN-MEM-SIZE/*ABOVE-MIN-MEM-SIZE/*ANY) can be too large because it was configured first. Another cache area which was configured later using this MEMORY setting is consequently too small. This is a case in which the current sizes of the cache areas should be modified.
To do this, the size set for the larger cache area must be decreased. After this has been done and a wait time of approx. two minutes, the current size of the smaller cache area should have increased (see the
/SHOW-DAB-CACHINGcommand). If the increase is not sufficient, the size of the larger cache area must be reduced again. If the increase is sufficient, the size of the larger cache area can be reset to its original value.