5 Database Utilities

DBCREATE, DBERASE and DBPURGE commands

Three commands (DBCREATE, DBERASE and DBPURGE) are used to create, erase and purge selected data set files or entire databases. Each command requires exclusive access to the database (meaning the database cannot be open).

DBCREATE

The DBCREATE command creates and initializes the data sets of a database. The schema processor only saves the meta information in the database server catalog, however no resources are allocated.

DBCREATE is used after the schema program has installed the database structure in the database server catalog. DBCREATE is available as a commandline utility or a Eloquence statement.

The following command can be executed from the operating system commandline:

dbcreate [options] database [data set [ data set ] . . .] ] ]

NOTE: The user must have administrative capabilities for either the server or the database. When using the eloqdb5 server, the user information is ignored and the maintenance password must be specified.

The DBCREATE statement can be used in a Eloquence program:

DBCREATE root file spec [;maintenance word] [,set list] [,return status]

NOTE: The user must be authorized with the DBLOGON statement before using executing DBCREATE. The user must have administrative capabilities for either the server or the database. When using the eloqdb5 server, the user information is ignored and the maintenance password must be specified.

The dbcreate commandline utility

Syntax of the dbcreate command is as follows:

dbcreate [-u user] [-p password] [-v] database [data set [ data set ] . . .] ] ]

The parameters are:

-u user
Specify user id. The user must have administrative capabilities for the server or the database. The user name is obtained by default from the LOGNAME or USER environment variable.
-p password
Specify password. When using the eloqdb5 server, this must be the maintenance password of the database.
-v
An optional parameter that displays the processing procedure. -v stands for "verbose".
database
A string expression identifying the database name (for example, SAD). If not specified, user will be prompted for database name and password.
data set
Name or number which identifies a particular data set. Specifying one or more data sets is optional. If no data sets are specified, all the sets in the database definition file are created. When data set identities are supplied, dbcreate creates only the data sets specified. Data sets may be identified by name or number.
dbcreate Example:

dbcreate -v SAD
Display:

B1368B DBCREATE (C) COPYRIGHT MARXMEIER SOFTWARE AG

Processing data base: SAD

DATA SET              INDEX(ES)
---------------- -- - --------------------
DATE             01 A
ORDER            02 A
PRODUCT          03 M   1
LOCATION         04 M
OPTION           05 D
CUSTOMER         06 D   2
  |              |  |   |
  |              |  |   |
  Dataset Name   |  |   Number of Indexes defined
                 |  |
                 |  Dataset Types
                 |    A= Automatic Master
                 |    M= Manual Master
                 |    D= Detail
                 |
                                       Dataset Number
In this example, all the data sets in the SAD data definition file are created.

The DBCREATE statement

Syntax of the DBCREATE statement is as follows:

DBCREATE database [;maintenance word] [,set list] [,return status]

The parameters are:

database
A string expression identifying the database name. An optional volume label can be appended to the database name.
maintenance word
A string expression identifying a security password. This expression can be from 1 through 16 characters in length. The maintenance password is only used with eloqdb5 servers.
set list
A string expression identifying particular data sets. Data sets are specified by either name or number. Set identifiers are separated by commas.
return status
A numeric variable in which an error number is returned (refer to page 197 ). 0 is returned if no error occurs.
When a set list is supplied, DBCREATE creates only the sets specified. Sets may be identified by name or number (for example: "1,2,CUSTOMER"). If no set list is supplied, DBCREATE attempts to create all data sets of the database.

When executed from the keyboard without a return status parameter, certain errors may be reported by DBCREATE without terminating execution (see page 197 for a description of these non-fatal errors). However, when DBCREATE is executed from a program or when it is executed from the keyboard and a return variable is used, the first error encountered terminates execution of the command. When the return status variable is used, the return variable contains the error number (or 0 if no errors are encountered), but no error message is displayed.

DBERASE

The DBERASE command erases all entries in data set files. All associated path information in related data sets is also erased. This command is often used prior to reloading data entries. DBERASE is available as a commandline utility or a Eloquence statement.

The following command can be executed from the operating system commandline:

dberase [-u user] [-p password] [-v] database [data set [ data set ] . . .] ] ]

NOTE: The user must have administrative capabilities for either the server or the database or must have the erase privilege for a dataset. When using the eloqdb5 server, the user information is ignored and the maintenance password must be specified.

The DBERASE statement can be used in a Eloquence program:

DBERASE root file spec [;maintenance word] [,set list] [,return status]

NOTE: The user must be authorized with the DBLOGON statement before using executing DBERASE. The user must have administrative capabilities for either the server or the database or must have the erase privilege for a dataset. When using the eloqdb5 server, the user information is ignored and the maintenance password must be specified.

The dberase commandline utility

Syntax of the dbcreate command is as follows:

dberase [-u user] [-p password] [-v] database [data set [ data set ] . . .] ] ]

The parameters are:

-u user
Specify user id. The user must have administrative capabilities for the server or the database. The user name is obtained by default from the LOGNAME or USER environment variable.
-p password
Specify password. When using the eloqdb5 server, this must be the maintenance password of the database.
-v
An optional parameter that displays the processing procedure. -v stands for "verbose".
database
A string expression identifying the database name (for example, SAD). If not specified, user will be prompted for database name and password.
data set
Name or number which identifies a particular data set. Specifying one or more data sets is optional. If no data sets are specified, all the sets in the database definition file are created. When data set identities are supplied, dbcreate creates only the data sets specified. Data sets may be identified by name or number.
dberase Example:

dberase -v SAD
Disaplay:

B1368B DBCREATE (C) COPYRIGHT MARXMEIER SOFTWARE AG

Processing database: SAD

DATA SET               INDEX
---------------- -- -  -----------------
DATA             01 A
ORDER            02 A
PRODUCT          03 M
LOCATION         04 M
OPTION           05 D
CUSTOMER         06 D
  |              |  |
  |              |  |
  Data Set Name  |  |
                 |  |
                 |  Data Set Type
                 |    A = Automatic Master
                 |    M = Manual Master
                 |    D = Detail
                 |
                 Data Set Number
In this example, the contents of all the data sets are erased.

The DBERASE Statement

Syntax of the DBERASE statement is as follows:

DBERASE database [;maintenance word] [,set list] [,return status]

The parameters are:

database
A string expression identifying the database name. An optional volume label can be appended to the database name.
maintenance word
A string expression identifying a security password. This expression can be from 1 through 16 characters in length. The maintenance password is only used with eloqdb5 servers.
set list
A string expression identifying particular data sets. Data sets are specified by either name or number. Set identifiers are separated by commas.
return status
A numeric variable in which an error number is returned (refer to page 197 ). 0 is returned if no error occurs.
When executed from the keyboard, DBERASE displays either the set number of the set being erased or the related set number followed by a P when path information is being erased.

When a set list is supplied, DBERASE erases only the data entries in the sets specified. Sets may be identified by name or number (for example: "1,2,CUSTOMER"). If no set list is supplied, DBERASE attempts to erase all data sets of the database.

When executed from the keyboard without a return-status parameter, certain errors may be reported by DBERASE without terminating execution (see page 197 for a description of these non-fatal errors). However, when DBERASE is executed from a program or when it is executed from the keyboard and a return variable is used, the first error encountered terminates execution of the command. When the return status variable is used, the return variable contains the error number (or 0 if no errors are encountered), but no error message is displayed.

NOTE: Executing a DBERASE on a master data set erases all chain information linking the master set entries with related detail entries. This erased chain information may cause unexpected errors on subsequent accesses of the database.

DBPURGE

The DBPURGE command deletes specified data sets or all data sets and the associated root file. This command is often used prior to recreating the database. DBPURGE is available as a commandline utility or a Eloquence statement.

The following command can be executed from the operating system commandline:

dbpurge [options] database [data set [ data set ] . . .] ] ]

NOTE: The user must have administrative capabilities for either the server or the database. When using the eloqdb5 server, the user information is ignored and the maintenance password must be specified.

The DBPURGE statement can be used in a Eloquence program:

DBPURGE root file spec [;maintenance word] [,set list] [,return status]

NOTE: The user must be authorized with the DBLOGON statement before using executing DBCREATE. The user must have administrative capabilities for either the server or the database. When using the eloqdb5 server, the user information is ignored and the maintenance password must be specified.

The dbpurge commandline utility

Syntax of the dbpurge command is as follows:

dbpurge [-u user] [-p password] [-v] [-f] database [data set [ data set ] . . .] ] ]

The parameters are:

-u user
Specify user id. The user must have administrative capabilities for the server or the database. The user name is obtained by default from the LOGNAME or USER environment variable.
-p password
Specify password. When using the eloqdb5 server, this must be the maintenance password of the database.The maintenance password is only used with eloqdb5 servers.
-v
An optional parameter that displays the processing procedure. -v stands for "verbose".
-f
Option to force the utility to purge the database, even if deletion of sets fails.
database
A string expression identifying the database name (for example, SAD). If not specified, user will be prompted for database name and password.
data set
Name or number which identifies a particular data set. Specifying one or more data sets is optional. If no data sets are specified, all the sets in the database definition file are created. When data set identities are supplied, dbcreate creates only the data sets specified. Data sets may be identified by name or number.
dbpurge Example:

dbpurge -v SAD
Display:

B1368B DBPURGE (C) COPYRIGHT MARXMEIER SOFTWARE AG
Processing database: SAD

DATA SET
---------------- -- -
DATA             01 A
ORDER            02 A
PRODUCT          03 M
LOCATION         04 M
OPTION           05 D
CUSTOMER         06 D
  *              |  |
  |              |  |
  |              |  |
  Data Set Name  |  |
  and ROOT File  |  |
                 |  Data Set Type
                 |    A = Automatic Master
                 |    M = Manual Master
                 |    D = Detail
                 |
                 Data Set Number
In this example, all the data sets and the root file of the SAD database are deleted.

The DBPURGE Statement

Syntax of the DBPURGE statement is as follows:

DBPURGE database [;maintenance word] [,set list] [,return status]

The parameters are:

database
A string expression identifying the database name. An optional volume label or unit specifier can be appended to the database name.
maintenance word
A string expression identifying a security password. This expression can be from 1 through 16 characters in length.The maintenance password is only used with eloqdb5 servers.
set list
A string expression identifying a particular data set. Data sets are specified by either name or number. Set identifiers are separated by commas.
return status
A numeric variable in which an error number is returned (refer to page 197 . A 0 is returned if no error occurs.
When executed from the keyboard, DBPURGE displays either the number of the set being purged or an * when the root file is being purged.

When a set list is supplied, DBPURGE deletes the data set files of the specified sets. Sets may be identified by either name or number (for example, "1,2,CUSTOMER"). If no set list is supplied, DBPURGE attempts to purge all data set files of the database, and if successful, attempts to purge the root file.

When executed from the keyboard without a return-status parameter, certain errors may be reported by DBPURGE without terminating execution (see page 197 for a description of these non-fatal errors). However, when DBPURGE is executed from a program or when it is executed from the keyboard and a return variable is used, the first error encountered terminates execution of the command. When the return status variable is used, the return variable contains the error number (or 0 if no errors are encountered), but no error message is displayed.

Eloquence Database Manual - 19 DEC 2002