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

This section describes the initialization parameters needed for an Adabas Cluster Services environment.

This document covers the following topics:

• ADARUN Initialization Parameters

• ADACOM Initialization Parameters

• ADANUC Initialization Parameters for Cluster Nuclei

• NETWRK Initialization Parameters for Entire Net-Work

ADARUN Initialization Parameters

ADARUN parameters are used to customize the Adabas environment. See the Adabas Operations documentation for information about ADARUN parameters and the format of ADARUN control statements.

For Adabas Cluster Services environments, three types of initialization parameters must be set based on the ADARUN parameter PROGRAM:

PROGRAM - Execute an ADARUN Program

The PROGRAM parameter is used to specify the name of the program being run, and must always be specified. There is no default.

• To run an Adabas nucleus, the name must be "ADANUC".

• To set up an Entire Net-Work node, the name must be "NETWRK".

• To set up an ADACOM task, the name must be ADACOM (no other ADARUN parameters are recognized for the ADACOM program run).

ADACOM Initialization Parameters

An unlimited number of Adabas nucleus clusters, each with up to 32 members sharing a common database, can be defined per parallel sysplex.

The ADACOM initialization task

• must be run on any operating system image that has cluster users but no cluster nuclei to set up the environment.

• can optionally be used to monitor and control the nuclei of one or more sysplex clusters.

Parameters specify the SVC/DBID combinations (sets) that the ADACOM is to manage. The DBID identifies the external physical database shared by a particular cluster of nuclei and known to the application. The SVC value may vary within a cluster and the same SVC may be used for different clusters. Other ADACOM parameters are discussed in the following sections.

Although a single ADACOM job can run all SVC/DBID sets in a sysplex environment, it is possible to run multiple ADACOM tasks simultaneously with the same, mixed, or completely different SVC/DBID sets. A subtask is attached to the ADACOM task for each SVC/DBID set occurring in the input of ADACOM. All work pertaining to an SVC/DBID set is performed by the subtask.

The COMPRINT dataset prints global messages that apply to all SVC/DBID sets defined to an ADACOM task. In addition, a SYSOUT dataset is dynamically allocated for command output to each SVC/DBID set. The format of this dataset DD-name is 'Pssddddd' where 'ss' is the last two digits of the SVC and 'ddddd' is the DBID.

For a sample job to run ADACOM, see the section Create a Start-up Procedure for ADACOM in the Installation documentation.

CMDMGR - ADACOM Use

The CMDMGR parameter specifies whether the ADACOM task remains in operation as a command manager for the cluster nuclei (CMDMGR=YES) or whether it runs like a batch job and terminates after processing the commands given in DD/KARTE (CMDMGR=NO).

DBID - Database Identification

The DBID parameter designates the ID of an Adabas cluster's external physical database; that is, the database number that the user programs address to send commands to the single physical database of an Adabas nucleus cluster.

This number must be unique among all Adabas database IDs, NUCIDs, Natural buffer pool IDs, Entire Net-Work target IDs (suggested range 65482-65535), and internal target IDs used by Adabas Cluster Services (restricted range 65001-65481).

FORCE - Force Restart after Abnormal Termination

If Adabas believes there are still active nuclei, ADACOMs, or users on an image after a termination, an NU parameter value that is different from the NU value already in effect will not be recognized on restart. If you are certain that Adabas is wrong in its belief, you can use FORCE=YES to force a clean restart.

Note, however, that if a sysplex cluster nucleus or an ADACOM with the same SVC number is active on the image where FORCE=YES is used, it will crash.

Notes:

1. FORCE=YES works only when the NU parameter value is being changed and has the effect of resetting the environment.
2. The nucleus ADARUN parameter FORCE is neither seen nor used by the Adabas Cluster Services SVCCLU. The ADACOM parameter FORCE may only be used to change the NU that is valid for the cluster.
3. If you use the ADACOM FORCE parameter, remember to remove it from ADACOM after you have reset the environment.

NU - Number of User Table Elements

In the extended CSA (ECSA), the SVCCLU maintains a user table with entries (UTEs) containing information about every active user in the sysplex cluster nuclei on the local image. A UTE is assigned when a user issues an OP command or (if the user did not issue an OP command) at the first Adabas command. The UTE is released when the user issues a CL command or when the assigned cluster nucleus otherwise deletes the user's UQE (e.g., due to timeout).

The ADACOM NU parameter specifies the number of concurrent users (UTEs) allowed for all cluster nuclei on the local operating system image. The first cluster nucleus or ADACOM started governs the value for NU: different values set for subsequent nuclei or ADACOMs are ignored.

