ADARUN Parameter Directory

This document describes all of the ADARUN parameters available for Adabas.

CFILE=({fnr | fnr1-fnrx}[,class][,scope][,cachetype])

nnn[K | M | G]

CXFILE=({fnr | fnr1-fnrx}[,,scope])

HEXnn=user-routine-name

AOSLOG Parameter: Log Active Nucleus Update Commands

Example

In the following example, Adabas calls that modify the nucleus are logged.

ADARUN PROG=ADANUC,AOSLOG=YES

AREXCLUDE Parameter: Exclude Files from Autorestart Processing

The AREXCLUDE parameter is intended for use only when autorestart processing fails (abends) due to response codes on one or more Adabas files. In this case, excluding the problem file(s) from autorestart might allow for successful autorestart processing on the other files.

Excluded files are marked as "utility use only". Software AG recommends that you restore excluded files from the latest save tapes and regenerate them.

Multiple file numbers can be specified on the same parameter if separated by commas.

Example

The following example excludes files 199 and 231 from autorestart processing.

ADARUN PROG=ADANUC,AREXCLUDE=199,231

ARMNAME Parameter: Activate Automatic Restart Management (ARM) Program

Automatic restart management (ARM) is used to automatically restart a nucleus when it abends. It is suppressed when the abend is intentional; for example, when it results from a parameter error.

ARM can be used in both cluster and noncluster nucleus environments.

ARM programs ('elements') are defined by the system programmer in the ARM 'policy'. They specify when, where, and how often a restart is to be attempted.

The ARMNAME parameter has no effect if an ARM policy has not been defined.

The name can be 1-16 characters long. In a cluster environment, the name must be unique across the cluster. Uppercase alphabetic characters, the numbers 0-9, and the special characters $, @, and #, and the underscore (_) may be used. The first character may not be numeric. Names that start with A through I and with SYS are reserved for use by IBM.

Example

The following example activates the automatic restart management program RESTART002.

ADARUN PROG=ADANUC,ARMNAME=RESTART002

ARNWORKBUFFERS Parameter: Autorestart WORK I/O Buffer Controls

When multiple WORK I/O buffers are allocated and used during autorestart processing, multiple WORK blocks may be read in each I/O. The use of multiple WORK buffers during autorestart processing may reduce the elapsed time needed to complete autorestart processing.

The buffers are allocated prior to the start of the backward repair phase of autorestart processing and deallocated at the end of autorestart processing.

If ARNWORKBUFFERS is set to zero or one, one WORK block will be read in each WORK read I/O during autorestart processing. The highest number of WORK I/O buffers allocated will be the number of WORK buffers in two cylinders.

In a noncluster nucleus, one set of buffers is allocated. In a cluster nucleus, one set of buffers is allocated for each cluster nucleus active at the time of the preceding failure. For example, if five cluster nuclei are active at the time all nuclei fail, five sets of WORK buffers are allocated.

When the ADARUN parameter V64BIT is set to YES, the autorestart WORK I/O buffers are allocated in virtual storage above the two gigabyte bar. When V64BIT=NO, the autorestart WORK I/O buffers are allocated in virtual storage above the 16 megabyte line and below the two gigabyte bar.

The default value for ARNWORKBUFFERS depends on the setting of the ADARUN V64BIT parameter.

• If V64BIT=NO, the default value for ARNWORKBUFFERS is one track worth of buffers. For example, on a 3390 device, nine WORK blocks fit in one track; in this example, the default value is "9".

• If V64BIT=YES, the default value for ARNWORKBUFFERS is two cylinders worth of buffers. For example, on a 3390 device, nine WORK blocks fit in one track and there are 15 tracks per cylinder. In this example, the default value is "270" (in other words, 9*15*2).

ASSOCACHE Parameter: Associator Controller Caching

This parameter applies to the z/OS operating system only.

Notes:

1. If ASSO blocks are highly scattered or the update frequency is low, controller caching can cause longer I/O response times.
2. ADARUN caching control parameters also exist for Data Storage (DATACACHE), the work area (WORKCACHE), the sort area (SORTCACHE), and the temp area (TEMPCACHE).

Example

The following example runs the nucleus without controller caching for the ASSO data set.

ADARUN PROG=ADANUC,ASSOCACHE=NO

ASSOSPACEWARN Parameter: Associator Space Notifications

The syntax of the ASSOSPACEWARN ADARUN parameter is:

The following specifications can be made in the ASSOSPACEWARN parameter:

Up to three threshold-increment pairs can be specified.

Example

In the following ADARUN parameter example, a space usage message is printed to the console when the percentage of ASSO space used is greater than or equal to 50%, 60%, 70%, 80%, 90% and 100% of the total ASSO space available. When ASSO space use increases from under 50% to 55%, a space usage message is printed specifying the used percentage of 55%. If the ASSO space use then decreases to less than 50% (for example, to a value of 38%), a space usage message is printed indicating that the ASSO space usage is now 38%.

ADARUN PROG=ADANUC,ASSOSPACEWARN=50,10

ASYTVS Parameter: Asynchronous Buffer Flush

Specific Product Recommendations

Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server, causing replication data to be written and read from the SLOG file.

Example

The following example disables the asynchronous buffer flush based on volume.

ADARUN PROG=ADANUC,ASYTVS=NO

AUDITLOG Parameter: Audit of AOS and Utility Functions

This ADARUN parameter allows you to activate writing auditing data for utility and AOS functions. The option of CONSOLE activates the AUDITLOG feature and utility and AOS functions will result in an AAUD01 message logged on the console identifying the function and the user that initiated the call. Specifying "NO" or having no setting at all as the default will result in the AUDITLOG remaining inactive.

Example

In the following example, AUDITLOG is activated and Audit data (AAUD01 messages) pertaining to the utility and AOS functions will be written to the console.

ADARUN AUDITLOG=CONSOLE

AUTOCQENV Parameter: Environment Affected by Command Return from the Command Queue

The AUTOCQENV parameter and its supplement, AUTOCQTIME, have an effect only in cluster databases (i.e., Adabas Cluster Services or Adabas Parallel Services). After the failure of a nucleus in the cluster, while online recovery is in progress, surviving Adabas cluster nuclei stop selecting user commands from the command queue. During this time, new commands issued by users accumulate in the command queue and wait to be processed. The AUTOCQENV and AUTOCQTIME parameters can be used to prevent overly long delays for many commands.

When set to ALL, unprocessed commands from all users in the command queue are reviewed during online recovery to determine if they meet the criteria specified by the AUTOCQTIME parameter. When set to CICS, only unprocessed commands from CICS sessions are reviewed.

When a command in the command queue is returned to the user, no related information is written to the CLOG data set.

The setting of this parameter is local and fixed. It applies only to the Adabas nucleus for which it is set and it retains its value for the entire nucleus session.

Example

The following example will review unprocessed commands from CICS sessions. If the reviewed commands meet the criteria specified by the AUTOCQTIME parameter, the commands are returned to the user with response code 22 (ADARSP022), subcode 55.

ADARUN PROG=ADANUC,AUTOCQENV=CICS

AUTOCQTIME Parameter: Wait Time Threshold for Commands in Command Queue during Online Recovery

The AUTOCQTIME parameter and its supplement, AUTOCQENV, have an effect only in cluster databases (i.e., Adabas Cluster Services or Adabas Parallel Services). After the failure of a nucleus in the cluster, while online recovery is in progress, surviving Adabas cluster nuclei stop selecting user commands from the command queue. During this time, new commands issued by users accumulate in the command queue and wait to be processed. The AUTOCQTIME and AUTOCQENV parameters can be used to prevent overly long delays for many commands.

When this parameter is set to 0 (zero), command time spans are not reviewed and commands remain in the command queue until they are processed.

When this parameter is set to a positive value, Adabas will, during online recovery, regularly review the command queue for unprocessed commands that have been waiting for the specified number of seconds or longer and meet the AUTOCQENV parameter criteria. Eligible unprocessed commands will be automatically returned with response code 22 (ADARSP022), subcode 55

When a command in the command queue is returned to the user, no related information is written to the CLOG data set.

The setting of this parameter is local and fixed. It applies only to the Adabas nucleus for which it is set and it retains its value for the entire nucleus session.

Example

The following example will return unprocessed commands in the command queue to the issuing user with response code 22, subcode 55 after the commands have been in the command queue for at least 60 seconds during an online recovery process following the failure of a cluster nucleus.

ADARUN PROG=ADANUC,AUTOCQTIME=60

AUTOINCASSOSIZE Parameter: Associator Automatic Database Increase Size

This parameter only has an effect if the AUTOINCASSOTHRESHOLD has a non-zero value. A numeric value followed by the letter B indicates the value specifies a number of blocks, which is then rounded up to the next highest amount that fills the final track or other platform-dependent minimum space allocation unit. A numeric value without the suffix B indicates the increment is in cylinders.

If an automatic database increase process is started to increase the ASSO component of the database, the last ASSO container data set will be increased by the number of cylinders or blocks specified by AUTOINCASSOSIZE. (The number of cylinders or blocks added may be less, however, if the limit set by the AUTOINCASSOTOTAL parameter is reached.)

If the last ASSO container data set cannot be increased by the specified size, but only by a lesser amount, the automatic increase process will increase the data set by the amount of space that it can get. Note that one data set can span at most 59 volumes with up to 16 extents on each volume. When these limits are reached, the database should be increased manually by adding a new container data set with the ADADBS ONLADD utility function.

When 4-byte RABNs are used, valid values for this parameter range from from zero (0) to 2147483647 blocks or the equivalent in cylinders. When 3-byte RABNs are used, the limits range from zero (0) to 16777215 blocks or the equivalent in cylinders. A value of "0" or "0B" means that no automatic increase will be performed for ASSO space. The default value for this parameter is zero, which functionally disables auto-increase for ASSO space.

If AUTOINCASSOSIZE is set to a small value, the automatic database increase process may be initiated multiple times and cause the container allocation to reach platform-dependent limits on extents and volumes. Once that occurs, there can be no more auto-increases until the container allocations are consolidated, which requires stopping all nuclei using the container. Alternatively, a manual increase can be used to add another container without stopping the Adabas nucleus.

This parameter can be changed at runtime via operator command or corresponding AOS and ADADBS functions. In a cluster, this is a global parameter; its setting is the same for all nuclei in the cluster.

Example

In the following example, the highest-numbered ASSO data set (the last) will be increased in size by 500000 blocks when the AUTOINCASSOTHRESHOLD is reached.

ADARUN PROG=ADANUC,AUTOINCASSOSIZE=500000B 

AUTOINCASSOTHRESHOLD Parameter: Associator Space Threshold

If the used Associator space matches or exceeds the percentage defined by the specified AUTOINCASSOTHRESHOLD setting, Adabas automatically initiates a database increase process for ASSO space.

Note that the database increase process may take some time, the length of which is related to the size by which the database is increased (the value of the AUTOINCASSOSIZE setting). The AUTOINCASSOTHRESHOLD setting should be configured so that the increase process is given sufficient time to complete before the database fills up, assuming a reasonable space consumption rate.

Once a database increase process has been initiated, another automatic increase for ASSO space may be started only after the first process has finished and the ASSO space usage again (or still) matches or exceeds the specified threshold.

Valid values for this parameter are either zero (0) or integers ranging from 50 through 100. A value of zero means that no automatic increase will be performed for ASSO space. A value of 100 means that an automatic increase process will be initiated only when the ASSO space grows full (i.e., no free space is left at all). The default value for this parameter is zero, which functionally disables auto-increase processes for ASSO space.

This parameter can be changed at runtime via operator command or corresponding AOS and ADADBS functions. In a cluster, this is a global parameter; its setting is the same for all nuclei in the cluster.

Example

In the following example, a database increase process for ASSO space will be initiated when the used ASSO space matches or exceeds 70% of the total ASSO space defined.

ADARUN PROG=ADANUC,AUTOINCASSOTHRESHOLD=70

AUTOINCASSOTOTAL Parameter: Associator Space Maximum Size

This parameter specifies the total maximum size, in cylinders or blocks, of the entire Associator space of the database. A numeric value followed by the letter B indicates the value specifies a number of blocks, which is then rounded up to the next highest amount that fills the final track or other platform-dependent minimum space allocation unit. A numeric value without a suffix B indicates the increment is in cylinders.

An automatic database increase process for ASSO space will not exceed the size specified by the AUTOINCASSOTOTAL parameter. This parameter can be used to limit the total amount of disk space used for the database, in order to protect the disk space remaining available for other databases and other users of the system. Note that this parameter limits only automatic increases by Adabas; it does not limit increasing the database manually using the ADADBS ADD, INCREASE, ONLADD or ONLINCREASE utility functions.

AUTOINCASSOTOTAL specifies the number of cylinders or blocks beyond which automatic database increase processes will not extend the ASSO space of the database. If AUTOINCASSOTOTAL is less than the current ASSO size plus AUTOINCASSOSIZE, an automatic increase will increase the ASSO space only by the difference between AUTOINCASSOTOTAL and the current size – that is, by less than the increase requested by the AUTOINCASSOSIZE parameter. If AUTOINCASSOTOTAL is not greater than the current ASSO size, no further automatic increases will be performed for ASSO space.

When 4-byte RABNs are used, valid values for this parameter range from from zero (0) to 2147483647 blocks or the equivalent in cylinders. When 3-byte RABNs are used, the limits range from zero (0) to 16777215 blocks or the equivalent in cylinders. A value of "0" or "0B" means that no automatic increase will be performed for ASSO space. The default value for this parameter is zero, which functionally disables auto-increase for ASSO space.

The total size of ASSO space may be constrained to less than the AUTOINCASSOTOTAL value for either of the following reasons.

• There may not be enough storage resources to extend to the specified limit.

• When using 4-byte RABNs, a component can have at most 2147483647 blocks, and for 3-byte RABNs the limit is 16777215 blocks.

This parameter can be changed at runtime via operator command or corresponding AOS and ADADBS functions. In a cluster, this is a global parameter; its setting is the same for all nuclei in the cluster.

Example

In the following example, the total ASSO space for a database is set to 16777215 blocks.

ADARUN PROG=ADANUC,AUTOINCASSOTOTAL=16777215B

AUTOINCDATASIZE Parameter: Data Storage Automatic Database Increase Size

This parameter only has an effect if the AUTOINCDATATHRESHOLD has a non-zero value. A numeric value followed by the letter B indicates the value specifies a number of blocks, which is then rounded up to the next highest amount that fills the final track or other platform-dependent minimum space allocation unit. A numeric value without the suffix B indicates the increment is in cylinders.

If an automatic database increase process is started to increase the DATA component of the database, the last DATA container data set will be increased by the number of cylinders or blocks specified by AUTOINCDATASIZE. (The number of cylinders or blocks added may be less, however, if the limit set by the AUTOINCDATATOTAL parameter is reached.)

If the last DATA container data set cannot be increased by the specified size, but only by a lesser amount, the automatic increase process will increase the data set by the amount of space that it can get. Note that one data set can span at most 59 volumes with up to 16 extents on each volume. When these limits are reached, the database should be increased manually by adding a new container data set with the ADADBS ONLADD utility function.

Even though the increase is for the DATA component, a response 77 is still possible for ASSO if the increase requires an ASSO extent to be taken and no ASSO space is available. Therefore, it is suggested to make sure ASSO storage is available as well.

When 4-byte RABNs are used, valid values for this parameter range from from zero (0) to 2147483647 blocks or the equivalent in cylinders. When 3-byte RABNs are used, the limits range from zero (0) to 16777215 blocks or the equivalent in cylinders. A value of "0" or "0B" means that no automatic increase will be performed for DATA space. The default value for this parameter is zero, which functionally disables auto-increase for DATA space.

If AUTOINCDATASIZE is set to a small value, the automatic database increase process may be initiated multiple times and cause the container allocation to reach platform-dependent limits on extents and volumes. Once that occurs, there can be no more auto-increases until the container allocations are consolidated, which requires stopping all nuclei using the container. Alternatively, a manual increase can be used to add another container without stopping the Adabas nucleus.

This parameter can be changed at runtime via operator command or corresponding AOS and ADADBS functions. In a cluster, this is a global parameter; its setting is the same for all nuclei in the cluster.

Example

In the following example, the highest-numbered Data Storage data set (the last) will be increased in size by 5000 cylinders when the AUTOINCDATATHRESHOLD is reached.

ADARUN PROG=ADANUC,AUTOINCDATASIZE=5000

