Version 8.2.3

Adabas Caching Parameters

This document describes the Adabas Caching configuration parameters.


Parameter Syntax

The parameter input follows the standard Adabas ADARUN parameter conventions as follows:

The parameters are displayed on DDPRINT. If an error is detected during the processing of a statement, an error message is displayed and the remainder of the statement is ignored. Processing continues with the next statement. All parameters successfully processed are used to define the runtime settings. Defaults are used for the parameters that were not specified or were ignored due to errors.

Top of page

Parameter Overview

An overview of the ADACSH parameters is provided in the table below.

Note:
The following parameters can only be used for global-level caching:

{CASSODSP | CASSOEXT | CASSOG64 | CASSOHSP | CASSOL64 | CASSOV64}
    {CDATADSP | CDATAEXT | CDATAG64 | CDATAHSP | CDATAL64 | CDATAV64} CSTORAGE

Note:
The following parameters can only be used for file-level caching:

CFILE and CXFILE.

Note:
Extended memory is the only option for RISC machines running BS2000. Hiperspace is an option only in z/OS environments. Virtual 64 storage is available only in z/OS environments.

The default value for each parameter is underlined.

Parameter Values Description
CACHE YES | NO Causes the ADACSH module to be loaded during session initialization. If CACHE=NO, no caching occurs and no ADACSH operator commands are accepted.
CACTIVATE YES | NO Activates all RABN ranges or files at session open for immediate use.

CASSODSP
CASSOEXT
CASSOHSP
CASSOG64
CASSOL64
CASSOV64

{rabn | rabn - rabn}, ... Specifies the Associator RABNs or RABN ranges to be cached and the type of cache space to be used. The default is no Associator RABNs. These parameters are mutually exclusive with the CFILE and CXFILE parameters.
CASSOMAXS 1024K The unit size for allocating Associator cache areas. Used with the CMAXCSPS parameter to define the maximum amount of Associator cache space that can exist for a given type of storage.
CBUFNO n One of two parameters used for read-ahead caching. Specifies the number of read-ahead buffers available for concurrent I/O processing.
CCTIMEOUT 7200 The maximum time of inactivity permitted before releasing an area of a cache space. The default is 7200 seconds (2 hours).

CDATADSP
CDATAEXT
CDATAHSP
CDATAG64
CDATAL64
CDATAV64

{rabn | rabn - rabn}, ... Specifies the Data Storage RABNs or RABN ranges to be cached and the type of cache space to be used. The default is no Data Storage RABNs. These parameters are mutually exclusive with the CFILE and CXFILE parameters.
CDATAMAXS 1024K The unit size for allocating Data Storage cache areas. Used with the CMAXCSPS parameter to define the maximum amount of Data Storage cache space that can exist for a given type of storage.
CDEMAND 0 | n The minimum acceptable Adabas buffer efficiency level. If the buffer efficiency level drops below this value, the cache spaces for Associator and Data Storage are activated. The default value of zero means no demand activation.
CDISPSTAT YES | NO Specifies whether or not all ADACSH messages are to be displayed on the system console.
CEXCLUDE { PHYS | LOGI | HIST | FIND } / ... One of two parameters used for read-ahead caching. Specifies the command types to be excluded from read-ahead caching.
CFILE ({fnr | fnr - fnr}, [cls],[scope] ,[cache]) Specifies which files to cache and the type of caching to occur. Multiple CFILE parameters may be specified.
CMAXCSPS 8 | n Determines the maximum number of storage areas of a size defined by the CASSOMAXS and CDATAMAXS parameters that can be allocated for a cache space.
CRETRY 900 The number of seconds between retries for allocating a storage area for a cache space if a previous allocation attempt failed.
CSTORAGE DATASPACE | EXTENDED | G64 | HIPERSPACE | L64 | VIRTUAL64 Specifies the type of cache space to be allocated for both Associator and Data Storage RABNs. Overrides any CASSO and CDATA parameters. The default is no type specified. This parameter is mutually exclusive with the CFILE and CXFILE parameters.
CWORKSTORAGE DATASPACE | EXTENDED | G64 |HIPERSPACE | L64 | VIRTUAL64 Specifies the type of cache space to be allocated for Work parts 2 and 3. The default depends on the Adabas operating system.
CWORK2FAC 0 The percentage of the number of Work part 2 RABNs to be cached. The default value of zero means that no caching of Work part 2 is in effect.
CWORK3FAC 0 The percentage of the number of Work part 3 RABNs to be cached. The default value of zero means that no caching of Work part 3 is in effect.
CXFILE ( { fnr | fnr - fnr } [,,scope] ) Specifies files to exclude from caching. Multiple CXFILE parameters may be specified. The commas ",," maintain a correspondence with the positions established for the CFILE parameter.

Top of page

Parameter Descriptions

CACHE Parameter: Adabas Caching Facility Control

CACHE (or CACH) specifies whether or not ADACSH is to be loaded during Adabas session initialization.

graphics/ccache.png

Value Description
YES ADACSH is loaded and available for operation.
NO ADACSH is not loaded. Caching is not available until the Adabas session is terminated and subsequently restarted with CACHE=YES.

Example

ADARUN CACHE=YES

