E Obsolete Database Utilities

The DBUTIL program

Introduction

Dbutil provides all functionality of the former DBMODS utility and additionally provides the ability to change some aspects of the database structure without having to export/import the database.

Database changes can either be defined interactive or by a script file (called control script). This makes it possible for a software vendor to provide a control script to a customer to perform database changes without manual interaction. The dbutil may even be used to interactively create a control script.

The following actions can be performed:

r Set the maintenance password

r Define access classes

r Grant or revoke access to datasets

r Create a new data item

r Change data item definition

r Create a new index item

r Change index item definition

r Create a new data set

r Add new data items to a data set

r Add new indices to a data set

r Additionally, in interactive mode, it is possible to print a schema definition of the database.

DBUTIL commandline arguments

Synopsis:

   usage: dbutil [options] [file]
   options:
    -help   = show usage (this list)
    -i      = interactive mode (batch mode only)
    -n      = pretend          (batch mode only)
    -v      = verbose          (batch mode only)
    -e cnt  = abort processing after encountering cnt errors
    -t tmp  = where temporary files are stored
    -d      = debug
If a file argument is present, dbutil will process in batch mode unless the -i option is present. If the -n option is present, no changes will be made to the database. Processing will end after checking the input file and the analysis phase.

Arguments:

-i
After processing the supplied batch file, dbutil will change into interactive mode, so you can verify the database changes made so far or you can add additional changes. Interactive mode is the default, if no control file is specified on the command line.
-n
dbutil will analyze the control file but will not make any changes to the database. This option can be used to check the syntax of the control file or to get an overview which changes would be applied to the database.
-v[v]
Specifying the -v option will cause dbutil to output a summary of changes after analyzing the control file and some descriptive text during the database restructuring.
Specifying two -v options will cause dbutil to echo the control file to stdout as it is analyzed.
-e cnt
Abort processing the control file after encountering the given number of syntax or validation errors.
-t tmp
This option makes it possible to specify where temporary files will be created. As temporary files can become quite huge, it may overflow the default location.
If the -t argument is not specified, dbutil will allocate temporary files at the same location as the database.
-d
This is used internally to debug dbutil itself. You should not use it.
If a file argument is present, dbutil will process in batch mode unless the -i option is present.

Dbutil execution

Dbutil will execute in different phases:

  1. If a control file is given on the command line, it will analyze the control file and all changes imposed by the control file.

  2. If the interactive mode is requested by either specifying the -i argument or by omitting the control file, it will change into interactive mode.

  3. Finally it will analyze all changes and list the restructure operations it needs to perform. If the -n argument is present execution will stop here.

  4. If stdout and stdin are connected to a tty device, dbutil will prompt for a confirmation to apply the database changes. This is the last chance to change your mind. If you interrupt the program beyond this point, your database will be lost and you have to restore it from your backup.

  5. Finally dbutil will start to restructure the database.

Example

   $ dbutil test/du5
   B1368B DBUTIL (C) COPYRIGHT MARXMEIER SOFTWARE AG 2002 (A.05.10)

   Analyzing restructure specification ...
   Analysis completed successfully

   Checking database consistency ...
   Consistency check completed successfully

   Database restructure analysis:
   Analyzing changes:
    NEW-SET-M
    * this is a new data set
      Estimated temporary disc space required: 1 MB
    NEW-SET-D
     * this is a new data set
     Estimated temporary disc space required: 1 MB

   Estimated temporary disc space required: 1 MB
   Temporary files will be created at
    /disc/project/eloq/db2/ndbmods/test/db/
   Available disc space: 147 MB
   Data restructure process required.

   ------------------------------------------------------------
   PLEASE NOTE:
   If the restructure process fails or is interrupted, YOUR
   DATA BASE IS LOST and can only be recovered from a backup.
   If you don't have a current backup, you should NOT continue.
   ------------------------------------------------------------

   Continue with database restructure (y/n) ? y
   CAUTION: DO NOT INTERRUPT THIS PROGRAM!
   Removing current ROOT file
   Restructuring database ...
   NEW-SET-M
   NEW-SET-D
   Dumping new ROOT file /disc/project/eloq/db2/ndbmods/test/db/DB
   End of Database Maintenance Utility

Control file syntax

The dbutil control file is a plain text file. The following general rules apply:

r Everything after a hash character (#) is considered a comment and will be ignored.

r dbutil does recognize keywords in either upper or lower case (but not mixed).

r Each statement must be delimited by a semicolon (;)

r Identifiers such as Item, Index and Set-names may be specified in either case (upper/lower case).

r Strings must be enclosed in double quotes. To include a quote character in a string, the quote character must be preceded by a backslash (\) character.

r A statement may span multiple lines.

r Some statements allow repeating a list of definitions by enclosing it in curly braces.

The syntax description below use the following conventions:

r All keywords are given in upper case.

r All Identifiers, such as Item, Index and Set names are given in upper/lower case.

r Optional syntax elements are enclosed in brackets.

Eloquence Database Manual - 19 DEC 2002