AUTOINCDATATHRESHOLD Parameter: Data Storage Space Threshold

If the used Data Storage space matches or exceeds the percentage defined by the specified AUTOINCDATATHRESHOLD setting, Adabas automatically initiates a database increase process for DATA space.

Note that the database increase process may take some time, the length of which is related to the size by which the database is increased (the value of the AUTOINCDATASIZE setting). The AUTOINCDATATHRESHOLD setting should be configured so that the increase process is given sufficient time to complete before the database fills up, assuming a reasonable space consumption rate.

Once a database increase process has been initiated, another automatic increase for DATA space may be started only after the first process has finished and the DATA space usage again (or still) matches or exceeds the specified threshold.

Valid values for this parameter are either zero (0) or integers ranging from 50 through 100. A value of zero means that no automatic increase will be performed for DATA space. A value of 100 means that an automatic increase process will be initiated only when the DATA space grows full (i.e., no free space is left at all). The default value for this parameter is zero, which functionally disables auto-increase processes for DATA space.

This parameter can be changed at runtime via operator command or corresponding AOS and ADADBS functions. In a cluster, this is a global parameter; its setting is the same for all nuclei in the cluster.

Example

In the following example, a database increase process for DATA space will be initiated when the used DATA space matches or exceeds 75% of the total DATA space defined.

ADARUN PROG=ADANUC,AUTOINCDATATHRESHOLD=75

AUTOINCDATATOTAL Parameter: Data Storage Space Maximum Size

This parameter specifies the total maximum size, in cylinders or blocks, of the entire Data Storage space of the database. A numeric value followed by the letter B indicates the value specifies a number of blocks, which is then rounded up to the next highest amount that fills the final track or other platform-dependent minimum space allocation unit. A numeric value without a suffix B indicates the increment is in cylinders.

An automatic database increase process for DATA space will not exceed the size specified by the AUTOINCDATATOTAL parameter. This parameter can be used to limit the total amount of disk space used for the database, in order to protect the disk space remaining available for other databases and other users of the system. Note that this parameter limits only automatic increases by Adabas; it does not limit increasing the database manually using the ADADBS ADD, INCREASE, ONLADD or ONLINCREASE utility functions.

AUTOINCDATATOTAL specifies the number of cylinders or blocks beyond which automatic database increase processes will not extend the DATA space of the database. If AUTOINCDATATOTAL is less than the current DATA size plus AUTOINCDATASIZE, an automatic increase will increase the DATA space only by the difference between AUTOINCDATATOTAL and the current size – that is, by less than the increase requested by the AUTOINCDATASIZE parameter. If AUTOINCDATATOTAL is not greater than the current DATA size, no further automatic increases will be performed for DATA space.

When 4-byte RABNs are used, valid values for this parameter range from from zero (0) to 2147483647 blocks or the equivalent in cylinders. When 3-byte RABNs are used, the limits range from zero (0) to 16777215 blocks or the equivalent in cylinders. A value of "0" or "0B" means that no automatic increase will be performed for DATA space. The default value for this parameter is zero, which functionally disables auto-increase for DATA space.

The total size of DATA space may be constrained to less than the AUTOINCDATATOTAL value for either of the following reasons.

• There may not be enough storage resources to extend to the specified limit.

• When using 4-byte RABNs, a component can have at most 2147483647 blocks, and for 3-byte RABNs the limit is 16777215 blocks.

This parameter can be changed at runtime via operator command or corresponding AOS and ADADBS functions. In a cluster, this is a global parameter; its setting is the same for all nuclei in the cluster.

Example

In the following example, the total DATA space for a database is set to 100000 cylinders.

ADARUN PROG=ADANUC,AUTOINCDATATOTAL=100000

CACHE Parameter: Adabas Caching Facility Control

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

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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

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

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.

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.

CDXnn Parameter: Collation Descriptor User Exit

Used in conjunction with the universal encoding subsystem (UES), the format of the collation descriptor user exit parameter is

CDXnn=exit-name

where

Only one program may be specified for each collation descriptor exit. Up to 8 collation descriptor exits may be specified (in any order). See the Adabas User, Hyperdescriptor, Collation Descriptor, and SMF Exits Manual for more information.

Example

The following example runs the Adabas nucleus using collation descriptor exits 1 and 2. It also gives control to the user routine UCOLDE1 at collation descriptor exit 1 and gives control to the user routine UCOLDE2 at collation descriptor exit 2.

ADARUN PROG=ADANUC,CDX01=UCOLDE1,CDX02=UCOLDE2

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.

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

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.

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.

CLOGBMAX Parameter: Logged Buffer Size Limit

If a buffer is longer than this value, the logged buffer is truncated from the point at which its size exceeds the setting of the CLOGBMAX parameter. The CLOGBMAX setting affects the ADARUN LOGGING parameter specifications for CLOGLAYOUT=8. The minimum value (368) is the size of the length of the CLOGLAYOUT=8 basic record plus the length of the extended Adabas control block (ACBX).

Example

The following example runs the Adabas nucleus using a logged buffer size limit of 512. Individual logged buffers for an Adabas command cannot exceed 512 bytes.

ADARUN PROG=ADANUC,CLOGB=512

CLOGDEV Parameter: Multiple Command Log Device Type
CLOGSIZE : Multiple Command Log Size

The CLOGDEV and CLOGSIZE parameters specify the type of external storage device used for multiple command logs and the number of blocks available for each command log data set. These parameters must be used together; if you specify one parameter, you must also specify the other parameter.

You must also specify the NCLOG parameter to use multiple command logs. If you specify a user exit, it must be UEX12.

The section Adabas Device Types and Blocks Sizes in the Adabas Installation documentation specifies the device types that Adabas supports.

All command logging data sets must be formatted using the ADAFRM utility before they are used.

The maximum size of the data set depends on the limits of the operating system and on the requirements of the user.

Example

The following example runs the Adabas nucleus with command logging. It uses six command log data sets and a model 3380 device for command logging. The size of each command log data set is 1350 blocks, based on an allocation of 10 cylinders. (Each cylinder of a 3380 device has 15 tracks, and each track can contain 9 blocks of command log data. Thus, 10 cylinders = 10 x 15 x 9 = 1350 blocks).

ADARUN PROG=ADANUC,LOGGING=YES,NCLOG=6,CLOGDEV=3380,CLOGSIZE=1350

CLOGLAYOUT Parameter: Command Logging Format

This parameter specifies the format of the Adabas command log. User programs designed for Adabas 8 or later should specify CLOGLAYOUT=8.

Use the command log format from Adabas 8. Both ACB and ACBX control blocks are converted to a common format. This format includes the corresponding Adabas buffer descriptions (ABDs) as well. Each segmented buffer (format, record, or multifetch) is written separately and uniquely identified.

The format of CLOGLAYOUT=8 records is described in the LORECX DSECT distributed with Adabas 8.

Example

The following example uses the Adabas 8 format of the command log.

ADARUN PROG=ADANUC,CLOGLAYOUT=8

CLOGMAX Parameter: Total Logged Buffer Size Limit for a Command

When the sum of sizes of the logged buffers for an Adabas command reaches the value of the CLOGMAX parameter, the buffer exceeding the limit is truncated and all following buffers are omitted. The size of CLOGMAX must at least be as large as the ADARUN CLOGBMAX parameter setting in order to accommodate the largest buffer of the Adabas command. The minimum value (368) is the size of the length of the CLOGLAYOUT=8 basic record plus the length of the extended Adabas control block (ACBX).

The CLOGMAX setting affects the ADARUN LOGGING parameter specifications for the ADARUN CLOGLAYOUT=8 parameter setting.

Example

The following example runs the Adabas nucleus using a command logged buffer size limit of 32K. The sum of all logged buffers for an Adabas command to this nucleus cannot exceed 32K.

ADARUN PROG=ADANUC,CLOGMAX=32768

CLOGMRG Parameter: Cluster Command Log Merge

An automatic CLOG merge process provides a single cluster-wide command log containing, in chronological order, all Adabas commands executed by any of the cluster nuclei in the time period covered by the log.

CLOGMRG specifies whether the Adabas cluster is to run with the automatic CLOG merge:

CLOGMRG is a global (that is, a cluster-wide) parameter, which means that the setting of this parameter in the first cluster nucleus to become active is propagated to all nuclei that subsequently become active.

Parameter Dependencies

It is possible to specify both LOGGING=NO and CLOGMRG=YES. In a cluster environment, it is also possible that a CLOG will be written to even if LOGGING=NO. As long as CLOGMRG=NO, nothing will be written to the CLOG if LOGGING=NO. However, if LOGGING=NO and CLOGMRG=YES, control records necessary for ADARES CLCOPY will be written to the CLOG.

CLOGMRG is effective only in an Adabas cluster environment; that is, when CLUSTER is specified with a value other than NO and NUCID is specified with a nonzero value.

Dynamic Modification

The setting of the CLOGMRG parameter can be changed dynamically using the CLOGMRG command from the operator console, the ADADBS OPERCOM CLOGMRG function, or the Modify Parameter function of Adabas Online System.

Because CLOGMRG is a global parameter, the change request to one nucleus is automatically propagated to all nuclei in the cluster.

CLUCACHEEXTRA Parameter: Adjust Shared Cache Vector Size

This parameter is local and unchangeable. It has effect only if both a cluster product (Adabas Cluster Services or Adabas Parallel Services) and Adabas Caching Facility are active.

If Adabas Cluster Services or Adabas Parallel Services are running on the same system as the Adabas Caching Facility, use the CLUCACHEEXTRA parameter to adjust the vector size of the shared cache. This ensures that Adabas Cluster Services and Adabas Parallel Services can track all of the blocks held privately by the Adabas Caching Facility.

Set the value to the maximum number of blocks expected to be cached by the Adabas Caching Facility. This number can be derived from the CASSOMAXS, CDATAMAXS, and CMAXCSPS parameter settings of the Adabas Caching Facility and the ASSO and DATA block sizes of the database.

CLUCACHENAME Parameter: Cluster Cache Structure/Area Name

For Adabas Cluster Services, the CLUCACHENAME identifies the particular sysplex cache structure (defined in the CFRM policy) associated with a particular Adabas sysplex nucleus cluster. The same name must be set in each nucleus in the cluster. CLUCACHENAME must be unique for each cluster; that is, each database.

Adabas Parallel Services automatically creates a default name for each global cache area allocated by ADACOM. However, if you wish to control the name of the global cache area, you can set this parameter.

For Adabas Parallel Services, the CLUCACHENAME identifies a particular global cache area associated with all cluster nuclei that have the same SVC/DBID set as the current nucleus. The same name must be set in each cluster nucleus that has the same SVC/DBID set. CLUCACHENAME must be unique for each SVC/DBID set.

In all cases, the name can be 1-16 characters long. Valid characters are numeric, uppercase alphabetic, the special characters $, @, and #. The name must begin with an alphabetic character (A-Z). IBM names begin with SYS, UNDESIG, or the characters A through I (these characters are not reserved).

Example

In the following example, the sysplex cache structure name is defined as "SAG1SMP#CACHE1".

ADARUN PROG=ADANUC, CLUCACHENAME=SAG1SMP#CACHE1

CLUCACHESIZE Parameter: Size of the Global Cache Area

The CLUCACHESIZE parameter specifies the amount of storage to be allocated for the global cache area which all nuclei in the Adabas Parallel Services cluster use to share Associator and Data blocks from the database. It has an effect only if CLUSTER=LOCAL is also specified.

The location and maximum size of the global cache area depends on the CLUCACHETYPE parameter. If CLUCACHETYPE=DSP, the global cache is kept in a dataspace shared between the Adabas Parallel Services nuclei. Otherwise, the cache is kept in shared 64-bit virtual storage (z/OS systems only).

CLUCACHESIZE must be specified for Adabas Parallel Services nuclei; there is no default.

Each Adabas Parallel Services nucleus has its own buffer pool sized by the ADARUN parameter LBP. Optionally, it may also have one or more local cache spaces administered by the Adabas Caching Facility (refer to the description of the ADARUN parameter CACHE). In addition, Adabas Parallel Services uses a global cache area to ensure that current images of Associator and Data blocks from the database are available to all Adabas Parallel Services cluster nuclei.

The global cache area must be large enough to retain:

• directory elements for all blocks that reside in all buffer pools and the global cache itself; and

• enough data elements to keep changed blocks between buffer flushes (cast-outs).

The ADARUN parameters DIRRATIO and ELEMENTRATIO determine the ratio between the number of directory and data elements.

CLUCACHESIZE may be specified in bytes, in kilobytes followed by a "K", in megabytes followed by an "M", or in gigabytes followed by a "G":

• the minimum size is 131072 bytes (or 128K);

• for CLUCACHETYPE=DSP, the maximum size is 2147483147 bytes (or 2097152K; or 2048M; or 2G); and

• the maximum allowed numeral is 2147483147; for CLUCACHETYPE=V64, use the K, M or G suffix (for example, 10G or 10240M or 10485760K for a global cache of 10 gigabytes size).

The value is rounded up to the nearest four-kilobyte boundary. If CLUCACHETYPE=L64, the value is rounded up to the nearest one-megabyte boundary. If CLUCACHETYPE=G64, the value is rounded up to the nearest two-gigabyte boundary.

Appropriate sizes for the global cache area depend very much on the application load in the cluster. For more details about these calculations, read Global Cache Area Size in the Adabas Parallel Services Operations Guide. You can use the Adabas Online System cache structure size calculator described in Estimating Sizes for the Cache Structure in a Cluster Environment in the Adabas Parallel Services Operations Guide to determine appropriate global cache area sizes.

Example

In the following example, the global cache area allocated is 500 M.

ADARUN PROG=ADANUC,CLUCACHESIZE=500M

CLUCACHETYPE Parameter: Global Cache Area Storage Type Option

The CLUCACHETYPE parameter specifies the type of virtual storage to be used for the global cache of an Adabas Parallel Services cluster. It has an effect only if CLUSTER=LOCAL is also specified. Valid values are "DSP" (available on all supported operating systems), "V64" (available on z/OS and z/VSE systems), "G64" (available only on z/OS systems) and "L64" (available only on z/OS systems).

The size of the global cache is specified in the CLUCACHESIZE parameter.

Notes:

1. If one ADACOM job is used to hold the shared cache and lock spaces for multiple Adabas Parallel Services clusters, L64 and G4 cache spaces of different clusters are slightly less isolated from one another than DSP or V64 cache spaces, creating a marginally higher risk that a cache-related error in one cluster might induce an error in a different cluster. This very small risk can be avoided altogether by using different ADACOM jobs for different Adabas Parallel Services clusters that use L64 or G64 cache spaces, but this is not mandatory.
2. Virtual 64-bit storage backed by page-fixed 1M large pages can only be used on IBM z10 mainframes running z/OS Version 1.9 or above and for which IBM large page support has been enabled via IBM APAR OA20902. You must also allocate the size of the large page pool (use the LFAREA parameter in the IEASYSxx member of SYS1.PARMLIB). The LFAREA parameter allows you to specify the amount of real storage to be used for page-fixed 1M large pages; this parameter cannot be changed dynamically and, if it is not set, page frames will remain allocated at a size of 4K.
3. Virtual 64-bit storage backed by page-fixed 2G large pages can only be used on IBM zEC12 mainframes running z/OS version 2.1 or above or an earlier z/OS version for which 2G large page support has been enabled via IBM APAR. You must also allocate the size of the large page pool (use the LFAREA parameter in the IEASYSxx member of SYS1.PARMLIB). The LFAREA parameter is extended to allow you to specify the amount of real storage to be used for page-fixed 1M and 2G large pages; this parameter cannot be changed dynamically and, if it is not set, page frames will remain allocated at a size of 4K.

Example

In the following example, the global cache area will be allocated in shared 64-bit virtual storage:

ADARUN PROG=ADANUC,CLUCACHETYPE=V64

CLUCACHEUNCHANGED Parameter: Global Cache Unchanged Block Option

The CLUCACHEUNCHANGED parameter specifies whether an Adabas Parallel Services nucleus should write unchanged blocks to the global cache. It has an effect only if CLUSTER=LOCAL is also specified. Valid values are "YES" and "NO".

• The default value is "NO", which indicates that the nucleus will write only changed (updated) Associator and Data blocks from the database to the global cache.

• If "YES" is specified, the nucleus will write changed and unchanged Associator and Data blocks to the global cache.

Recommendation

