DBRECOV


DBRECOV

     The DBRECOV program usually is executed after a backup database copy
 has been restored by running DBRESTOR in the event of a system failure.
 DBRECOV reads the log file containing records of all database modifications
 and re-executes the transactions against the restored database(s).

 The DBRECOV >FILE command enables individual users to be informed of the
extent of recovery.

DBRECOV also uses a mirror database on a secondary system as a workable
 maintenance method. The options used with DBRECOV for this type of recovery
 and maintenance method are RESTART, ABORT and PURGE.

DBRECOV can perform rollforward recovery of TurboIMAGE/XL databases stored
 using the TurboSTORE/iX 7x24 True-Online Backup. No new option for DBRECOV is needed.

The commands associated with DBRECOV are:

 >CONTROL, >EXIT, >FILE, >PRINT, >RECOVER, >ROLLBACK and >RUN.

SYNTAX

     :RUN DBRECOV.PUB.SYS [,option]


PARAMETERS

option

RESTART restarts the roll-forward recovery process.
 Information in the RESTART file is used by DBRECOV to
 restart recovery from the point it was stopped.

ABORT purges the RESTART file and returns the flags to the same
 settings as before the recovery process was started.

PURGE deletes the current RESTART file before beginning the
 mirror database process again. PURGE can also be used
 if ABORT fails to abort recovery (possibly due to an
 inconsistent RESTART file).

OPERATION

The recovery system prints a banner indicating the version, date, and time.
It then prompts for a command input.

>CONTROL

Used to control various options that affect the execution of DBRECOV.
The options are STAMP, NOSTAMP, STORE, NOSTORE, ABORTS, NOABORTS, UNEND,
NOUNEND, STOPTIME, ERRORS, STATS, NOSTATS, MODEX, MODE 4, EOF, MDBX, and NOMDBX.

Syntax

   >CONTROL parameters [,parameters...]

Parameters:

If the >CONTROL command is not used, the following default conditions apply:

STAMP is the database time stamp and must correspond with the one written
 to the log file.

STORE is the DBSTORE flag set in the database root file.

ABORTS causes transactions which failed to complete due to a program abort
 to be recovered.

NOUNEND suppresses the posting of transactions which did not complete or were
 aborted prior to a system failure.

ERRORS= during job (batch) execution allows zero errors (DBRECOV terminates),
and during interactive sessions allows 30,000 errors.

MODEX DBRECOV proceeds with exclusive access to the database, using deferred output.

NOSTATS if the database is not recovered, no tabulated information will be printed.

STOPTIME= DBRECOV will recover all log records, regardless of the time stamp.

EOF= DBRECOV will recover all log records in the log file.

MDBX DBRECOV treats multiple database transactions contained in the log file
 as separate transactions.

The >CONTROL command is used to override the default conditions.
If a particular parameter is not specified within a >CONTROL command,
the default condition remains in effect. Any number of parameters can be named
in any order, but if more than one condition is specified for one parameter,
the last condition entered applies. For example:

>CONTROL NOSTAMP, STAMP

or

>CONTROL NOSTAMP
>CONTROL STAMP

In both cases, the STAMP condition cancels the previous NOSTAMP.
Recovery proceeds with the time stamp check intact.

If additional databases are specified for simultaneous recovery,
they are all governed by the same >CONTROL options.

In the specifications below, default options are shown in brackets [ ].
The default conditions for STOPTIME, ERRORS, and EOF are included with
their descriptions.

[STAMP] is the time stamp in the database root file.
It is compared with the time stamp in each DBOPEN log record
 in the log file. If the time stamps do not match, DBRECOV
 returns an error message, and terminates recovery for the
 offending database.

NOSTAMP disables the check of the database and log file time stamps.
 Allows recovery to proceed regardless of the database and
 log file time stamps.

[STORE] is the DBSTORE flag in the database root file and is checked
 to ensure that the database has not been modified between
 restoration and recovery. If the flag has been cleared,
 the >RECOVER command fails. The DBSTORE flag is set only when
 the database is stored using DBSTORE. It is cleared when the
 database is accessed by DBDELETE, DBPUT, or DBUPDATE.

NOSTORE disables the check of the DBSTORE flag. Allows recovery to
 proceed whether or not the DBSTORE flag is set. Useful when
 the database has been stored by the MPE/iX STORE command rather
 than DBSTORE. Storing the database using the STORE command does