To manually change the NU value, you must stop all sysplex cluster nuclei and ADACOM initialization tasks (if used) in the local image that have the same SVC number, modify the NU value for all the nucleus and ADACOM jobs, and then restart.

When the NU parameter is set to zero, any space allocated for the user table is freed, the Adabas Cluster Services control block (PLXCB) is freed, and the ADACOM subtask for this SVC/DBID set terminates, regardless of the CMDMGR parameter setting. However, if the ADACOM subtask believes that there are active nuclei or users on this database, and FORCE=YES is not used, no action is taken and the subtask terminates abnormally with user ABEND 40 (hex). The ADACOM main task and any subtasks handling other SVC/DBID sets are not affected.

Example:

Run the Adabas cluster nuclei on the local image with 500 elements in the user table.

NU=500

SVC - Interregion Communication Number

The SVC is used to perform various Adabas internal functions; the number is used to communicate between the users and the database.

The SVC number is specified as an integer and must correspond to the number used for the version 7.4 Adabas SVC (ADASVC). Valid SVC values are 200-255.

Example:

Execute an Adabas Cluster Services session under an OS/390 or z/OS image using SVC 202.

SVC=202

ADANUC Initialization Parameters for Cluster Nuclei

Software AG recommends that you use your existing values (or the default settings) of the Adabas ADARUN parameters for each Adabas nucleus in a cluster, and then tune the values after analyzing the performance of the cluster. See the Performance and Tuning documentation for information about expected differences.

Session statistics can be used to determine the best settings for each parameter. The statistics are printed automatically at the end of a session, but can also be displayed using nucleus or ADACOM operator commands during the session.

Global ADARUN Parameters

ADARUN parameters that must be the same for all nuclei in the cluster are called "global".

Some global parameters are set at nucleus startup and cannot be changed during the ensuing session; other global parameters can be changed during a session.

Changing Parameter Values at Nucleus Startup

After the first nucleus in an Adabas cluster starts, XCF messages are used to communicate the ADARUN parameter settings of the first nucleus to all subsequent cluster nuclei. Each following nucleus receives this information during initialization and determines whether its global nonchangeable parameters are equal to those of the first nucleus.

If they are not equal, the nucleus fails with a parameter error. The nonequal global changeable parameters are reset to the value retrieved from the XCF messages and a corresponding message is printed.

Changing Parameter Values during a Session

On a running system, a cluster nucleus may want to modify one or more of the "changeable" global parameters. This nucleus acquires a "parameter change lock", makes the changes in its local parameter area, and communicates the changes to the other cluster nuclei using XCF messages.

All other nuclei in the cluster receive the XCF messages containing the global parameters that have changed, change the parameters in their local parameter area, and send the "acknowledge" message.

Parameter Types

A cluster nucleus requires

• global parameters. Adabas Cluster Services enforces the same value for all nuclei in a cluster. Some of these parameters are modifiable (GM) during a session using an operator command or AOS (NISNHQ, NONDES, and AOSLOG are only modifiable using AOS); others are fixed (GF) and cannot be modified.

• local parameters, which can be different for each nucleus. Some of these parameters are modifiable (LM) using an operator command or AOS; others are fixed (LF) and cannot be modified.

A few Adabas ADARUN parameters are not available to a cluster nucleus (No).

Parameter Directory

Note:
All Adabas Caching Facility ADARUN parameters are supported as local, modifiable parameters.

Note:
* Adabas Cluster Services 7.4 does not support DTP=TM or DTP=RM. It does support DTP=ET, which is a parameter setting that must be the same for all cluster nuclei and cannot be changed online (global, fixed). ** The PREFxxx parameters are used with application programs (PROGRAM=USER) making Adabas calls. They have no effect when specified for an Adabas nucleus.

Specifying ADARUN Parameters for Cluster Nuclei

When specifying ADARUN session parameters for Adabas cluster nuclei:

• ensure that the correct program to be executed is specified (PROG=ADANUC); and

• determine which setting is applicable for the SVC parameter for the session.

The parameters CLOGMRG, CLUCACHENAME, CLUGROUPNAME, CLULOCKNAME, CLUSTER, DIRRATIO/ELEMENTRATIO, LRDP, MXMSG, and NUCID are used to set up the Adabas Cluster Services sysplex cluster nucleus and its environment.

If protection logs are used in a cluster environment, they must be dual or multiple logs and all nuclei must use them. All cluster nuclei must have the same PLOGRQ setting.

If command logs are used, each nucleus must have its own. If command logs are to be merged, they must be dual or multiple logs and all nuclei must use them. All cluster nuclei must have the same CLOGMRG setting.

The remaining Adabas cluster nucleus parameters are the same as those of a standard Adabas nucleus. See the Adabas Operations documentation for more information.