If a lot of virtual storage can be made available for local and global caching by the Adabas Parallel Services cluster (where local caching is controlled by the ADARUN LBP parameter and possibly the Adabas Caching Facility add-on product), assigning the bulk of the available storage to the global cache (ADARUN CLUCACHESIZE parameter), which is shared by all Adabas Parallel Services nuclei for the database, provides for more economic use of the storage than assigning it to the local caches of the individual cluster nuclei (ADARUN LBP parameter and the Adabas Caching Facility ADARUN CASSOMAXS and CDATAMAXS parameters), which are private to each nucleus. However, each cluster nucleus requires sufficient local buffer pool space (LBP parameter) to hold the entire working set of Associator and Data blocks needed for parallel command processing.

In cases where the global cache size (CLUCACHESIZE parameter) is set to a large value, CLUCACHEUNCHANGED should be set to "YES", so that the global cache achieves a better hit rate (efficiency).

Example

In the following example, the CLUCACHEUNCHANGED parameter is set to that both changed and unchanged Associator and Data blocks are written to the global cache.

ADARUN PROG=ADANUC, CLUCACHEUNCHANGED=YES

CLUGROUPNAME Parameter: Cluster Group Name

The CLUGROUPNAME parameter need not be specified for Adabas Parallel Services except when Adabas Parallel Services is used to recover an Adabas Cluster Services database after a failure that resulted in a remnant DIB entry. In this case, the CLUGROUPNAME parameter for Adabas Parallel Services must be set to the same value as it was for the failed Adabas Cluster Services nuclei.

For Adabas Cluster Services, the CLUGROUPNAME parameter provides the XCF group name to be used by the cluster nuclei for their communication using XCF.

All nuclei in the same cluster must have the same CLUGROUPNAME. Nuclei belonging to different clusters must have different CLUGROUPNAMEs.

In addition, the CLUGROUPNAME must be different from the XCF group names used by other subsystems that communicate using XCF.

The name can be 1-8 characters long. Valid characters are numeric, uppercase alphabetic, and the special characters $, @, and #. The name must begin with an alphabetic character (A-Z). IBM names begin with SYS, UNDESIG, or the characters A through I (these characters are not reserved).

Example

The following examples specifies the name of the XCF messaging group as "SAG1CLU".

ADARUN PROG=ADANUC,CLUGROUPNAME=SAG1CLU

CLULOCKNAME Parameter: Cluster Lock Structure/Area Name

For Adabas Cluster Services, CLULOCKNAM identifies a particular sysplex lock structure (defined in the CFRM policy) associated with a particular Adabas nucleus cluster. The same name must be set in each nucleus in the cluster. CLULOCKNAME must be unique for each cluster; that is, each database.

Adabas Parallel Services automatically creates a default name for each global lock area allocated by ADACOM. However, if you wish to control the name of the global lock area, you can set this parameter.

For Adabas Parallel Services, the CLULOCKNAME identifies a particular global lock area associated with all Adabas Parallel Services cluster nuclei that have the same SVC/DBID set as the current nucleus. The same name must be set in each cluster nucleus that has the same SVC/DBID set. CLULOCKNAME must be unique for each SVC/DBID set.

In all cases, the name can be 1-16 characters long. Valid characters are numeric, uppercase alphabetic, the special characters $, @, and #. The name must begin with an alphabetic character (A-Z). IBM names begin with SYS, UNDESIG, or the characters A through I (these characters are not reserved).

Example

The following example set the name of the lock structure or global lock area as "SAG1SMP#LOCK1".

ADARUN PROG=ADANUC,CLULOCKNAME=SAG1SMP#LOCK1

CLULOCKSIZE Parameter: Size of the Global Lock Area

The CLULOCKSIZE parameter specifies the amount of storage to be allocated for the global lock area which all nuclei in the Adabas Parallel Services cluster use to synchronize their processing. It has an effect only if CLUSTER=LOCAL is also specified.

CLULOCKSIZE must be specified for Adabas Parallel Services nuclei; there is no default.

CLULOCKSIZE may be specified in bytes, in kilobytes followed by a "K", in megabytes followed by an "M", or in gigabytes followed by a "G".

• The minimum size is 131072 bytes (or 128K)

• The maximum size is 2147483147 bytes (or 2097152K, 2048M, or 2G).

The value is rounded up to the nearest 4-kilobyte boundary.

Appropriate sizes for the global lock area depend on the expected amount of parallel command processing in the cluster. For more details about these calculations, read Global Cache Area Size in the Adabas Parallel Services Operations Guide. You can use the Adabas Online System lock structure size calculator described in Estimating Sizes for the Lock Structure in a Cluster Environment in the Adabas Parallel Services Operations Guide to determine appropriate global lock area sizes.

CLUPUBLPROT Parameter: Publishing of Protection Data

The optional CLUPUBLPROT parameter specifies whether or not cluster nuclei make their protection data available within the cluster before they make the related updates available to the other nuclei. Valid values are YES and NO. The default value is NO. CLUPUBLPROT is a global, modifiable parameter - that is, all active nuclei in the cluster run with the same setting and this setting can be changed at runtime. When a starting nucleus joins a cluster, it takes over the current setting of the nuclei that are already active.

If CLUPUBLPROT is specified as YES, each nucleus in the cluster writes updated ASSO and DATA blocks to the global cache only after it has first written the protection data for the latest updates to these blocks either to its WORK dataset or to the global cache. With this setting, when one nucleus in the cluster performs a buffer flush, the other nuclei need not be able to participate in the execution of the flush - the nuclei are more independent of one another.

If CLUPUBLPROT is not specified or is specified as NO, the nuclei in the cluster do not write protection data to the global cache. They continue to write protection data to their respective WORK datasets when this is necessary to provide for the recovery of the database after any failure of a nucleus. With this setting, when one nucleus in the cluster performs a buffer flush, all other nuclei must also take a few actions required for the execution of the flush (such as writing out their latest protection data to their WORK datasets).

Setting CLUPUBLPROT=YES is performance-sensitive for update-intensive workloads. The related CLUWORK1CACHE parameter should be configured suitably for all nuclei in the cluster before CLUPUBLPROT is set to YES before or during a nucleus session.

CLUSTER Parameter: Adabas Nucleus Cluster Session Control

The CLUSTER parameter specifies whether the Adabas nucleus will participate in a cluster of nuclei working on the same Adabas database, and if so, which type of cluster:

• If CLUSTER=NO (the default), the nucleus will not participate in an Adabas cluster. If CLUSTER=NO, the NUCID parameter must be set (or default) to 0.

• If CLUSTER=LOCAL, the nucleus will participate in a cluster where all nuclei run on the same operating system image. The add-on product Adabas Parallel Services is required to run in this mode.

• If CLUSTER=SYSPLEX, the nucleus will participate in a cluster where the nuclei may run on different systems within a parallel sysplex. This is supported only for z/OS systems. The add-on product Adabas Cluster Services is required to run in this mode.

If CLUSTER=LOCAL or SYSPLEX, the NUCID parameter must be set to a nonzero value that identifies the individual cluster nucleus. Also, the parameter settings MODE=SINGLE, READONLY=YES, LFIOP=0 and DTP=TM, and the use of sequential protection log data sets (DD-name/link name DDSIBA) are not allowed for cluster nuclei.

Example

The following example includes the nucleus in a cluster run with Adabas Cluster Services:

ADARUN DBID=53,CLUSTER=SYSPLEX,NUCID=5301

CLUWORK1CACHE Parameter: Number of WORK Blocks in Global Cache

The optional CLUWORK1CACHE parameter specifies how a cluster nucleus should make its latest protection data available within the cluster, if the CLUPUBLPROT parameter is set to YES. Valid values are integers in the range 0 through 32,767. The default value is 0. CLUWORK1CACHE is a local, unmodifiable parameter — that is, different nuclei in the same cluster may run with different CLUWORK1CACHE values and the value for a nucleus cannot be changed while that nucleus is running.

If the specified value for CLUWORK1CACHE is larger than NWORK1BUFFERS+1 or LP / 20, the smaller of these two values is taken as the effective CLUWORK1CACHE value. If the effective CLUWORK1CACHE value is equivalent to more than 1% of the total size of the data elements in the global cache, it is reduced to 1% of that size, in order to limit the portion of the cache that may be used for protection data. Any reductions of the CLUWORK1CACHE value to these boundaries are reported in the ADAX5E and ADAX5F messages.

CLUWORK1CACHE specifies the maximum number of WORK blocks that the cluster nucleus should keep in the global cache at a time. It also defines the size of an extension of the area on the WORK dataset where the nucleus stores protection data. Another nucleus in the cluster may copy protection data to this extension area from the global cache if this nucleus is slow or unable to participate in a buffer flush.

Apart from defining the size of the protection data extension area on WORK, the CLUWORK1CACHE parameter has an effect only when the related CLUPUBLPROT parameter is set to YES.

If CLUWORK1CACHE is specified as or defaults to zero and CLUPUBLPROT=YES, the nucleus always writes protection data directly to its WORK dataset before it writes updated ASSO and DATA blocks to the global cache, if the protection data relates to updates to those blocks. The nucleus does not write protection data to the global cache.

If CLUWORK1CACHE is specified greater than zero and CLUPUBLPROT=YES, the nucleus writes protection data to the global cache that is not yet present on WORK and relates to updates to be written to the cache. At most the number of WORK blocks specified by CLUWORK1CACHE will be stored in the cache. If further protection data needs to be made available within the cluster before updates can be written to the cache, older protection data is written to WORK first to make space for new WORK blocks in the cache.

When CLUPUBLPROT=YES, the setting of the CLUWORK1CACHE parameter is performance-sensitive for update-intensive workloads. Setting CLUWORK1CACHE=0 may lead to a significant number of additional WORK writes. Setting the parameter to a large value may lead to a significant number of additional cache writes. Any number in-between may lead to some additional WORK writes and some additional cache writes. Trials with different settings may be necessary to find the right balance that is best for the overall performance of the cluster for a given workload.

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.

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.

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.

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.

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.

CT Parameter: Command Timeout Limit

For Adabas Review, this is the maximum number of seconds (more precisely, units of 1.048576 seconds) that can elapse from the time an Adabas Review hub command has been completed until the results are returned to the user through the interregion communication (operating-system-dependent).

This parameter is used to prevent a command queue element and attached buffer from being held for a long period of time for a user who has terminated abnormally.

Possible causes of a command timeout are

• user region is swapped out or cannot be dispatched;

• user is canceled;

• user has low priority in high activity system.

If the CT limit is exceeded,

• the command queue element and attached buffer are released;

• a message ADAM93 is printed; and

• if the user has not terminated, response code 254 (ADARSP254) is returned to the user program.

Example

The following example permits about 30 seconds to obtain a result through interregion communication from the Adabas Review hub

ADARUN PROG=ADAREV,CT=30

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.

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") is available in z/OS environments only.

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.

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.

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.

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.

DATACACHE Parameter: Data Storage Controller Caching

This parameter applies to the z/OS operating system only.

Notes:

1. If Data Storage blocks are highly scattered or the update frequency is low, controller caching can cause longer I/O response times.
2. ADARUN caching control parameters also exist for the Associator (ASSOCACHE), the work area (WORKCACHE), the sort area (SORTCACHE), and the temp area (TEMPCACHE).

Example

The following example runs the nucleus without controller caching for the Data Storage data set.

ADARUN PROG=ADANUC,DATACACHE=NO

DATASPACEWARN Parameter: Data Storage Space Notifications

The syntax of the DATASPACEWARN ADARUN parameter is:

The following specifications can be made in the DATASPACEWARN parameter:

Up to three threshold-increment pairs can be specified.

Example

In the following example, the ADARUN parameter setting for DATASPACEWARN specifies that a space usage message is printed when the percentage of Data Storage space use is greater than or equal to 50%, 60%, 70%, 80%, 85%,90%, 95%, 96%, 97%, 98%, 99%, and 100% of the total DATA space available. So when DATA space use exceeds 50%, a space usage message is printed. Thereafter, a space usage message is printed for every 10% increase until the DATA space use reaches 80%. Once DATA space use reaches 80%, a space usage message is issued every time DATA space use increases 5% until DATA space use reaches 95%. Once DATA space use reaches 95%, a space usage message is printed every time DATA space use increases 1%.

Likewise, similar space usage messages are produced as DATA space use decreases from the percentages (50%, 80%, and 95%) listed and at the increments listed (10%, 5%, and 1%) in the DATASPACEWARN setting. In this case, space usage messages would be issued when DATA space use drops below 100%, 99%, 98%, 97%, 96%, 95%, 90%, 85%, 80%, 70%, 60%, and 50% of the total DATA space available.

ADARUN PROG=ADANUC,DATASPACEWARN=50,10,80,5,95,1

DBID Parameter: Database Identification

Example

The following example runs the ADAINV utility against physical database 2 using SVC 241.

ADARUN PROG=ADAINV,DBID=2,SVC=241

DEVICE Parameter: Device Type

The device type of the external storage device on which the first block of the Associator is stored.

This device type is also used as default for most device type parameters.

The Adabas Installation documentation specifies the device types supported by Adabas.

Example

The following example runs the ADALOD utility and stores the first block of the Associator on a 3390 device.

ADARUN PROG=ADALOD,DEVICE=3390

DIRRATIO / ELEMENTRATIO Parameters: Cluster Cache Directory-to-Data Elements Ratio

The DIRRATIO and ELEMENTRATIO parameters together define the ratio of directory elements to data elements in the Adabas Cluster Services coupling facility cache structure or the Adabas Parallel Services global cache area.

This ratio influences the allocation of the cache structure/area when the first cluster nucleus starts. It has no influence on the cache structure/area when a subsequent nucleus starts.

The DIRRATIO / ELEMENTRATIO ratio is optionally used in Adabas cluster environments to tune the cache structure/area for better performance.

Directory elements are used to keep track of the cluster members that have individual blocks in their local caches (buffer pool and Adabas Caching Facility caches), so that the blocks can be invalidated should other members modify them.

Data elements are used to hold the contents of Associator and Data blocks from the database.

If the number of directory elements is insufficient, existing directory elements are reused and the blocks associated with those directory elements are invalidated and can then no longer be reused. When blocks become invalid even though they have not been modified, they must be reread and registered again the next time they are referenced and validated.

It is generally better to reassign storage for data elements to keep more Associator and Data blocks in the cache structure/area than to define too many directory elements in the cache. More data elements than necessary can be used to keep additional blocks to improve the cache efficiency.

The number of directory elements need not be greater than the sum of the sizes of all buffer pools plus the amount of space represented by data elements (number of data elements times data element size), divided by the smallest Associator block size.

You can use the Adabas Online System cache structure size calculator described in Estimating Sizes for the Cache Structure in a Cluster Environment in the Adabas Parallel Services Operations Guide or the Adabas Cluster Services Operations Guide to determine appropriate global cache area sizes and DIRRATIO/ELEMENTRATIO parameter values.

When connecting to the cache structure/area during startup, the ADAX57 message reports the number of directory and data elements allocated and the size of a data element.

DSF Parameter: Adabas Delta Save Facility Control

The DSF parameter controls the Adabas Delta Save Facility for an Adabas nucleus or utility. If Adabas Delta Save is not installed on your system, specifying this parameter may cause an error.

Example

The following example runs the Adabas nucleus in DSF mode; performing Adabas Delta Save functions is possible for this nucleus.

ADARUN PROG=ADANUC,DSF=YES

DSFEX1 Parameter: Delta Save Facility Exit

Used in conjunction with the Adabas Delta Save Facility, the format of the user exit parameter is

DSFEX1=exit-name

where

Only one program may be specified for the DSF user exit. Only one DSF user exit may be specified. See the Adabas Delta Save Facility documentation for more information.

Example

This example indicates that the Adabas nucleus should use the Delta Save Facility with the user exit routine DSAVEPGM.

ADARUN PROG=ADANUC,DSF=YES,DSFEX1=DSAVEPGM

DTP Parameter: Distributed Transaction Processing Control

The DTP parameter controls the distributed transaction processing status of the Adabas nucleus. If Adabas Transaction Manager is not installed on a separate nucleus in your system, specifying this parameter may cause an error.

Example

The following example indicates that the nucleus will participate as a resource manager in a distributed transaction processing system coordinated by a transaction manager.

ADARUN PROG=ADANUC,DTP=RM

DUALCLD Parameter: Dual Command Log Device Type
DUALCLS Parameter: Dual Command Log Size