not set the DBSTORE flag, and is not recommended.

[ABORTS] when transactions do not complete due to a program abort,
 TurboIMAGE/XL appends an abnormal DBEND (DBABEND) to the log file
 and considers the transactions completed. This enables DBRECOV to
 recover these transactions and thereby avoids suppressing all
 subsequent dependent transactions.

NOABORTS causes DBRECOV to suppress transactions not originally completed
 by user programs. This option tells TurboIMAGE/XL a user or
 program abort is abnormal, or incomplete. NOABORTS should only be
 used if all database modifications were stopped immediately after
 the abort and recovery was initiated. Otherwise, recovery can fail
 due to record file overflow (see below).

[NOUNEND] causes DBRECOV to suppress incomplete transactions.
Recovery can fail due to a record file overflow.

UNEND prevents DBRECOV from suppressing incomplete transactions.

STOPTIME=mm/dd/yy hh:mm
causes DBRECOV to impose an artificial end-of-file when the
 specified log record time stamp (supplied by MPE/iX) is
 encountered. All log records with subsequent time stamps will
 not be recovered. This feature is useful in the event of a user
 program failure; the database can be recovered to a point in time
 before the suspect program began execution.

Default condition: Log record time stamps are not checked by DBRECOV.

ERRORS=nnnn controls the maximum number of non-fatal errors allowed during a
 job (batch) execution. Should nnnn be exceeded, DBRECOV terminates
 and sets the job control word to -1 to indicate an error. However,
this check does not take effect until all commands have been parsed
 and processed.

Default condition: ERRORS=0 for batch jobs and ERRORS=30,000 for
 interactive sessions. The number of errors allowed can be altered
by entering a revised ERRORS parameter.

[NOSTATS] negates the STATS option; tabulated information is not printed
 unless a database is recovered.

STATS is used to obtain information from the log file without actually
recovering a database. Requires use of a file equation to specify
 the log file. For example:

:FILE LOGFILE=ORDER001;DEV=TAPE;LABEL=LOG001
:RUN DBRECOV.PUB.SYS
>CONTROL STATS
>RUN