ADACSH is loaded during the Adabas session initialization. ADACSH operator commands are accepted and caching is in effect.

CACTIVATE Parameter: Adabas Caching Facility RABN Activation

CACTIVATE (or CACT) specifies whether or not all RABN ranges are to be activated at session open.

graphics/ccact.png

Value Description
YES All RABN ranges are activated at session open. This provides for immediate use of the cache without consideration of the CDEMAND threshold level.
NO None of the RABN ranges is activated unless:
  • the CDEMAND threshold level is reached; or

  • the CENABLE operator command is accepted by ADACSH.

Example

ADARUN CACTIVATE=YES

All RABN ranges are made available for immediate use; that is, as soon as the Adabas nucleus needs to move a block from the Adabas buffer pool into a RABN range, the RABN range is allocated.

CASSODSP / CASSOEXT / CASSOHSP / CASSOG64 / CASSOL64 / CASSOV64 Parameters: Adabas Caching Facility Associator RABN Cache Space Control

Note:
CASSOxxx parameters are mutually exclusive with the CFILE and CXFILE parameters.

The CASSOxxx parameters identify one or more Associator RABNs to be cached where xxx indicates the type of cache space.

Note:
Virtual 64 storage is only available in z/OS environments.

graphics/ccasso.png

Value Description
rabn The Associator RABN to be cached.
rabn - rabn The range of Associator RABNs to be cached. The range is specified as two numbers separated by a hyphen with no intervening spaces or special characters. More than one RABN range (separated by a comma) may be specified on the same line. There are no continuations. If more than one line is required, additional CASSOxxx parameters must be specified.

If CASSOxxx is specified, only the specified RABNs are cached. Unspecified RABNs are not cached and are subject to normal Adabas I/O operations.

Associator RABNs 1 through 30 are not cached; they are ignored if specified by the user.

Notes:

  1. If an invalid RABN range is specified in the CASSOxxx parameter, subsequent RABN ranges for the CASSOxxx parameter are ignored. The ignored parameters can be added after initialization by using an operator command.
  2. The CSTORAGE parameter overrides any CASSOxxx parameter and ADACSH will cache all Associator RABNs as defined for the database.

RABNs for the ranges specified are cached in the cache space indicated by the parameter suffix. RABN ranges defined with this parameter must therefore compete for the space available in a given cache space. When the maximum is allocated, RABNs are purged from the cache space based on a first-in-first-out (FIFO) mechanism and are reused to accommodate the latest RABNs being purged from the Adabas buffer pool.

Example

 ADARUN CASSODSP=1330-2349,126-187,124-125,205-216 
ADARUN CASSOHSP=218-252,203-204,260-275,277-335

ADACSH caches the specified RABN ranges. No other Associator RABNs are cached.

The first four RABN ranges defined are cached in the Associator cache space allocated in data space (suffix DSP). The second four RABN ranges defined are cached in the Associator cache space allocated in hiperspace (suffix HSP).

CASSOMAXS Parameter: Associator Cache Space Unit Size

The CASSOMAXS (or CASSOM) parameter specifies the unit size in which areas are allocated for Associator cache space.

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

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, CASSOMAXS is always rounded up to the nearest 4-kilobyte boundary.

Note:
When using data space storage on BS2000 systems, allocation units are rounded to one-megabyte units. The Adabas Caching Facility may extend data space storage and deliver the message ADAN8M ddddd area-type (stg-type) size extended by nnnnnn bytes. However, if the megabyte limit is reached, it will deliver the message: ADAN8S area-type (stg-type) Allocate failed. Retcode=64. We recommend that you set the ADARUN parameters CASSOMAXS and CDATAMAXS high enough (in the megabyte range) to prevent repeated expansion. It may be necessary to set the BS2000 user attribute ADDRESS-SPACE-LIMIT high enough to accommodate this.

For virtual 64 memory and virtual 64 backed by large pages, virtual storage above the 2G 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. For cache spaces for which storage is backed by 2G large pages ("G64"), CASSOMAXS is rounded up to the nearest multiple of two gigabytes.

    Note:
    If "G64" is specified for a cache space, we recommend that you specify a CASSOMAXS value that is a multiple of two gigabytes. The specified size will be rounded up to the nearest multiple of two gigabytes and any difference between the specified size and the allocated size will remain unused. Specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused.

The total space available is equal to:

Maximum-ASSO-cache-space-size = CASSOMAXS x CMAXCSPS

Storage areas for a cache space are allocated when required. The Adabas nucleus informs ADACSH when a RABN is about to be purged from the buffer pool. If ADACSH determines that this RABN is being cached, it attempts to allocate space in the appropriate cache space.

When no space is available in the currently allocated areas for a cache space, or no areas are allocated, a new area of storage is allocated with the size specified by the CASSOMAXS parameter. For cache storage in

This occurs until the maximum number of areas as determined by the CMAXCSPS parameter is reached. At this point, space is made for the latest RABNs to be purged from the Adabas buffer pool based on the aging algorithms.

The CASSOMAXS limit used for the allocation of new areas in a cache space is based on the last specification for this value. If no operator or Adabas Online System command is issued, this is the value specified in the startup parameters. If this value is specified by an operator command or through Adabas Online System, it takes effect the next time an additional area is allocated in an ASSO cache space.

Example

ADARUN CASSOMAXS=15000000

Cache space areas for ASSO RABNs are allocated in units of 15003648 bytes (or 14652K; or approximately 14M).

CBUFNO Parameter: Number of Read-Ahead Buffers for Concurrent I/O Processing

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

CBUFNO is one of two parameters (CBUFNO and CEXCLUDE) used for read-ahead caching. Read-ahead caching performs a read-ahead of consecutive Associator and/or Data Storage blocks when processing serial Adabas commands (Read Logical, Read Physical, Histogram), and when searching using nondescriptors.

The read-ahead is performed by issuing a single EXCP to read all the consecutive Associator or Data Storage blocks that reside on a single track of the disk device. The blocks are kept in cache and are immediately available when the nucleus requests the next block in a sequence.

This feature may enhance performance by reducing the number of physical read I/Os. For example, for a 3380 Associator, a reduction factor of 18:1 may be achieved.

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.

During normal cache processing, if a read I/O request qualifies for read-ahead processing but no read-ahead buffer is available, the read I/O is satisfied with a single block EXCP. In other words, no optimization is done to issue an EXCP to read the entire track.

Note:
Read-end-of-track processing is not available in Cluster and SMP environments.

Example

ADARUN CBUFNO=5,CEXCLUDE=FIND/HIST

Five buffers are available for read-ahead caching. No read-ahead processing is performed for S1 (nondescriptor search) and L9 (histogram) commands.

CCTIMEOUT Parameter: Cache Space Area or RABN Inactivity Time

The CCTIMEOUT (or CC) parameter specifies the amount of time (in seconds) a cache space area can remain inactive before it is released back to the system.

If demand caching (CDEMAND) is in effect, CCTIMEOUT specifies the number of seconds a RABN range, file, or file range can remain inactive before it is disabled.

graphics/cctimeout_syntax.png

Value Description
n

The amount of time (in seconds) a cache space area can remain inactive before it is released back to the system.

If demand caching (CDEMAND) is in effect, CCTIMEOUT specifies the number of seconds a RABN range, file, or file range can remain inactive before it is disabled.

The minimum number of seconds is 60; the maximum is 2,147,483,647.

The default number of seconds is 7200 (2 hours).

If a cache space area has not been accessed for the specified period of time, ADACSH releases the storage associated with the area back to the operating system. A message is displayed on the operator console indicating that the cache space area was timed out. The cache space area can be re-allocated immediately by the caching system when required.

If a RABN range, file, or file range is not referenced for the specified period of time, and demand caching is in effect, the RABN range, file, or file range is disabled. A message is displayed on the operator console informing the user that the RABN range, file, or file range was timed out. No further caching occurs for that RABN range, file, or file range until the Adabas buffer efficiency goes below the level specified by CDEMAND. Once this occurs, the RABN range, file, or file range is enabled again and begins caching its associated RABNs.

Activity is checked at an interval of one half of the CCTIMEOUT value. For example, if CCTIMEOUT=3600 is specified, the allocated cache space areas, RABN ranges, files, or file ranges are checked every 1800 seconds (30 minutes).

A change to CCTIMEOUT using an operator command causes the check to be performed immediately, and subsequently at intervals of one half of the new CCTIMEOUT value.

Example

ADARUN CCTIMEOUT=3600

A cache space area is released (or a RABN range/file/file range is disabled if demand caching is in effect) if there is no activity associated with it for a continuous period of 1 hour (3600 seconds).

CDATADSP / CDATAEXT / CDATAHSP / CDATAG64 / CDATAL64 / CDATAV64 Parameter: Adabas Caching Facility Data Storage RABN Cache Space Control

Note:
CDATAxxx parameters are mutually exclusive with the CFILE and CXFILE parameters.

The CDATAxxx parameters identify one or more Data Storage RABNs to be cached where xxx indicates the type of cache space.

Note:
Only extended memory is available for BS2000 RISC machines. Hiperspace is an option only in z/OS environments. Virtual 64 storage is available only in z/OS environments.

graphics/ccdata.png

Value Description
rabn The Data Storage RABN to be cached.
rabn - rabn The range of Data Storage RABNs to be cached. The range is specified as two numbers separated by a hyphen with no intervening spaces or special characters. More than one RABN range (separated by a comma) may be specified on the same line. There are no continuations. If more than one line is required, additional CDATAxxx parameters must be specified.

If CDATAxxx is specified, only the specified RABNs are cached. Unspecified RABNs are not cached and are subject to normal Adabas I/O operations.

Notes:

  1. If an invalid RABN range is specified in the CDATAxxx parameters, subsequent RABN ranges for the CDATAxxx parameters will be ignored. The ignored parameters can be added after initialization by using an operator command.
  2. The CSTORAGE parameter overrides any CDATAxxx parameter and ADACSH will cache all Data Storage RABNs as defined for the database.

RABNs for the ranges specified are cached in the cache space indicated by the parameter suffix. RABN ranges defined with this parameter must therefore compete for the space available in a given cache space. When the maximum is allocated, RABNs are purged from the cache space based on a first-in-first-out (FIFO) mechanism and are reused to accommodate the latest RABNs being purged from the Adabas buffer pool.

