Adabas Caching Operations

#### Search Results

Search

# Adabas Caching Operations

This document describes the operator commands available for Adabas Caching.

- Operator Command Overview

- Operator Command Summary Table

- Operator Command Syntax

- Identifying a RABN Range or File Range

- Command Descriptions

- CSTAT/CFSTAT Statistics Report

## Operator Command Overview

The Adabas Caching operator commands are used to perform the following actions:

- Add a new RABN range (`CASSOxxx` and `CDATAxxx`)

- Add a new file or file range (`CFILE`)

- Enable a RABN range (`CENABLE`) or file / file range (`CFENABLE`)

- Disable a RABN range (`CDISABLE`) or file / file range (`CFDISABLE`)

- Delete a RABN range (`CDELETE`) or file / file range (`CFDELETE`)

- Display caching statistics for a RABN range (`CSTAT`) or file / file range (`CFSTAT`)

- Display summary statistics for RABN ranges or files / file ranges (`CSUM`)

- Modify the exclusion list for read-ahead caching (`CEXCLUDE`, `CINCLUDE`)

- Modify the number of buffers available for read-ahead caching (`CBUFNO`)

- Modify or display runtime options:

  - the current runtime options including the ADACSH start-up parameters (`CPARM` )

  - the size used for the allocation of future Associator cache space areas ( `CASSOMAXS`)

  - the size used for the allocation of future Data Storage cache space areas (`CDATAMAXS`)

  - the maximum time of inactivity permitted before releasing a cache space area or disabling a RABN range or file (`CCTIMEOUT`)

  - the number of seconds between retries for allocating a cache space area if a previous attempt to allocate the area failed. (`CRETRY`)

  - the minimum acceptable Adabas buffer efficiency level (`CDEMAND`)

  - whether all ADACSH messages are to be displayed on the system console (`CDISPSTAT`)

## Operator Command Summary Table

The following table shows for which type of caching a command can be used. The columns headings G,F,S and D indicate for which type of caching the command can be used.

- G: global caching only

- F: file-level caching only

- S: both global and file-level caching with the same meaning

- D: both global and file-level caching, but with different meanings and syntax.

Command | Action | G | F | S | D
--- | --- | --- | --- | --- | ---
`CASSOxxx` | Defines new Associator RABN ranges and type of cache | Y |  |  |
`CASSOMAXS` | (runtime option): Size used for allocation of future Associator cache space areas |  |  | Y |
`CBUFNO` | Modifies the number of buffers available for read-ahead caching |  |  | Y |
`CCTIMEOUT` | (runtime option): Maximum time of inactivity permitted before releasing a cache space area or disabling a RABN range or file |  |  | Y |
`CCHANGE` | Changes specified cache space or all cache spaces from current type to another type | Y |  |  |
`CDATAxxx` | Defines new Data Storage RABN ranges and type of cache | Y |  |  |
`CDATAMAXS` | (runtime option): Size used for allocation of future Data Storage cache space areas |  |  | Y |
`CDELETE` | Deletes specified or all RABN ranges (global); or deletes the cache spaces of Work parts 2 or 3 (file-level) |  |  |  | Y
`CDEMAND` | (runtime option): Minimum acceptable Adabas buffer efficiency level |  |  | Y |
`CDISABLE` | Disables the specified or all RABN ranges (global); or suspends caching of Work parts 2 or 3 (file-level) |  |  |  | Y
`CDISPSTAT` | (runtime option): Indicates whether or not all messages are to be displayed on the system console |  |  | Y |
`CENABLE` | Enables the specified or all RABN ranges (global); or restarts caching of Work parts 2 or 3 (file-level) |  |  |  | Y
`CEXCLUDE` | Excludes command types from read-ahead caching |  |  | Y |
`CFDELETE` | Deletes cache spaces for one or more files |  | Y |  |
`CFDISABLE` | Suspends caching for one or more files |  | Y |  |
`CFENABLE` | Restarts caching for one or more files |  | Y |  |
`CFILE` | Defines one or more files for caching |  | Y |  |
`CFSTAT` | Displays cache space statistics for one or more files |  | Y |  |
`CINCLUDE` | Includes command types for read-ahead caching |  |  | Y |
`CPARM` | (runtime option): Displays current runtime options including start-up parameters |  |  | Y |
`CRETRY` | (runtime option): Number of seconds between retries for allocating a cache space area if a previous attempt failed |  |  | Y |
`CSTAT` | Displays statistics for the specified or all RABN ranges (global); or displays statistics about caching Work parts 2 or 3 (file-level) |  |  |  | Y
`CSUM` | Displays accumulated summary for all active and inactive RABN ranges or files |  |  | Y |

## Operator Command Syntax

The syntax for the operator command interface is identical to that for Adabas operator commands.

There is no short form for any of the operator commands. The command option must be specified as documented.

    F jobname,option

where:

jobname | is the Adabas jobname
option | is the ADACSH operation to be performed

## Identifying a RABN Range or File Range

For many commands, it is necessary to identify the RABN range or file range to which the command applies. When global caching is active, each RABN range defined is allocated a unique ID number up to and including 65,535. This number may be used to identify the RABN ranges uniquely.

When file-level caching is active, each file number is unique and is used to identify the subject of an operator request. One or more RABN ranges may be associated with a file; each is given a unique RABN Range ID within the context of that file; however, these cannot be addressed individually and operator commands may only be issued to the file or file range as a whole.

When file-level caching is active, caching for Work parts 2 and 3 may also be active. For each Work RABN range, a number greater than 64000 is allocated for the Range ID to differentiate it from a file number. This imposes a theoretical restriction of 64000 file numbers for which caching may be active.

When file-level caching is active and ALL is specified, the command is issued against all files currently known to ADACSH and is subsequently issued against any Work RABN ranges that may be defined.