The DUALCLD and DUALCLS parameters specify the type of external storage device used for dual command logging and the number of blocks available for each dual command log data set. These parameters must be used together; if you specify one parameter, you must also specify the other parameter. If you specify a user exit, it must be UEX2.

The Adabas Installation documentation specifies the device types that Adabas supports.

Both dual command logging data sets must be formatted using the ADAFRM utility before they are used.

The maximum size of the data set depends on the limits of the operating system and on the requirements of the user.

Example

The following example runs the Adabas nucleus with command logging and uses a model 3380 device for dual command logging. The size of each command log data set is 1350 blocks, based on an allocation of 10 cylinders. (Each cylinder of a 3380 device has 15 tracks, and each track can contain 9 blocks of command log data. Thus, 10 cylinders = 10 x 15 x 9 = 1350 blocks).

ADARUN PROG=ADANUC,LOGGING=YES,DUALCLD=3380,DUALCLS=1350

DUALPLD Parameter: Dual Protection Log Device Type
DUALPLS : Dual Protection Log Size

The DUALPLD and DUALPLS parameters specify the type of external storage device used for dual data protection logging and the number of blocks available for each log data set. These parameters must be used together; if you specify one parameter, you must also specify the other parameter. If you specify a user exit, it must be UEX2.

When these parameters are specified, dual protection logging is activated for the session. See Adabas Restart and Recovery for information about dual protection logging.

The Adabas Installation documentation specifies the device types that Adabas supports.

Both dual protection log data sets must be formatted using the ADAFRM utility before they are used. The appropriate JCL for the data sets is required.

Example

The following example runs the Adabas nucleus with dual data protection logging and uses a model 3380 device; the size of each dual log data set is 1200 blocks, based on an allocation of 10 cylinders. (Each cylinder of a 3380 device has 15 tracks, and each track contains 8 blocks of protection log data. Thus, 10 cylinders = 10 * 15 * 8 = 1200 blocks).

ADARUN PROG=ADANUC,DUALPLD=3380,DUALPLS=1200

EXCPVR Parameter: Control EXCP or EXCPVR Use

The EXCPVR parameter controls whether EXCP or EXCPVR should be used when from an APF-authorized load library in z/OS environments. If, EXCPVR=YES is specified, EXCPVR is used; if EXCPVR=NO is specified, EXCP is used.

Example

The following example runs Adabas APF-authorized using EXCP.

ADARUN PROG=ADANUC,EXCPVR=NO

FASTPATH Parameter: Adabas Fastpath Control

The FASTPATH parameter controls the optional Adabas Fastpath product. If Adabas Fastpath is installed on your system, FASTPATH=YES enables the full functionality of the product.

If Adabas Fastpath is not installed on your system, FASTPATH=YES invokes the Adabas Fastpath command analysis sampler AFPLOOK that is provided with Adabas.

The demo version of Adabas Online System that is supplied with Adabas provides access to the Adabas Fastpath online system SYSAFP so that the AFPLOOK sample can be viewed online exactly as it would appear if Adabas Fastpath were installed. For complete information about AFPLOOK, read AFPLOOK.

Example

The following example runs Adabas Fastpath with Adabas.

ADARUN PROG=ADANUC,FASTPATH=YES

FMXIO Parameter: Parallel LFIOP I/O Operations

The LFIOP parameter enables asynchronous buffer flush operation and sets the I/O pool size. The FMXIO parameter sets the limit on the number of I/O operations that can be started in parallel by LFIOP flush processing.

Parameter Dependencies

The precise meaning of the FMXIO parameter depends on the setting of the ASYTVS parameter):

• When ASYTVS=YES (perform buffer flushes by volume), FMXIO specifies the number of I/Os to be started in parallel on each volume. The minimum and default number is 1; the maximum number is 16. If the specified number exceeds that, it is automatically reduced to 16.

• When ASYTVS=NO (perform buffer flushes in ascending RABN sequence, without regard to the distribution of the blocks over volumes), FMXIO specifies the number of I/Os to be started in parallel overall. The minimum number is 1; the maximum value is 100; and the default is 60.

Dynamic Modification

The setting of FMXIO can be modified dynamically using the command FMXIO=nnn from the operator console or the Modify Parameter function of Adabas Online System.

Specific Product Recommendations

Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server, causing replication data to be written and read from the SLOG file.

Example

The following example specifies that a maximum of 30 I/O operations for asynchronous buffer flushes can be started in parallel:

ADARUN PROG=ADANUC,ASYTVS=NO,FMXIO=30

FORCE Parameter: Allow Nucleus Database ID or Review Hub Table Entry Overwrite

If running Adabas Review, this indicates whether the Adabas Review hub can overwrite an existing ID table entry. When a Review hub starts up, ADARUN scans the ID table to ensure that no entry exists for the Review hub. You can use the FORCE parameter to indicate whether the Review hub can overwrite an existing ID table entry.

The ID table entry is derived from the database ID and the job name. For Adabas Review, the ID table entry is derived from the Review hub ID (REVIEW=). The ID table entry is deleted when the nucleus terminates normally.

The FORCE parameter allows the nucleus or Adabas Review hub to overwrite the existing ID table entry and access the database.

Warning: Do not use the FORCE parameter unless absolutely necessary, or the integrity of the database could be lost. Ensure that no nucleus or Review hub is active for the ID table entry being overwritten.

A data integrity block (DIB) entry will only be removed once the ID Table initialization has been successful. Therefore, you must set IGNDIB and FORCE both to "YES" if either of the following occur:

• You receive a PARM ERROR 26 after parameter settings IGNDIB=NO and FORCE=YES were applied;

• You receive a PARM ERROR 23 after parameter settings IGNDIB=YES and FORCE=NO were applied.

Examples

The following example specifies that if the ID table contains an active entry for DBID 7, overwrite the entry.

ADARUN PROG=ADANUC,FORCE=YES,DBID=7

The following example specifies that if the ID table contains an active entry for the Adabas Review hub, overwrite the entry.

ADARUN PROG=ADAREV,FORCE=YES,REVIEW=202

HEXnn Parameter: Hyperdescriptor User Exit

Used in conjunction with the hyperdescriptor facility, the format of the parameter is

HEXnn=exit-name

where

Only one program may be specified for each hyperdescriptor exit. Up to 31 hyperdescriptor exits may be specified (in any order). See the Adabas User, Hyperdescriptor, Collation Descriptor, and SMF Exits Manual for more information.

Example

The following example runs the Adabas nucleus using hyperdescriptor exits 1 and 2. It also gives control to the user routine UHYPER1 at hyperdescriptor exit 1 and gives control to the user routine UHYPER2 at hyperdescriptor exit 2.

ADARUN PROG=ADANUC,HEX01=UHYPER1,HEX02=UHYPER2

IGNDIB Parameter: Ignore DIB Entry for Adabas Nucleus

The DIB is the data integrity block in the Associator. The DIB contains an entry that indicates whether an Adabas session is active for the database. This feature prevents an update nucleus session from being started while another one is running on the same database; it is especially important when several CPUs share the same database DASD devices. The DIB entry is automatically released when the Adabas session is terminated normally.

This parameter indicates whether this update nucleus session should ignore and delete the entry in the data integrity block (DIB) in the Associator.

A data integrity block (DIB) entry will only be removed once the ID Table initialization has been successful. Therefore, you must set IGNDIB and FORCE both to "YES" if either of the following occur:

• You receive a PARM ERROR 26 after parameter settings IGNDIB=NO and FORCE=YES were applied;

• You receive a PARM ERROR 23 after parameter settings IGNDIB=YES and FORCE=NO were applied.

Example

The following example runs an Adabas update session and ignores and deletes the DIB entry for an active Adabas update nucleus.

ADARUN PROG=ADANUC,IGNDIB=YES

IGNDTP Parameter: Ignore Two-Phase Commit Area (Work Part 4)

Warning: This parameter is for emergency use only; contact your Software AG technical support representative before using it. Whenever the information on Work part 4 is ignored, the integrity of the incomplete global transactions that are related to that information cannot be guaranteed.

IGNDTP=YES can be specified with DTP=NO or DTP=RM.

When DTP=NO, the nucleus will not start if there is data in Work part 4 related to the recovery of previously incomplete global transactions. In this situation, specifying IGNDTP=YES forces the nucleus to ignore the data in Work part 4 and start anyway.

When DTP=RM, the nucleus also ignores any data on Work part 4 and reinitializes the area. This can be useful during a recovery when the state and correctness of the incomplete global transactions that are stored on Work part 4 has already been established.

Example

The following example runs an Adabas update session without support for distributed transactions; it ignores data in the Work part 4 area left over from the previous session with support for distributed transaction processing.

ADARUN PROGRAM=ADANUC,DTP=NO,LDTP=8,IGNDTP=YES

INDEXCROSSCHECK Parameter: Data Storage Record Validation

This parameter controls whether index cross-checking is turned on or off. Index cross-checking is a process Adabas uses to ensure that a data storage record it is reading actually matches the descriptor value in the index by which the record was found. When index cross-checking is turned on, Adabas extracts the descriptor value from the record being read and compares it to the value used for positioning in the index. If there is a mismatch, Adabas returns response code 175 (ADARSP175).

If "YES" is specified (the default value), Adabas extracts the descriptor value from the record being read and compares it to the value used for positioning in the index. If the two values are not equal, Adabas checks for a parallel update command on the same record and retries after that update has finished. If there is no parallel update command, Adabas returns response code 175 (ADARSP175) to indicate an inconsistency between the data storage and the index.

If "NO" is specified, Adabas does not extract the descriptor value from the record, but immediately checks for a parallel update command on the same record. If there is one, even if it does not update the descriptor in question, Adabas waits until the update has finished and then retries. With this parameter setting, Adabas does not validate the index against the data storage record and does not return response code 175 (ADARSP175).

Setting INDEXCROSSCHECK to "NO" may, under certain circumstances, reduce the CPU time required for ensuring that the Data Storage record being read matches the descriptor value by which the record was found. This applies in particular to cases where neither the descriptor itself nor (if it is a special descriptor) its parent field(s) occur in the format buffer specifying the fields to be returned and where the descriptor or one of its parents were defined near the end of the FDT.

Example

The following example specifies that Adabas should not extract the descriptor value from the record being read. The index is not validated against the data storage record.

ADARUN PROGRAM=ADANUC,INDEXCROSSCHECK=NO

INDEXUPDATE Parameter: Index Update Processing Control

This parameter controls which index structure rules the Adabas nucleus uses to perform index updates. For each file in the database, the file's index stores the descriptor values from the file's data storage records in a tree structure. Adabas can use two very similar, but slightly different sets of rules that govern the tree structure. The advanced rules are less strict than the original ones and allow Adabas to perform certain types of index updates more efficiently than the original rules do.

When INDEXUPDATE is set to "ORIGINAL", Adabas uses the original, strict rules for the structure of the index trees in the database. This is the default value

When INDEXUPDATE is set to "ADVANCED", Adabas uses modified, less strict rules for the index tree structure for certain types of index updates. For these index updates, efficiency gains are expected and less protection data will be written to the WORK dataset.

The INDEXUPDATE setting cannot be changed at runtime. In a cluster, INDEXUPDATE should (but need not) be set to the same value in all nuclei in the cluster. It is possible to set INDEXUPDATE back to "ORIGINAL" after Adabas has been performing updates with INDEXUPDATE=ADVANCED. In this case, the index structure established with the advanced rules will stay in effect and the nucleus will perform further index updates according to the original index structure rules.

INFOBUFFERSIZE Parameter: Information Buffer Pool (Adabas Event Log) Size

The information buffer pool is a wraparound buffer in memory that represents the size of the new Adabas event log. At this time, the Adabas event log is used to log each response code 145 (ADARSP145) event. The INFOBUFFERSIZE parameter identifies the size of the Adabas event log. Each entry in the event log is currently 128 bytes, although this may change in later Adabas releases. When the Adabas event log fills up, the oldest entries in the log are overwritten.

Setting INFOBUFFERSIZE to zero (0) indicates that no buffer pool (Adabas event log) is allocated. The minimum size of the pool is 1024 bytes.

The information in the Adabas event log can be printed using the ADADBS DEVENTLOG utility function. For more information, refer to the Adabas Utilities Manual.

Example

The following example specifies an information buffer pool (Adabas event log) that is 50,000 bytes in size.

ADARUN PROGRAM=ADANUC,INFOBUFFERSIZE=50000

INTAUTO Parameter: Time Interval Between Autorestart Progress Messages

When performing session autorestart to recover from a preceding failure, Adabas prints autorestart progress messages (in message ADAN56) to indicate how much repair and recovery work has already been done and how much remains to be done. By default, these messages occur when each phase of the autorestart (backward repair, forward repair, autobackout) completes.

The INTAUTO parameter allows you to set the time interval (in seconds) at which autorestart progress messages will be printed, in addition to the standard messages printed at the end of each phase (assuming a phase takes longer than the specified time interval). The default (0 seconds) indicates that autorestart progress messages should only be printed at the completion of each autorestart phase.

Example

The following ADARUN INTAUTO parameter indicates that Adabas should print progress messages every ten seconds when performing session autorestart processing.

ADARUN PROGRAM=ADANUC,INTAUTO=10

INTNAS Parameter: Time Interval Between SYNS 60 Checkpoints

The SYNS 60 statistic checkpoint is generated by the Adabas nucleus and written to the Adabas Checkpoint system file. It may be displayed using the CPLIST function of the ADAREP utility or Adabas Online System. For more information about checkpoints see the ADAREP utility discussion in the Adabas Utilities Manual.

INTNAS allows you to set the time interval (in units of 1.048576 seconds) between SYNS 60 checkpoints. The default (3600) is approximately 1 hour meaning that nucleus statistics will be recorded once each hour.

Example

The following example sets Adabas so that nucleus statistics are recorded every 30 minutes.

ADARUN PROGRAM=ADANUC,INTNAS=1800

LARGEPAGE Parameter: Large Page Support Option

This parameter indicates whether or not the Adabas nucleus should use large pages. The default is NO.

The amount of storage in your operating system available for page-fixed 1M or 2G large pages is set using the LFAREA parameter in PARMLIB member IEASYSxx. For complete information on the LFAREA parameter, refer to the IBM z/OS Extended Addressability Guide.

Example

The following example requests that the Adabas nucleus should make use of virtual storage above the 2G bar and should use 1M large pages.

ADARUN PROG=ADANUC,LARGEPAGE=YES,V64BIT=YES

LBP Parameter: Length of Buffer Pool

The maximum number of bytes to be used for the Adabas buffer pool during a session.

Adabas allocates the number of bytes specified to the Adabas buffer pool if sufficient memory is available. A minimum of 80000 bytes must be available to successfully initiate a session. For performance reasons, however, Software AG recommends that you specify at least 50000 bytes per thread. Ensure that sufficient memory is available to accommodate the LBP size specified. If asynchronous buffer flush management is used (that is, the LFIOP parameter specifies a nonzero value), the LBP value must be greater than that specified by LFIOP.

In environments running in 31-bit addressing mode, the buffer pool space is allocated above the 16-megabyte line.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session.

The buffer efficiency statistic can be used to determine the optimal size of the parameter.

Specific Product Recommendations

• Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server, causing replication data to be written and read from the SLOG file.

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example allocates a maximum of 800000 bytes to the Adabas buffer pool for this session.

ADARUN PROG=ADANUC,LBP=800000

LCP Parameter: Length of Security Pool

The maximum number of bytes to be used for the Adabas security pool during a session. The pool is used to keep security information in memory in order to optimize performance.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session.

Example

The following example allocates a maximum of 50000 bytes to the Adabas security pool for this session.

ADARUN PROG=ADANUC,LCP=50000

LDEUQP Parameter: Length of Unique Descriptor Pool

The unique (UQ) descriptor pool comprises elements that are the length of a unique descriptor value plus 14 bytes. The UQ descriptor pool should be large enough to hold all unique descriptor values that are being changed by all transactions at any point in time.

Adabas will make an entry in this pool every time a unique descriptor value is deleted from or inserted into a file's index. A full update of a unique descriptor value produces two entries: one for the deletion of the old value and one for the insertion of the new value. The entry for an insertion is normally removed as soon as the index update has been performed. The entry for a deletion is removed when the current transaction ends. However, Adabas Cluster Services and Adabas Parallel Services nuclei always keep entries for insertions until the end of the transaction too.

Specific Product Recommendations

• Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server, causing replication data to be written and read from the SLOG file.

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