Example

 ADARUN CDATADSP=1-4900,6523-7853 
ADARUN CDATAHSP=5032-6204,8123-10382

ADACSH caches the specified RABN ranges. No other DATA RABNs are cached.

The first two RABN ranges defined are cached in the Data Storage cache space allocated in data space (suffix DSP). The second two RABN ranges defined are cached in the Data Storage cache space allocated in hiperspace (suffix HSP).

CDATAMAXS Parameter: Data Storage Cache Space Unit Size

The CDATAMAXS (or CDATAM) parameter specifies the unit size in which areas are allocated for Data Storage cache space.

graphics/cdatamaxs_syntax.png

Value Description
n

The unit size in which areas are allocated for Data Storage cache space. Size may be specified in bytes, in kilobytes (K), in megabytes (M) or in gigabytes (G).

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.

Note:
When using data space storage on BS2000 systems, allocation units are rounded to one-megabyte units. The Adabas Caching Facility may extend data space storage and deliver the message ADAN8M ddddd area-type (stg-type) size extended by nnnnnn bytes. However, if the megabyte limit is reached, it will deliver the message: ADAN8S area-type (stg-type) Allocate failed. Retcode=64. We recommend that you set the ADARUN parameters CASSOMAXS and CDATAMAXS high enough (in the megabyte range) to prevent repeated expansion. It may be necessary to set the BS2000 user attribute ADDRESS-SPACE-LIMIT high enough to accommodate this.

For virtual 64 memory and virtual 64 backed by large pages, virtual storage above the 2G 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. For cache spaces for which storage is backed by 2G large pages ("G64"), CDATAMAXS is rounded up to the nearest multiple of two gigabytes.

    Note:
    If "G64" is specified for a cache space, we recommend that you specify a CDATAMAXS value that is a multiple of two gigabytes. The specified size will be rounded up to the nearest multiple of two gigabytes and any difference between the specified size and the allocated size will remain unused. Specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused.

The total space available is equal to:

Maximum-DATA-cache-space-size = CDATAMAXS x CMAXCSPS

Storage areas for a cache space are allocated when required. The Adabas nucleus informs ADACSH when a RABN is about to be purged from its buffer pool. If ADACSH determines that this RABN is being cached, it attempts to allocate space in the appropriate cache space.

When no space is available in the currently allocated areas for a cache space, or no areas are allocated, a new area of storage is allocated with the size specified by the CASSOMAXS parameter. For cache storage in

This occurs until the maximum number of areas as determined by the CMAXCSPS parameter is reached. At this point, space is made for the latest RABNs to be purged from the Adabas buffer pool based on the aging algorithms.

The CDATAMAXS limit used for the allocation of new areas in a cache space is based on the last specification for this value. If no operator or Adabas Online System command is issued, this is the value specified in the startup parameters. If this value is specified by an operator command or through Adabas Online System, it takes effect the next time an additional area is allocated in a Data Storage cache space.

Example

ADARUN CDATAMAXS=15000000

Cache space areas for Data Storage RABNs are allocated in units of 15003648 bytes (or 14652K; or approximately 14M).

CDEMAND Parameter: Lowest Adabas Buffer Efficiency for Caching

The CDEMAND (or CDE) parameter specifies the lowest Adabas buffer efficiency level accepted before caching is activated.

Calculated by the nucleus, Adabas buffer efficiency is the number of read requests divided by the actual number of reads to storage. If the Adabas buffer efficiency level drops below the specified CDEMAND level, ADACSH activates all disabled RABN ranges. In this way, RABN ranges are dynamically activated as demand on the Adabas buffer pool increases.

The CDEMAND parameter should be used in conjunction with the CCTIMEOUT parameter to establish resource usage boundaries that permit the timely acquisition and release of system resources. In other words, CDEMAND may be used to activate RABN ranges when the demand load on Adabas is high, and CCTIMEOUT may be used to deactivate RABN ranges when Adabas is idle.

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.

If CDEMAND is not zero, the Adabas buffer efficiency is first checked approximately 30 minutes after the Adabas nucleus is initialized. Thereafter, the Adabas buffer efficiency is checked at intervals of approximately 15 minutes.

CDEMAND does not affect the activation of caching for Work parts 2 and 3 because these areas do not influence the Adabas buffer efficiency. Only Associator and Data Storage blocks reside in the Adabas buffer pool and, consequently, only the cache spaces for the Associator and Data Storage serve to increase the Adabas buffer efficiency level.

Example

ADARUN CDEMAND=7

ADACSH activates the RABN ranges if the Adabas buffer efficiency level drops below 7.

CDISPSTAT Parameter: Adabas Caching Facility RABN Range Statistics Display Control

The CDISPSTAT (or CDI) parameter specifies whether the RABN range statistics are to be displayed on both the operator console and DDPRINT, or only on DDPRINT.

The individual RABN range statistics are displayed whenever a RABN range is released due to a parallel utility operation or an inactivity timeout, or when a RABN range is dynamically added or deleted.

graphics/ccdisp.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.

Example

ADARUN CDISPSTAT=NO

When the status of a RABN range is changed due to a parallel utility operation, a timeout, or an operator command to add or delete, the individual RABN range statistics are to be displayed on DDPRINT only.