## Command Descriptions

The available ADACSH operator commands are described in this section.

- CASSODSP / CASSOEXT / CASSOG64 / CASSOHSP / CASSOL64 / CASSOP64 / CASSOV64

- CASSOMAXS

- CBUFNO

- CCTIMEOUT

- CCHANGE

- CDATADSP / CDATAEXT / CDATAG64 / CDATAHSP / CDATAL64 / CDATAP64 / CDATAV64

- CDATAMAXS

- CDELETE

- CDEMAND

- CDISABLE

- CDISPSTAT

- CENABLE

- CEXCLUDE

- CFDELETE

- CFDISABLE

- CFENABLE

- CFILE

- CFSTAT

- CINCLUDE

- CPARM

- CRETRY

- CSTAT

- CSUM

### CASSODSP / CASSOEXT / CASSOG64 / CASSOHSP / CASSOL64 / CASSOP64 / CASSOV64

The `CASSOxxx` command is used to define new Associator RABN ranges, and also the type of cache space to be used.

This command is not available for file-level caching. It is rejected as invalid if file-level caching is active.

The last three characters of the command name determine the type of cache space to be used:

- CASSODSP: Data Space

- CASSOEXT: Extended Memory

- CASSOG64: Virtual 64-bit storage backed by 2G large pages

- CASSOHSP: Hiperspace

- CASSOL64: Virtual 64-bit storage backed by fixed 1M large pages

- CASSOP64: Virtual 64-bit storage backed by pageable 1M large pages

- CASSOV64: Virtual 64-bit storage backed by pageable 4K large pages

For more information, see section Caching Configuration.

Value | Description
--- | ---
rabn | A single RABN or RABN range may be specified. A range is specified as two numbers separated by a hyphen with no intervening spaces or special characters.
csn | Specifies a unique number (RABN Range ID) that will be assigned to the new RABN range. Valid values are 0 through 65535. Note This was previously referred to as the cache space number (CSN). For compatibility, the CSN terminology has been retained; however, the CSN now identifies the RABN Range ID to be used as there is no longer a direct correlation between cache spaces and RABN ranges. If the number specified is already in use, the new RABN range definition is ignored and an error message is displayed on both DDPRINT and the operator console. If not specified, the next available number is assigned to the RABN range automatically. This option enables the use of batch programs that issue operator commands to identify new RABN ranges for batch jobs. A subsequent batch job may issue the `CDELETE` operator command to delete the RABN ranges that were added for the batch jobs.
DISABLED / ENABLED | This option can be used to control the activation of the newly defined RABN range: DISABLED: the RABN range is to be added but is unavailable for use ENABLED: the RABN range is to be added and is available for use immediately If the RABN range is defined as DISABLED, only a subsequent `CENABLE` operator command permits activation; or, if the option `CDEMAND` is in effect, the RABN range is activated when the `CDEMAND` threshold level is reached.

### CASSOMAXS

`CASSOMAXS` is one of the commands used to modify or display the ADACSH runtime options. It specifies the size of each Associator cache space area to be allocated.

Value | Description
--- | ---
n | The unit size in which areas are allocated for Associator cache space. Size may be specified in bytes, in kilobytes (K), in megabytes (M) or in gigabytes (G). Changing this value affects the size for Associator cache space areas defined after the new `CASSOMAXS` value is in effect. All previously allocated Associator cache spaces are unaffected. For extended memory, data spaces, and hiperspaces: the minimum unit size is 81920 bytes (or 80K); the maximum unit size is 2147475456 bytes (or 2097144K; or 2047M); and In these cases, `CASSOMAXS` is always rounded up to the nearest 4-kilobyte boundary. For Virtual 64 memory and Virtual 64 storage backed by large pages, virtual storage above the 2GB bar is allocated in terms of memory objects, each of which comprises one or more virtual segments or pages of one megabyte each. In essence, `CASSOMAXS` determines the number of 1-megabyte segments to be allocated for the memory object: the minimum unit size and the default unit size is 1M (1048576 bytes or 1024K). the maximum unit size depends on the limit set for your installation. For memory objects, `CASSOMAXS` is rounded up to the nearest megabyte boundary. The default unit size for all memory types is 1048576 bytes (or 1024K; or 1M).

### CBUFNO

`CBUFNO` specifies the number of read-ahead buffers available for concurrent I/O processing.

Value | Description
--- | ---
n | The number of read-ahead buffers available for concurrent I/O processing. The recommended setting is a value that accommodates the expected number of concurrent `L2`, `L3`, and `L9` commands. The minimum number of read-ahead buffers is 0 (the default). If `CBUFNO=0` is specified, no read-ahead caching is performed. The maximum number is the same as the number of threads specified for the nucleus parameter `NT`, because there cannot be more than `NT` number of commands active at any time.

For more information, see also the ADARUN parameter `CBNUFNO`.

### CCTIMEOUT

`CCTIMEOUT` is one of the commands used to modify or display the ADACSH runtime options. It specifies the number of seconds of non-activity permitted before releasing a cache space area or disabling a RABN range, file, or file range.

The minimum value permitted is 60 seconds.

For more information, see the ADARUN parameter `CCTIMEOUT`.

### CCHANGE

`CCHANGE` is used to change the specified cache space (RABN Range ID) or all cache spaces from the current to the specified cache type so that an existing RABN range uses a different type of cache space.

Value | Description
--- | ---
csn | The RABN Range ID (csn) which is to use a type of cache space that is different from that which it is currently using. The cache storage that the RABN range is currently using will be freed and then linked with the requested cache space type. As the RABN range becomes active again, the affected RABNs are cached in the new type of cache space. If a RABN Range ID is not specified, then all RABN ranges are changed to the specified cache space type. A Work part 2 or 3 RABN range is not changed if the Work RABN range is active and active user queue elements (UQEs) are present in Adabas, because these active UQEs may be utilizing the Work cache. In this case, a warning message is displayed on the operator console.
DATASPACE EXTENDED G64 HIPERSPACE L64 P64 VIRTUAL64 | The type of cache space to be used. If the current type of cache space is the same as the new type, no change takes place and the cached RABNs associated with the RABN range remain cached.