For example, assuming that the average length of unique descriptor values is about 16 bytes, the following Adabas session can process a maximum of about 1000 unique descriptors at one time.

ADARUN PROG=ADANUC,LDEUQP=30000

LDTP Parameter: Length of Distributed Transaction Processing Area (Work Part 4)

If you have Adabas Transaction Manager installed, this parameter specifies the size (in blocks) of the WORK4 index which is used to administer the data on DDWORKR4:

• If DTP=RM and LDTP is either unspecified or specified as "0", a default of 8 blocks is used.

• If specified, the ADARUN LDTP must be at least 8 blocks. The maximum size that can be specified is the size of the DDWORK4 data set divided by 8.

DDWORKR4 is a container data set used for the same purpose as Work part 4 of DDWORKR1 was used previously, with the difference that DDWORKR4 can be used in parallel by all members in a cluster. The DDWORKR4 data set should be allocated and formatted in the normal way, using a block size greater than or equal to DDWORKR1. It should be at least as large as the cluster’s LP parameter of the database or cluster.

Example

In the following example, the LP parameter specifies 2000 blocks for the data protection area (Work part 1). This example also uses 2500 blocks for the distributed transaction processing area on the Adabas Work data set (part 4).

ADARUN PROG=ADANUC,DTP=RM,LP=2000,LDTP=2500

LFIOP Parameter: Asynchronous Buffer Pool Control

The asynchronous buffer flush I/O pool enables asynchronous Adabas buffer flush operation and defines the size of the related buffer. Specifying a non-zero value for LFIOP enables asynchronous buffer flush operation; the value specified determines the buffer size, in bytes.

If LFIOP is not specified or zero is specified (the default), synchronous buffer flushing is performed. Note that flushing is always synchronous in single-user mode (MODE=SINGLE).

When LFIOP=1 or LFIOP=n and the specified or calculated flush pool size is less than 80000 bytes, Adabas uses a size of 80000 bytes.

In environments running in 31-bit addressing mode, the I/O pool is allocated above the 16-megabyte line.

In environments supporting 64-bit virtual storage, the flush I/O pool is allocated above the 2 gigabyte bar when the V64BIT ADARUN parameter is set to "YES".

Specific Product Recommendations

• Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server causing replication data to be written and read from the SLOG file.

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1") consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example enables asynchronous buffer flush operation for this session and allocates an I/O pool of 200000 bytes (25% of the LBP size).

ADARUN PROG=ADANUC,LFIOP=1,LBP=800000

LFP Parameter: Length of Internal Format Buffer Pool

This pool stores internal format buffers used with Adabas read and update commands as described in the Adabas Command Reference Guide.

Each internal format buffer pool entry requires approximately 60 + (64 * n) bytes, where n equals the number of fields referenced in the command.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session.

In environments running in 31-bit addressing mode, the LFP pool is allocated above the 16-megabyte line.

Specific Product Recommendations

If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example allocates 8000 bytes for the Adabas internal format buffer pool for this session.

ADARUN PROG=ADANUC,LFP=8000

LI Parameter: Length of Table of ISNs (TBI)

LI specifies the number of bytes allocated for the table of ISNs (TBI), which is used to store ISN lists (overflow ISNs or saved ISN lists). Each ISN list is identified by a command ID (CID) and stored in a TBI element.

You must also specify a value for the NSISN parameter, which sets the maximum number of ISNs per TBI element. Each TBI element has a length of 64 + ( NSISN * 4 ) bytes.

The number of TBI elements required determines the length of the TBI. For complex searches, the Adabas nucleus builds temporary TBI elements in addition to the permanent TBI element; for example, for holding the results of descriptor searches, for reading the result records in Data Storage and collecting matches, or for holding the results of the partial criteria associated with the R operator. Although the temporary TBI elements are deleted at the end of a search, the TBI must be large enough to hold all of the temporary and permanent TBI elements in parallel during search processing.

The Adabas session statistics or Adabas Online System can be used to set this parameter for the next session.

When running with Adabas expanded files, a larger-than-normal LI value is recommended.

In environments running in 31-bit addressing mode, the LI pool is allocated above the 16-megabyte line.

Example

The following example allocates 30000 bytes for the table of ISN list IDs for this session.

ADARUN PROG=ADANUC,LI=30000

LNKGNAME Parameter: Link Globals Table Name

The parameter name LNKGNAME may be abbreviated to LGN.

Notes:

1. If you specify the LNKGNAME parameter, you must also specify the ADARUN DBID and SVC parameters.
2. To use this and other keywords for a batch or TSO job step, the application must be linked with the ADAUSER load module and call Adabas to invoke the ADAUSER load module.
3. If the job step specifies PROG=USER or PROG=RENTUSER with no LNKGNAME keyword, either the ADALNK or ADALNKR module will be loaded by ADARUN. This is intended to allow the Adabas 7 batch/TSO link routines to be loaded and executed for the job step. Take care to ensure the proper load library concatenation is provided on the job step so the Adabas 7 ADALNK or ADALNKR module will be loaded. This should allow gradual migration of job steps from Adabas 7 to Adabas 8 as required.

Example:

In the following example, the link globals table in module MYGBLS is used.

ADARUN PROG=USER,LNKGNAME=MYGBLS

LOCAL Parameter: Local Adabas Review Hub

Defines an isolated Adabas nucleus or Adabas Review hub that is only available locally. The nucleus or hub is unreachable to Entire Net-Work. A nucleus or Adabas Review hub specifying LOCAL=YES (the default) can have the same database ID or hub ID as another database nucleus or Review hub on another network node.

Examples

In the following example, the Adabas nucleus is not isolated and can be addressed by other Entire Net-Work nodes.

ADARUN PROG=ADANUC,LOCAL=NO

In the following example, the Review hub is isolated and cannot be addressed by other Entire Net-Work nodes.

ADARUN PROG=ADAREV,LOCAL=YES

LOGGING / LOGxxxx Parameters: Command Logging Control

The LOGGING parameter specifies whether to use command logging for the Adabas session. The LOGxxxx parameters specify the type of information to be logged. Valid values are YES and NO for all of these parameters.

If you specify LOGGING=YES, you must also specify YES for one or more of the following ADARUN LOGxxxx parameters. By default, each type of information is not logged.

¹LOGCLEX=YES requires that Adabas Review modules must be available. The data provided in command log records with CLEX can be viewed using the batch program REVIEWB. For more information review the Field Reference in the Adabas Review Reference Guide.

² If the LOGIO parameter is set to "NO", no I/O buffer element is logged at all. If LOGIO is set to "YES" but LOGVOLIO is set to "NO", only the standard I/O buffer element is logged. The extended I/O list is only logged if both the LOGIO and LOGVOLIO parameter are set to "YES".

You can use Adabas operator commands or Adabas Online System to modify logging parameters during session execution.

Example

The following example runs the Adabas nucleus with command logging and logs the Adabas control block.

ADARUN PROG=ADANUC,LOGGING=YES,LOGCB=YES

LOGSIZE Parameter: Maximum Command Log Size

This parameter controls the maximum block size for the sequential command log DD/LOG. The default value is identical to the value of the QBLKSIZE parameter. If dual or multiple command logging is used, this parameter is ignored.

Example

In the following example, the block size of the command log is set as 2000 bytes.

ADARUN PROG=ADANUC,LOGSIZE=2000

LOGWARN Parameter: CLOG and PLOG Alert Message Interval

This parameter is optional, but a valid user exit 2 (ADARUN parameter UEX2) or user exit 12 (ADARUN parameter UEX12) must also be specified when this parameter is set to any value other than zero (0). A value of zero (0), the default, indicates that no CLOG and PLOG status checks should occur and that no alert messages should be produced. Any other valid LOGWARN value represents the interval (in seconds) at which the PLOG and CLOG status is checked and resulting alert messages are produced.

After checking the status of the CLOG and PLOG data sets, alert messages are written when Adabas detects that a PLOG or CLOG data set has not been copied within a specified time interval. Thereafter, an alert message is written at regular intervals as long as there is a PLOG or CLOG data set waiting to be copied. These alert messages are issued until the PLOG or CLOG data set is copied or until no logs remain to be copied. Your user exits 2 or 12 can be set up so that the messages appear providing a comprehensive trace of activity so you can resolve and problems with the PLOG or CLOG.

This feature helps you prevent the potential problem of Adabas overwriting an older CLOG or PLOG data set without waiting for direction from the user. Ordinarily, when a PLOG or CLOG data set fills up, the Adabas nucleus examines the return code from user exit 2 or user exit 12 to determine whether it should wait before overwriting an older PLOG or CLOG data set with new information. If there is no user exit 2 or 12, Adabas does not wait, but simply overwrites the older log. If this LOGWARN parameter is set to a value other than zero, the statuses of the CLOG and PLOG data sets are analzed at the frequency specified by this parameter, warning about their status and providing you with the information you need to prevent any overwriting of older logs.

Example

In the following example, the CLOG and PLOG statuses are checked every hour.

ADARUN PROG=ADANUC,LOGWARN=3600,UEX2=SUBR2

LP Parameter: Length of Data Protection Area (Work Part 1)

The LP parameter specifies the number of blocks to allocate to the Work data protection area, which is part 1 of the Work data set. This area must be large enough to accommodate the data protection information for the current transaction for all ET logic users. Details can be found in Adabas Restart and Recovery.

The LP parameter is no longer limited to 65535 blocks; however, it is still limited by the size of the Work data set and the sizes of Work parts 2, 3, and 4.

Specific Product Recommendations

• Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server, causing replication data to be written and read from the SLOG file.

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example uses 2,000 blocks to store data protection information on the Adabas Work data set.

ADARUN PROG=ADANUC,LP=2000

LQ Parameter: Length of Sequential Command Table

The table of sequential commands contains internal entries required during the processing of the Adabas read sequential (L2/L5, L3/L6, and L9) commands.

Each sequential pass of an Adabas file requires one entry in this table. Each table entry requires approximately 60-100 bytes, depending on the command type. Additionally, a variable portion (descriptor value) is required in the table entry for the L3/L6/L9 commands. An entry is deleted when an end-of-file condition is detected during sequential processing or when an RC or CL command is issued.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session. If using expanded files, the LQ value may need to be set to a higher-than-normal value.

The LQ value also determines the maximum number of command IDs that each user can specify. See the NQCID parameter description, later in this chapter, for more information.

In environments running in 31-bit addressing mode, the LQ pool is allocated above the 16-megabyte line.

Example

The following example allocates 30000 bytes for the table of sequential commands for this session.

ADARUN PROG=ADANUC,LQ=30000

LRDP Parameter: Length of the Redo Pool

The LRDP parameter specifies the size of the redo pool in an Adabas Cluster Services or Adabas Parallel Services nucleus. It has an effect only when CLUSTER=SYSPLEX or LOCAL has also been specified. For Adabas Parallel Services 8.2 or later, its default is zero (0). For Adabas Cluster Services 8.2 or later, its default is either 10 megabytes (10M) or the value of the ADARUN LFIOP parameter, whichever is smaller. For earlier releases of Adabas Parallel Services and Adabas Cluster Services, the default is the value of the ADARUN LFIOP parameter.

• If LRDP is set to zero, the cluster nucleus performs immediate publishing: Updated database blocks are always written to the global cache at the time each update takes place.

• If LRDP is set to (or defaults to) a nonzero value, the cluster nucleus performs deferred publishing: The writing of updated database blocks to the global cache is deferred until later. However, updates are always published in the global cache before the transactions they belong to are committed (by ET commands). The redo pool is used to maintain descriptions of all unpublished updates, in case they need to be redone due to concurrent updates to the same blocks by other nuclei in the cluster.

By combining multiple updates to the same block into a single write-to-cache operation, deferred publishing tends to result in fewer read and write operations from and to the global cache than immediate publishing. Depending on the type of application workload, this may have a large positive effect on performance. This is especially the case for Adabas Cluster Services, where frequent communication with the cache in the coupling facility may cause a high overhead.

Recommendation: For Adabas Cluster Services, specify a nonzero LRDP parameter (or use the default).

Different nuclei in the same cluster can have different settings of LRDP. It is also possible, although not recommended, to run one nucleus with LRDP=0 and another one with LRDP>0.

If the redo pool specification is too small and the pool runs full, the nucleus will write additional updated blocks to the global cache before the surrounding transactions end. Such additional cache writes may hurt system performance. To obtain more information about the current usage of the redo pool, review the redo high-water mark in the output of the DRES operator command and in the cluster nucleus shutdown statistics. This information is also available in corresponding Adabas Online System (AOS) displays and in the output of the ADADBS OPERCOM function.

LRPL Parameter: Adabas or Event Replicator Replication Pool Size

Notes:

1. The LRPL parameter should be specified for an Adabas nucleus running with ADARUN parameter REPLICATION=YES. In addition, the replication pool will be allocated in 64-bit virtual storage when an Adabas nucleus runs with ADARUN parameters REPLICATION=YES and V64BIT=YES.
2. The LRPL parameter should be specified for an Event Replicator Server.
3. The LRPL parameter values in the Adabas nucleus and the Event Replicator Server may be different.
4. Software AG recommends setting LRPL to a relatively large value (e.g. LRPL=40M or greater). To determine what this setting should be for your site, you could run Adabas in a test environment with replication turned on, simulate the activity in the production environment on this test system, and use the Adabas DRES operator command to view the current and high-water mark of replication pool usage.
5. If Event Replicator 3.4 SP1 or later is installed and if an Adabas nucleus with replication is run with V64BIT=YES and LARGEPAGE=G64, the allocation request for the replication pool will be rounded up to the nearest multiple of two gigabytes. Any difference between the specified size and the allocated size will remain unused. For this reason we recommend that if LARGEPAGE=G64, you specify the LRPL value as a multiple of two gigabytes to avoid leaving a potentially large amount of allocated storage unused. If LARGEPAGE=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.

Example:

ADARUN PROG=ADANUC,REPLICATION=YES,LRPL=50000K

LS Parameter: Length of Internal Sort Area

The LS parameter specifies the maximum number of bytes within the Work pool to be used for sort work space during the processing of a single command of the following type:

• S2 and S9 commands;

• complex search commands, which require the storage of bit strings.

The following formula may be used to estimate the number of Adabas ISNs that may be sorted in the work space provided (S2 or S9 commands):

If the TOPISN in the file is less than 65536:

Notes:

1. TOPISN is the highest ISN currently in use for the file, less (MINISN - 1). TOPISN is not controlled by a parameter.
2. 4-byte ISNs are used for the internal sort area, regardless of the ISNSIZE specified for the file.

If the TOPISN in the file is greater than 65536:

For complex searches, it is desirable for performance reasons to set LS value to the next integer multiple of 256 bytes greater than TOPISN / 8. For example, if TOPISN = 480000, then TOPISN / 8 = 60000, so LS should be set to the next higher multiple of 256, namely 60160.

Example

In the following example, the maximum amount of internal sort space during this session is set at 60160 bytes.

ADARUN PROG=ADANUC,LS=60160

LSF Parameter: Logical Save Facility

The LSF parameter enables the nucleus to support Logical Save Facility processing. In the majority of sites Logical Save Facility will not be installed and this parameter should be set to NO (or allowed to default).

LTZ Parameter: Time Zone Pool Size

When LTZ=0 is specified, no time zone pool is allocated. This disables the use of time zones for user sessions. The minimum, non-zero allocation is 12288 (12K).

Time zone information varies in size with an average of 1000 bytes. So the default of 32768 (32K) allows for approximately 32 time zones.

Finally, while the maximum value that can be specified for the LTZ parameter is 2147483647 bytes, only 491520 bytes (480K) is required to load all available time zones.

Example

In the following example, the minimum size (12288 bytes) is set for the time zone pool.

ADARUN PROG=ADANUC,LTZ=12288

LU Parameter: Length of Intermediate User Buffer Area

The LU parameter is optional. The size specified must be large enough to accommodate all Adabas control information (204 bytes), all user buffers (format, record, search, value, ISN) that may be required for any given Adabas command, plus any user information passed from Adabas link routines to nucleus user exits. If the ADALNK has user exits, the addresses of the ACB and each buffer passed will be stored in this space. Also, if the ADALNK has declared LUSIZE and has user exits, this buffer size plus 64 bytes will also be stored in this space.

If the multifetch/prefetch option or a utility that needs large record/ISN buffers is to be used during the session, the setting of LU must be large enough to contain the buffers needed.