CEXCLUDE Parameter: Adabas Caching Facility Excluded Command Types

CEXCLUDE specifies the command types to be excluded from read-ahead caching.

CEXCLUDE is one of two parameters (CBUFNO and CEXCLUDE) used for read-ahead caching. Read-ahead caching performs a read-ahead of consecutive Associator and/or Data Storage blocks when processing serial Adabas commands (Read Logical, Read Physical, Histogram), and when searching using nondescriptors.

The read-ahead is performed by issuing a single EXCP to read all the consecutive Associator or Data Storage blocks that reside on a single track of the disk device. The blocks are kept in cache and are immediately available when the nucleus requests the next block in a sequence.

This feature may enhance performance by reducing the number of physical read I/Os. For example, for a 3380 Associator, a reduction factor of 18:1 may be achieved.

graphics/ccexcl.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-byte 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.

The exclusion list may be changed during the nucleus session using the CEXCLUDE and CINCLUDE operator commands.

Example

ADARUN CBUFNO=5,CEXCLUDE=FIND/HIST

Five buffers are available for read-ahead caching. No read-ahead processing is performed for S1 (nondescriptor search) and L9 (histogram) commands.

CFILE Parameter: Adabas Caching Facility File Range

Note:
CFILE is mutually exclusive with the CASSOxxx, CDATAxxx, and CSTORAGE parameters. If any of these parameters is used with CFILE, they will be ignored.

The CFILE parameter defines a file or file range to be cached. It is also used to provide the settings used to control how caching is to be implemented for the file or file range.

graphics/ccfile.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 data set.
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 cache 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.

Notes:

  1. Virtual 64-bit values "G64", "L64", and "VIRTUAL64" are cache options only in z/OS environments.
  2. 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.
  3. If "G64" is specified, we recommend you specify a cache space size (CASSOMAXSCASSOMAXS/CDATAMAXSCDATAMAXS) that is a multiple of two gigabytes. The specified size will be rounded up to the nearest multiple of two gigabytes and any difference between the specified size and the allocated size will remain unused. Specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused.

Within the parentheses, the value terms are positional. This means that 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 within the parentheses.

Multiple CFILE parameters may be specified.

CFILE and CXFILE parameters together are processed in order from left to right (or top to bottom if different ADARUN statements are used). Parameters or statements that specify file ranges are processed before those that specify specific files.

Examples

ADARUN CACHE=YES,CFILE=(7,2)

File-level caching is active for file number 7. The file is permitted to use up to 75% of the maximum total available cache space (class of service 2). Both Associator and Data Storage RABNS are cached (the default) and the type of cache space used is data space (the default).

ADARUN CACHE=YES,CFILE=(3-6,,DATA,HIPERSPACE)

File-level caching is active for file numbers 3 through 6. The files are permitted to use up to 50% of the maximum total available cache space (class of service 3, the default). Only Data Storage RABNS are cached, and the type of cache space used is hiperspace.

ADARUN CACHE=YES,CFILE=(14-17,,,HIPERSPACE)

File-level caching is active for file numbers 14 through 17. The files are permitted to use up to 50% of the maximum total available cache space (class of service 3, the default). Both Associator and Data Storage RABNs are cached (the default), and the type of cache space used is hiperspace.

CMAXCSPS Parameter: Adabas Caching Facility Storage Area Quantities

The CMAXCSPS (or CM) parameter specifies the number of storage areas that can be allocated for an ADACSH cache space in data spaces, hiperspaces, or memory objects (64-bit virtual storage). It has no effect on a cache space in extended memory, where only one Associator and one Data Storage area are allowed.

In conjunction with the CASSOMAXS and CDATAMAXS parameters, this parameter is used to control both the total amount of space that can be allocated for a cache space and the granularity with which it is allocated.

Value Description
n

The number of storage areas that can be allocated for an ADACSH cache space in data spaces, hiperspaces, or memory objects (64-bit virtual storage). It has no effect on a cache space in extended memory, where only one ASSO and one DATA storage area are allowed.

The minimum value permitted is 1; the maximum is 16, the default is 8.

This means that a potential maximum of 34 storage areas can be allocated for each type of cache space used: 16 for Associator RABNs, 16 for Data Storage RABNs, and 1 each for Work parts 2 and 3.

Note:
Increasing the value of CMAXCSPS can increase the overall CPU load used by ADACSH as more storage areas must be searched when allocating storage. This value must be carefully selected in association with the CASSOMAXS and CDATAMAXS values to obtain the correct mix of granularity and CPU overhead. Experience indicates that the default CMAXCSPS setting (8) usually provides an appropriate mix.

Example

ADARUN CMAXCSPS=6

Up to six Associator cache space areas of size CASSOMAXS and up to six Data Storage cache space areas of size CDATAMAXS can be allocated for a particular type of cache space.

CRETRY Parameter: Adabas Caching Facility Retry Time

The CRETRY (or CR) parameter specifies the amount of time (in seconds) between attempts to acquire an area of cache space if the previous GETMAIN or space allocation failed.

graphics/cretry_syntax.png

Value Description
n The number of seconds between attempts to acquire an area of cache space if the previous GETMAIN or space allocation failed.