### CDATADSP / CDATAEXT / CDATAG64 / CDATAHSP / CDATAL64 / CDATAP64 / CDATAV64

The `CDATAxxx` command is used to define new Data Storage RABN ranges, and also the type of cache space to be used.

This command is not available for file-level caching. It is rejected as invalid if file-level caching is active.

The last three characters of the command name determine the type of cache space to be used:

- CDATADSP: Data Space

- CDATAEXT: Extended Memory

- CDATAG64: Virtual 64-bit storage backed by 2G large pages

- CDATAHSP: Hiperspace

- CDATAL64: Virtual 64-bit storage backed by fixed 1M large pages

- CDATAP64: Virtual 64-bit storage backed by pageable 1M large pages

- CDATAV64: Virtual 64-bit storage backed by pageable 4K large pages

For more information, see section Caching Configuration.

Value | Description
--- | ---
rabn | A single RABN or RABN range may be specified. A range is specified as two numbers separated by a hyphen with no intervening spaces or special characters.
csn | Specifies a unique number (RABN Range ID) that will be assigned to the new RABN range. Valid values are 0 through 65535. Note This was previously referred to as the cache space number (CSN). For compatibility, the CSN terminology has been retained; however, the CSN now identifies the RABN Range ID to be used as there is no longer a direct correlation between cache spaces and RABN ranges. If the number specified is already in use, the new RABN range definition is ignored and an error message is displayed on both DDPRINT and the operator console. If not specified, the next available number is assigned to the RABN range automatically. This option enables the use of batch programs that issue operator commands to identify new RABN ranges for batch jobs. A subsequent batch job may issue the `CDELETE` operator command to delete the RABN ranges that were added for the batch jobs.
DISABLED / ENABLED | This option can be used to control the activation of the newly defined RABN range: DISABLED: the RABN range is to be added but is unavailable for use ENABLED: the RABN range is to be added and is available for use immediately If the RABN range is defined as DISABLED, only a subsequent `CENABLE` operator command permits activation; or, if the option `CDEMAND` is in effect, the RABN range is activated when the `CDEMAND` threshold level is reached.

### CDATAMAXS

`CDATAMAXS` is one of the commands used to modify or display the ADACSH runtime options. It specifies the size of each Data Storage cache space area to be allocated.

Value | Description
--- | ---
n | The value n is the size of each Data Storage cache space area allocated. Size may be specified in bytes, in kilobytes (K), in megabytes (M) or in gigabytes (G). Changing this value affects the size of Data Storage cache space areas defined after the new `CDATAMAXS` value is in effect. All previously allocated Data Storage cache space areas are unaffected. For extended memory, data spaces, and hiperspaces: the minimum unit size is 81920 bytes (or 80K); the maximum unit size is 2147475456 bytes (or 2097144K; or 2047M); and the default unit size is 1048576 bytes (or 1024K; or 1M). In these cases, `CDATAMAXS` is always rounded up to the nearest 4-kilobyte boundary. For Virtual 64 memory and Virtual 64 storage backed by large pages, virtual storage above the 2GB bar is allocated in terms of memory objects, each of which comprises one or more virtual segments or pages of one megabyte each. In essence, `CDATAMAXS` determines the number of 1-megabyte segments to be allocated for the memory object: the minimum unit size and the default unit size is 1M (1048576 bytes or 1024K). the maximum unit size depends on the limit set for your installation. For memory objects, `CDATAMAXS` is rounded up to the nearest megabyte boundary. The default unit size for all memory types is 1048576 bytes (or 1024K; or 1M).

For extended memory, data spaces, and hiperspace, the minimum unit size is 81920 bytes (or 80K) and the maximum unit size is 2147475456 bytes (or 2097144K; or 2047M). The value is always rounded up to the nearest 4-kilobyte boundary.

For Virtual 64 memory and Virtual 64 storage backed by large pages, the minimum unit size is 1048576 bytes (or 1024K; or 1M) and the maximum unit size is determined by your installation. Consult your system programmer for specific information. The value is always rounded up to the nearest megabyte boundary.

### CDELETE

For global caching, the `CDELETE` command can be used to delete RABN ranges. For file-level caching, `CDELETE` can be used to delete the cache spaces of the Work file part 2 or part 3.

#### For Global Caching

For global caching, the `CDELETE` command is used to delete one or more specified, existing RABN ranges, or all RABN ranges:

Value | Description
--- | ---
ALL | Delete all RABN ranges.
csn | Delete one or more specific RABN Range IDs.

The `CDELETE` command frees any cache space currently used by the RABN range. This space is then made available to other RABN ranges using the same cache space. Once this is done, the RABN range control storage is freed and all reference to the RABN range is removed from ADACSH. If caching is subsequently required for the RABN range that was deleted, the `CASSOxxx` or `CDATAxxx` operator commands must be used to re-establish the desired caching.

If a RABN range is active when the `CDELETE` command is entered, no further caching takes place and the normal Adabas read I/O operations occur.

A Work part 2 or 3 RABN range is not deleted if the Work cache is active and active user queue elements (UQEs) are present in Adabas because these active UQEs may be utilizing the Work cache. In this case, a warning message is displayed on the operator console.

Caution
Caution should be exercised when deleting Work part 2 and/or 3 because (at present) there is no way to define dynamically a new Work part 2 and/or 3 RABN range.

#### For File-Level Caching

