Version 8.2.3	SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

This document describes the operator commands available for Adabas Caching.

• Operator Command Overview

• Operator Command Summary Table

• Operator Command Syntax

• Identifying a RABN Range or File Range

• Command Descriptions

• CSTAT/CFSTAT Statistics Report

Operator Command Overview

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

• Add a new RABN range (CASSOxxx and CDATAxxx)

• Add a new file or file range (CFILE)

• Enable a RABN range (CENABLE) or file / file range (CFENABLE)

• Disable a RABN range (CDISABLE) or file / file range (CFDISABLE)

• Delete a RABN range (CDELETE) or file / file range (CFDELETE)

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

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

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

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

• Modify or display runtime options:

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

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

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

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

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

  • the minimum acceptable Adabas buffer efficiency level (CDEMAND)

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

Operator Command Summary Table

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

• G: global caching only

• F: file-level caching only

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

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

Operator Command Syntax

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

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

z/OS environment

F jobname,option

where:

VSE/ESA Environment

MSG fn
replid option

where:

BS2000 Environment

tttt INTR,option

where:

Identifying a RABN Range or File Range

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

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

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

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

Command Descriptions

The available ADACSH operator commands are described in this section.

• CASSODSP / CASSOEXT / CASSOHSP / CASSOL64 / CASSOV64

• CASSOMAXS

• CBUFNO

• CCTIMEOUT

• CCHANGE

• CDATADSP / CDATAEXT / CDATAHSP / CDATAL64 / CDATAV64

• CDATAMAXS

• CDELETE

• CDEMAND

• CDISABLE

• CDISPSTAT

• CENABLE

• CEXCLUDE

• CFDELETE

• CFDISABLE

• CFENABLE

• CFILE

• CFSTAT

• CINCLUDE

• CPARM

• CRETRY

• CSTAT

• CSUM

CASSODSP / CASSOEXT / CASSOHSP / CASSOL64 / CASSOV64

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

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

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

• CASSODSP: Data Space

• CASSOEXT: Extended Memory

• CASSOHSP: Hiperspace

• CASSOL64: Virtual 64 backed by large pages

• CASSOV64: Virtual 64

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

For more information, see section Caching Configuration.

CASSOMAXS

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

CBUFNO

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

For more information, see also the ADARUN parameter CBNUFNO.

CCTIMEOUT

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

The minimum value permitted is 60 seconds.

For more information, see the ADARUN parameter CCTIMEOUT.

CCHANGE

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

CDATADSP / CDATAEXT / CDATAHSP / CDATAL64 / CDATAV64

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

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

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

• CDATADSP: Data Space

• CDATAEXT: Extended Memory

• CDATAHSP: Hiperspace

• CDATAL64: Virtual 64 backed by large pages

• CDATAV64: Virtual 64

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

For more information, see section Caching Configuration.

CDATAMAXS

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

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

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

CDELETE

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

For Global Caching

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

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

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

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

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

For File-Level Caching

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

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

CDEMAND

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

For more information, see the CDEMAND ADARUN parameter.

CDISABLE

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

For Global Caching

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

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

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

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

For File-Level Caching

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

CDISPSTAT

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

CENABLE

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

For Global Caching

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

For File-Level Caching

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

CEXCLUDE

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

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

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

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

See also the related command CINCLUDE.

CFDELETE

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

This command is valid for file-level caching only.

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

CFDISABLE

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

This command is valid for file-level caching only.

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

CFENABLE

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

This command is valid for file-level caching only.

CFILE

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

Notes:

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

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

CFSTAT

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

This command is valid for file-level caching only.

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

A sample display of the report is shown below:

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

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

CINCLUDE

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

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

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

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

See also the related command CEXCLUDE.

CPARM

CPARM is one of the commands used to modify or display the ADACSH runtime options. It displays the current runtime options including the ADACSH start-up parameters.

CRETRY

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

The minimum time permitted is 60 seconds.

CSTAT

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

For Global Caching

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

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

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

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

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

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

For File-Level Caching

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

CSUM

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

A sample report is shown below:

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

The report is explained in the following table.

CSTAT/CFSTAT Statistics Report

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

• Line Number 2 (Status Line)

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

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

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

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

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

• Line Number 8 (Max Time / EXCP Time)

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

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

Line Number 2 (Status Line)

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

Example: ALLOCATED, LA=17:04:26

Line Number 3 (Cache Writes / Blocks in Cache)

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

Example: 253 CACHE WRITES + 47 BLKS IN CACHE

Line Number 4 (Read EXCPs / Data Space Size)

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

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

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

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

Example: 408 CACHE READS + 55 BLKS/DATA SPC

Line Number 6 (Total Reads / RABN Table Size)

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

Example: 455 TOTAL READS + 616 RABN TAB SIZE

Line Number 7 (Cache Efficiency / Cache Space Used)

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

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

Line Number 8 (Max Time / EXCP Time)

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

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

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

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

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

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

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

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

www.softwareag.com

Copyright © 2013 Software AG, Darmstadt, Germany.

SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT