HP 3000 Manuals HP 3000 Manuals
Utility Program Operation (contd.)
DBUNLOAD
Copies the data entries from each data set to specially formatted tape
volumes.
Operation.
1
[:FILE DBUNLOAD[=filename] [;DEV=device] ]
2
:RUN DBUNLOAD.PUB.SYS [,CHAINED]
[,SERIAL ]
:
3
WHICH DATA BASE? database name [/maint word]
:
4
DATA SET m: x ENTRIES EXPECTED, x ENTRIES PROCESSED
5
END OF VOLUME n, y WRITE ERRORS RECOVERED
SAVE VOLUME ON LOGICAL DEVICE z AS n
6
DATABASE UNLOADED
END OF PROGRAM
(Refer to "Operation Discussion" later in this section.)
Parameters.
filename is the name (up to 8 characters) that replaces
DBUNLOAD in the mount prompt at the operator's
console.
If you want information about your data set chains
without actually performing a DBUNLOAD, supply
$NULL as the filename. This causes a simulated
unloading of the database, preventing the need to
mount a tape.
device is the device class name of the device to which the
data entries are to be copied.
database name is the name of the TurboIMAGE/XL database to be
unloaded.
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 data sets in the database.
x is the number of entries (expected) and the number
of entries processed or copied from the specified
data set.
n is the number of the volume.
y is the number of write errors from which DBUNLOAD
has successfully recovered.
z is the logical device number of the unit.
DBUNLOAD is necessary if you want to modify the database structure to,
for example, increase the capacity of a data set. To increase a
capacity,
1. Unload the entries.
2. Purge the database.
3. Change the schema and create a new root file.
4. Execute the DBUTIL >>CREATE command.
5. Reload the data entries from the volumes created by DBUNLOAD.
The data sets are unloaded in the order that they were defined in the
original schema. No data set names are recorded on the backup volume(s);
entries are merely associated with the corresponding data set from which
they are read. DBUNLOAD calls the DBGET procedure to read each entry
from each set of the database and, to read the complete entry, uses a
list parameter of an at-sign followed by a semicolon (@;). Values for
data items appear in each entry in the same order as the items were
mentioned in the data set definition in the schema. The language ID is
copied along with the data of the database.
DBUNLOAD requires exclusive access to the database. If the database is
already open by any other process, DBUNLOAD prints the message:
DATABASE IN USE
and prompts again for a database name.
DBUNLOAD operates in either serial or chained mode as explained below.
The mode is determined by the entry point specified with the RUN command;
for example:
:RUN DBUNLOAD.PUB.SYS,CHAINED
The default entry, if none is specified, is chained.
* In serial mode, DBUNLOAD copies the data entries serially in
record number order. "Stand-alone" detail data sets, those which
are not tied to any master data sets through specified search item
paths, are always unloaded serially.
* In chained mode, DBUNLOAD copies all of the detail entries with
the same primary path search item value to contiguous locations on
the backup file. The ordering of the search item values from the
primary path is based on the physical order of the matching value
in the associated master data set. Figure 8-1 (shown at the
end of this section on DBUNLOAD) illustrates the method for
unloading a data set in chained mode. After the database is
reloaded, chained access along the primary path is more efficient.
Broken Chains
If a chained DBUNLOAD encounters a broken chain, it will unload all
entries in the chain down to, but not including the break. It will then
go to the end of the chain and follow the chain backward to the break,
then unload the remaining records of the chain. In some instances, this
will save all entries in the chain. In any case, the order of the
entries is preserved. Information about each broken chain in a data set
is printed before the end-of-the-data-set summary (see statement 4 under
"Operation Discussion" in this section).
Operation Discussion.
1 An optional file equation that specifies the device class name for
the device on which the data entries are to be copied. The default
is device class TAPE.
2 Initiates execution of the DBUNLOAD program in the PUB group of the
SYS account.
3 In session mode, DBUNLOAD 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.
4 After copying a data set without detecting a broken chain, DBUNLOAD
prints a message that includes the data set number and the number of
entries copied.
If DBUNLOAD detects a broken chain, the following messages are also
returned:
DATA SET m: Broken Chain at Entry #p[,following Entry #q]
Chain Head is Entry #r of Data Set #s
Key = k
l entries [expected,j entries salvaged]
where:
p is the entry number where the break was detected.
q is the number of the entry last unloaded from the front of the
chain, if any.
r is the entry number of the chain head.
s is the data set number of the chain head.
k is the value of the key of the broken chain.
l is the length of the chain according to the user label.
j is the number of entries salvaged from the chain.
These four message lines are repeated for every broken chain in the
data set, followed by the end-of-data-set summary that reports the
number of lost entries, if any:
DATA SET m: x ENTRIES[EXPECTED, t LOST!!]
For example:
DATA SET 1: 3 ENTRIES
DATA SET 2: Broken Chain at Entry #2, following Entry #1
Chain Head is Entry #5 of Data Set #1
KEY = AA
4 entries expected, 3 entries salvaged
DATA SET 2: 11 ENTRIES EXPECTED; 1 LOST!!
5 When the end of a volume is encountered, DBUNLOAD prints this
message:
END OF VOLUME n, y WRITE ERRORS RECOVERED
where n is the number of the volume and y is the number of write
errors from which DBUNLOAD successfully recovered. DBUNLOAD also
instructs the operator to save the current volume and mount a new one
by printing the following two messages on the system console (where z
is the logical device number of the tape drive and n is the volume
number):
SAVE VOLUME ON LOGICAL DEVICE z AS n
MOUNT NEXT VOLUME ON LOGICAL DEVICE z.
6 After the data sets have been successfully copied, DBUNLOAD issues a
completion message.
DATABASE UNLOADED
END OF PROGRAM
Console Messages
After you supply the database name and DBUNLOAD opens the output 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 DBUNLOAD in session mode, you can press ControlY to
request the approximate number of entries in the current data set that
have already been written. DBUNLOAD then prints the following message on
$STDLIST:
<CONTROL Y>DATA SET m: x ENTRIES HAVE BEEN PROCESSED
Writing Errors
If an unrecoverable write error occurs, DBUNLOAD prints the message:
UNRECOVERABLE WRITE ERROR, RESTARTING AT BEGINNING OF VOLUME
and attempts to recover by starting the current volume again. It also
sends this message to the system operator (where z is the logical device
number of the unit):
WRITE PROBLEMS TRY ANOTHER VOLUME ON LOGICAL DEVICE z
If an excessive number of non-fatal write errors occur, DBUNLOAD again
attempts to recover from the beginning of the volume after printing the
following message on the $STDLIST and sends the same message to the
system operator as described for unrecoverable errors above:
EXCESSIVE WRITE ERROR RECOVERIES, RESTARTING AT BEGINNING OF VOLUME
Example (Session Mode).
:RUN DBUNLOAD.PUB.SYS
:
WHICH DATABASE? ORDERS
DATA SET 1: 3 ENTRIES EXPECTED, 3 ENTRIES PROCESSED.
DATA SET 2: 11 ENTRIES EXPECTED, 11 ENTRIES PROCESSED.
END OF VOLUME 1, 0 WRITE ERRORS RECOVERED
DATABASE UNLOADED
END OF PROGRAM
Example (Job Mode).
:JOB MGR.ACCOUNTA Initiate job.
:RUN DBUNLOAD.PUB.SYS Initiate execution of DBUNLOAD.
ORDERS Specify database name.
:EOJ Initiate end of job.
Because the user in this example is the database creator, a maintenance
word is not provided. The DBUNLOAD program is executed in chained mode
by default because no entry is specified.
As the job executes, the following information is printed on the
$STDLIST:
DATA SET 1: 50 ENTRIES EXPECTED, 50 ENTRIES PROCESSED.
DATA SET 2: 9 ENTRIES EXPECTED, 9 ENTRIES PROCESSED.
DATA SET 3: 24 ENTRIES EXPECTED, 24 ENTRIES PROCESSED.
DATA SET 4: 12 ENTRIES EXPECTED, 12 ENTRIES PROCESSED.
DATA SET 5: 5 ENTRIES EXPECTED, 5 ENTRIES PROCESSED.
DATA SET 6: 0 ENTRIES EXPECTED, 0 ENTRIES PROCESSED.
END OF VOLUME 1,0 WRITE ERRORS RECOVERED
DATABASE UNLOADED
END OF PROGRAM
![[]](../../pic3k/M017091/FFN313c50.gif)
Figure 8-1. DBUNLOAD File: Sequence of Entries
DBUTIL
The DBUTIL program performs several different functions according to the
command you enter. Each DBUTIL command is described separately on the
following pages.
Operation.
1 :RUN DBUTIL.PUB.SYS
2 >>command
Operation Discussion.
1 Initiates execution of the DBUTIL program in the PUB group of the SYS
account.
2 Prompts for a DBUTIL >>command. Enter one of the following:[REV BEG]
HELP VERIFY ADDINDEX EXIT
CREATE SET DROPINDEX
ERASE ENABLE REBUILDINDEX
MOVE DISABLE REDO
PURGE RELEASE DO
DEACTIVATE SECURE LISTREDO
ACTIVATE SHOW DETACH
[REV END]
DBUTIL commands can be abbreviated to the first three characters or less.
For example, >>CREATE can be abbreviated to >>C or >>CRE. Enter the HELP
command for the minimum abbreviation for each command.
When using the >>CREATE, >>PURGE, or >>ERASE command, you can bypass the
command prompt by specifying the full command as an entry point with the
RUN command; for example,
:RUN DBUTIL.PUB.SYS,CREATE
If you use an entry point, TurboIMAGE/XL prompts you for the database
name and, optionally, for the maintenance word, as follows:
Database name: database name [/maint word]
where:
database name is the name of a TurboIMAGE/XL database root file
catalogued in the current session or job's account
and logon group.
maint word is an optional ASCII string, one to eight
characters long with no commas or semicolons, that
defines a password to be used by anyone other than
the database creator to enable them to execute
certain DBUTIL commands, and operate other
utilities. (The database creator can also define
or change the maintenance word by using the >>SET
command).
In job mode, the database name and maintenance word, if any, must be in
the record immediately following the RUN command. To perform any DBUTIL
command except >>SHOW, >>HELP, or >>EXIT, you must have exclusive access
to the database or database-access file.
>>ACTIVATE
Activates the database-access file for use with DBOPEN. Before using this
command, read the description of remote database access in chapter 9.
This command should be used to prepare a database-access file before
accessing a remote database residing on another HP 3000.
Syntax.
>>A[CTIVATE] database-access file name
For example:
ACTIVATE ORDDBA
where ORDDBA is the database-access file name
Parameter.
database- is the name of the database-access file that you created
access file with an editor.
name
The database-access file (created on the local system) can
have any legal MPE/iX file name and is not dependent on
the database name.
Unexpected Results
TurboIMAGE/XL checks that the following conditions are not violated:
* File code is 0.
* Record length does not exceed 128 characters.
* File is unnumbered.
* File has at least three records.
An appropriate error message is returned if any of these conditions is
violated. If all of the conditions are satisfied, DBUTIL prints the
message:
Verification follows:
and the syntax of the file is checked record by record. The monitoring
messages associated with the file records are of the form:
FILE command: <result>
DSLINE command: <result>
HELLO command: <result>
where <result> is "Looks good" if there are no errors associated with the
record. Appendix A lists the record errors (results) that would cause
the file to be rejected.
Example.
:RUN DBUTIL.PUB.SYS Initiate DBUTIL execution.
:
>>ACT ORDDBA Enter abbreviated form of ACTIVATE command and database-access file name.
Verification follows
FILE command: Looks good
DSLINE command: Looks good
HELLO command: Looks good
HELLO command: Looks good
ACTIVATED
>>
DBUTIL checks the structure of the file named ORDDBA for correct format
and activates the file. You will not be able to edit the file unless you
deactivate it using the DBUTIL >>DEACTIVATE command.
>>ADDINDEX
[REV BEG]
The ADDINDEX command updates the root file, and adds the associated
B-Tree index file. When using the ALL option and there is no master
dataset, a warning is generated, but the command is considered to be
successful.
Syntax.
{ALL }
>>ADDI[NDEX] database name [/maintword] FOR { setnamelist}
{setnumlist }
For example:
>>ADDINDEX ORDERS FOR ALL
where ORDERS is the database name.
Parameters.
database name is the name of a TurboIMAGE database.
maintword is the maintenance password.
setnamelist is the list setname [,...]
setnumlist is the list setnum[,...]
ALL means all master data sets for the database.
Example.
>>ADDINDEX ORDERS/secret FOR ALL
Found 4 master datasets.
Adding index to set# 1 (#entries = 162,730, capacity = 218,987)
Adding index to set# 2 (#entries = 84,164, capacity = 188,517)
Adding index to set# 3 (#entries = 18,784, capacity = 21,943)
Adding index to set# 4 (#entries = 783, capacity = 2583)
Done.
If the data set is big and DBUTIL is interactive, a progress report at an
interval of every 5% will be displayed.
5% done ...
10% done ...
It is always displayed on the same line. It will be overwritten by the
next permanent line.
Adding index to ... or Done.
[REV END]
>>CREATE
Creates and initializes a file for each data set in the database.
Once the Schema Processor has created the root file, the database creator
must build a file for each data set in the database using the >>CREATE
command. DBUTIL initializes each data set to zeros and saves it as a
catalogued MPE/iX file in the same logon group as the root file, on the
device classes specified in the schema. The data set names are created
by appending two digits to the root file name. If the root file is named
XXXX, then the first data set defined in the schema is named XXXX01, the
second data set is named XXXX02, and so on. In order to save files for
the maximum of 199 data sets per database, files are incremented from
XXXX01-99, XXXXA0-A9, XXXXB0-B9, up to XXXXJ9.
To execute the DBUTIL program to create and initialize the database, you
must be the database creator; that is, you must log on with the same user
name, account and group that was used to run the Schema Processor and
create the root file. After DBUTIL has created and initialized the
database files, it prints a confirmation message on the list file device
and prompts for another command.
[REV BEG]
The CREATE command has been enhanced to create the required chunk control
and chunk data files for jumbo data sets. To specify a jumbo data set,
the JUMBO option must be included in the schema before defining a jumbo
data set. Then any data set whose capacity is greater than 4GB
automatically becomes a jumbo data set.
The CREATE command does an implicit ADDINDEX command for each dataset
marked by DBSCHEMA as indexed.[REV END]
Syntax.
>>C[REATE] database name [/maint word]
For example:
CREATE ORDERS
where ORDERS is the database name.
Parameters.
database name is the name of a TurboIMAGE/XL database being
created.
maint word is the maintenance word that can be defined by the
database creator when the database is created. To
access the database, anyone other than the database
creator must supply this word.
Example (Session Mode).
:RUN DBUTIL.PUB.SYS Initiate DBUTIL executions.
:
>>CREATE ORDERS Respond to DBUTIL prompt with >> CREATE command and database name.
Database ORDERS has been CREATED
>>
DBUTIL creates, initializes, and saves files named ORDERS01, ORDERS02,
and so forth, one file for each data set. These constitute the empty
database.
Example (Job Mode).
:JOB MGR.ACCOUNTA Initiate job.
:RUN DBUTIL.PUB.SYS Initiate DBUTIL execution.
CREATE ORDERS Enter >>CREATE command and database name.
EXIT Terminate DBUTIL.
:EOJ Terminate job.
After the data files are created and initialized, DBUTIL prints the
following message on the list file device:
DATABASE ORDERS HAS BEEN CREATED
NOTE >>CREATE will fail if the native language defined for the database
is not supported at the system level. (Refer to appendix A or the
Native Language Support Programmer's Guide for more information.)
>>DEACTIVATE
Deactivates the database-access file to allow modifications to the file
or to disallow remote database access.
This command is used before you change the contents of the
database-access file. (Refer to chapter 9 for more information about
accessing remote databases.)
If DBUTIL successfully deactivates the file, it prints a confirmation
message on the list file device.
Syntax.
>>DE[ACTIVATE] database-access file name
For example:
DEACTIVATE ORDDBA
where ORDDBA is the database-access file name.
Parameter.
database-access file name is the name of the database-access file to be
deactivated.
Example.
:RUN DBUTIL.PUB.SYS Initiate DBUTIL execution.
:
>>DEACTIVATE ORDDBA Enter a >>DEACTIVATE command and the database-access file name.
DEACTIVATED
>>
>>DETACH
[REV BEG]
The DETACH command detaches the database from the DBEnvironment(s) the
database is attached to. You can use one command of DBUTIL to detach a
given database from all of the DBEnvironments to which it is attached;
you do not have to specify each DBEnvironment name.
If you copy your database to a different account or different group, then
issue a DETACH command for the copied database, you will get an error
stating that the detach failed from dbename.group.account (ATCERR 32052).
It is because the DETACH of the database triggers a lookup of the TC file
(which contains the names of the DBE to which the database is attached).
However, DBUTIL's subsequent verification of the original DBE shows the
name of the original database (not the name of the copied database) as
the one attached to this DBE. Due to this discrepancy, the following
things happen:
* DBUTIL reports an error and does not perform a real detach of the
copied database.
* The attached flag in the rootfile (copy) as well as the entry in
the TC file is cleared, in spite of the error.
* The original production database still remains attached to the
DBE.
The DETACH command updates the root file. Therefore, use caution when
copying an attached database.
Syntax.
>> DET[ACH] database name [/maintword]
For example:
>>DETACH ORDERS
where ORDERS is the database name.
Parameters.
database name is the name of the database.
maint word is the maintenance password.
Example.
>>DETACH ORDERS/secret
Database has been detached from these HP SQL DBEnvironments:
NEWDBE.BTRTESTS.IMAGESQL
TEMDBE.BTRTESTS.IMAGESQL
>>
[REV END]