For file-level caching, `CDELETE` is used to delete the cache spaces of the Work file part 2 (WORK2) or part 3 (WORK3).

Caution
Caution should be exercised when deleting Work part 2 and/or 3 because (at present) there is no way to define dynamically a new Work part 2 and/or 3 RABN range.

### CDEMAND

`CDEMAND` is one of the commands used to modify or display the ADACSH runtime options. It specifies the minimum acceptable Adabas buffer efficiency level.

Value | Description
--- | ---
0 | If `CDEMAND=0` (the default), no demand-level caching occurs.
n | Demand-level caching is to be activated whenever the Adabas buffer efficiency drops below the value specified. An integer value between 1 and 2,147,483,647 is permitted.

For more information, see the `CDEMAND` ADARUN parameter.

### CDISABLE

For global caching, `CDISABLE` can be used to suspend caching of one or more RABN ranges that are currently enabled or active. For file-level caching, `CDISABLE` can be used to suspend caching of the Work file parts 2 or 3.

#### For Global Caching

For global caching, `CDISABLE` can be used to suspend caching of one or more RABN ranges that are currently enabled or active.

Value | Description
--- | ---
ALL | Suspend caching of all RABN ranges.
csn | Suspend caching of one or more specified RABN ranges identified by their RABN Range IDs.

`CDISABLE` frees any cache space that the RABN range is currently using. This space is then made available to other RABN ranges using the same cache space.

If a RABN range is active when `CDISABLE` issued, no further caching takes place and the normal Adabas read I/O operations occur.

A Work part 2 or 3 RABN range is not disabled if the Work cache is active and active user queue elements (UQEs) are present in Adabas because these active UQEs may be utilizing the Work cache. In this case, a warning message is displayed on the operator console.

#### For File-Level Caching

For file-level caching, `CDISABLE` is used to suspend caching of the Work file parts 2 or 3.

### CDISPSTAT

`CDISPSTAT` is one of the commands used to modify or display the ADACSH runtime options. It specifies whether or not all ADACSH messages are to be displayed on the system console.

Value | Description
--- | ---
YES | RABN range statistics are to be displayed on both the operator console and DDPRINT.
NO | RABN range statistics are to be displayed only on DDPRINT.

### CENABLE

For global caching, `CENABLE` can be used to enable caching of a RABN range that was previously disabled or not allocated, either because the RABN range was defined as DISABLED or the `CDEMAND` level was not reached. For file-level caching, `CENABLE` can be used to restart caching of the Work file parts 2 or 3.

#### For Global Caching

The `CENABLE` command enables a RABN range that was previously disabled or not allocated, either because the RABN range was defined as DISABLED or the `CDEMAND` level was not reached.

Value | Description
--- | ---
ALL | Enable all RABN ranges.
csn | Enable one or more specified RABN ranges identified by their RABN Range IDs.

#### For File-Level Caching

For file-level caching, `CDISABLE` is used to enable caching of the Work file parts 2 or 3.

### CEXCLUDE

The exclusion list for read-ahead caching may be changed during the nucleus session using the `CEXCLUDE` and `CINCLUDE` commands. Command types may be excluded and included to meet the demands of various job streams and Adabas access loads.

The `CEXCLUDE` command can be used to modify the exclusion list for read-ahead caching to exclude certain command types.

Value | Description
--- | ---
PHYS | Exclude `L2` and `L5` (physical sequence) commands.
LOGI | Exclude `L3` and `L6` (logical sequence) commands.
HIST | Exclude `L9` (histogram) command.
FIND | Exclude `S1` (nondescriptor search) command.

The exclusion list must be specified with each four-character name separated by a slash ( / ). No intervening spaces or special characters, such as commas, are permitted.

The exclusion is made globally: for example, if `CEXCLUDE=PHYS` is specified, all `L2` and `L5` commands are excluded from read-ahead processing, regardless of the file to which the command was directed.

See also the related command `CINCLUDE`.

### CFDELETE

The `CFDELETE` command is used to delete the cache spaces for one or more files.

This command is valid for file-level caching only.

Value | Description
--- | ---
fnr | Delete cache spaces for one or more individual files.
fnr - fnr | Delete cache spaces for a single range of files.
ALL | Delete cache spaces for all files and Work datasets (the default).

If caching is subsequently required for the deleted file, files, or file range, the `CFILE` operator command can be used to re-establish the desired caching.

### CFDISABLE

The `CFDISABLE` command can be used to suspend caching for one or more files.

This command is valid for file-level caching only.

Value | Description
--- | ---
fnr | Suspend caching for one or more individual files.
fnr - fnr | Suspend caching for a single range of files.
ALL | Suspend caching for all files and Work datasets (the default).

If `CDEMAND` is set, caching will start again automatically when buffer efficiency falls below the specified threshold. Otherwise, caching can be restarted using the `CFENABLE` command.

### CFENABLE

The `CFENABLE` command can be used to restart caching for one or more files that were previously disabled or not allocated either because the file range was defined as DISABLED, or the `CDEMAND` level was not reached.

This command is valid for file-level caching only.

Value | Description
--- | ---
fnr | Restarts caching for one or more individual files.
fnr - fnr | Restart caching for a single range of files.
ALL | Restart caching for all files and Work datasets (the default).

### CFILE

The `CFILE` command can be used to enable caching for one or more files.

