The REGENERATE function reapplies all the updates performed between two checkpoints.
In addition to restoring normal updates, ADARES REGENERATE also restores any of the following ADADBS utility (or Adabas Online System) function updates that were performed between the specified checkpoints for the selected file or files:
| ALLOCATE | DELETE | NEWFIELD | RELEASE |
| CHANGE | DSREUSE | PRIORITY | RENAME |
| DEALLOCATE | ISNREUSE | RECOVER | RENUMBER |
| DELCP | MODFCB | REFRESH | UNCOUPLE |
For the database, all file-related operations listed above are performed, plus any of the following ADADBS (or Adabas Online System) database-related functions:
| ADD | INCREASE (data set size) |
| DECREASE (data set size) | RECOVER |
This document covers the following topics:
You can specify either the log number (PLOGNUM) or the session number (FROMPLOG) of the protection log as a starting point for REGENERATE processing. If you specify a session number, you can also specify a range of sessions to be processed using the TOPLOG parameter.
FROMPLOG specifies the session number at which the specified ADARES function is to start. ADARES searches the PLOG input file for the correct starting session. To define the starting point more precisely, specify the FROMCP and FROMBLK parameters.
Note:
If only FROMPLOG is specified (without the TOPLOG parameter),
only the session number specified by FROMPLOG is regenerated. If PLOGs with
higher session numbers are concatenated, they are ignored.
PLOGNUM is the log number of the data protection log to be used as input for regenerate processing. The log number may be obtained from the database status report.
ALLOCATION specifies the action to be taken if file extent allocations cannot be obtained according to the placement parameters ACRABN, DSRABN, NIRABN, or UIRABN.
ALLOCATION concerns the following operations, which are replayed as part of the regeneration:
ADADBS ALLOCATE
Adabas Online System "Define File"
Adabas Online System "Install/Change DLOG Area"
By default (that is, ALLOCATION=FORCE), the utility terminates with error if any file extent allocation cannot be met according to RABN placement parameters.
If ALLOCATION=NOFORCE is specified and any allocation with placement parameters fails, the utility retries the allocation without the placement parameter.
When the TOCP parameter is specified, incomplete transactions are not normally backed out at the end of processing. This allows you to reexecute the utility function that corresponds to the TOCP checkpoint, followed by another ADARES operation with FROMCP specifying the starting checkpoint.
In situations where a REGENERATE/BACKOUT should end at the TOCP checkpoint, using the AUTOBACKOUT parameter to back out incomplete transactions ensures the logical consistency of the database. Note that AUTOBACKOUT is allowed only if TOCP is specified.
CONTINUE allows AUTOBACKOUT of any incomplete transaction changes during file regeneration. If specified, all changes made by incomplete transactions are backed out of the database data sets specified by the FILE parameter.
If the file list contains either coupled or expanded component files and CONTINUE is specified, the usual checking of the list for inclusion of complete coupled pairs and/or component file sets is not performed; in this case, IGNORECOUPLE or IGNOREEXP does not have to be specified to stop the respective file list check.
If CONTINUE is specified, the complete database is locked for use by the REGENERATE function only.
EXCLUDE lists the numbers of the files to be excluded from REGENERATE processing; that is, the files that are not to be regenerated. Any protection records that pertain to these files are ignored.
The parameter is optional: if not specified, no files are excluded. A file number may be listed only once.
When the FILE parameter is specified, all files specified in the EXCLUDE parameter must also be specified in the FILE parameter.
The EXCLUDE parameter has no bearing on whether the REGENERATE is performed with or without transaction logic.
The EXCLUDE parameter is provided for use in recovery jobs built by the Adabas Recovery Aid (ADARAI).
Excluded files are listed in the extended CPLIST of the ADAREP report.
FILE specifies the files to be included in the regeneration process. If all files are to be included, do not specify the FILE parameter. If the specified file is a component file of an Adabas expanded file, all other component files of the expanded file must also be specified here. If a specified file is coupled to other files, the coupled files must also be specified.
Note:
Before beginning, ADARES locks all specified files for the
duration of REGENERATE execution. If the FILE parameter is omitted, the entire
database will be locked.
FROMBLK specifies the block number in which the FROMCP checkpoint entry is contained. This block number may be obtained from the previous ADASAV restore output or database status report. It refers to PLOGNUM or FROMPLOG. FROMBLK can be specified only if FROMCP is specified.
FROMCP defines the checkpoint after which the REGENERATE process is to begin. Processing begins with the information following the specified checkpoint. The checkpoint name may be obtained from the previous ADASAV restore output (SYN2/5), the database status report, or the ADARES COPY/PLCOPY output resulting from specifying UTICPLIST. If processing is to begin at the beginning of the log, do not specify the FROMCP parameter. FROMCP refers to the protection log specified by PLOGNUM or FROMPLOG.
For information about the 'SYNS,INCLUDE' option, see the section INCLUDE: Include Checkpoint in Regeneration.
In a cluster environment, the NUCID parameter or a combination of the FROMNUCID and TONUCID parameters may be required to identify the nuclei associated with the checkpoints referenced in this regeneration run. If the starting checkpoint block (FROMBLK parameter) and ending checkpoint block (TOBLK parameter) are for the same nucleus, use the NUCID parameter; if the starting checkpoint block (FROMBLK) and ending checkpoint block (TOCP) are for different nuclei, use the FROMNUCID and TONUCID parameters.
The FROMNUCID parameter specifies the nucleus ID for the starting nucleus. If you specify the FROMNUCID parameter, a corresponding TONUCID parameter is expected.
IGNORECOUPLE (or CONTINUE) stops the REGENERATE function from checking the FILE list for complete coupled file pairs. If neither CONTINUE nor IGNORECOUPLE is specified and the FILE list specifies a coupled file without specifying its mate, ADARES terminates and issues an error message.
If the FILE list includes any Adabas expanded component files, ADARES BACKOUT normally checks to ensure that all related component files are also in the list; if not, ADARES ends the REGENERATE operation and issues an error message. Specifying IGNOREEXP (or CONTINUE) stops the checking for related component files.
The optional keyword INCLUDE specified for FROMCP and/or TOCP includes the checkpoint where the regenerate starts/stops in the operation; that is, the function associated with the checkpoint is reexecuted. The checkpoint name must be SYNS, since ADARES can reexecute only functions associated with SYNS checkpoint. The checkpoint name and parameter combination 'SYNS,INCLUDE' must be enclosed in apostrophes.
If INCLUDE is not specified (the default), the REGENERATE operation starts immediately after the checkpoint specified by FROMCP and stops immediately before the checkpoint specified by TOCP.
The INCLUDE parameter is provided for use in recovery jobs built by the Adabas Recovery Aid (ADARAI).
MTR=YES activates the multithreaded regenerate feature; MTR=NO disables it.
When the multithreaded regenerate feature is active, multiple buffers containing PLOG information are sent to the Adabas nucleus in parallel to improve performance. When the feature is not active, only one buffer is sent to Adabas at a time.
If the nucleus ADARUN parameter MODE=SINGLE, MTR is automatically set to NO. Multiple threads are not available to Adabas running in single user mode.
If the FILE parameter is not specified, or is specified with CONTINUE, the default value for MTR is YES. In these cases, multithreaded regenerate has exclusive control of the whole database and is generally effective.
Otherwise, the default value is NO. If it only has exclusive control of some files, as is the case when FILE is specified without CONTINUE, multithreaded regenerate can run in parallel with normal applications accessing different files and has the potential to negatively impact the performance of production applications.
NOAUTOBACKOUT stops the normal backout of incomplete transactions at the end of REGENERATE operation. Normally, ADARES performs an automatic backout of all incomplete logical transactions at the end of the function if both of the following are true:
The REGENERATE was for the entire database (FILE parameter omitted), or the CONTINUE parameter was specified; and
The TOCP parameter was omitted, which implies that processing is to be performed until the end of the input data set is reached.
If several consecutive REGENERATE runs are needed to process multiple protection logs resulting from a single Adabas session, an automatic backout should be performed only for the last input log. The NOAUTOBACKOUT parameter should therefore be specified for each REGENERATE run except for the run in which the last input log is used.
Notes:
When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.
Note:
When NOUSERABEND is specified, we recommend that it be specified
as the first parameter of the utility function (before all other parameters).
This is necessary to ensure that its parameter error processing occurs
properly.
When MTR=YES, the NPCALLS parameter may be specified to limit the number of parallel calls sent to the Adabas nucleus.
If the FILE parameter is not specified, or is specified with CONTINUE, the default value for NPCALLS is the nucleus ADARUN parameter NT+1 or NC, whichever is smaller.
If the FILE parameter is specified without CONTINUE, the default value is the nucleus ADARUN parameter NT+1 or NC/2, whichever is smaller.
NPCALLS is primarily used to reduce the number of parallel calls allowed by the default value. Fewer parallel calls mean a smaller nucleus workload produced by ADARES. This is especially useful for increasing the resources available to application programs running in parallel with REGENERATE FILE.
In a cluster environment, the NUCID parameter or a combination of the FROMNUCID and TONUCID parameters may be required to identify the nuclei associated with the checkpoints referenced in this regeneration run. If the starting checkpoint block (FROMBLK parameter) and ending checkpoint block (TOBLK parameter) are for the same nucleus, use the NUCID parameter; if the starting checkpoint block (FROMBLK) and ending checkpoint block (TOCP) are for different nuclei, use the FROMNUCID and TONUCID parameters.
The PARALLELREAD parameter provides for concurrent read-only access to the files being processed by ADARES REGENERATE both for database-wide and file-oriented functions:
for file-oriented functions, specifying PARALLELREAD causes ADARES to issue an OPEN call with "EXU=file-list" in the record buffer. This allows read-only access to the files for other users while ADARES is active.
when FILE is not specified or when CONTINUE is specified, the PARALLELREAD parameter is effective for database-wide session regeneration. The parameter makes it possible for read-only users to access the database at the same time the database session is being regenerated.
Update commands are rejected.
If parallel access users read records that were updated in the database session being regenerated, they may see record images that are logically wrong in the sense of the application, or response codes such as 113 (ADARSP113) that indicate inconsistencies.
Notes:
PLOGDBID specifies an alternate DBID from which the PLOG has been taken. When regenerating with a protection log from a database other than that specified by the ADARUN statement's DBID parameter, use PLOGDBID to specify the database ID of the alternate protection log. The default is the database ID (DBID) from the ADARUN-specified database.
The RAID parameter terminates a regeneration with error 146 whenever a file is to be excluded because a utility checkpoint (other than ADADBS or Adabas Online System checkpoints) was encountered or a nucleus response code was received for the file.
If RAID is not specified (the default), ADARES continues processing the other files after a file is excluded from REGENERATE processing.
RAID is provided for use in recovery jobs built by the Adabas Recovery Aid (ADARAI).
The RPLDATA parameter allows you to specify whether or not the nucleus should replicate the protection log data sent to it. Valid values are "YES" and "NO"; the default is "NO".
The TEST parameter tests the operation syntax without actually performing the operation. Only the syntax of the specified parameters can be tested; not the validity of values and variables.
TOBLK specifies the block number in which the TOCP checkpoint entry is contained. TOBLK, which can be specified only if TOCP is also specified, refers to the protection log specified by TOPLOG, if specified, or else by PLOGNUM or FROMPLOG.
TOCP specifies the checkpoint before which the REGENERATE process is to stop. Processing continues up to, but not including, the specified checkpoint. If REGENERATE processing is to continue until the end of the log, do not specify TOCP. TOCP refers to the protection log specified by TOPLOG, if specified, or else PLOGNUM or FROMPLOG.
For information about the 'SYNS,INCLUDE' option, see the section INCLUDE: Include Checkpoint in Regeneration.
In a cluster environment, the NUCID parameter or a combination of the FROMNUCID and TONUCID parameters may be required to identify the nuclei associated with the checkpoints referenced in this regeneration run. If the starting checkpoint block (FROMBLK parameter) and ending checkpoint block (TOBLK parameter) are for the same nucleus, use the NUCID parameter; if the starting checkpoint block (FROMBLK) and ending checkpoint block (TOCP) are for different nuclei, use the FROMNUCID and TONUCID parameters.
The TONUCID parameter specifies the nucleus ID for the ending nucleus. Only specify a TONUCID parameter if a corresponding FROMNUCID parameter is also specified.
TOPLOG specifies the last session to be processed by the specified ADARES function. If ADARES finds a session on the PLOG input file that is greater than the specified TOPLOG session, that session is excluded from ADARES processing. If TOPLOG is not specified, the FROMPLOG session becomes the default.
ADARES REGENERATE PLOGNUM=4
All files are to be included in regenerate processing. The protection log number is 4. Regenerate processing is to begin at the beginning of the log and is to end at the end of the log. At the end of REGENERATE processing, incomplete transactions are automatically backed out.
ADARES REGENERATE FILE=4,7,FROMPLOG=11,FROMCP=CH01,FROMBLK=106, ADARES TOPLOG=12,TOCP=CH05,TOBLK=2031
Regenerate processing is to be limited to files 4 and 7. All updates applied to files 4 and 7 between the taking of checkpoints CH01 and CH05 are to be reapplied. CH01 is located in block 106 of data protection log 11. Checkpoint CH05 is located in block 2031 of data protection log 12. No automatic backout of incomplete transactions occurs following REGENERATE processing, as in the previous example.
ADARES REGENERATE EXCLUDE=10,11,12
Files 10 through 12 are excluded from the REGENERATE database function. No changes to these files are replayed.
ADARES REGENERATE ADARES FROMCP='SYNS,INCLUDE',FROMBLK=123 ADARES TOCP=SYNP,TOBLK=234
ADARES regenerates the database.
The REGENERATE starts at the SYNS checkpoint in PLOG block 123; ADARES reexecutes the associated ADADBS/Adabas Online System function.
The REGENERATE stops just before the SYNP checkpoint in block 234; ADARES does not replay the associated utility function.
ADARES REGENERATE FILE=10 ADARES FROMCP='SYNS,INCLUDE',FROMBLK=345 ADARES TOCP='SYNS,INCLUDE',TOBLK=456
ADARES regenerates file 10.
The REGENERATE starts at the SYNS checkpoint in PLOG block 345; ADARES reexecutes the associated ADADBS/Adabas Online System function if it pertains to file 10.
The REGENERATE stops at the SYNS checkpoint in block 456; ADARES replays the associated ADADBS/Adabas Online System function if it pertains to file 10.
ADARES REGENERATE ADARES RAID
ADARES regenerates the database.
ADARES reexecutes all database updates found on the input PLOG.
ADARES immediately terminates with error 146 if it receives a nucleus response code or encounters a utility checkpoint other than from ADADBS or Adabas Online System.
File processing statistics from ADARES REGENERATE function processing are provided at the end of the run. These statistics include the number of data storage records regenerated for each file as well as information about the PLOG blocks read and sent, the commands and transactions processed, the number of Adabas calls processed (including maximum and average calls processed in parallel), and the average record buffer size. The statistics are gathered via 4-byte counters that keep count of the total data storage updates for each file during REGENERATE processing.
Spanned records and records with large object (LB) fields can span more than one data storage block. Thus an update to a record of this type will increment the data record update counter by one for each data storage block. For example, suppose a spanned record is updated that is stored across three data storage blocks. In this case, the record update counter is incremented three times, one for each data storage block.
Data storage records that were modified in a transaction that did not successfully terminate with an ET command are counted, even though they are backed out by the nucleus.
The following is a sample of an ADARES REGENERATE report (when MTR=YES):
Note:
The number of records listed as "Data Record
Updates" is the number of data storage records processed; the
number of records listed as "PLOG Records sent to
ADABAS" is the number of input records from the protection log
(PLOG). The PLOG record count is usually much larger than the data record
update count.
(REGENERATE) File Processing Statistics
---------------------------------------------
I File Number I Data Record Updates I
I-----------------I-------------------------I
I 10 I 127 I
---------------------------------------------
Multi-Threading Processing Statistic
------------------------------------
PLOG Blocks Read from Input 17
PLOG Records Sent to ADABAS 405
Commands Processed 158
Transactions Processed 28
Number of ADABAS Calls 28
Maximum Calls in Parallel 23
Average Calls in Parallel 10
Average Record Buffer Size 1574
The following is a sample of an ADARES REGENERATE report when MTR=NO:
(REGENERATE) File Processing Statistics
---------------------------------------------
I File Number I Data Record Updates I
I-----------------I-------------------------I
I 10 I 127 I
---------------------------------------------
ADARES (REGENERATE) Normal end: 17 blocks / 405 records processed.