If you are using the ADARPD IQETBBROKERID NET communication (used with Event Replicator for Adabas), make sure that the webMethods EntireX Broker NET definition parameter IUBL is set to a value as large as the setting of this LU ADARUN parameter.

Notes:

1. An error occurs if the LU parameter specifies a value greater than the byte count implied by the NAB (number of attached buffers) parameter. On z/OS systems, LU cannot exceed a value greater than that produced by the following calculation: (NABvalue x 4096); on z/VSE and BS2000 systems, LU cannot exceed a value greater than that produced by the following calculation: (NABvalue x 4096) – 256. For more information about the NAB parameter, read NAB: Number of Attached Buffers.
2. Due to the length of the record buffer of the utilities that need the nucleus, e.g., ADAULD, the default value is set to 65,535. If the value of LU is less than 65,535 for an Adabas session, a response code will occur when such a utility is running.

The LU parameter syntax is:

LU={ n | 65535 }

Specific Product Recommendations

• For Event Replicator Server databases running with Adabas 8, the LU parameter must be greater than or equal to 167,000.

  In addition, if data is sent through Entire Net-Work from one or more Adabas nuclei to an Event Replicator Server, the Entire Net-Work LU parameter must be greater than or equal to the LU parameter setting for the Event Replicator Server itself (greater than or equal to 167,000).

• The ADACHK utility can use large record buffer lengths when making nucleus calls to verify spanned Data Storage records or an index structure with many levels. If this is the case, the settings of your LU and NAB ADARUN parameters may need to be increased.

Example

The following example runs the Adabas nucleus with an Adabas intermediate user buffer area of 20,000 bytes.

ADARUN PROG=ADANUC,LU=20000

LWKP2 Parameter: Length of ISN List Processing Area (Work Part 2)

This parameter specifies the size (in blocks) of the Adabas Work part 2, which holds intermediate ISN lists during Sx commands.

If LWKP2=0 (the default), Adabas calculates the Work part 2 size automatically using the following formula:

WORK2 = 22 + 2 * (4 * RECORDS / (BLKSIZE - 16))

where

If you choose not to use LWKP2=0, the minimum value is LWKP2=20 blocks.

Example:

For example, for the following Adabas session, the size of the Adabas Work part 2 is 50000 blocks.

ADARUN PROG=ADANUC,LWKP2=50000

LWP Parameter: Length of Adabas Work Pool

The Adabas work pool area is used to store the following:

• descriptor value tables (DVT);

• intermediate user buffer areas (see parameter LU);

• sort work space areas (see parameter LS);

• work space during session and command execution.

In environments running in 31-bit addressing mode, the work pool space is allocated above the 16-megabyte line.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session. If expanded files are being used, the LWP value may need to be increased above the normal setting.

Specific Product Recommendations

If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example runs the Adabas nucleus with a work pool of 900000 bytes.

ADARUN PROG=ADANUC,LWP=900000

MLWTO Parameter: Multi-Line Console Message Control

To activate multi-line console messages, set MLWTO to YES in the nucleus startup job. When MLWTO is set to NO (or is allowed to default), no multi-line console messages will appear.

Multi-line console messages are only supported in z/OS and z/VSE environments. Specifying MLWTO=YES in BS2000 environments has no effect on the console messages.

Example:

ADARUN PROG=ADANUC,MLWTO=YES

MODE Parameter: Mode of Operation

Note the following:

1. The MODE parameter does not affect parallel utility execution.

2. The nucleus cannot run in single-user mode (MODE=SINGLE cannot be specified) if it is to run

   • with Adabas Parallel Services or Adabas Cluster Services (NUCID 1)

   • with support for distributed transactions (DTP=RM)

   • as an Adabas Transaction Manager (DTP=TM)

   In addition, a valid Adabas SVC should be specified when running in single-user (MODE=SINGLE) mode.

3. When running several nuclei against the same database, only one update nucleus can be used.

Example

The following example runs the ADAINV utility in single-user mode.

ADARUN PROG=ADAINV,MODE=SINGLE,SVC=234

MSGBUF Parameter: Size of Message Buffer

MSGBUF specifies the size (in kilobytes) of the area used to buffer messages for use for performance and tuning and problem analysis. Adabas messages buffered in this area can be reviewed even when online access to the console or DDPRINT messages is unavailable. While the buffer is intended for messages written to the system log or DDPRINT, it can be used for any purpose by any caller.

MSGBUF presupposes that ADARUN SMGT=YES.

MSGBUF=0 (the default) means that message buffering is not active for the session.

To activate message buffering, set MSGBUF to a value greater than 0. Software AG recommends setting MSGBUF to 10 (kilobytes).

Message buffering can be temporarily disabled and subsequently reactivated using the SMGT operator command.

See the Adabas DBA Tasks Manual for more information about message buffering.

Example

The following example activates message buffering when the Adabas nucleus is initialized with a message buffer size of 10 KB.

ADARUN PROGRAM=ADANUC
  ADARUN SMGT=YES
  ADARUN MSGBUF=10

MSGCONSL Parameter: Case of Messages Sent to the Console
MSGDRUCK Parameter: Case of Messages Sent to DD/DRUCK
MSGPRINT Parameter: Case of Messages Sent to DD/PRINT

Adabas messages are displayed in mixed upper and lowercase. You can use one or more of these ADARUN parameters to display different message types in all uppercase.

Notes:

1. The first message line in DDPRINT will not be influenced by the value of parameter MSGPRINT.
2. Lowercase fields will not display correctly (they will be converted to uppercase) if you use the ADARUN parameter settings MSGCONSL=U, MSGDRUCK=U, or MSGPRINT=U.

Example

The following example will display messages in the DDDRUCK and DDPRINT data sets in all uppercase:

ADARUN MSGDRUCK=U,MSGPRINT=U

MXCANCEL Parameter: Timeout Threshold for Canceled Peer Nucleus

The optional MXCANCEL parameter specifies the maximum number of seconds for which one cluster nucleus (the sending nucleus) waits for the termination of another nucleus (the peer nucleus) in the cluster that it has canceled for not responding to an internal, intracluster command. If a value for MXCANCEL is not specified, the value specified for the ADARUN MXMSG parameter is used. Values from zero through 14 are not valid MXCANCEL values.

If the sending nucleus does not receive notification that the canceled nucleus has terminated within the MXCANCEL timeout period, it does one of the following things:

• It returns response code 124 (ADARSP124), subcode 28 (no reply) to the user on whose behalf the intracluster command was issued.

• It terminates itself abnormally if the communication occurred on behalf of an internal process that must not fail.

When a cluster nucleus fails, the other nuclei in the cluster can recover from the failure only once they know for sure that the first nucleus has disconnected from the shared structures and is no longer writing to the database. When an unresponsive cluster nucleus has been canceled, it is important that it terminate quickly, so that it does not hold up the recovery process performed by the other nuclei in the cluster.

The value for MXCANCEL can be changed dynamically (for the time the Adabas nucleus is running) using the MXCANCEL operator command.

MXCANCELWARN Parameter: Timeout Threshold for Canceled Peer Nucleus Warning

The optional MXCANCELWARN parameter specifies the number of seconds after an intracluster cancellation request is made when the cluster nucleus requesting the cancellation should issue warnings about the inability of the canceled peer nucleus to terminate. If no value is specified for the MXCANCELWARN parameter, the value used is calculated as the value of the ADARUN MXCANCEL parameter divided by four. When dividing by four to determine the default value, the quotient is rounded up to the next integer value.

The value of MXCANCELWARN must be less than the value of MXCANCEL. If MXCANCELWARN is set to a value greater than or equal to the value specified for MXCANCEL, the value is rejected. If MXCANCELWARN is set to a value of zero (0), no warnings are issued about canceled cluster nuclei that are slow to terminate.

If the target nucleus does not terminate within the time period set by MXCANCELWARN, the nucleus that issued the cancellation request writes message ADAX9G to the operator console, identifying the target nucleus by its nucleus ID, job name, and system name. This message indicates that the nucleus writing the message may be in danger of terminating itself if the canceled peer nucleus does not terminate within the timeout period defined by the MXCANCEL parameter. You can use the ADAX9G message to trigger an alert or take other appropriate action before the MXCANCEL timeout period expires.

If the peer nucleus targeted for cancellation terminates after the ADAX9G message is written, the nucleus that issued the cancellation request writes message ADAX9K to the operator console, indicating that the cancellation occurred and the requesting nucleus is no longer in danger of terminating itself as a result of this particular incident.

The value for MXCANCELWARN can be changed dynamically (for the time the Adabas nucleus is running) using the MXCANCELWARN operator command.

MXMSG Parameter: Timeout Threshold for Internucleus Command Processing

The optional MXMSG parameter specifies the maximum number of seconds in which one cluster nucleus waits for the response of another nucleus in the cluster to an internal, intracluster command. If a value for MXMSG is not specified, a value of 300 seconds (5 minutes) is used.

If the receiving nucleus does not respond to the intracluster command within the time period set by the MXMSG parameter, the requesting cluster nucleus issues a cancellation request for the unresponsive nucleus. The cancellation is requested to preserve the ability of all of the other active nuclei in the cluster to process user commands.

Adabas nuclei working on the same cluster database must collaborate to keep the database physically and logically consistent while processing user commands. To do this, they intermittently submit internal, intracluster commands to one another. If a nucleus in the cluster does not respond to these intracluster requests in a timely manner, the other nuclei in the cluster may quickly or gradually become unable to continue processing user commands.

Problems that may prevent a cluster nucleus from responding to intracluster commands fall into two broad categories:

• Problems have occurred in the cluster nucleus, such as a CPU loop or a resource deadlock. In such cases, the nucleus experiencing the problem must be terminated to resolve the problem and the sooner this happens, the sooner the other cluster nuclei can recover from the failure and get back to normal processing.

• Problems have occurred outside the cluster nucleus, such as CPU starvation or a problem in the host system. In such cases, the cause of the delayed response might possibly be removed by system measures unrelated to the cluster database, and letting the other cluster nuclei wait some time for a resolution might prevent an unnecessary abnormal termination of a cluster member.

The value of MXMSG should strike a balance between these two categories, so that faulty cluster nuclei that cannot possibly stay active are canceled reasonably quickly while cluster nuclei that are victims of temporary system problems are not unnecessarily terminated. For assistance in setting the value of the MXMSG parameter, review the statistics provided on the messaging performance reports produced at termination or by the DXMSG operator command.

The value for MXMSG can be changed dynamically (for the time the Adabas nucleus is running) using the MXMSG operator command.

MXMSGWARN Parameter: Timeout Threshold for Internucleus Command Processing Warning

The optional MXMSGWARN parameter specifies the number of seconds after an intracluster request is made when the cluster nucleus issuing the intracluster request should issue warnings about the failure of the target cluster nucleus to respond. If no value is specified for the MXMSGWARN parameter, the value used is calculated as the value of MXMSG divided by four. When dividing by four to determine the default value, the quotient is rounded up to the next integer value.

The value of MXMSGWARN must be less than the value of MXMSG. If MXMSGWARN is set to a value greater than or equal to the value specified for MXMSG, the value is rejected. If MXMSGWARN is set to zero, no warnings are issued about cluster nuclei that are slow to respond.

If the target nucleus does not respond within the time period set by MXMSGWARN, plus any extra time allowed for some types of requests (such as ET synchronization), the nucleus that issued the request writes message ADAX9C to the operator console, identifying the target nucleus by its nucleus ID, job name, and system name. This message indicates that the target nucleus may be in danger of being canceled by the nucleus that issued the request if it does not respond within the timeout period defined by the MXMSG parameter. You can use the ADAX9C message to trigger an alert or take other appropriate action before the MXMSG timeout period expires.

If the target nucleus responds to the intracluster command after the ADAX9C message is written, the nucleus that issued the intracluster-command writes message ADAX9D to the operator console, indicating that a response was given and the target nucleus is no longer in danger of being canceled as a result of this particular incident.

The value for MXMSGWARN can be changed dynamically (for the time the Adabas nucleus is running) using the MXMSGWARN operator command.

MXSTATUS Parameter: Member-Level XCF Status Monitoring Heartbeat Interval

The optional MXSTATUS parameter specifies the number of seconds between member-level XCF status monitoring heartbeats. If no value is specified for the MXSTATUS parameter, a value of "15" is used.

If MXSTATUS is set to zero, member-level status monitoring will not occur. However, system-level status monitoring always occurs.

The value for MXSTATUS can be changed dynamically (for the time the Adabas nucleus is running) using the MXSTATUS operator command.

XCF status monitoring provides a second method by which Adabas Cluster Services can warn you that a cluster nucleus might be unable to respond in a timely way to intracluster commands. The first method is, of course, via the normal intracluster communication that occurs between cluster members. If a nucleus has heartbeat exceptions (as determined by XCF status monitoring), it most likely will be unable to process and respond to an intracluster command; if a nucleus is slow to respond to an intracluster command, it might or might not have a heartbeat monitor exception (a nucleus may appear to be active to XCF but be unable to respond to an intracluster command). If the ADARUN MXMSGWARN parameter for a cluster nucleus is nonzero, it produces warning messages (ADAX9B or ADAX9C) when intracluster communication with other nuclei in the cluster is too slow; likewise, when XCF status monitoring determines that a nucleus is missing its heartbeat updates, it produces warning messages (ADAX22 and ADAX04). You can use an automated mechanism set up at installation to raise an alert or take other appropriate action based on the existence of these messages, as they identify existing or potential problems in the cluster.

MXTNA Parameter: Maximum Non-activity Time

The TNAx parameter specifies the maximum elapsed time (in units of 1.048576 seconds) that users may be considered active without issuing an Adabas command. Limits may be set for three types of user:

• the TNAA parameter for access-only users

• the TNAE parameter for ET logic users

• the TNAX parameter for exclusive control users

You can override these parameter settings for an individual user by specifying a different value in the Adabas control block of an OP command. See the discussion of the OP command in the Adabas Command Reference Guide.

For these parameters, the MXTNA parameter sets a limit on the amount of time that can be specified in the OP command for an individual user.

If the nonactivity time limit is exceeded, action is taken as described in Adabas Timeout Feature.

The value of the MXTNA parameter can only be set when the nucleus is started. It cannot be changed using operator commands or the ADADBS OPERCOM utility function.

Example

For example, during the following Adabas session, the nonactivity time limit for exclusive control users is about 5 minutes (300 seconds). This limit cannot be extended for an individual user beyond 8 minutes (480 seconds).

ADARUN PROG=ADANUC,TNAX=300,MXTNA=480

MXTSX Parameter: Maximum Sx Command Execution Time

The TLSCMD parameter specifies the maximum time (in units of 1.048576 seconds) to be used to process a single Adabas S1, S2, or S4 command with a complex search criterion.

If the estimated time to process a command exceeds the TLSCMD time limit, the command is not processed and the user who issued the command receives a nonzero response code.

If the estimated time to process a command does not exceed the time limit, the command is processed to completion, whether the actual time required exceeds the time limit specified by the TLSCMD or not.

You can override the TLSCMD parameter setting for an individual user by specifying a different value in the Adabas control block for an OP command. See the discussion of the OP command in the Adabas Command Reference Guide.

The MXTSX parameter sets the maximum time that can be specified for the TLSCMD parameter, including any override execution time setting specified in the Adabas control block of an OP command.

The value of the MXTSX parameter can only be set when the nucleus is started. It cannot be changed using operator commands or the ADADBS OPERCOM utility function.

Example

For example, during the following Adabas session, the Sx command execution time limit is about 1 hour 20 minutes (4800 seconds). This limit cannot be extended for an individual user beyond 2 hours (7200 seconds).

ADARUN PROG=ADANUC,TLSCMD=4800,MXTSX=7200

MXTT Parameter: Maximum Transaction Time

The TT parameter specifies the maximum elapsed time (in units of 1.048576 seconds) permitted for a logical transaction issued by an ET logic user. See ADARUN parameter TT for more information.

You can override this parameter setting for an individual user by specifying a different value in the Adabas control block of an OP command. See the discussion of the OP command in the Adabas Command Reference Guide.

The MXTT parameter sets a limit on the amount of time that can be specified in the OP command for an individual user.

The time measurement for a logical transaction starts when the first command that results in a record being placed in hold status is issued. It ends when an ET, BT, or CL command is issued.

If the transaction time limit is exceeded, action is taken as described in Adabas Timeout Feature.

The value specified for MXTT directly influences the required size of the Adabas parameter LP (length of the data protection area).