Value | Description
--- | ---
fnr | The file number of the file to be cached. The minimum value is 0; the maximum is the actual number of files in the database. File number 0 may be specified to cache RABNs that are not associated with any given file. Currently, this is only the DSST on the Associator dataset.
fnr - fnr | Range of files to be cached specified by two file numbers (the lower number first) separated by a hyphen with no intervening spaces or special characters.
cls | Class of service. The percentage of available cache space that can be used to cache RABNs associated with the specified file(s). This term effectively assigns a priority to the file(s). RABNs belonging to the file(s) with the lowest priority are purged first. Valid values are: 1: 100% (highest priority) 2: 75% 3: 50%; the default 4: 25% 5: 10% (lowest priority)
scope | Caching scope. Valid values are: ASSO (or A) : Caching is to be used only for Associator for the file DATA (or D) : Caching is to be used only for Data Storage for the file BOTH (or B) : Caching is to be used for both Associator and Data Storage for the file The default is BOTH.
cache | Specifies the type of storage in which RABNs for the file will be cached. Valid values are: DATASPACE (or D) EXTENDED (or E) G64 (or G) HIPERSPACE (or H) L64 (or L) VIRTUAL64 (or V) The default is DATASPACE. Note Specify "L64" to request that cache storage be virtual storage above the 2G bar backed by page-fixed 1M large pages; specify G64 to request that cache storage be virtual storage above the 2G bar backed by page-fixed 2G large pages.

Notes:

1. Although it is possible to define different cache spaces for the Associator and Data Storage of a single file using a separate ADARUN `CFILE` parameter for each, it is not possible to do so using AOS functions or operator commands. To define both Associator and Data Storage caching for a file using AOS functions or operator commands, you must use the BOTH option that uses the same caching parameters for both.
2. Once file-level caching has been defined for a file using the ADARUN `CFILE` parameter, AOS functions, or operator commands, it is not possible to change the caching parameters without first deleting the defined cache space and then adding a new cache space with the different parameters. For example, if you have Data Storage caching defined for a file and you want to add Associator caching, you must first delete the Data Storage cache space and redefine caching for the file using the BOTH option.

The terms are positional. You can omit a term if you want to accept the default value for it, but you must enter a comma to identify the position if you are specifying a subsequent term. See the description of the ADARUN parameter `CFILE` for more information and examples.

### CFSTAT

The `CFSTAT` command can be used to display cache space statistics for one or more files.

This command is valid for file-level caching only.

Value | Description
--- | ---
fnr | Display cache space statistics for one or more individual files.
fnr - fnr | Display cache space statistics for a single range of files.
ALL | Display cache space statistics for all files and Work datasets (the default).

When file-level caching is active, a report is produced for each RABN range associated with the file request.

A sample display of the report is shown below:

    +--------------------------------------------------------------------+
          1     + FNR 00001 AC CL1 EXT RABNS 91 THRU 93
                +--------------------------------------------------------+
          2     +   ALLOCATED, LA=09:55:36
                +--------------------------------------------------------+
          3     +         60 CACHE WRITES  +             0 BLKS IN CACHE +
          4     +          2 READ EXCPS    +    32,767,404 EXTM  SIZE    +
          5     +         52 CACHE READS   +        16,351 BLKS/EXTM     +
          6     +         54 TOTAL READS   +            28 RABN TAB SIZE +
          7     +       96.2 ESP EFFICIENCY+         4,008 MAX ESP USED  +
          8     +   0.001503 MAX NIOT (SEC)+      0.092800 MAX EXCPT(SEC)+
          9     +   0.000018 MIN NIOT (SEC)+      0.092071 MIN EXCPT(SEC)+
         10     +   0.000062 AVE NIOT (SEC)+      0.092435 AVE EXCPT(SEC)+

    +--------------------------------------------------------------------+

The lines of the report are numbered on the left. Line 1 of the report is explained in the table below. For a detailed explanation of lines 2-10, see the section CSTAT/CFSTAT Statistics Report.

Line 1 Field | Explanation
--- | ---
FNR | The file for which the statistics are reported. Two-byte file numbers are supported.
AS, AC, A2, NI, UI, or DS | The type of RABNs being cached: AS: unassigned AC: Address Converter A2: Secondary ISNs NI: Normal Index UI: Upper Index DS: Data
CL | Class of service. The percentage of available cache space that can be used to cache RABNs associated with the specified file(s). This term effectively assigns a priority to the file(s). RABNs belonging to the file(s) with the lowest priority are purged first. Valid values are: 1: 100% (highest priority) 2: 75% 3: 50%; the default 4: 25% 5: 10% (lowest priority)
DSP, EXT, HSP, L64 or V64 | The type of cache: DSP: data space EXT: extended memory HSP: hiperspace L64: virtual 64 backed by large pages V64: virtual 64
RABNs | The RABNs being cached. RABNs displayed are in decimal.

### CINCLUDE

The exclusion list for read-ahead caching may be changed during the nucleus session using the `CEXCLUDE` and `CINCLUDE` commands. Command types may be excluded and included to meet the demands of various job streams and Adabas access loads.

The `CINCLUDE` command can be used to modify the exclusion list for read-ahead caching to include certain command types. For example, if batch-processing streams issue large numbers of `Read Physical (L2)` commands, `CINCLUDE=PHYS` can be issued before the batch processing to boost performance for these jobs.

Value | Description
--- | ---
PHYS | Include `L2` and `L5` (physical sequence) commands.
LOGI | Include `L3` and `L6` (logical sequence) commands.
HIST | Include `L9` (histogram) command.
FIND | Include `S1` (nondescriptor search) command.

The inclusion list must be specified with each four-byte name separated by a slash ( / ). No intervening spaces or special characters, such as commas, are permitted.

The inclusion is made globally: for example, if `CINCLUDE=PHYS` is specified, all `L2` and `L5` commands are included in read-ahead processing, regardless of the file to which the command was directed.

See also the related command `CEXCLUDE`.

### CPARM

`CPARM` is one of the commands used to display the ADACSH runtime options. It displays the current runtime options valid for both global and file level caching.

`CPARM` does not display the options set by the `CINCLUDE` command, only those set by `CEXCLUDE`. Any option not listed under `CEXCLUDE` is included by default.

