DBUNLOAD


DBUNLOAD

     Copies the data entries from each data set to specially formatted tape volumes.

SYNTAX

     [:FILE DBUNLOAD[=filename] [;DEV=device] ]
:RUN DBUNLOAD.PUB.SYS [,CHAINED | ,SERIAL ]
 WHICH DATABASE? database_name [/maint_word]
.
.
.

DATA SET m: x ENTRIES EXPECTED, x ENTRIES PROCESSED

END OF VOLUME n, y WRITE ERRORS RECOVERED
SAVE VOLUME ON LOGICAL DEVICE z AS n

DATABASE UNLOADED


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.

The file equation is optional and specifies the device class name for the device
to which the data entries are to be unloaded. The default is device class TAPE.

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.


OPERATION

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 with DBUTIL >>PURGE.
3.Change the schema and create a new root file with DBSCHEMA.
4.Execute the DBUTIL >>CREATE command.
5.Reload the data entries from the volumes created by DBUNLOAD with DBLOAD.

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.

DBUNLOAD File:

Sequence of Entries (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.

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.

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!!

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.

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

ADDITIONAL INFORMATION

Commands:  DBLOAD, DBUTIL