Software AG recommends that you set the MXTT parameter lower than the MXTNA parameter.

The value of the MXTT parameter can only be set when the nucleus is started. It cannot be changed using operator commands or the ADADBS OPERCOM utility function.

Example

For example, during the following Adabas session, the transaction time limit for ET logic users is about 3 minutes (180 seconds) and cannot be extended for an individual user beyond 5 minutes (300 seconds).

ADARUN PROG=ADANUC,TT=180,MXTT=300

MXWTOR Parameter: Self-Termination Operator Query Interval

The optional MXWTOR parameter specifies the maximum number of seconds that a cluster nucleus should wait for an operator response to a self-terminating operator query. If no value is specified for the MXWTOR parameter, a value of zero is used. Values from 1 through 14 are not valid MXWTOR values.

A cluster nucleus issues a self-terminating operator query to the console via message ADAX9J if a canceled peer nucleus remains active after the time period defined by the MXCANCEL parameter. The MXWTOR parameter specifies how long the nucleus should wait for a response to this query.

One way that the operator may reply to the ADAX9J message is to make sure that the canceled cluster nucleus mentioned in the message actually terminates; once this happens, the ADAX9J message is retracted automatically, an online recovery process is performed, and the nucleus that issued the ADAX9J message remains active.

If the operator does not respond to the ADAX9J message within the time period set by the MXWTOR parameter and the canceled peer nucleus has not terminated in the meantime, the nucleus that requested the operator response and printed message ADAX9J terminates itself with message ADAX99.

If MXWTOR is set to zero (the default), the operator query does not occur (no ADAX9J messages are written) and no operator intervention is expected. Instead, the nucleus terminates itself immediately with the ADAX99 message and user abend code 79.

Some installations may want to specify MXWTOR value long enough to allow the operator a good opportunity to bring down the canceled peer nucleus. Other installations may prefer not to get such operator queries at all.

The value for MXWTOR can be changed dynamically (for the time the Adabas nucleus is running) using the MXWTOR operator command.

NAB Parameter: Number of Attached Buffers

The NAB parameter defines the number of attached buffers to be used during the session. An attached buffer is an internal buffer used for interregion communication. It is required in all environments. Adabas allocates an attached buffer pool with a size equal to the value of NAB multiplied by 4096 bytes.

You may specify as many attached buffers as fit into the available virtual storage.

In environments running in 31-bit addressing mode, the attached buffer pool space is allocated above the 16-MB line.

The NAB parameter syntax is:

NAB={ n | 16 }

Specific Product Recommendations

• For Event Replicator Server databases, set parameter NAB to a value greater than or equal to: 41 * 10 * the-number-of-Adabas-nuclei-sending-data-to-the-Event-Replicator-Server.

  For example, if one Adabas nucleus will be sending data to the Event Replicator Server, set the NAB parameter greater than or equal to 410 (for example NAB=420).

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

• If data is sent through Entire Net-Work from one or more Adabas nuclei to an Event Replicator Server, the Entire Net-Work NAB parameter must also be set to a value greater than or equal to: 41 * 10 * the-number-of-Adabas-nuclei-sending-data-to-the-Event-Replicator-Server.

• Users of the Adabas Review hub should read Storage Requirements in the Adabas Review Concepts Manual for more information about the space requirements of the Command Queue for Adabas Review.

• The ADACHK utility can use large record buffer lengths when making nucleus calls to verify spanned Data Storage records or an index structure with many levels. If this is the case, the settings of your LU and NAB ADARUN parameters may need to be increased.

Example

The following example runs the Adabas Review hub nucleus with 50 attached buffers.

ADARUN PROG=ADAREV,NAB=50

NC Parameter: Number of Command Queue Elements

The number of command queue elements (CQEs) established for the Adabas or Review hub session determines the maximum number of Adabas commands that may be queued or be in process at any one time during the session.

Each call from the Adabas nucleus is assigned a CQE. The CQE is released when the user receives the results of the command, the Adabas Review hub has processed the command, or the user has been timed out..

192 bytes are required for each CQE.

Software AG recommends that you set NC high enough to allow one command per active user for possible synchronization during execution of the online SAVE database function of the ADASAV utility.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session.

For more information about the space requirements of the Command Queue for Adabas Review, refer to Storage Requirements in the Adabas Review Concepts Manual.

Specific Product Recommendations

• For Event Replicator Server databases, set parameter NC to a value greater than or equal to: 10 * the-number-of-Adabas-nuclei-sending-data-to-the-Event-Replicator-Server. For example, if one Adabas nucleus will be sending data to the Event Replicator Server, set the NC parameter greater than or equal to 10 (for example NC=20).

• If data is sent through Entire Net-Work from one or more Adabas nuclei to an Event Replicator Server, the Entire Net-Work NC parameter must also be set to a value greater than or equal to: 10 * the-number-of-Adabas-nuclei-sending-data-to-the-Event-Replicator-Server.

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example:

Run the Adabas nucleus with a maximum of 500 elements in the command queue.

ADARUN PROG=ADANUC,NC=500

The following example runs the Adabas Review hub nucleus with a maximum of 500 elements in the command queue.

ADARUN PROG=ADAREV,NC=500

NCLOG Parameter: Number of Command Log Data Sets

This parameter specifies the maximum number of command log data sets to be opened and logged in the parallel participant table (PPT) for the current nucleus. Valid values are 0 (the default) and 2-8. Other values produce a parameter error. A zero value disables the parameter.

If more than the number of log data sets specified in the NCLOG parameter are allocated in the startup JCL, only the number specified in the NCLOG parameter are opened and logged; any additional allocated data sets are activated using the dynamic allocation process.

NCLOG must be specified with a nonzero value in conjunction with the CLOGDEV, CLOGSIZE, and UEX12 parameters.

NCLOG is not valid if DUALCLD, DUALCLS, DUALPLD, DUALPLS, or UEX2 are specified.

UEX2 and UEX12 are mutually exclusive.

If a nonzero NCLOG, CLOGDEV, and CLOGSIZE are specified, but LOGGING=NO, Adabas attempts to open and log the number of data sets specified by NCLOG; however, no logging occurs until the LOGGING parameter has been set to YES using either an operator command or Adabas Online System.

Example

The following example runs the Adabas nucleus with command logging, uses six command log data sets, and uses a model 3380 device for command logging. The size of each command log data set is 1350 blocks, based on an allocation of 10 cylinders. (Each cylinder of a 3380 device has 15 tracks, and each track can contain 9 blocks of command log data. Thus, 10 cylinders = 10 15 9 = 1350 blocks).

ADARUN PROG=ADANUC,LOGGING=YES,NCLOG=6,CLOGDEV=3380,CLOGSIZE=1350

NH Parameter: Number of Hold Queue Elements

One hold queue element is required for each record (ISN) placed in hold status. A hold queue element is released when the record is released from hold status.

The hold queue is normally used to hold ISNs for the duration of a transaction. Therefore NH should be large enough to contain at least the average number of ISNs held per transaction multiplied by the maximum number of transactions running in parallel.

One hold queue element takes 52 bytes of storage. In environments running in 31-bit addressing mode, the hold queue is allocated above the 16-megabyte line.

Each shared hold request with a different command ID (CID), as well as a (shared or exclusive) hold request without a CID, is counted against the NH limit.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session.

Specific Product Recommendations

• Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server, causing replication data to be written and read from the SLOG file.

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example runs the Adabas nucleus with a maximum of 2000 elements in the hold queue.

ADARUN PROG=ADANUC,NH=2000

NISNHQ Parameter: Number of ISNs in Hold Queue per User

NISNHQ determines the maximum number of held ISNs the hold queue (see the NH parameter description) can contain from one user. The maximum value allowed for this parameter is the value set for the NH ADARUN parameter (which has a maximum value of 16777215). The default is the greater of either 20 or the number of ISNs the hold queue can contain divided by the number of users, multiplied by two.

A user who attempts to place more records in hold status than permitted receives response code 47 (ADARSP047), subcode 1.

Each shared hold request with a different command ID (CID), as well as a (shared or exclusive) hold request without a CID, is counted against the NISNHQ limit.

Specific Product Recommendations

Consider adjusting the value of this parameter when the SLOG file is defined for use on the Event Replicator Server, causing replication data to be written and read from the SLOG file.

Overriding the Parameter Setting

You can override this parameter setting for an individual user by specifying a different value in the Adabas control block for an OP command. See the discussion of the OP command in the Adabas Command Reference Guide.

Examples

In the following example, the maximum number of records that may be in hold status for a single user is set at 100.

ADARUN PROG=ADANUC,NISNHQ=100,NH=450...

In the following example, NISNHQ is not specified. The maximum number of records that may be in hold status for a single user is 80 (the NISNHQ default of (NH / NU) * 2, which is greater than the alternative default of 20).

ADARUN PROG=ADANUC,NU=50,NH=2000...

NONDES Parameter: Nondescriptor Searches

By default, you can perform searches on Adabas fields that have not been defined as descriptors. However, nondescriptor searches carry significant overhead.

NONDES=NO prevents searches on nondescriptors. An attempt to search on a nondescriptor field produces response code 68 (ADARSP068).

Example

The following example disallows searches using nondescriptors.

ADARUN PROG=ADANUC,NONDES=NO

NPLOG Parameter: Number of Protection Log Data Sets

This parameter specifies the maximum number of protection log data sets to be opened and logged in the parallel participant table (PPT) for the current nucleus. Valid values are 0 (the default) and 2-8. Other values produce a parameter error. A zero value disables the parameter.

If more than the number of log data sets specified in the NPLOG parameter are allocated in the startup JCL, only the number specified in the NPLOG parameter are opened and logged; any additional allocated data sets are activated using the dynamic allocation process.

NPLOG must be specified with a nonzero value in conjunction with the PLOGDEV, PLOGSIZE, and UEX12 parameters.

NPLOG is not valid if DUALCLD, DUALCLS, DUALPLD, DUALPLS, or UEX2 are specified.

UEX2 and UEX12 are mutually exclusive.

Example

The following example runs the Adabas nucleus with six data protection log data sets and uses a model 3380 device. The size of each log data set is 1200 blocks, based on an allocation of 10 cylinders. (Each cylinder of a 3380 device has 15 tracks, and each track contains 8 blocks of protection log data. Thus, 10 cylinders = 10 * 15 * 8 = 1200 blocks).

ADARUN PROG=ADANUC,NPLOG=6,PLOGDEV=3380,PLOGSIZE=1200

NPLOGBUFFERS Parameter: PLOG Protection I/O Buffer Control

PLOG protection I/O buffers are only allocated when ADARUN parameter LFIOP is set to a nonzero value. The realistic maximum setting of the NPLOGBUFFERS parameter is limited by the available amount of virtual and real memory. The number of protection I/O buffers allocated is limited to the number of PLOG blocks available on the dual/OCTO PLOG data sets (see the related ADARUN parameters DUALPLS and PLOGSIZE).

To determine the setting for NPLOGBUFFERS, look at the related high-water mark shown in the output of the DRES operator command or in the nucleus shutdown statistics. If the related high-water mark hits 100%, consider increasing the size of NPLOGBUFFERS

The use of the NPLOGBUFFERS parameter may considerably improve performance in update intensive applications that were formerly constrained by writes to the PLOG. When NPLOGBUFFERS is greater than 1, multiple PLOG blocks may be written in one write I/O to the PLOG.

In environments running in 31-bit addressing mode, the PLOG protection I/O buffers are allocated above the 16-megabyte line.

In environments supporting 64-bit virtual storage, the PLOG protection I/O buffers are allocated above the 2 gigabyte bar when the V64BIT ADARUN parameter is set to "YES".

Example

The following example sets the number of PLOG protection I/O buffers to 5.

ADARUN PROG=ADANUC,NPLOGBUFFERS=5

NQCID Parameter: Number of Active Command IDs per User

The table of sequential commands contains the control blocks for sequential read operations. Each operation is identified by a command ID (CID). NQCID defines the total number of CIDs allowed per user, and therefore the maximum number of table elements the user has available at any point in time.

Overriding the Parameter Setting

You can override this parameter setting for an individual user by specifying a different value in the Adabas control block for an OP command. See the discussion of the OP command in the Adabas Command Reference Guide.

Example

The following example sets the maximum number of parallel sequential processes per user to 25.

ADARUN PROG=ADANUC,NQCID=25,NU=200,LQ=3000

Since one element in the sequential command table occupies approximately 100 bytes (varies depending on the command type; see the description of the LQ parameter), NQCID=25 limits each user to approximately 2500 bytes of the table.

NSISN Parameter: Number of ISNs per ISN Table Element

The parameter NSISN specifies the maximum number of ISNs kept in a TBI element in memory (list of resulting ISN lists). The more ISNs that are kept in memory, the fewer the Work I/Os needed to read additional resulting ISN lists from the Work data set. This parameter influences the performance of the L1/4 command with the N (GET NEXT) option.

The highest value that can be specified for NSISN depends on the Work device. For Adabas-specified Work block sizes, the maximum values are shown in the device tables provided later in this section. However, the tables do not apply to user-defined Work block sizes; in this case, the maximum is determined as follows, where WORK is the block size of the Work data set:

• (WORK - 6) / 4

• The TBI element has a length of 64 + (NSISN * 4) bytes in the TBI pool (see the LI parameter).

IBM and Compatible Devices

Overriding the Parameter Setting

You can override this parameter setting for an individual user by specifying a different value in the Adabas control block for an OP command. See the discussion of the OP command in the Adabas Command Reference Guide.

Example

In the following example, the maximum number of ISNs per TBI element during the Adabas session is set to 400.

ADARUN PROG=ADANUC,NSISN=400

NT Parameter: Number of Threads

A thread is used to execute a single command for any user (access or update). Each thread requires 8192 bytes.

In environments running in 31-bit addressing mode, the threads are allocated above the 16-megabyte line.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session.

For Event Replicator Server databases, this parameter must be greater than or equal to 15.

Specific Product Recommendations

• For Event Replicator Server databases, the NT parameter must be greater than or equal to 15.

• If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example runs the Adabas nucleus with six (6) user threads.

ADARUN PROG=ADANUC,NT=6

NU Parameter: Number of User Queue Elements

Adabas assigns a user queue element (UQE) to each active user when the user issues an OP command or (if the user did not issue an OP command) the first Adabas command.

Adabas releases the UQE when the user issues a CL command or when there is a timeout for an ET logic user who did not specify a restart ID in the control block (Additions 1 field) for the OP command.

Currently, 272 * (NU + 4) bytes are allocated to the user queue. The length of each UQE is 288 bytes.

In environments running in 31-bit addressing mode, the user queue is allocated above the 16-megabyte line.

Because each user's file list can be a different size, the number of users who can be active at the same time may be less than the NU value. Therefore, you may need to specify an NU value that is greater than the maximum number of users desired.

The Adabas session statistics or Adabas Online System can be used to tune this parameter for the next session.

Specific Product Recommendations

If the Event Replicator Server is set to support updates by multiple concurrent users to Adabas targets (when the NPADACALLS initialization parameter is set to any value greater than "1"), consider adjusting the value of this parameter in the target Adabas nucleus to ensure the target nucleus can handle updates from multiple concurrent users.

Example

The following example runs the Adabas nucleus with a maximum of 500 elements in the user queue.

ADARUN PROG=ADANUC,NU=500

NUCID Parameter: Adabas Cluster Nucleus ID

NUCID identifies an Adabas cluster nucleus. The cluster may span operating system images under Adabas Cluster Services, or it may be confined to a single operating system image under Adabas Parallel Services. A value greater than 0 (the default) identifies this nucleus as an Adabas cluster nucleus.

Guidelines

• Each nucleus being run must have its own Work data set.

• All nuclei in a cluster must be run against the same database.

• Software AG strongly recommends that you run utilities or user applications against a nucleus in the local z/OS image. Although a remote open nucleus may be used, performance degradation due to network overhead is likely.

Example

The following example starts an Adabas cluster session with the specified cluster nuclei:

ADARUN PROG=ADANUC,NUCID=1, ...

NWORK1BUFFERS Parameter: Work Part 1 Protection I/O Buffer Control

Work part 1 protection I/O buffers are only allocated when ADARUN parameter LFIOP is set to a nonzero value. The realistic maximum setting of the NWORK1BUFFERS parameter is limited by the available amount of virtual and real memory. The number of protection I/O buffers allocated is limited to the number of Work part 1 blocks available (see the related ADARUN LP parameter).

