HP 3000 Manuals HP 3000 Manuals
Utility Program Operation Database utilities can be run in either job or session mode. With the exception of DBUTIL's >>SHOW command, DBUTIL, DBSTORE, DBRESTOR, DBUNLOAD, and DBLOAD all require you to be logged on in the group and account that contains the database root file. Consequently, these utilities cannot be used with a remote database unless you initiate a remote session and run the utility as part of that session. The DBUTIL, DBSTORE and DBRESTOR utilities do not allow you to use the MPE/iX FILE command to equate a database or database-access file.
CAUTION DBUNLOAD and DBLOAD do allow MPE/iX FILE commands to equate a database and can redirect the database to a different file. Except in a controlled environment, you should not use the MPE/iX FILE command to redirect a database or database-access file to a different file, because that file can be purged easily.
The DBRECOV utility is not included in the discussion above because it is an exception. With DBRECOV, MPE/iX FILE commands are permissible and you need not be logged on to the same group and account as the log file. However, DBRECOV must be invoked on the system where the database resides. To execute the DBUTIL >>CREATE command or to change or remove the maintenance word with the DBUTIL >>SET command, you must log on with the same user name (including account name) that was used when the Schema Processor created the root file; this verifies to TurboIMAGE/XL that you are the database creator. To operate the other database utilities or enter other DBUTIL commands, you need not be the database creator provided you know the maintenance word. If no maintenance word is defined, only the database creator can execute the other utilities and the DBUTIL commands that require a maintenance word. The exception to this rule is that a user with system manager (SM) capability can use the DBUTIL >>SHOW command on any database without having to supply the maintenance word.
NOTE To maintain compatibility with earlier versions of DBUTIL, the >>CREATE, >>ERASE, and >>PURGE commands can also be executed by specifying them as DBUTIL entry points.
Backup Files The backup files created by DBSTORE and DBUNLOAD can be written only to magnetic tape volumes. In the discussion of the utilities that follows, the term volume refers to a magnetic reel. Error Messages Some of the error messages are described with the operating instructions for the utilities. Appendix A contains a complete listing of the error messages issued by these programs. DBLOAD Loads data entries from the backup volume(s) created by the DBUNLOAD utility into data sets of the database. Operation 1 [:FILE DBLOAD[=filename] [;DEV=device] ] 2 :RUN DBLOAD.PUB.SYS : 3 WHICH DATABASE? database name [/maint word] WARNING: The LANGUAGE of the database is DIFFERENT from the language found on the DBLOAD MEDIA. Continue DBLOAD operation? (Y/N): 4 DATA SET m: x ENTRIES : 5 END OF VOLUME n, y READ ERRORS RECOVERED 6 DBLOAD OPERATION COMPLETED END OF PROGRAM (Refer to "Operation Discussion" later in this section.) The volume(s) must have been produced by the DBUNLOAD program, and the database name on the volume must be exactly the same as the database name, or root file name, in the current session or in the group and account of the job. DBLOAD issues an error message if the database name or maintenance word specified is different from the DBUNLOAD file. In addition, DBLOAD checks that the group and account specified is the same as that in the DBUNLOAD file. To reload the identical data into the database, the DBUTIL ERASE command must be used prior to DBLOAD unless the database has been purged and re-created. Executing the >>ERASE command reinitializes the data sets to an empty state while keeping the root file and data sets as catalogued MPE/iX files on the disk. DBLOAD reads each entry from the backup volume and puts it into the respective data set from which it was read by DBUNLOAD. If a data set in the receiving database is an automatic master, no entries are directly put into it by DBLOAD, even though there are entries on the volume associated with the data set's number. Automatic master entries are created as needed in the normal fashion when entries are put into the detail data sets related to the automatic master. DBLOAD calls the DBPUT procedure to put the entries read from the backup volume into the appropriate data sets. In every case, the DBPUT dset parameter is a data set number and the list parameter is an at-sign followed by a semicolon (@;). Prior to calling DBPUT, DBLOAD moves each entry from the backup volume into a buffer. The length of the entry is determined by the definition of entries in the target data set. When DBLOAD is calling DBPUT, this length is less than, equal to, or greater than the length of an entry on the backup volume. If the data set entry is larger than the backup entry, the data is left-justified and is padded out to the maximum entry length with binary zeros. If the data entry is smaller than the backup entry, the backup volume record is truncated on the right and the truncated data is lost. The location of master set entries is based on their key item value which is hashed to an internal location. The detail data set entries are put into consecutive data set records with the appropriate new chain pointer information. DBLOAD requires exclusive access to the database. If the database is already open to any other process, DBLOAD terminates and prints the message: DATABASE IN USE Parameters filename is the name (up to 8 characters) that replaces DBLOAD in the mount request at the operator's console. device is the device class name of the device from which the data entries are to be loaded. Tape is the only supported device class. database name is the name of a TurboIMAGE/XL database root file created in the current session or job's account and logon group. maint word is the maintenance word defined by the database creator. This word must be supplied by anyone other than the database creator. Message Variables m is the number of the last data set loaded from the backup volume. x is the number of entries loaded into the specified data set. x is zero if the data set is an automatic master. Note: This number may not represent the total number of records in the data set if entries existed prior to DBLOAD execution. n is the volume number. y is the number of read errors from which DBLOAD recovered. Operation Discussion 1 Is an optional file equation that specifies the device class name for the device from which the data entries are to be loaded. The default is device class TAPE. 2 Initiates execution of the DBLOAD program in the PUB group and SYS account. 3 In session mode, DBLOAD prompts for the database name and maintenance word. In job mode, the database name and maintenance word, if any, must be in the record immediately following the RUN command. The language ID of the database is stored along with data when DBUNLOAD has been used to copy the database to tape. If the database native language (on disk) is not consistent with the system level native language (on tape), the following message will appear (refer to appendix A for more information): WARNING: The LANGUAGE of the database is DIFFERENT from the language found on the DBLOAD MEDIA. Continue DBLOAD operation? (Y/N): 4 After each data set is copied, DBLOAD prints a message on the list file device which includes the data set number and the number of entries copied. 5 When the end of a volume is encountered, DBLOAD prints a message (where z is the logical device number of the unit, XXXX is the database name, and n is the volume number). DBLOAD also instructs the operator to mount a new tape with the following message on the system console: MOUNT DBLOAD VOLUME XXXXn ON LOGICAL DEVICE z If the operator mounts the wrong volume, DBLOAD informs the operator with the following message (where z is the logical device number): WRONG VOLUME MOUNTED ON LOGICAL DEVICE z DBLOAD then terminates and you must begin loading the database again. This requires executing the DBUTIL >>ERASE command again if any entries have already been loaded. 6 After the data entries have been successfully loaded, DBLOAD prints a completion message. Console Messages After you supply the database name and DBLOAD opens the input file, a message is displayed on the system console. A tape must be mounted on the appropriate unit and identified through an operator reply. Refer to the Volume Management Reference Manual for instructions about console interaction. Using ControlY When executing DBLOAD in session mode, ControlY can be pressed to request the approximate number of entries in the current data set that have already been copied. DBLOAD prints the following message on $STDLIST: <CONTROL Y> DATA SET m:x ENTRIES HAVE BEEN PROCESSED Example :RUN DBLOAD.PUB.SYS WHICH DATABASE? ORDERS/SELL DATA SET 1: AUTOMATIC MASTER DATA SET 2: 19 ENTRIES DATA SET 3: 25 ENTRIES DATA SET 4: 12 ENTRIES DATA SET 5: 32 ENTRIES DATA SET 6: 258 ENTRIES END OF VOLUME 1, 0 READ ERRORS RECOVERED DATABASE LOADED END OF PROGRAM Initiate execution of DBLOAD. Supply the database name and maintenance word. DBLOAD indicates the number of entries copied. Data set 1 is an automatic master so 0 entries are copied; the entries are created as related detail entries are copied to the database. One volume was copied with no read errors.
NOTE For optimum performance, DBLOAD uses deferred output when it adds entries to a database. With deferred output, data and structural information cannot be written back to disk each time DBPUT returns to the DBLOAD program. As a result, the database is not considered to be logically or structurally complete on disk until the DBLOAD is complete. During DBLOAD the database being loaded is considered inconsistent ("bad") and only at the completion of a DBLOAD run is the database considered consistent ("good") again. During a load if an MPE/iX or hardware failure occurs, the database is definitely not structurally intact, and it returns its "bad" flag. After the system is brought back up, TurboIMAGE/XL does not allow the database to be opened for normal access. If you get a "bad database" error in such a situation, erase the database with DBUTIL and then perform the load again. (For more information on the error message "Bad Database" refer to appendix A). Alternatively, the database can be purged with DBUTIL and then restored from a backup copy.
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. For more information on roll-forward recovery, roll-back recovery, and the DBRECOV STOP-RESTART feature, refer to chapter 7. 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. Example 4 shows a step-by-step mirror database maintenance. The commands associated with DBRECOV are >CONTROL, >EXIT, >FILE, >PRINT, >RECOVER, >ROLLBACK and >RUN. Each command is discussed separately on the following pages. Operation :RUN DBRECOV.PUB.SYS [,option] Options 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). Initiates execution of the DBRECOV program in the PUB group and SYS account. The recovery system prints a banner indicating the version, date and time. It then prompts for a command input. 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 Text Reference Chapter 7 >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...] Discussion The >CONTROL options are described in detail on the next page. 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 (see discussion under DBCONTROL in chapter 5). 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. Parameters [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). For more information on both ABORTS and NOABORTS refer to chapter 7. [NOUNEND] causes DBRECOV to suppress incomplete transactions. Recovery can fail due to a record file overflow (see "Record Numbers" later in this section). UNEND prevents DBRECOV from suppressing incomplete transactions. STOPTIME= causes DBRECOV to impose an artificial end-of-file when mm/dd/yy hh:mm 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. 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. [NOSTATS] negates the STATS option; tabulated information is not printed unless a database is 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. Text Reference Chapter 7 >EXIT Used to terminate DBRECOV without recovering any databases. Syntax >EXIT Text Reference Chapter 7 >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. See "File Command" in chapter 7 for a full discussion qualifying the return of log records. 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. Text Reference Chapter 7