Version 7.4.2
 —  Introduction  —

Logs and Log Merges

In an Adabas cluster environment, the protection logs (and optionally, the command logs) of all individual nuclei in the cluster are merged into single log files in chronological order for the cluster database shared by all the nuclei as a whole. The chronological order is determined by timestamps on all individual nucleus log records, which are synchronized across systems in a parallel sysplex environment by an IBM Sysplex Timer TM.

ADARES is the only utility that handles both the unmerged and merged PLOGs and CLOGs. The log merge process

For more detailed information, see the Operations documentation and the section ADARES in the Adabas Utilities documentation.

The document covers the following topics:


Protection Logs

Either all nuclei in an Adabas cluster must run without protection logs (PLOGs) or all nuclei must run with PLOGs. The same ADARUN PLOGRQ setting is enforced for all nuclei in a cluster. This value cannot be modified during a session.

If the nuclei in the cluster are running with PLOGs, they must be dual or multiple PLOGs: sequential PLOGs are not allowed. See the Adabas Operations documentation for more information.

Each nucleus in the cluster writes its protection data to its own Work and PLOG datasets: no synchronization is required. However, every protection record is preceded by an 8-byte timestamp indicating the time of its creation. The timestamp is the only difference between protection records written by a cluster nucleus and those written by a noncluster nucleus. The timestamp is required for the merge process and is removed after the protection log is merged but before it is written to the sequential dataset.

Merging Protection Logs

For recovery processing, all protection log datasets are automatically merged into a single log "stream" for each cluster database when ADARES PLCOPY is executed. The PLCOPY process accesses the parallel participant table (see section PPT) to determine which protection logs to copy and opens the appropriate datasets using dynamic allocation. PLCOPY copies/merges as much data as possible; if a nucleus is still writing to a protection log dataset, PLCOPY 'partially' merges the dataset.

ADARES expects that at least one of the protection logs being merged is at 'completed' status. If this is not the case, ADARES reports that there is no data to be copied.

The merge begins with the lowest timestamp from all protection logs being merged and ends with the lowest of the ending timestamps from all datasets. Records beyond this point are written to an 'intermediate' dataset, which must be supplied as input to the next merge.

Intermediate Datasets

It is necessary to supply two intermediate datasets to the PLCOPY merge process: one is used as input and the other as output. ADARES analyzes both datasets to determine which is which.

A cross-check ensures that the correct input intermediate dataset has been supplied; the utility will not continue if the correct dataset has not been supplied. The input intermediate dataset contains "leftover unmerged" data from the last run of the utility, without which the merged protection data is incomplete.

User Exits for Merging Protection Logs

A user exit is necessary for merging protection logs automatically: user exit 2 (UEX2) for dual logs or user exit 12 (UEX12) for multiple logs. However, you may choose to run without the user exit. This may be advisable for testing purposes, for example. If one nucleus in a cluster has the user exit specified, then all other nuclei in the cluster must also supply the user exit. The user exit supplied must be the same across all nuclei.

Sample user exits (UEX2 and UEX12) are provided that illustrates the necessary changes for the intermediate dataset. Once DD statements for the PLOG datasets have been supplied on the session start-up JCL, you do not need to supply them again for ADARES as these are opened using dynamic allocation. If the DD statements are supplied, they are ignored.

If there is a problem with the user exit, the Extended Error Recovery logic allows you to disable the exit and load a new exit without bringing the nucleus down.

Note:
While a non-cluster nucleus runs with the PSW in problem state, an Adabas Cluster Services nucleus runs with the PSW in supervisor state. User exits must return in the same state (i.e., problem state or supervisor state) in which they receive control. In fact, user exits must return with all PSW fields the same except for the next instruction address and the condition code.

Top of page

Command Logs

Each nucleus has its own command log (CLOG) datasets where it logs commands during a session. Command logging is activated by setting the ADARUN parameter LOGGING=YES.

Multiple command logging requires that you set ADARUN parameters correctly. See the Adabas Operations documentation for more information.

Merging Command Logs Manually

You can copy the dual or multiple command logs into a single sequential dataset for a nucleus using the default ADARES CLCOPY function. Then, using the output from the CLCOPY execution as input, you can use the ADARES MERGE CLOG function to create 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:

ADARES MERGE CLOG NUMLOG=n

where n is the number of command logs to be merged, but not more than 32.

The ADARES MERGE CLOG function takes as input the sequential command log datasets from each of the cluster nuclei that were produced by running CLCOPY, merges them into chronological order and copies the resulting command log dataset from disk to a sequential dataset.

Merging Command Logs Automatically

For accounting or other tracking purposes, you may want to automate the CLOG merge process. When ADARUN CLOGMRG=YES is set, CLOGs are merged automatically as part of the ADARES CLCOPY process in much the same way that PLOGs are merged as part of the ADARES PLCOPY process.

Existing CLCOPY jobs must be modified to include intermediate datasets. The sample CLCOPY job ADARESMC illustrates the necessary addition of the intermediate datasets. When intermediate datasets are used for both PLCOPY and CLCOPY merge processes, the dataset names must be unique so that they are not overwritten.

You can use the same exit for the CLOG merge process that is supplied for the PLOG merge process (see the sample exit USEREX2P):

Likewise, CLOG datasets with slightly modified names can be included in the user exit 2 or user exit 12 JCL used for other NUCIDs.

Note:
While a non-cluster nucleus runs with the PSW in problem state, an Adabas Cluster Services nucleus runs with the PSW in supervisor state. User exits must return in the same state (i.e., problem state or supervisor state) in which they receive control. In fact, user exits must return with all PSW fields the same except for the next instruction address and the condition code.

Dynamically Modifying the CLOGMRG Parameter Setting

The CLOGMRG parameter setting can be changed dynamically with the new operator command CLOGMRG, the new ADADBS OPERCOM CLOGMRG function, or with the Modify Parameters function of Adabas Online System.

CLOGMRG is a global (that is, cluster-wide) parameter. A change made to one nucleus is automatically propagated to all nuclei in the cluster.

Top of page

Coordinated Log Switching

The automated log merge process makes it necessary to coordinate the log switch process so that the merge process can copy as much data as possible without causing too many switches.

The first cluster nucleus that needs to switch logs (a log is full or the FEOFPL or FEOFCL command has been issued) sends a broadcast message to the other nuclei in the cluster indicating that it is switching. Then it goes on as normal, switching and calling the appropriate user exit.

Note:
User exit 2 for dual logs or user exit 12 for multiple logs is recommended and is required if PLOGRQ=FORCE is set. If it is supplied to one nucleus in a cluster, it must be supplied to all the other nuclei. PLOGRQ must have the same setting across all nuclei in the cluster. If a cluster nucleus is to run with PLOGs, they must be dual or multiple PLOGs; sequential PLOGs are not allowed.

When a cluster nucleus receives the message that another nucleus is switching logs, it must decide if it will switch based on the status of its current log and whether it has an available log:

Note:
While a non-cluster nucleus runs with the PSW in problem state, an Adabas Cluster Services nucleus runs with the PSW in supervisor state. User exits must return in the same state (i.e., problem state or supervisor state) in which they receive control. In fact, user exits must return with all PSW fields the same except for the next instruction address and the condition code.

Global FEOFPL and FEOFCL Commands

The GLOBAL option has been added to both the ADADBS OPERCOM FEOFPL and FEOFCL commands and the corresponding console operator commands:

If there is no log dataset available to write to, the switch does not occur even if GLOBAL has been specified. This functions the same way when the FEOFPL or FEOFCL command is issued for a single nucleus.

Top of page