To determine the setting for NWORK1BUFFERS, look at the related high-water mark shown in the output of the DRES operator command or in the nucleus shutdown statistics. If the related high-water mark hits 100%, consider increasing the size of NWORK1BUFFERS

The use of the NWORK1BUFFERS parameter may considerably improve performance in update intensive applications that were formerly constrained by writes to Work part 1. When NWORK1BUFFERS is greater than 1, multiple Work part 1 blocks may be written in one write I/O to the Work data set.

In environments running in 31-bit addressing mode, the Work part 1 protection I/O buffers are allocated above the 16-megabyte line.

In environments supporting 64-bit virtual storage, the Work part 1 protection I/O buffers are allocated above the 2 gigabyte bar when the V64BIT ADARUN parameter is set to "YES".

Example

The following example sets the number of Work part 1 protection I/O buffers to 5.

ADARUN PROG=ADANUC,NWORK1BUFFERS=5

OPENRQ Parameter: Open Command Required

This parameter may be used to indicate whether an open (OP) command must be issued as the first command of a user session.

Example

The following example specifies that the first session command issued by users does not have to be an OP command.

ADARUN PROG=ADANUC,OPENRQ=NO

PAMREQS Parameter: Maximum PAM Blocks for One PAM Macro

This parameter is valid on BS2000 systems only.

Using this parameter, you can set a reduced default to avoid the receipt of I/O errors DMS09AC (too many simultaneous I/O requests on some machines).

Example

The following example specifies that the maximum number of PAM blocks that can be transferred in a PAM macro request is 50.

ADARUN PROG=ADANUC,PAMREQS=50

PGFIX Parameter: EXCPVR Page Fixing Control

This parameter is only valid for z/OS users using EXCPVR (for example, when running the Adabas nucleus or utility jobs APF-authorized). It allows you to control how page-fixing occurs when EXCPVR is in use. When PGFIX=NO is specified, pages containing the I/O control blocks are fixed only for the duration of the I/O processing. When PGFIX=YES is specified, pages containing the I/O control blocks are fixed for the duration of the job.

PLOGDEV Parameter: Multiple Protection Log Device Type
PLOGSIZE Parameter: Multiple Protection Log Size

The PLOGDEV and PLOGSIZE parameters specify the type of external storage device used for multiple data protection log data sets and the number of blocks available for each log data set. These parameters must be used together; if you specify one parameter, you must also specify the other parameter.

You must also specify the NPLOG parameter to use multiple protection logs. If you specify a user exit, it must by UEX12. See Adabas Restart and Recovery, for information about multiple data set protection logging.

The Adabas Installation documentation specifies the device types that Adabas supports.

All protection log data sets must be formatted using the ADAFRM utility before they are used. The appropriate JCL for the data sets is required.

Example

The following example runs the Adabas nucleus with six (6) data protection log data sets and uses a model 3380 device. The size of each log data set is 1200 blocks, based on an allocation of 10 cylinders. (Each cylinder of a 3380 device has 15 tracks, and each track contains 8 blocks of protection log data. Thus, 10 cylinders = 10 * 15 * 8 = 1200 blocks).

ADARUN PROG=ADANUC,NPLOG=6,PLOGDEV=3380,PLOGSIZE=1200

PLOGRQ Parameter: Protection Log Required

The valid values are as follows:

Example

The following example indicates that a data protection log (SIBA or PLOG) is not mandatory during the Adabas session but will be used if provided.

ADARUN PROG=ADANUC,PLOGRQ=NO

PREFETCH Parameter: Activate Prefetch Feature

This parameter determines whether the Adabas prefetch feature is enabled automatically; if it is, execution is transparent to the user program.

There are two Adabas prefetch options: the multifetch option is supported across Adabas platforms; the prefetch option is available only on mainframe Adabas. For information about these two options, see the Adabas Command Reference Guide.

Records can be prefetched and stored in a prefetch buffer for the following commands:

• L1/L4 with I or N option (read by ISN, find with GETNEXT)

• L2/L5 (read physical)

• L3/L6 (read logical by descriptor)

• L9 (histogram)

Sequential commands of the types listed above can retrieve the next record from the prefetch buffer, which saves cross-region/cross-network calls to the nucleus.

The PREFETCH parameter has the following values:

Examples

The following example runs a user program using multifetch.

ADARUN PROG=USER,PREFETCH=YES

The following example runs a user program using prefetch.

ADARUN PROG=USER,PREFETCH=OLD

PREFICMD Parameter: Include Commands in Prefetch/Multifetch Processing
PREFIFIL Parameter: Include Files in Prefetch/Multifetch Processing

Together, PREFIFIL and PREFICMD specify one or more files to be included in prefetch/multifetch processing. PREFIFIL specifies one or more files by file number; PREFICMD specifies a command for each file number.

You can either include list of files using PREFIFIL/PREFICMD or exclude lists of files using the parameters PREFXFIL/PREFXCMD), depending on which list is shorter. You cannot both include and exclude files at the same time.

If prefetching/multifetching has been specified and

• files/commands have been neither included nor excluded, the prefetching/multifetching applies to all files by default.

• files/commands have been included using the ADARUN parameters PREFIFIL/PREFICMD, the prefetching/multifetching applies only to the files on the inclusion list.

• both PREFIFIL/PREFICMD and PREFXFIL/PREFXCMD are specified, Adabas recognizes the exclusion parameters PREFXFIL/PREFXCMD and ignores the inclusion parameters PREFIFIL/PREFICMD.

Multiple Inclusions

Specify multiple file numbers in multiple PREFIFIL statements or in a list, separated by commas. Specify multiple commands in multiple PREFICMD statements or in a list, separated by slashes (/). The maximum number of entries for each is 50.

If you use lists, they must have the same number of entries. There is a one-to-one correspondence, by position, between a file number in the PREFIFIL list and a command in the PREFICMD list.

Eligible Commands and Command Pairs

The following commands can be included in prefetch/multifetch processing for a file:

• L1/L4

• L2/L5

• L3/L6

• L9

If either command in one of the pairs above is specified in a PREFICMD statement, both commands are included. For example, if PREFICMD=L1 is specified, both L1 and L4 are included.

Examples

The following example includes the L3 command for file 8 in prefetch processing.

ADARUN PREFIFIL=8,PREFICMD=L3

The following example includes the L3 command for file 8 and the L3 and L9 commands for file 12 in prefetch/multifetch processing. As this example shows, you can specify the same file number several times, with a different command each time. Likewise, you can specify the same command code several times, with a different file number each time.

ADARUN PREFIFIL=8,12,12,PREFICMD=L3/L3/L9

or

ADARUN PREFIFIL=8,PREFICMD=L3
  ADARUN PREFIFIL=12,PREFICMD=L3
  ADARUN PREFIFIL=12,PREFICMD=L9

The following example executes a user program with multifetch and allocates 20000 bytes for the total prefetch buffer area. It includes the L3 and L6 commands for files 8 and 12 in multifetch processing and it includes all commands for file 7. No PREFSBL value is specified, so the buffer length for a single prefetch sequence defaults to 3000 bytes; up to 6 prefetch sequences can be handled.

ADARUN PROG=USER,PREFETCH=YES,PREFTBL=20000
  ADARUN PREFIFIL=8,12,PREFICMD=L3/L3
  ADARUN PREFIFIL=7,7,7,7,PREFICMD=L1/L2/L3/L9

PREFNREC Parameter: Multifetch Record Count

This parameter specifies the maximum number of records that the multifetch feature (specified by the PREFETCH=YES parameter) obtains.

In mode PREFETCH=YES the maximum that can be specified depends on the maximum that can be held by the record and multifetch buffers.

In mode PREFETCH=OLD the maximum that can be specified depends on the maximum that can be held by the record and ISN buffers, each of which is assumed to be less than 32 kilobytes.

If no value or zero (the default) is specified, the sizes of the ISN and record buffers determine the number of records that are prefetched. Specifying zero (0) does not disable multifetch operation.

Example

The following example enables the multifetch feature and allows a maximum of 32 records to be prefetched.

ADARUN PROG=USER,PREFETCH=YES,PREFNREC=32

PREFSBL Parameter: Prefetch Buffer Length per Call

The PREFSBL parameter specifies the size of an internal buffer that the multifetch/prefetch feature uses to prefetch data for a single sequential read command. By setting of this buffer size you control the maximum amount record data that is prefetched. See also the description of the PREFTBL parameter, which specifies the total buffer space used by prefetch/multifetch.

When prefetch or multifetch is active, Adabas makes a buffer available to the user program for storing prefetched records on the client side. If a required record is already in a prefetch buffer, the record is taken directly from the buffer.

The following formula can be used to estimate the approximate maximum number of records (n) that will be prefetched.

In mode PREFETCH=OLD:

600 + FBL + ((RBL * 3) * n) = PREFSBL

In this calculation, FBL is the length of the format buffer and RBL is the length of the record buffer.

The 32K buffer size limit will limit the maximum number of prefetched records to:

MAX(n) = 32768 / RBL 

In mode PREFETCH=YES:

1400 + FBL + ((RBL * 3) * n) = PREFSBL

In this calculation, FBL is the length of the format buffer and RBL is the length of the record buffer.

For long sequential processes, this parameter should be as large as possible unless the sequential processes are frequently interrupted with value start (L3/L6) or RC commands; in that case, a large value often causes records to be prefetched needlessly.

Example

The following example executes a user program using multifetch and uses a 15000-byte prefetch buffer.

ADARUN PROG=USER,PREFETCH=YES,PREFSBL=15000

PREFSTDD Parameter: Multifetch Statistics DD Name

The PREFSTDD parameter specifies the job control statement label (DD name) in the nucleus startup job that defines the location to which multifetch statistics should be written when multifetch statistics are printed. The length of the job statement label (DD name) is limited to seven (7) characters.

When PREFSTDD is specified, the ADARUN PREFETCH parameter must be set to "YES".

Multifetch statistics are written when a CL command is issued. If no CL command is issued, no multifetch statistics are produced. If multiple CL commands are issued, multiple multifetch statistics are produced. The first multifetch statistics contains the values cumulated since start of job. The second and following multifetch statistics contain the values cumulated since start of job and the interval from the last Close command.

Example 1

The following example executes a user program using multifetch, uses a 15,000-byte prefetch buffer, and writes multifetch statistics to the output location identified by the STATDD job control statement:

ADARUN PROG=USER,PREFETCH=YES,PREFSBL=15000,PREFSTDD=STATDD

On z/OS, the STATDD job control statement that accompanies these ADARUN parameters might simply indicate that multifetch statistics should be written to SYSOUT:

//STATDD    DD SYSOUT=*

Alternatively, the STATDD job control statement on z/OS that accompanies these ADARUN parameters might specify a specific data set:

//STATDD    DD DISP=(NEW,CATLG),DSN=ADABAS.MLF.STATS,
//             UNIT=SYSDA,SPACE=(TRK,(1,1),RLSE),
//             DCB=(RECFM=FB,LRECL=121,BLKSIZE=1210)

On BS2000, the STATDD must be a file. This would be defined in the job as follows:

/DELETE-FILE ADABAS.MLF.STATS
 /SET-JOB-STEP
 .
 .
 /SET-FILE-LINK STATDD,ADABAS.MLF.STATS,REC-FORM=F(REC-SIZE=80) 

The following is an example of the multifetch statistics output produced:

ADAML1 +--------------------------------------------------------+
ADAML1 +                                                         
ADAML1 + A D A M L F   V833   S T A T I S T I C S                
ADAML1 +                                                         
ADAML1 + Cumulated since start of Job                            
ADAML1 +--------------------------------------                   
ADAML1 + Percentage of PREFTBL used          :        50.00      
ADAML1 + Number of calls to ADAMLF           :         2007      
ADAML1 + Number of cmds to ADABAS            :           43      
ADAML1 + Number of cmds returned from ADAMLF :         1998      
ADAML1 + Number of over reads                :            0      
ADAML1 +                                                         
ADAML1 +--------------------------------------------------------+

On VSE, multifetch statistics are written to SYSLST. Users should specify ADARUN parameter PREFSTDD=STATDD. No job control statement changes are required.

Example 2

The following example executes a user program issuing three Close commands, using multifetch, uses a 15,000-byte prefetch buffer, and writes multifetch statistics to the output location identified by the STATDD job control statement (like Example 1):

ADARUN PROG=USER,PREFETCH=YES,PREFSBL=15000,PREFSTDD=STATDD

//STATDD    DD DISP=MOD,DSN=ADABAS.MLF.STATS

The following is an example of the multifetch statistics output produced:

ADAML1 +--------------------------------------------------------+
ADAML1 +                                                         
ADAML1 + A D A M L F   V833   S T A T I S T I C S                
ADAML1 +                                                         
ADAML1 + Cumulated since start of Job                            
ADAML1 +--------------------------------------                   
ADAML1 + Percentage of PREFTBL used          :        50.00      
ADAML1 + Number of calls to ADAMLF           :         2007      
ADAML1 + Number of cmds to ADABAS            :           43      
ADAML1 + Number of cmds returned from ADAMLF :         1998      
ADAML1 + Number of over reads                :            0      
ADAML1 +                                                         
ADAML1 +--------------------------------------------------------+
ADAML1 +--------------------------------------------------------+
ADAML1 +                                                         
ADAML1 + A D A M L F   V833   S T A T I S T I C S                
ADAML1 +                                                         
ADAML1 + Cumulated since start of Job                            
ADAML1 +--------------------------------------                   
ADAML1 + Percentage of PREFTBL used          :        50.00      
ADAML1 + Number of calls to ADAMLF           :         4015      
ADAML1 + Number of cmds to ADABAS            :           86      
ADAML1 + Number of cmds returned from ADAMLF :         3996      
ADAML1 + Number of over reads                :            0      
ADAML1 +                                                         
ADAML1 + Cumulated since last Close cmd (1)                      
ADAML1 +--------------------------------------                   
ADAML1 + Percentage of PREFTBL used          :        50.00      
ADAML1 + Number of calls to ADAMLF           :         2008      
ADAML1 + Number of cmds to ADABAS            :           43      
ADAML1 + Number of cmds returned from ADAMLF :         1998      
ADAML1 + Number of over reads                :            0      
ADAML1 +                                                         
ADAML1 +--------------------------------------------------------+
ADAML1 +--------------------------------------------------------+
ADAML1 +                                                         
ADAML1 + A D A M L F   V833   S T A T I S T I C S                
ADAML1 +                                                         
ADAML1 + Cumulated since start of Job                            
ADAML1 +--------------------------------------                   
ADAML1 + Percentage of PREFTBL used          :        50.00      
ADAML1 + Number of calls to ADAMLF           :         6023      
ADAML1 + Number of cmds to ADABAS            :          122      
ADAML1 + Number of cmds returned from ADAMLF :         5994      
ADAML1 + Number of over reads                :            0      
ADAML1 +                                                         
ADAML1 + Cumulated since last Close cmd (2)                      
ADAML1 +--------------------------------------                   
ADAML1 + Percentage of PREFTBL used          :        50.00      
ADAML1 + Number of calls to ADAMLF           :         2008      
ADAML1 + Number of cmds to ADABAS            :           36      
ADAML1 + Number of cmds returned from ADAMLF :         1998      
ADAML1 + Number of over reads                :            0      
ADAML1 +                                                         
ADAML1 +--------------------------------------------------------+

The following table describes these statistics:

The version is adapted with every change of the release.

PREFTBL Parameter: Total Size of Prefetch Buffer

PREFTBL specifies the size of the total prefetch buffer area for this operation. This buffer length should be large enough to hold the PREFSBL-specified value, multiplied by the number of command-ID-controlled sequential prefetches for this operation. This allows a user program to perform multiple sequential operations requiring prefetches, each with a prefetch buffer of the size specified in the PREFSBL parameter.

If this user program has a single prefetch sequence only, the PREFTBL value must be equal to or greater than the PREFSBL value. The PREFTBL-specified space is always allocated to the program.

Example

The following example executes a user program using multifetch. No PREFSBL value is specified, so this example uses the default buffer length for a single prefetch (3,000 bytes). It also allocates 30000 bytes for the total prefetch buffer area; this size provides buffer space for up to 10 prefetch sequences.

ADARUN PROG=USER,PREFETCH=YES,PREFTBL=30000

PREFXCMD (PREFXFIL) Parameters: Exclude Commands (Files) from Prefetch/Multifetch Processing