`CPARM` also does not display any files set for caching by the `CFILE` command. Use the `CFSTAT` command to display informaton about files that are cached or will be cached.

### CRETRY

`CRETRY` is one of the commands used to modify or display the ADACSH runtime options. It specifies the number of seconds between retries for allocating a cache space area if a previous attempt to allocate the area failed.

The minimum time permitted is 60 seconds.

### CSTAT

For global caching, `CSTAT` can be used to display the current statistics for the specified or all RABN ranges. For file-level caching, `CSTAT` displays caching statistics for the Work file parts 2 or 3.

#### For Global Caching

For global caching, `CSTAT` can be used to display the current statistics for the specified or all RABN ranges.

Value | Description
--- | ---
ALL | Display statistics report for all RABN ranges or cache space.
csn | Display statistics report for one or more specified RABN Range IDs (csn).

If no cache space area is defined, no report is produced.

A report is produced for each RABN range associated with the request.

A sample display of the report produced for each RABN range is shown below:

    +------------------------------------------------------------------+
         1    + 00005 DATA SPACE, DATA,  RABNS 301 THRU 450            +
              +--------------------------------------------------------+
         2    +   ALLOCATED, LA=17:04:26                               +
              +--------------------------------------------------------+
         3    +        253 CACHE WRITES  +            47 BLKS IN CACHE +
         4    +         47 READ EXCPS    +       171,820 DATA SPC SIZE +
         5    +        408 CACHE READS   +            55 BLKS/DATA SPC +
         6    +        455 TOTAL READS   +           616 RABN TAB SIZE +
         7    +       89.6 DSP EFFICIENCY+       167,936 MAX DSP USED  +
         8    +   0.071810 MAX NIOT (SEC)+      0.698682 MAX EXCPT(SEC)+
         9    +   0.000080 MIN NIOT (SEC)+      0.009600 MIN EXCPT(SEC)+
         10   +   0.000245 AVE NIOT (SEC)+      0.167286 AVE EXCPT(SEC)+

    +------------------------------------------------------------------+

The lines of the report are numbered on the left. Line 1 of the report is explained in the table below. For a detailed explanation of lines 2-10, see the section CSTAT/CFSTAT Statistics Report.

Line 1 Field | Explanation
--- | ---
nnnnn | The RABN Range ID depending on its associations. For global caching, the ID is unique within the whole system. If the RABN range is for WORK parts 2 or 3, the ID is a unique number. In the above example, the RABN Range ID is 00005.
DATA SPACE | The type of cache space being used by the RABN range. In the above example, the type is DATASPACE.
DATA | The type of RABNs being cached: ASSO, DATA, WORK2, WORK3. In the above example, the type is DATA.
RABNs | The RABNs being cached. RABNs displayed are in decimal. In the above example, RABNs 301 - 450 are to be cached.

#### For File-Level Caching

For file-level caching, CSTAT can be used to display caching statistics for the Work file parts 2 or 3.

### CSUM

The `CSUM` command can be used to display for the current session the accumulated cache summary for all active and inactive RABN ranges, including statistics from previously deleted RABN ranges.

A sample report is shown below:

              +--------------------------------------------------------+
              + A D A B A S  Dynamic Caching Session  S U M M A R Y    +
     1        +        23.3  Current ADABAS Buffer efficiency          +
     2        +        10.2  Projected non-cache buffer efficiency     +
     3        +          16  Active RABN ranges                        +
     4        +          20  RABN ranges defined                       +
              + ------------ -----ASSO---- -----DATA---- -----WORK---- +
     5        + Cache Writes           186         1,099             3 +
     6        +   Read EXCPs            81           462             0 +
     7        +  Cache Reads           113           640            23 +
     8        +  Total Reads           194         1,109            23 +
     9        +   Efficiency          58.2          58.3         100.0 +
              + ------------ ------------- ------------- ------------- +
     10       +   RABNS Read             7            16               +
     11       +   REOT EXCPs             2             8               +
     12       +    Logi/Phys             1             4               +
     13       +    Hist/Find             2             4               +
     14       + Ave RBS/REOT           2.3           2.0               +
              +--------------------------------------------------------+
     15       + Max cache           3,000K        3,000K       12,248K +
     16       + DS Alloc'ED         1,000K        1,000K               +
     17       +        High         1,000K        1,000K               +
     18       + HS Alloc'ED         1,000K            0K               +
     19       +        High         1,000K            0K               +
     20       + EXT Alloc'ED            0K            0K               +
     21       +        High             0K            0K               +
     22       + V64 Alloc'ED            0K            0K               +
     23       +        High             0K            0K               +
     24       + L64 Alloc'ED            0K            0K               +
     25       +        High             0K            0K               +
              +--------------------------------------------------------+

The report is explained in the following table.