NETWRK Initialization Parameters for Entire Net-Work

The ADARUN parameters for Entire Net-Work specify all interregion communication information for the node. They are specified with ADARUN PROGRAM=NETWRK.

Software AG recommends that you use your existing values (or the default settings) of the ADARUN parameters for each Entire Net-Work node, and then tune the values after analyzing the performance of the node. See the Performance and Tuning documentation for information about expected differences.

The following table summarizes the Entire Net-Work ADARUN parameters:

* Software AG strongly recommends that you restrict Entire Net-Work target IDs in a sysplex cluster environment to values in the range 65482 through 65535 to avoid interference with the target IDs used for other cluster requirements.

Following is an example of an ADARUN statement for Entire Net-Work:

ADARUN PROG=NETWRK,TARGETID=3333,NAB=20,NC=50,LU=65535,SVC=251

For this node, Entire Net-Work

• runs with a target ID of 3333;

• allocates an attached buffer pool for 20 interregion communication buffers;

• processes as many as 50 requests simultaneously;

• uses the SVC 251; and

• ensures adequate buffer size for Adabas compatibility by setting the value of the LU parameter to 65535.

Guidelines

Use the following guidelines when specifying ADARUN session parameters:

• Ensure that the correct program to be executed is specified (PROG=NETWRK).

• Ensure that the correct target ID is specified (TARGETID parameter).

• Determine which settings for the following parameters are applicable for the session:

CT - Command Timeout Limit

The maximum number of seconds (more precisely, units of 1.048576 seconds) that can elapse from the time an Entire Net-Work request is completed until the results are retrieved by the user through the interregion communication ("16-call"/operating system-dependent).

This parameter is used to prevent a request queue element (RQE) and the attached buffer from being held indefinitely if a user with an outstanding Entire Net-Work request terminates abnormally.

Possible causes for a command timeout are

• non-dispatchable or swapped-out user address space;

• user canceled;

• low user priority in a high-activity system.

If the CT limit is exceeded, the RQE and the attached buffer are released and message NETM93 is printed. If the user attempts to access the RQE after the timeout has occurred, response code 254 is returned.

Example:

Execute an Entire Net-Work task; set the maximum permitted time to obtain the result of a command using interregion communication to approximately 30 seconds.

ADARUN PROG=NETWRK,CT=30

FORCE - Overwrite ID Table Entry

By default (FORCE=NO), error NETM98 occurs if the TARGETID parameter (see TARGETID) specifies a target ID that is already in the target ID table:

NETM98 targetid TARGET INITIALIZATION ERROR: DUP ID (LOCAL)

FORCE=NO prevents the table entry from being overwritten. FORCE=YES allows the existing target ID table entry to be overwritten by the value specified for the TARGETID= parameter.

When a target terminates, its ID table entry is normally removed from the ID table. However, if an Entire Net-Work task has terminated abnormally without the recovery mechanism receiving control, its entry can remain in the ID table. FORCE=YES permits an Entire Net-Work target to be restarted even though its ID is already present in the ID table.

In addition to Entire Net-Work, other Software AG products such as Adabas or Entire System Server (formerly Natural Process) may have entries in the ID table.

Because FORCE=YES replaces any entry that matches the specified TARGETID value, you must ensure that the ID table does not contain that same value for any target that is active.

Warning: If you were to mistakenly override the ID table entry of an active target, it could severely disrupt the operation of the affected service system.

For this reason, all target and database IDs must be unique, and FORCE should be issued only after you determine that no other target with the ID specified by TARGETID is active.

Example:

Execute an Entire Net-Work task.

If the ID table contains an entry for target ID 3333, overwrite it; that is, allow the new task to use ID table entry 3333. Disconnect any existing task with an ID of 3333 from all user access.

ADARUN PROG=NETWRK,FORCE=YES,TARGETID=3333

If FORCE=NO (the default), Entire Net-Work does not permit the use of target ID 3333 if the ID table already contains an entry for that ID. The message NETM98 is issued, indicating that a target using the ID 3333 is already active.

LU - Length of Intermediate User Buffer

The size specified must be large enough to accommodate all Adabas control information (108 bytes), all user buffers (format, record, search, value, ISN) that may be required for any given Adabas command, and any user information passed from Adabas link routines to nucleus user exits.

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

An error occurs if the LU parameter specifies a value greater than the byte count implied by the NAB (number of attached buffers) parameter. The NAB default of 16 allocates more than 64 kilobytes.

Example:

Start an Entire Net-Work session using an Adabas intermediate user buffer area of 20,000 bytes.

ADARUN PROG=NETWRK,LU=20000

NAB - Number of Attached Buffers