The minimum number of seconds is 60; the maximum is 2147483647.

The default number of seconds is 900 (15 minutes).

If an area of cache space cannot be allocated, ADACSH waits for the specified number of seconds before attempting to allocate the area of cache space again. During this period of time, caching continues in the other areas of the cache space already allocated, but the maximum allowed cache space is not available. If, after the time period has elapsed, there is a request to cache a RABN and no space is available in the current allocation, ADACSH attempts to allocate the area of cache space again. These attempts continue until the cache space is successfully allocated.

Note:
CRETRY does not apply to an area of cache space that was released due to a timeout (see CCTIMEOUT).

Example

ADARUN CRETRY=500

If an attempt to allocate an additional area of a cache space fails, another attempt to cache a RABN in the cache space in question is made after 500 seconds. If the currently allocated space is still full, the attempt is again made to allocate an additional area of cache space.

CSTORAGE Parameter: Adabas Caching Facility Override Cache Type

The CSTORAGE parameter can be used to indicate that all RABNs for the database are to be cached using the system defaults and the type of cache specified by this parameter.

The CSTORAGE (or CS) parameter overrides any CASSOxxx or CDATAxxx parameter that may be specified. If the CSTORAGE parameter is specified, all RABNs for the database are cached using the system defaults and the type of cache space specified by CSTORAGE.

Note:
This parameter is mutually exclusive with the CFILE and CXFILE parameters.

graphics/ccstor.png

Value Description
DATASPACE Data space
EXTENDED Extended memory
HIPERSPACE Hiperspace
G64 Virtual 64-bit storage backed by 2G large pages

Note:
If "G64" is specified, we recommend you specify a cache space size (CASSOMAXSCASSOMAXS/CDATAMAXSCDATAMAXS) that is a multiple of two gigabytes. The specified size will be rounded up to the nearest multiple of two gigabytes and any difference between the specified size and the allocated size will remain unused. Specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused.

L64 Virtual 64-bit storage backed by 1M large pages
VIRTUAL64 Virtual 64-bit storage

Extended memory is the only option available on BS2000 RISC machines. Hiperspace is an option only in z/OS environments. Virtual 64 storage is available only in z/OS environments.

Example

ADARUN CASSOHSP=1-1795
ADARUN CDATAHSP=81-135,1140-1298,136-170,181-230 
ADARUN CSTORAGE=EXTENDED

ADACSH caches all Associator and Data Storage RABNs in extended memory (above the 16 megabyte line). All CASSOHSP and CDATAHSP RABN ranges are ignored.

CWORKSTORAGE Parameter: Adabas Caching Facility Work Area Cache Type

The CWORKSTORAGE (or CWORKS) parameter specifies the type of cache space to use for the CWORK2FAC and/or CWORK3FAC areas.

graphics/ccwork.png

Value Description
DATASPACE Data space
EXTENDED Extended memory
HIPERSPACE Hiperspace
G64 Virtual 64-bit storage backed by 2G large pages

Note:
'If "G64" is specified, the sizes of the cache spaces for Work parts 2 and 3 will be rounded up to the nearest multiple of two gigabytes and any difference between the specified size and the allocated size will remain unused. To avoid leaving a large amount of cache storage unused, we recommend you use "G64" only if the sizes of the Work part 2 and Work part 3 cache spaces (as per the CWORK2FACCWORK2FAC and CWORK3FACCWORK3FAC parameters) will not be much smaller than a multiple of two gigabytes.

L64 Virtual 64-bit storage backed by 1M large pages
VIRTUAL64 Virtual 64-bit storage

Extended memory is the only option available on BS2000 RISC machines. Hiperspace is an option only in z/OS environments. Virtual 64 storage is available only in z/OS environments.

If CWORKSTORAGE is not specified, but the CWORK2FAC and/or CWORK3FAC parameters are specified, then the default CWORKSTORAGE is as follows:

Example

ADARUN CWORKSTORAGE=HIPERSPACE

For Work parts 2 and/or 3, cache space is allocated in hiperspace.

CWORK2FAC Parameter: Adabas Caching Facility Work Part 2 Percentage

The CWORK2FAC (or CWORK2) parameter specifies the percentage of Work part 2 to be cached.

Value Description
n The percentage of Work part 2 to be cached.

The minimum and the default is 0; the maximum is 100.

If CWORK2FAC=0 is specified, Work part 2 is not cached.

The number of Work part 2 RABNs to be cached is computed by multiplying the specified percentage factor by the number of RABNs allocated for Work part 2.

Each cache space allocation is based on the number of RABNs and the device block size, rounded up to the nearest 4-kilobyte boundary.