Line | Field | Explanation
--- | --- | ---
1 | CURRENT ADABAS BUFFER EFFICIENCY | Adabas buffer efficiency calculated by the Adabas nucleus. The number of requested reads divided by the number of actual reads.
2 | PROJECTED NON-CACHE BUFFER EFFICIENCY | This number postulates the Adabas buffer efficiency if caching were not active. The number is calculated by adding all of the CACHE READS (that is, EXCPs saved) to the total number of actual reads for the nucleus.
3 | ACTIVE RABN RANGES | The number of RABN ranges currently active and servicing I/O requests.
4 | RABN RANGES DEFINED | The number of RABN ranges currently defined to the system.
5 | CACHE WRITES | The total number of cache writes, accumulated across all active, inactive, and previously deleted ASSO, DATA, and WORK RABN ranges (see `CSTAT` description).
6 | READ EXCPS | The total number of non-cache reads, accumulated across all active, inactive, and previously deleted ASSO, DATA, and WORK RABN ranges (see `CSTAT` description). Note that the READ EXCPS for Work will always be zero because no actual EXCPs are performed for Work parts 2 and 3 caching.
7 | CACHE READS | The total number of reads from the cache, accumulated across all active, inactive, and previously deleted ASSO, DATA, and WORK RABN range spaces (see `CSTAT` description).
8 | TOTAL READS | The totals of READ EXCPS and CACHE READS for ASSO, DATA, and WORK.
9 | EFFICIENCY | The number of CACHE READS for the RABN ranges expressed as a percentage of the TOTAL READS.
10 | RABNS READ | (read-ahead caching). The number of RABNs read when more than one RABN is read into cache.
11 | REOT EXCPS | (read-ahead caching). The number of physical I/Os.
12 | Logi/Phys | (read-ahead caching). The number of physical I/Os for Logical Sequence commands or Physical Sequence commands.
13 | Hist/Find | (read-ahead caching). The number of physical I/Os for a Histogram command or a nondescriptor search command.
14 | AVE RBS/REOT | (read-ahead caching). The average number of RABNs read per physical I/O.
15 | MAX CACHE | The maximum amount of space that may be allocated for caching the appropriate Adabas storage RABNs. For ASSO and DATA, it is a function of the `CASSOMAXS` / `CDATAMAXS` and `CMAXCSPS` parameters. For WORK, it is based on the percentages of the Work parts 1 and 2 cached and the size of the Work dataset.
16 | DS ALLOC'ED | The amount of storage currently allocated in data spaces for the appropriate Adabas storage.
17 | DS ALLOC'ED / HIGH | The highest allocation of data space storage during this Adabas nucleus session.
18 | HS ALLOC'ED | The amount of storage currently allocated in Hiperspaces for the appropriate Adabas storage.
19 | HS ALLOC'ED / HIGH | The highest allocation of Hiperspace storage during this Adabas nucleus session.
20 | EXT ALLOC'ED | The amount of storage currently allocated in extended memory for the appropriate Adabas storage.
21 | EXT ALLOC'ED/HIGH | The highest allocation of extended memory storage during this Adabas nucleus session.
22 | V64 ALLOC’ED | The amount of backed by pageable 4K large pages storage currently allocated in virtual 64 storage for the appropriate Adabas storage.
23 | V64 ALLOC’ED/HIGH | The highest allocation of backed by pageable 4K large pages virtual 64 storage during this Adabas nucleus session.
24 | L64 ALLOC’ED | The amount of storage currently allocated in virtual 64 storage backed by large pages for the appropriate Adabas storage.
25 | L64 ALLOC’ED/HIGH | The highest allocation of virtual 64 storage backed by large pages during this Adabas nucleus session.

## CSTAT/CFSTAT Statistics Report

This section describes lines 2-10 of the reports produced by the `CSTAT` or `CFSTAT` command.

- Line Number 2 (Status Line)

- Line Number 3 (Cache Writes / Blocks in Cache)

- Line Number 4 (Read EXCPs / Data Space Size)

- Line Number 5 (Cache Reads / Max Blocks for Caching)

- Line Number 6 (Total Reads / RABN Table Size)

- Line Number 7 (Cache Efficiency / Cache Space Used)

- Line Number 8 (Max Time / EXCP Time)

- Line Number 9 (Min Elapsed Time / Min Elapsed EXCP Time)

- Line Number 10 (Avg Elapsed Time / Avg Elaspse EXCP Time)

### Line Number 2 (Status Line)

Line number 2 contains the current status of the RABN range and the time of last activity.

Example: ALLOCATED, LA=17:04:26

Field | Explanation
--- | ---
Status | The current status of the RABN range. Values that may appear include the following: ALLOCATED: The RABN range is active. UNALLOCATED: The RABN range is not active. DISABLED: The RABN range is disabled and is not used unless the `CDEMAND` level is reached or a `CENABLE` command is issued. GETSPACE FAILED: Cache space allocation failed. INSUFF.MEM (EXT): Extended memory cannot be allocated. ADD TO ALET FAILED (DSP): Data space cannot be activated.
Last Activity Time | The time of the last activity in hh:mm:ss format.

### Line Number 3 (Cache Writes / Blocks in Cache)

Line number 3 contains the number of cache writes and the number of RABNs stored in the cache space for this RABN range when the `CSTAT` command was issued.

Example: 253 CACHE WRITES + 47 BLKS IN CACHE

Field | Explanation
--- | ---
CACHE WRITES | The number of RABNs moved from the Adabas buffer pool into the cache space for this RABN range. This number may include RABNs that were moved back and forth between the buffer pool and cache more than once, i.e., counted more than one time.
BLKS IN CACHE | The number of RABNs stored in the cache space for this RABN range when the `CSTAT` command was issued. This number fluctuates as RABNs are moved into and removed from the cache space.

### Line Number 4 (Read EXCPs / Data Space Size)

Line number 4 contains the number of actual read I/O requests issued for the RABNs within the specified RABN range during the time the RABN range was active, and the amount of cache space theoretically available for caching RABNs associated with the range.

Example: 47 READ EXCPS + 171,820 DATA SPC SIZE

Field | Explanation
--- | ---
READ EXCPS | The number of actual read I/O requests issued for the RABNs within the specified RABN range during the time the RABN range was active. This number reflects the fact that a requested block was not in the cache space and had to be read from disk. Note In the case of I/O count comparisons, the READ EXCPs counted by ADACSH do not reflect the read I/O requests issued by the nucleus for RABNs outside the specified RABN ranges; nor do they include I/O counts during the period that a RABN range is not allocated. Therefore, the totals for the READ EXCPs will not correspond directly to the I/O counts displayed by the nucleus and ADAIOR.
DATA SPC SIZE | The amount of cache space theoretically available for caching RABNs associated with the range. For global caching, it reflects the maximum possible size of the cache space. For file level caching, it reflects the percentage of the total available to the file based on its class of service. The value displayed in this field will correspond to the cache space type; that is, DATA SPC SIZE for data spaces; EXTM SPC SIZE for extended memory; HIPERSPC SIZE for hiperspaces; V64 SPC SIZE for 64-bit virtual storage.