This example shows the log file ORDER001 residing on tape and
 belonging to an expandable file set (refer to the GETLOG command
 with AUTO option in the MPE/iX Commands Reference Manual. The
 recovery system responds by printing tabulated information from
log files, similar to tables printed after a database recovery.
However, no databases are actually opened or recovered.

[MODEX] causes recovery to execute in exclusive (deferred) mode.
 No other users can access the database concurrent with recovery.

MODE4 recovery proceeds in DBOPEN mode 4, allowing users in mode 6 to
 access (read) the database while recovery is in process.

EOF=nnnn causes DBRECOV to impose an artificial end-of-log file when the
specified log record number is encountered. All log records with
 subsequent numbers will not be recovered. This feature is useful
in the event of a user program failure; the database can be
 recovered up to a record number preceding the suspect records.
 While logging is in progress, the MPE/iX SHOWLOGSTATUS command
 can be used to determine the current number of records logged
 before initiating a questionable program.

Default condition: All log records are recovered by DBRECOV.

[MDBX] causes DBRECOV to treat multiple database transactions contained
 in the log file as separate transactions. If all of the databases
 involved in the multiple database transaction are not specified in
 the >RECOVER or >ROLLBACK command, DBRECOV will abort. It does not
 allow partial recovery of multiple data base transactions. If a
 multiple database transaction is dependent on any transaction that
 was not recovered, the multiple database transaction will be rolled out.

NOMDBX causes DBRECOV to treat multiple database transactions contained in
the log file as single transactions. Therefore, each database can be
 recovered separately. This option is useful if only part of a multiple
 database transaction is to be recovered.

Record Numbers

DBRECOV identifies detail records by their record number.
 Suppressing aborted or unended transactions during recovery with the
 NOUNEND or NOABORTS options can cause subsequent detail calls to DBPUT
 to use different record numbers. In order to change old record numbers
 into new ones, DBRECOV uses an internal record table. The record table
 provides a "before" and "after" location of the record numbers for DBPUT calls.

>EXIT

Used to terminate DBRECOV without recovering any databases.

Syntax

   >EXIT

>FILE

Routes log records to individual user files, providing the application
program with information about the outcome of recovery; provides a useful
tool for auditing previous entries. One file for each user can be opened
simultaneously by re-entering the >FILE command once for each user, or all
users can be directed to a single file.

Syntax

   >FILE fileref,userref [,rmode,fmode]

Parameters

fileref   is an MPE/iX file reference: filename[/lockword][.group[.account``]].
 This is the destination file for each user's log records.

userref is a user reference, specifying which user's log records to copy to
 this user recovery file. The format is: username[/ident].account.

The optional identifier, which also must be passed to DBOPEN as part of the
password parameter, uniquely identifies persons using the same logon.

rmode is for roll-forward recovery only. Directs recovery system to copy
log records associated with transactions successfully recovered.
 rmode can take one of the following values:
0 No records associated with recovered transactions are copied to
 the user file. (Default value.)
1 Log records corresponding to the last successfully recovered
 call to DBEND of each transaction block are copied.
2 The sequence of log records associated with the last successfully
 recovered transaction of each transaction block are copied.
 In addition, all DBMEMO log records which immediately follow this
 transaction are copied.
3 All log records associated with successfully recovered transactions
 for each transaction block are copied.
fmode directs recovery system to copy log records associated with transactions
that failed to recover. Used with both roll-forward and roll-back recovery.

CAUTION

The (roll-forward) recovery system cannot guarantee that all records
 associated with unsuccessfully recovered transactions can be copied,
because log records which reside in the log system's memory buffers
 are lost in the event of a system failure. When accessing the database
 for critical transactions, use DBEND mode 2 for immediate posting of the
log system's memory buffer.

fmode can take one of the following values:
0 No records associated with failed transactions are copied.(Default value.)
1 Log records corresponding to the first unsuccessfully recovered
 call to DBBEGIN of each transaction block are copied.
2 The sequence of log records associated with the first unsuccessfully
 recovered transaction of each transaction block are copied.
3 All log records that could not be recovered are copied.

Discussion

The >FILE command copies qualified DBOPEN and DBCLOSE log records to each
user's recovery file. The optional rmode and fmode parameters specify the
copies of additional log records.

Once the >FILE command is entered, the user recovery file is opened and any
existing records are deleted. If the specified user file does not exist, an
error is reported unless the file references the logon group and account,
in which case the file is automatically created. The state of a log record
(either recovered or not) is indicated by a flag set by DBRECOV in the record
itself. MPE/iX WRITELOG records returned by DBRECOV are variable length,
because DBRECOV eliminates the continuation records by appending their data
to the original WRITELOG record. Consequently, DBRECOV will create recovery
files with a variable length record format. However, fixed length records are
permitted if the file already exists or an MPE/iX FILE command is in effect.
If a log record exceeds the record size of a user file with fixed length
records, the log record is truncated and an error message is printed.

Example

   >FILE PART/MGR,MARY/RYAN.MKTG,0,3

PART is the filename. MGR is the lockword. MARY is the username and RYAN
is the identifier. MKTG is the account. The 0 is the rmode, and the 3 is the fmode.

The >FILE command is repeated for each recovery file to be created and for
each user whose records will be copied to a user recovery file.

>PRINT

Prints the names of databases specified for recovery (DBTABLE option)
or recovery files specified (FILETABLE option). Can be used as a check
before actually initiating recovery with the >RUN command.

NOTE

The >PRINT DBTABLE command produces the DATABASE STATISTICS table,
but does not include statistics. The table, along with statistics,
is automatically displayed by every execution of the recovery system.
If you need this table, along with statistics, without actually performing
the recovery, use the >CONTROL STATS command instead.

Syntax

>PRINT {DBTABLE | FILETABLE}

Parameters:

DBTABLE     displays names of databases specified for recovery.

FILETABLE displays file references, user references, rmodes and
 fmodes specified in >FILE commands.

Example

   >PRINT DBTABLE

****************************************************************
* DATABASE STATISTICS *
* *
* NAME GROUP ACCOUNT OPENS TRANS PUTS DELETES UPDATES *
* ---- ----- ------- ----- ----- ---- ------- ------- *
* ORDERS TST MKG 0 0 0 0 0 *
****************************************************************

>RECOVER

Used to designate the name of a database to be roll-forward recovered;
opens database root file, validates logid and password with MPE/iX, and
checks the DBSTORE flag. Multiple databases can be roll-forward recovered
concurrently if they have all logged to the same log file by entering the
>RECOVER command once for each database.

Syntax

   >RECOVER database_name[/maint_word][.group[.account]]

Parameters:

database_name   is the name of the TurboIMAGE/XL database to be recovered.

maint_word is the maintenance word defined by the database creator.
 This word must be supplied by anyone other than the database creator.

group is the group where the database(s) resides.

account is the account where the database(s) resides.

Discussion

If the >RECOVER command is accepted, the following message is returned: 

DATABASE database name LAST DBSTORED day, date, time

The following conditions must be satisfied before the >RECOVER command is accepted:

1. The database must be accessible to the user (database administrator)
running DBRECOV. This user must either be the creator of the database or know
the maintenance word. If the database resides in a group or account different
 from the user's logon, the MPE/iX file security must permit the user read and
write access to the database files.

2. The database must be enabled for recovery.

3. The log identifier characteristics (name, password, log file name and
device type) must not have been altered since the log file was generated.
 This restriction applies to MPE/iX log commands as well as those provided
for TurboIMAGE/XL by DBUTIL. This is necessary because the MPE/iX log
 identifier is used by TurboIMAGE/XL to obtain the name and device type of
 the log file. The >RECOVER command will not be accepted if the logid is
 unknown to MPE/iX. However, if the logid is known to MPE/iX but specifies
 the wrong log file, this condition is not detected at this time and
 >RECOVER will be accepted. DBRECOV will generate erroneous data in the
 database if the database is recovered with the wrong log file.

4. The DBSTORE flag must be set, indicating that the database has not been
 modified between restoration and roll-forward recovery. This check can be
 overridden by the NOSTORE option of the >CONTROL command.

5. No other users can be accessing the database when >RECOVER is called.
 Exception: When the MODE4 option of the >CONTROL command is specified,
 the database can be concurrently accessed in mode 6 (read only).

The >RECOVER command itself does not initiate recovery, but makes several
preparatory checks. The recovery system is actually initiated by the
>RUN command.

Example

   >RECOVER ORDERS, RETAIL
DATABASE ORDERS LAST DBSTORED THURS, SEP 7, 1989, 6:30 PM
DATABASE RETAIL LAST DBSTORED MON, SEP 11, 1989, 10:00 PM

ORDERS and RETAIL are database names.

>ROLLBACK

Rolls out any incomplete transactions following a system crash.
Multiple databases can be roll-back recovered concurrently by
entering the command as follows: >ROLLBACK dbname, dbname...

Syntax

   >ROLLBACK database_name[/maint_word][.group[.account]]

Parameters

database_name   is the name of individual database(s) to be rolled-back.

maint_word is the maintenance word defined by the database creator.
 This word must be supplied by anyone other than the database creator.

group is the group where the database(s) resides.

account is the account where the database(s) resides.

Discussion

If the >ROLLBACK command is accepted, the following message is returned: 

DATABASE database name LAST USED day, date, time

The following conditions must be satisfied before the >ROLLBACK command
is accepted:

1. The database must be accessible to the user (database administrator)
 running DBRECOV. This user must either be the creator of the database
or know the maintenance word. If the database resides in a group or
 account different from the user's on, the MPE/iX file security must
 permit the user read and write access to the database files.

2. The database must have been enabled for roll-back recovery.

3. The log identifier characteristics (name, password, log file name and
 device type) must not have been altered since the log file was generated.
 This restriction applies to MPE/iX log commands as well as those provided
 by TurboIMAGE/XL by DBUTIL. This is necessary because the MPE/iX log
 identifier is used by TurboIMAGE/XL to obtain the name and device of the log file.

4. When roll-back is enabled, DBUTIL sets a roll-back flag to indicate that roll-back
 is enabled for the database. The roll-back time stamp is updated when the database
 is first opened and is logged to the log file. Roll-back recovery then uses the
 time stamp during recovery to verify the correct log file for each database.

5. No other users can be accessing the database when >ROLLBACK is called.
 The database can be concurrently accessed by users when the >CONTROL command
 is specified with the MODE4 option.

The >ROLLBACK command itself does not initiate recovery, but makes several
preparatory checks. The recovery system is actually initiated by the >RUN command.

The following commands are used with >ROLLBACK:

>FILE
>PRINT
>CONTROL

The >FILE command optional parameter rmode is not used with >ROLLBACK.
The following >CONTROL options are not applicable with >ROLLBACK:

STAMP, NOSTAMP, STORE, NOSTORE, STOPTIME

Example

>CONTROL NOSTATS
>ROLLBACK ORDERS
DATABASE ORDERS LAST USED THURS, SEP 7, 1989, 6:00 PM
>RUN

ORDERS is the database name.

>RUN

Initiates recovery-process. The recovery system opens the log file and
validates the log identifier before roll-forward recovery or roll-back
recovery begins.

Syntax

   >RUN

Discussion

For recovery to succeed, the log file must be accessible to the
database administrator. This means that the database administrator
must either be the creator of the log identifier used to create the
log file, or know the maintenance word and have system manager (SM)
or operator (OP) capability. If the database administrator does not
have system manager capability, and if the log file resides on disk
in a group and account different from logon, then the administrator
must have read access to the log file according to MPE/iX file security.

File equations are permitted. However, the fully qualified file name of
the expected log file must be specified. If the log file resides on tape,
the database administrator must know the volume identifier, so that the
operator can respond to the log file tape mount request.

If recovery succeeds, tabulated information is displayed and the program
is terminated. A table of process statistics includes the number of DBPUT,
DBDELETE, and DBUPDATE log records processed and the total transactions for
each process.

When using roll-forward recovery, an asterisk (*) may appear next to any
process indicating that either a DBCLOSE record is missing or some
transactions may not have been recovered. Therefore, no asterisk for a
process in the table of process statistics indicates that all transactions
were recovered.

The same table information is displayed when using roll-back recovery;
however, there is a slight difference. The database table will list all
incomplete transactions or DBPUT, DBDELETE, and DBUPDATE log records
that were "rolled-out." An asterisk (*) will appear next to these processes.
A table of database statistics includes the same information totaled for
each database. A logging system table includes the log identifier, log file
information, and recovery file information if this facility is used.

Example 1

Roll-forward recovery of database ORDERS. 

:RUN DBRECOV.PUB.SYS
>RECOVER ORDERS
DATABASE ORDERS LAST DBSTORED THURS, SEP 21, 1989, 8:30 AM
>RUN

Example 2

Roll-forward recovery of multiple databases ORDERS and RETAIL.
PART and SALES are filenames, ADMIN and MKTG are accounts in the FILE commands.
The 0 is the rmode and the 3 is the fmode.

:RUN DBRECOV.PUB.SYS
>RECOVER ORDERS
DATABASE ORDERS LAST DBSTORED MON, SEP 25, 1989, 6:40 PM
>CONTROL NOSTORE
>RECOVER RETAIL
>FILE PART,JOHN.ADMIN
>FILE SALES,MARY.MKTG,0,3
>RUN

Example 3

Roll-back recovery of multiple databases ORDERS and RETAIL. 

:RUN DBRECOV.PUB.SYS
>CONTROL NOABORTS
>ROLLBACK ORDERS,RETAIL
DATABASE ORDERS LAST USED THURS, SEP 21, 1989, 6:00 PM
DATABASE RETAIL LAST USED FRI, SEP 22, 1989, 8:00 AM
>RUN

Example 4

DBRECOV STOP-RESTART recovery on database ORDERS.
The recovery process is done on a secondary system with the mirror
database maintenance and recovery process. The following example
begins with a prompt for the user to continue or stop the roll-forward
recovery process on the secondary system. When DBRECOV cannot find the
next log file in a log set, the user can stop the recovery process and
back up the secondary system. In the example, note that the restart file
ORDERLOG is named after the database logid.

UNABLE TO OPEN LOG FILE ORDER005
REPLY `CONTINUE' OR `STOP' ON CONSOLE.
STOP

DATABASE(S) WITH RECOVERY SUSPENDED:
ORDERS.DATAMGT.ADMIN

RESTART RECOVERY WITH LOG FILE: ORDER005
QUIET BLOCK BEGINS AT RECORD 1005
NUMBER OF RECORDS IN STAGING DISC 1810
RESTART FILE NAME: ORDERLOG
:FILE L;DEV=TAPE
:STORE ORDERS@;*L
:RUN DBRECOV.PUB.SYS,RESTART
WHICH DATABASE? ORDERS

DATABASE(S) TO BE RESTARTED:
ORDERS.DATAMGT.ADMIN

CONTINUE WITH RECOVERY (N/Y)? Y

ADDITIONAL INFORMATION

Commands:  DBRESTOR, DBUTIL