Adabas Caching Operations

This document describes the operator commands available for Adabas Caching.


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.

z/OS environment

F jobname,option

where:

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

VSE/ESA Environment

MSG fn
replid option

where:

fn is the VSE partition in which Adabas is executing
replid is the Reply ID assigned by VSE when the MSG command is issued
option is the ADACSH operation to be performed

BS2000 Environment

tttt INTR,option

where:

tttt is the task number of the Adabas Caching database
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 / 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 1M large pages

  • CASSOV64: Virtual 64-bit storage

Extended memory is the only option available on BS2000 RISC machines. Hiperspace is a valid option only under z/OS. The options Virtual 64 and Virtual 64 backed by large pages are valid only under z/OS.

For more information, see section Caching Configuration.

graphics/cassodsp_syntax.png

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.

graphics/cassomaxs_syntax.png

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.

graphics/cbufno_syntax.png

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.

graphics/cctimeout_syntax.png

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.

graphics/cchange_syntax.png

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
HIPERSPACE
L64
VIRTUAL64

The type of cache space to be used.

Note:
Extended memory is the only option on BS2000 RISC machines. Hiperspace is an option only in z/OS environments. Virtual 64 backed by large pages (L64) and Virtual 64 (VIRTUAL64) are only available for z/OS environments.

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 / 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 1M large pages

  • CDATAV64: Virtual 64-bit storage

Extended memory is the only option available on BS2000 RISC machines. Hiperspace is a valid option only under z/OS. Virtual 64 and Virtual 64 backed by large pages are only available under z/OS.

For more information, see section Caching Configuration.

graphics/cdatadsp_syntax.png

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.

graphics/cdatamaxs_syntax.png

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:

graphics/cdelete_syntax1.png

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).

graphics/cdelete_syntax2.png

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.

graphics/cdemand_syntax.png

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.

graphics/cdisable_syntax1.png

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.

graphics/cdisable_syntax2.png

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.

graphics/cdispstat_syntax.png

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.

graphics/cenable_syntax1.png

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.

graphics/cenable_syntax2.png

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.

graphics/cexclude_syntax.png

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.

graphics/cfdelete_syntax.png

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.

graphics/cfdisable_syntax.png

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.

graphics/cfenable_syntax.png

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.

graphics/cfile_syntax.png

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:
Virtual 64-bit values "G64", "L64", and "VIRTUAL64" are cache options only in z/OS environments. 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.

graphics/cfstat_syntax.png

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.

graphics/cinclude_syntax.png

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 modify or display the ADACSH runtime options. It displays the current runtime options including the ADACSH start-up parameters.

graphics/cparm_syntax.png

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.

graphics/cretry_syntax.png

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.

graphics/cstat_syntax1.png

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.

graphics/cstat_syntax2.png

CSUM

graphics/csum_syntax.png

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           647            23 +
 8        +  Total Reads           194         1,109            23 +
 9        +   Efficiency          58.2          58.3         100.0 +
          + ------------ ------------- ------------- ------------- +
 10       +   RABNS Read             7             0               +
 11       +   REOT EXCPs             2             0               +
 12       + Ave RBS/REOT           3.5           n/a               +
          +--------------------------------------------------------+
 13       + Max cache           3,000K        3,000K       12,248K +
 14       + DS Alloc'ED         1,000K        1,000K               +
 15       +        High         1,000K        1,000K               +
 16       + HS Alloc'ED         1,000K            0K               +
 17       +        High         1,000K            0K               +
 18       + EXT Alloc'ED            0K            0K       11,552K +
 19       +        High             0K            0K       11,552K +
 20       + V64 Alloc'ED            1M            2M               +
 21       +        High             1M            2M               +
 22       + L64 Alloc'ED            1M            1M               +
 23       +        High             1M            1M               +
          +--------------------------------------------------------+

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 AVE RBS/REOT (read-ahead caching). The average number of RABNs read per physical I/O.
13 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.
14 DS ALLOC'ED The amount of storage currently allocated in data spaces for the appropriate Adabas storage.
15 DS ALLOC'ED / HIGH The highest allocation of data space storage during this Adabas nucleus session.
16 HS ALLOC'ED The amount of storage currently allocated in Hiperspaces for the appropriate Adabas storage.
17 HS ALLOC'ED / HIGH The highest allocation of Hiperspace storage during this Adabas nucleus session.
18 EXT ALLOC'ED The amount of storage currently allocated in extended memory for the appropriate Adabas storage.
19 EXT ALLOC'ED/HIGH The highest allocation of extended memory storage during this Adabas nucleus session.
20 V64 ALLOC’ED The amount of storage currently allocated in virtual 64 storage for the appropriate Adabas storage.
21 V64 ALLOC’ED/HIGH The highest allocation of virtual 64 storage during this Adabas nucleus session.
22 L64 ALLOC’ED The amount of storage currently allocated in virtual 64 storage backed by large pages for the appropriate Adabas storage.
23 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 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).