cache size = int ( ( ( #RABNs x blksize ) + 4095 ) x 4096 ) + 4096

- where

#RABNs = int ( WORK part 2 size x CWORK2FAC )

If the specified CWORK2FAC cannot accommodate the working set of Work part 2 RABNs, the RABNs beyond the computed CWORK2FAC are not cached. Normal I/O operations are performed for the non-cached Work part 2 RABNs.

For any percentage less than 100, the writes to Work are still done; however, RABNs read from Work will be obtained from the cache if the RABN is available.

Example

ADARUN CWORK2FAC=50

ADACSH caches 50 percent of Work part 2, beginning from the first block. If Work part 2 contains 1000 blocks, a cache space is allocated for 500 blocks. If the Work device type is a 3380, the cache space size required is

cache size = int ( ( ( #RABNs x blksize ) + 4095 ) ÷ 4096 ) x 4096 
               = int ( ( ( 500 x 5492 ) + 4095 ) ÷ 4096) x 4096 
               = 2,750,095

CWORK3FAC Parameter: Adabas Caching Facility Work Part 3 Percentage

The CWORK3FAC (or CWORK3) parameter specifies the percentage of Work part 3 to be cached.

Value Description
n The percentage of Work part 3 to be cached.

The minimum and the default is 0; the maximum is 100.

If CWORK3FAC=0 is specified, Work part 3 is not cached.

The number of Work part 3 RABNs to be cached is computed by multiplying the specified percentage factor by the number of RABNs allocated for Work part 3.

Each cache space allocation is based on the number of RABNs and the device block size, rounded up to the nearest 4-kilobyte boundary.

cache size = int ( ( ( #RABNs x blksize ) + 4095 ) ÷ 4096 ) x 4096

- where

#RABNs = int ( WORK part 3 size x CWORK3FAC )

If the specified CWORK3FAC cannot accommodate the working set of Work part 3 RABNs, the RABNs beyond the computed CWORK3FAC are not cached. Normal I/O operations are performed for the non-cached Work part 3 RABNs.

For any percentage less than 100, the writes to Work are still done; however, RABNs read from Work will be obtained from the cache if the RABN is available.

Example

ADARUN CWORK3FAC=50

ADACSH caches 50 percent of Work part 3, beginning from the first block of Work part 3. If Work part 3 contains 1000 blocks, a cache space is allocated for 500 blocks. If the Work device type is a 3380, the cache space size required is

cache size = int ( ( ( #RABNs x blksize ) + 4095 ) ÷ 4096 ) x 4096 
               = int ( ( ( 500  5492 ) + 4095 ) ÷ 4096 ) x 4096 
               = 2,750,095

CXFILE Parameter: Adabas Caching Facility Excluded Files

The CXFILE parameter is used to exclude files from caching.

Note:
CXFILE is mutually exclusive with CASSOxxx, CDATAxxx, and CSTORAGE parameters. If any of these parameters is used with CXFILE, they will be ignored.

graphics/ccxfile.png

Value Description
fnr The file to be excluded specified by file number. The minimum value is 0; the maximum is the actual number of files in the database. File number 0 may be specified to exclude RABNs that are not associated with any given file. Currently, this is only the DSST on the Associator data set.
fnr - fnr A range of files to be excluded specified by two file numbers (the lower number first) separated by a hyphen with no intervening spaces or special characters.
scope Specifies the scope of exclusion:
  • ASSO (or A): Only Associator RABNs are to be excluded

  • DATA (or D): Only Data Storage RABNs are to be excluded

  • BOTH (or B): Both Associator and Data Storage RABNs are to be excluded

If the scope term is specified, it must be preceded by two commas to maintain its position within the parentheses. See the CFILE parameter for more information about the positional terms used within the parentheses. The cls and cache terms are not used for the CXFILE parameter but the position of the scope term is nevertheless maintained.

Multiple CXFILE parameters may be specified.

CFILE and CXFILE parameters together are processed in order from left to right (or top to bottom if different ADARUN statements are used).

Examples

ADARUN CACHE=YES,CFILE=(13-19),CXFILE=(17)

Files 13 through 19 are cached using the standard defaults for class of service (3), scope (BOTH), and cache (DATASPACE) with the exception of file 17, which is not cached.

ADARUN CACHE=YES,CFILE=(13-19),CXFILE=(17),CXFILE=(16,,DATA)

Files 13 through 19 are cached using the standard defaults; however, file 17 is not cached and only the associated Associator RABNs are cached for file 16 since the Data Storage RABNs are excluded.

Top of page

ADACSH Session Parameter Examples

The following combinations of ADARUN session parameters can be used as guidelines for setting up Adabas Caching. The applicability of these examples depends on the operating system environment and available resources.

Example 1:

 ADARUN CACHE=YES 

When CACHE=YES is the only parameter specified, the ADACSH module is loaded, but no cache spaces are predefined and no caching occurs.

ADACSH defaults to a global caching mode that allows RABN ranges to be added dynamically using operator or Adabas Online System commands. In this situation, any attempt to start caching on a file level is rejected.

Caching of Work parts 2 and 3 cannot be dynamically defined and is unavailable for this Adabas session.

Example 2:

  ADARUN CACHE=YES,CSTORAGE=HIPERSPACE,CACTIVATE=YES
    

Adding the CSTORAGE parameter instructs ADACSH to define cache spaces to encompass all of the Associator and Data Storage RABNs. The Adabas general control block (GCB) is used as the basis for the Associator and Data Storage RABN ranges. Although this is the most generalized parameter setup, an important consideration is the number of Associator and Data Storage RABNs that are defined for the database.

Using the CASSOMAXS, CDATAMAXS, and CMAXSPS parameters minimizes the total space allocated for the actual cache spaces. However, ADACSH must allocate space for RABN indexes for the cache space and for RABN tables for each RABN range being cached. If the database has a large number of RABNs defined, or the total amount of cache space available is very large, the memory requirements may exceed estimates. Therefore, this setup is not recommended for very large databases.

If the CACTIVATE=YES parameter is not specified, the cache spaces must be activated using Adabas Online System (AOS) or operator console communication.

Example 3:

ADARUN CACHE=YES,CDEMAND=30,CCTIMEOUT=3600
ADARUN CASSOHSP=1-5000,CDATAHSP=1-8000

No caching occurs for approximately 30 minutes after the nucleus has been brought up. After 30 minutes, if the nucleus requires caching and the Adabas buffer efficiency level is below the CDEMAND level, the RABN ranges are activated.

Following this, the first time space is required to cache a RABN, the first area of cache space is allocated. Once activated, a RABN range remains in operation as long as there is activity against it. Likewise, any allocated area of cache space remains allocated as long as there is activity against it.

If a RABN range remains inactive for more than 3600 seconds, it is disabled and is only re-activated if the Adabas buffer efficiency level is below the CDEMAND level. Areas of cache space represented by Hiperspaces are released back to the system if an area of cache space remains inactive for more than 3600 seconds. Unlike the RABN ranges, these are re-allocated immediately when required.

Example 4:

ADARUN CACHE=YES,CACTIVATE=YES,CDEMAND=30 
ADARUN CCTIMEOUT=7200 ADARUN CASSODSP=1-5000,CDATADSP=1-8000

The CACTIVATE=YES parameter specifies that the two data space RABN ranges are to be available for activation as soon as the nucleus requires caching. The CDEMAND parameter is not discarded but is initially superseded by the CACTIVATE parameter.

If a RABN range is inactive for more than 7200 seconds, it is disabled. When caching is required by the nucleus for RABNs within those RABN ranges which have been disabled, this will only occur once the CDEMAND level is reached. As long as the Adabas buffer efficiency level remains greater than the CDEMAND level, no disabled RABN ranges will be activated.

When an area of cache space represented by a data space is inactive for more than 7200 seconds, the data space is released. If this area is required at a later stage in the processing, it is re-activated as required and does not require that the Adabas buffer efficiency level fall below the value specified by CDEMAND.

Example 5:

ADARUN CACHE=YES,CACTIVATE=YES,CDEMAND=0
ADARUN CCTIMEOUT=7200 
ADARUN CASSOEXT=1-5000,CDATAEXT=1-8000 
ADARUN CWORKSTORAGE=DATASPACE,CWORK2FAC=50
ADARUN CWORK3FAC=70 

The CACTIVATE=YES parameter specifies that the two extended storage RABN ranges are to be available for activation as soon as the nucleus requires caching. The CDEMAND=0 parameter means that the RABN ranges are not disabled due to time out criteria; however, when areas of the cache space represented by the block of extended storage are not referenced for 7200 seconds, the block of storage is freed. It can be re-activated immediately when it is required by the nucleus.

Also, the first 50 percent of Work part 2 is cached in a data space cache and the first 70 percent of Work part 3 is cached in a second data space cache.

Example 6:

ADARUN CACHE=YES,CACTIVATE=YES ADARUN CCTIMEOUT=3600
ADARUN CFILE=3 ADARUN CFILE=1,2,ASSO,HIPERSPACE
ADARUN CFILE=200,1,BOTH,EXTENDED

The CACTIVATE=YES parameter specifies that caching for the files specified by the CFILE parameters can be activated as soon as the nucleus requires caching. If no reference is made to a cache space for more than 3600 seconds, it is released. If activity on the system increases and the cache space is again required, it is allocated immediately.

The first time each of the files 1, 3, and 200 are referenced, ADACSH synchronizes the file's RABN range definitions based on the file layout. The first time a RABN block being cached for one of these files is purged from the Adabas buffer pool, cache space is allocated and the RABN is written there first.

File number 3 is cached based on the defaults; that is, both Associator and Data Storage RABNs for the file are cached in data space and up to 50% of the cache space available for Associator or Data Storage RABN caching in data space may be used.

File number 1 has caching active only for Associator RABN blocks, which are cached in hiperspace. Up to 75% of the cache space available for Associator RABN caching in Hiperspace may be used.

File number 200 has caching active for both Associator and Data Storage RABN blocks, which are cached in extended memory. Up to 100% of the cache space available for Associator or Data Storage RABN caching in extended memory may be used.

Example 7:

ADARUN CACHE=YES,CFILE=(1-5,2),CXFILE=(2),CFILE=(2,1,DATA,HIPERSPACE)

CFILE and CXFILE parameters are processed in order from left to right (or top to bottom if different ADARUN statements are used). Parameters or statements that specify file ranges are processed before those that specify specific files.

Files 1 through 5 are cached with class of service 2 (use up to 75% of available cache space) and defaults for the other terms within the parentheses (scope BOTH and cache DATASPACE). File 2 is excluded; then it is added again with class of service 1 (use up to 100% of available cache space), caching Data Storage RABNs only, and caching in hiperspace.

To illustrate the order dependence of the CXFILE and CFILE parameters:

Top of page