NAB is an optional parameter that defines the number of attached buffers to be used during the Entire Net-Work session. Entire Net-Work allocates an attached buffer pool whose size equals the NAB value multiplied by 4112.

An attached buffer is an internal buffer used for interregion communication. Entire Net-Work requires the use of attached buffers in all environments.

Note:
A value of less than 16 prevents some Adabas utility functions from being performed remotely.

Example:

Execute an Entire Net-Work session; use 50 attached buffers.

ADARUN PROG=NETWRK,NAB=50

NC - Number of Request Queue Elements

NC is an optional parameter that specifies the maximum number of user requests that can be processed simultaneously by this Entire Net-Work communicator. Any user requests originating on this node that cause the NC value to be exceeded receive response code 151.

Each user request originating from this node is assigned a request queue element (RQE), which exists for the duration of the request. The RQE is released when the user has either received the results of this request from Entire Net-Work, or has been timed out. Each RQE requires 192 bytes.

Example:

Execute an Entire Net-Work session; set the request queue to contain as many as 500 elements at one time.

ADARUN PROG=NETWRK,NC=500

SVC - Interregion Communication Number

The number of the SVC to be used for the Entire Net-Work session. The SVC number is specified as an integer. The SVC is used to perform various internal functions, especially the processing of interregion communication.

SVC is an optional parameter that defines the interregion communications supervisor call (SVC) to be used for this session.

The SVC number specified must correspond to that which has been installed as the Software AG communications SVC at the user installation. The same SVC may be used for Adabas, Adabas Cluster Services, Entire Net-Work, and all other Software AG products using interregion communication.

Example:

Execute an Entire Net-Work session using SVC 205.

ADARUN PROG=NETWRK,SVC=205

TARGETID - Entire Net-Work Target Identification

* Software AG strongly recommends that you restrict Entire Net-Work target IDs in a sysplex cluster environment to values in the range 65482 through 65535 to avoid interference with the target IDs used for other cluster requirements.

The TARGETID parameter value must uniquely identify a particular Entire Net-Work node. Each target (node) ID must be unique, and can be any valid decimal value ranging from 1 (the default) to 65535. If the default is used for one node, it cannot be used for any other node and thus, this parameter must be specified for all other nodes.

In a sysplex cluster environment, all NUCIDs, Adabas database IDs (DBIDs), internally assigned operating system image IDs, target IDs used by Entire Net-Work, Natural global buffer pool IDs, etc., must be unique throughout all Entire Net-Work nodes. In particular, the Entire Net-Work target ID must not coincide with any database ID used in the network. An exception to this rule allows databases to be specified as "local" targets as explained on page 25.

Example:

Execute an Entire Net-Work session using target ID 65485.

ADARUN PROG=NETWRK,TARGETID=65485

Uniqueness Required (Global)

Entire Net-Work normally enforces unique target IDs throughout the network, that is, across all connected nodes. A target is not permitted to start if another target with the same ID is active anywhere in the network. The ADAM98 message (target initialization error) will result.

When a link is established between two previously unconnected partial networks, it is possible that the same target ID is used in both parts simultaneously. Because target IDs must be unique within the network, this is considered an error situation.

Entire Net-Work cannot determine which of the targets should be deactivated. Therefore the link between the two parts of the network is not established and explanatory messages (NET0108 and NET0106) are written to the operator consoles of both nodes trying to connect.

It is the responsibility of the installation to terminate one of the conflicting targets. The link can then be connected from either side by using the CONNECT link operator command.

Special Exception (Local)

The Adabas ADARUN parameter LOCAL permits the use of duplicate target IDs under special circumstances. A target ID can be used on all nodes in the network simultaneously if all targets with that ID are declared LOCAL=YES (see the Adabas Operations documentation for the appropriate ADARUN parameter). In this case, any one of the targets with that ID can be accessed only by users running on the same node.

Entire Net-Work does not transport requests to LOCAL targets. Response code 148 is generated if a user program calls a target declared LOCAL from a remote node.

A target ID cannot be used simultaneously for both a local target and a global target. The reason for this restriction is illustrated in the following example.

Imagine that a (global) database, DBID 35, is active on node PROD, and user programs from all nodes in the network are issuing calls to it. If a local database, also with DBID 35, starts on node TEST, it immediately draws all calls that originate on node TEST to the local database DBID 35. Users on other nodes are not affected, but all users on node TEST are switched in mid-transaction from the global database DBID 35 to the local database DBID 35, a different and probably totally unrelated database. This error situation cannot be permitted.

Entire Net-Work enforces this rule and thus prevents the confusion that would result if a local target ID coincided with a global target ID by broadcasting information about local targets to all nodes the same way it does for global targets.

www.softwareag.com

Copyright © Software AG 2009. All rights reserved.

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