### Line Number 5 (Cache Reads / Max Blocks for Caching)

Line number 5 contains the number of times the nucleus issued a read request that did not result in a READ EXCP because the RABN was found in the cache space, and the number of ASSO, DATA or WORK blocks that would fit into the maximum amount of space that could possibly be used by this range.

Example: 408 CACHE READS + 55 BLKS/DATA SPC

Field | Explanation
--- | ---
CACHE READS | The number of times the nucleus issued a read request that did not result in a READ EXCP because the RABN was found in the cache space. This number represents the reduction in EXCPs resulting from dynamic caching.
BLKS/DATA SPC | The number of ASSO, DATA or WORK blocks that would fit into the maximum amount of space that could possibly be used by this range. This number reflects the maximum number of blocks that could ever be cached at any given time. It is unlikely that a single RABN range would ever be in a position to use the maximum amount of space possible due to competition for space among RABN ranges. The value displayed in this field will correspond to the cache space type; that is, BLKS/DATA SPC for data spaces; BLKS/EXTM SPC for extended memory BLKS/HIPERSPC for hiperspaces; or BLKS/V64 SPC for 64-bit virtual storage.

### Line Number 6 (Total Reads / RABN Table Size)

Line number 6 contains the total of READ EXCPS and CACHE READS, and the amount of storage allocated in the extended memory area of the primary address space for the RABN table associated with the RABN range.

Example: 455 TOTAL READS + 616 RABN TAB SIZE

Field | Explanation
--- | ---
TOTAL READS | The total of READ EXCPS and CACHE READS. This value gives an indication of the number of EXCPs that would have been issued if dynamic caching had not been in effect.
RABN TAB SIZE | The amount of storage allocated in the extended memory area of the primary address space for the RABN table associated with the RABN range.

### Line Number 7 (Cache Efficiency / Cache Space Used)

Line number 7 contains the cache efficiency and the size of the cache space actually used.

Example: 89.6 DSP EFFICIENCY+ 167,936 MAX DSP USED

Field | Explanation
--- | ---
DSP EFFICIENCY | The number of CACHE READS expressed as a percentage of TOTAL READS: Efficiency = (CACHE READS / TOTAL READS) * 100 (Also xxx EFFICIENCY where xxx is ESP (extended memory); DSP (data space); HSP (hiperspace); or V64 (virtual 64) cache space types.)
MAX DSP USED | The size of the cache space actually used. This value represents the high-water space usage. This value can be used to fine tune the cache space allocations to maximize data space, hiperspace, extended memory usage, or 64-bit virtual storage. Note that if the maximum cache space (DATA SPC SIZE) is reached, the MAX DSP USED reflects a difference of 4096 because the start location for the data space and hiperspace is set to 4096.

### Line Number 8 (Max Time / EXCP Time)

Line number 8 contains the maximum elapsed time value for a single read request, and the time required for the EXCP.

Example: 0.071810 MAX NIOT (SEC)+ 0.698682 MAX EXCPT(SEC)

Field | Explanation
--- | ---
MAX NIOT (SEC) | The maximum elapsed time value for a single read request. Non-I/O time (NIOT) is the time required for a block to be returned from the cache space; all times are given in seconds and fractions of seconds. The NIOT is measured from the point when the ADACSH module determined the location of the requested block to the point when the block was returned to the nucleus. Note that a block found in the cache space always returns an I/O completion for that block because no CPU-I/O overlap processing is required. NIOT includes the time associated with the data space, hiperspace, or extended memory operations.
MAX EXCPT (SEC) | EXCP Time (EXCPT) is the time required for the EXCP. EXCPT is measured from the point when the I/O request was given to ADAIOR to the point when ADAIOR returned the I/O completion for that block to the nucleus. EXCPT includes the time for the EXCP processing, as well as the time elapsed within the CPU-I/O overlap processing between the nucleus and ADAIOR.

### Line Number 9 (Min Elapsed Time / Min Elapsed EXCP Time)

Line number 9 contains the minimum elapsed Non-I/O Time value for a single read request, and the minimum elapsed EXCP Time value for a single read request.

Example: 0.000080 MIN NIOT (SEC)+ 0.009600 MIN EXCPT(SEC)

Field | Explanation
--- | ---
MIN NIOT (SEC) | The minimum elapsed Non-I/O Time value for a single read request (see line number 8 above).
MIN EXCPT (SEC) | The minimum elapsed EXCP Time value for a single read request (see line number 8 above).

### Line Number 10 (Avg Elapsed Time / Avg Elaspse EXCP Time)

Line number 10 contains the average elapsed Non-I/O Time value for a single read request, and the average elapsed EXCP Time value for a single read request.

Example: 0.000245 AVE NIOT (SEC)+ 0.167286 AVE EXCPT(SEC)

Value | Explanation
--- | ---
AVE NIOT (SEC) | The average elapsed Non-I/O Time value for a single read request (see line number 8 above). The AVE NIOT is computed by dividing the total accumulated NIOT by the total number of CACHE READS (see line number 5 above).
AVE EXCPT (SEC) | The average elapsed EXCP Time value for a single read request (see line number 8 above). The AVE EXCPT is computed by dividing the total accumulated EXCPT by the total number of READ EXCPS (see line number 4 above).

### On this page

- Operator Command Overview
- Operator Command Summary Table
- Operator Command Syntax
- Identifying a RABN Range or File Range
- Command Descriptions
- CSTAT/CFSTAT Statistics Report