Adabas Caching Parameters

This document describes the Adabas Caching configuration parameters.

Parameter Syntax
Parameter Overview
Parameter Descriptions
ADACSH Session Parameter Examples

Parameter Syntax

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

The format for specifying session parameters is: ADARUN { parameter=value } , ...
ADARUN must be entered in positions 1-6 of each ADARUN statement
At least one blank is required between ADARUN and the first parameter
No blanks are permitted within a parameter=value entry
Multiple parameter=value entries separated by a comma may be included in a statement. The last trailing comma is ignored.
A blank following a parameter=value entry indicates the end of the statement
All entries must end before position 73. A parameter=value entry that would extend beyond position 72 must be coded on a new statement.
An asterisk (*) in position 1 indicates a user comment line

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.

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 | CASSOHSP | CASSOG64 | CASSOL64 | CASSOV64} {CDATADSP | CDATAEXT | CDATAHSP | CDATAG64 | 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.

Parameter Descriptions

CACHE Parameter: Adabas Caching Facility Control
CACTIVATE Parameter: Adabas Caching Facility RABN Activation
CASSODSP / CASSOEXT / CASSOHSP / CASSOG64 / CASSOL64 / CASSOV64 Parameters: Adabas Caching Facility Associator RABN Cache Space Control
CASSOMAXS Parameter: Associator Cache Space Unit Size
CBUFNO Parameter: Number of Read-Ahead Buffers for Concurrent I/O Processing
CCTIMEOUT Parameter: Cache Space Area or RABN Inactivity Time
CDATADSP / CDATAEXT / CDATAHSP / CDATAG64 / CDATAL64 / CDATAV64 Parameter: Adabas Caching Facility Data Storage RABN Cache Space Control
CDATAMAXS Parameter: Data Storage Cache Space Unit Size
CDEMAND Parameter: Lowest Adabas Buffer Efficiency for Caching
CDISPSTAT Parameter: Adabas Caching Facility RABN Range Statistics Display Control
CEXCLUDE Parameter: Adabas Caching Facility Excluded Command Types
CFILE Parameter: Adabas Caching Facility File Range
CMAXCSPS Parameter: Adabas Caching Facility Storage Area Quantities
CRETRY Parameter: Adabas Caching Facility Retry Time
CSTORAGE Parameter: Adabas Caching Facility Override Cache Type
CWORKSTORAGE Parameter: Adabas Caching Facility Work Area Cache Type
CWORK2FAC Parameter: Adabas Caching Facility Work Part 2 Percentage
CWORK3FAC Parameter: Adabas Caching Facility Work Part 3 Percentage
CXFILE Parameter: Adabas Caching Facility Excluded Files

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.

CASSODSP (or CASSOD) caches the Associator RABNs in data space.
CASSOEXT (or CASSOE) caches the Associator RABNs in extended memory.
CASSOHSP (or CASSOH) caches the Associator RABNs in hiperspace.
CASSOG64 (or CASSOL) caches the Associator RABNs in virtual 64-bit storage backed by 2G large pages.

Note:
If "G64" is specified, we recommend you specify a cache space size (CASSOMAXS) 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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.
CASSOL64 (or CASSOL) caches the Associator RABNs in virtual 64-bit storage backed by 1M large pages.
CASSOV64 (or CASSOV) caches the Associator RABNs in virtual 64-bit storage.

Note:
Virtual 64-bit storage is only available in z/OS and z/VSE 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 CASSO`xxx` 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:

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

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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.

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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.

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

extended memory, additional storage is requested in this area;
data space, an additional data space is allocated;
hiperspace, an additional hiperspace is built; and
virtual 64 memory backed by large pages, an additional memory object is allocated; and
virtual 64 memory, an additional memory object is allocated.

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

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.

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 2147483647. The default number of seconds is 7200 (2 hours).

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

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.

CDATADSP (or CDATAD) caches the Data Storage RABNs in data space.
CDATAEXT (or CDATAE) caches the Data Storage RABNs in extended memory.
CDATAHSP (or CDATAH) caches the Data Storage RABNs in hiperspace.
CDATAG64 (or CDATAL) caches the Data Storage RABNs in virtual 64-bit storage backed by 2G large pages.

Note:
If "G64" is specified, we recommend you specify a cache space size (CDATAMAXS) 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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.
CDATAL64 (or CDATAL) caches the Data Storage RABNs in virtual 64-bit storage backed by 1M large pages.
CDATAV64 (or CDATAV) caches the Data Storage RABNs in virtual 64-bit storage.

Note:
Only extended memory is available for BS2000 RISC machines. Hiperspace is an option only in z/OS environments. Virtual 64-bit storage is available only in z/OS and z/VSE 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 CDATA`xxx` 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:

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.
The CSTORAGE parameter overrides any CDATAxxx parameter and ADACSH will cache all Data Storage RABNs as defined for the database.

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

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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.

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.

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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.

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.

extended memory, additional storage is requested in this area;
data space, an additional data space is allocated;
hiperspace, an additional hiperspace is built; and
virtual 64 memory backed by large pages, an additional memory object is allocated; and
virtual 64 memory, an additional memory object is allocated.

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 2147483647 is permitted.

Value

Description

If CDEMAND=0 (the default), no demand-level caching occurs.

Demand-level caching is to be activated whenever the Adabas buffer efficiency drops below the value specified.

An integer value between 1 and 2147483647 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.

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: Option "VIRTUAL64" is only available in z/OS and z/VSE environments; options "G64" and "L64" are available only in z/OS environments. Specify "VIRTUAL64" to request that cache storage be virtual storage above the 2G bar; 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. If "G64" is specified, we recommend you specify a cache space size (CASSOMAXS/CDATAMAXS) 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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.

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.

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 (CASSOMAXS/CDATAMAXS) 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. In this case, specifying a multiple of two gigabytes avoids leaving a potentially large amount of storage unused. If "G64" is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.
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-bit storage ("VIRTUAL64") is available in z/OS and z/VSE environments only. Large page support ("G64" and "L64" options) is available in z/OS environments only.

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 CWORK2FAC and CWORK3FAC parameters) will not be much smaller than a multiple of two gigabytes. If “G64” is specified and 2G large pages are not available for allocation, the specified size will be rounded up to the nearest multiple of one megabyte, and the storage will not be backed by large pages. A console message will report on this case.
L64	Virtual 64-bit storage backed by 1M large pages
VIRTUAL64	Virtual 64-bit storage

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

DATASPACE for BS2000 (except RISC machines), z/OS, z/VSE
EXTENDED for BS2000 RISC machines

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.

The 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 2 size x CWORK2FAC ) +50) ÷ 100)

The RABN index table is allocated to obtain space for #RABN blocks.

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,748,416

The RABN index table is allocated to obtain space for 500 blocks.

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.

The 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 ) + 50 ) ÷ 100)

The RABN index table is allocated to obtain space for all blocks of WORK part 3.

If the cache space, specified by CWORK3FAC cannot accommodate the working set of Work part 3 RABNs, an aging process similar to ASSO/DATA RABNs is etablished. In case of a "short on storage" situation, the oldest RABN, i.e. the RABN in cache space which was the longest time not accessed, will be reused.

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. 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,748,416

The RABN index table is allocated to obtain space for 1000 blocks.

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.

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.

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 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:

If the CXFILE parameter is omitted in the above example, the result is the same.
If the CXFILE parameter and the second CFILE parameter are reversed, file 2 is not cached.