Chapter 8
Changing the Definition Database
IMPORTANT: Some functions described in this chapter are available only with those
versions of BASIS that support screen mode: UNIX and VMS. BASIS on Windows
supports statement mode only. Generally, statement mode instructions are available in
Database Definition and Development; Windows users should look there for equivalent
information. Specific cross-references have been provided wherever possible.
Definition Database Structure
Each application database that you and others at your site create consists of a pair of
related databases:

a Record Database (RDB) that stores data

a Definition Database (DDB) that stores information describing the organization and
features of records in the Record Database
In addition, each site has a Master Definition Database (MDDB) which stores
information about each DDB. The MDDB is defined and supplied by Open Text and
cannot be directly accessed or changed. Your DDB is in a sense a “Record Database” in
relation to the MDDB.
Changing the Definition Database  321
Records in the DB consist of two kinds:

Statement records define objects in your database. Their content corresponds closely
to what you see on a DMDBA screen or syntax chart.

System records are processed or “applied” statement records. Containing more
detailed information needed by other modules of the system when they access a DDB
or RDB, system records can be thought of as an “executable” form of the statement
records. System records are never updated directly by the user.
Statement records and system records are stored in the Definition Database for your
application.
You can change your DDB and display and update its information by using the DMDBA
utility.
You can retrieve and display information about your DDB by using the FQM module.
The FQM SHOW/DDB command displays information about your DDB.
If you open the DDB for your application with INTENT=READ, specifying the
Xdb.USER model, where db is the name of your RDB, you can FIND and TYPE
information from your DDB.
For more information about . . .
See . .
BASIS Definition Database structure
Database Definition and Development,
“Overview of Database Definition and
Development”
Using the DMDBA utility
Database Definition and Development,
“DMDBA Module”
BASIS/Express-D
BASIS/Express Volume 2
Not available on Windows operating
systems.
FQM SHOW/DDB, FIND, and TYPE
commands
322  Changing the Definition Database
Interactive FQM Commands, “FQM
Basics” and The Complete FIND
Handbook
Backing Up Your Databases
WARNING: You should make a backup copy of the DDB before and after
changing it. If you make changes that require dumping and reloading data (changes
with a RES-N/A change code) or changes that require restructuring your RDB
(changes with a RES change code), you should also make a backup copy of your
RDB. (The RDB and the DDB have a generation number that the system uses to
make sure they are synchronized.) Use your host operating system backup utility or
command to make a backup copy of files.
For more information about dumping and reloading and restructuring the RDB, see
“Changes Requiring a Dump and Reload” and “Changes Requiring Index Restructure”
later in this chapter.
In addition to backing up your DDB before making changes, it is also advisable to know
ahead of time if dumping or index restructuring will be required. (Change codes on
change orders will tell you what you will need to do to complete the changes; they are
described later in this chapter.) For major changes, chart out what you plan to do and in
what order. Keep in mind things that involve down time (applies, dump/reload, index
dropping/rebuilding). You might also consider making a trial change on a small test copy
of the database that has data.
Methods of Changing the DDB
Just as you could define your database and perform administrative tasks using either
screen mode or statement mode, so also in changing the definition, you can use either
mode. For information about screen mode and statement mode, see Database Definition
and Development, “Overview of Database Definition and Development.”
Examples of changing various parts of the DDB will sometimes illustrate screen mode
and other times illustrate statement mode. Whichever mode you use, it is important when
you are changing a definition to be aware of what related parts may be affected and what
else you may need to do to complete the change. For a list of the various kinds of
changes that can be made to the DDB and the implications of those changes, see
Database Definition and Development, “Change Codes.”
Many DBAs prefer to enter the definition initially in statement mode but modify the
definition in screen mode. Since screen mode requires you to display the object before
changing it, the possibility of inadvertently omitting an existing parameter value is
minimized. Screen mode does not require knowing definition syntax and is best suited for
making small changes to a few objects.
Changing the Definition Database  323
If you use screen mode, it is wise to use journaling for the DDB so that you have a record
of what you have done.
You may, however, find statement mode faster and easier, especially if you are
performing a repetitive task such as authorizing users and you are confident of knowing
the implications of your changes.
WARNING: If you do not explicitly specify each parameter of an existing object
when you change it, the current parameter values are replaced by defaults.
The steps for changing the DDB are similar to those for creating the DDB. For
information about changing the DDB, change orders, and applying changes to the DDB,
see Database Definition and Development, “Overview of Database Definition and
Development.”
/UPDATE or /REPLACE
When you are changing the definition of an existing record or view, the difference
between /REPLACE and /UPDATE is important.

/UPDATE, the default, merges new information with current information about the
RECORD or VIEW.

/REPLACE completely overwrites the existing RECORD definition or VIEW
definition. With /REPLACE, only those fields specified in a statement file are
included in the new definition. If a field is in the current definition but is omitted
from the statement file, it will be deleted.
Assume an existing record or view, EXISTING_REC, contains three fields:
RECORD=EXISTING_REC,...
FIELD=A,TYPE=CHAR,SIZE=0:10...
FIELD=B,TYPE=CHAR,SIZE=0:10...
FIELD=C,TYPE=CHAR,SIZE=0:10...
The /UPDATE action leaves any field in the existing record or view intact if it is not
specified in the new statement file. Use the /UPDATE action to add to existing records.
EXISTING_REC can be changed with the /UPDATE action in this way:
RECORD/UPDATE=EXISTING_REC, ...
FIELD=A, TYPE=CHAR,SIZE=0:200, ...
DELETE FIELD EXISTING_REC.C;
FIELD=D, TYPE=CHAR, SIZE=0:10, ...
324  Changing the Definition Database
a.
Field A’s definition is updated to reflect the SIZE parameter
change. Any Field A parameters that are not included in the
new definition are replaced by defaults.
b.
Field B’s definition remains unchanged.
c.
Field C is deleted from the record.
d.
Field D is added to the definition.
If, instead of being compiled with /UPDATE as above, the following statement file is
compiled with RECORD/REPLACE to change the definition of EXISTING_REC
RECORD/REPLACE=EXISTING_REC,...
FIELD=A,TYPE=CHAR,SIZE=0:200...
FIELD=B,TYPE=CHAR,SIZE=0:10...
FIELD=D,TYPE=CHAR,SIZE=0:10...
a.
The definition of Field A has a new maximum size.
b.
Field B remains the same.
c.
Field C is deleted.
d.
Field D is added to the definition.
Any parameters of Field A or Field B that are not specifically defined in the new
statement file are replaced with defaults.
Note: When changing a UDM screen form view (FORM=YES), always use
/REPLACE.
Some Helpful Hints for Screen Mode
UNIX, VMS
This subsection is not applicable to Windows.

The system must be able to identify a particular record in order to change it.
Therefore, before you can change a record, you must uniquely identify it. Field
labels for parts that make up the key for uniquely identifying a DDB record are
prefaced by a pound sign (#).
Changing the Definition Database  325

A few objects are uniquely identified by a number instead of a name. Some
examples are Assertions, Files, and Backup Sets.

In going from a summary screen (Screen 12, for example) to a screen for adding or
revising more parameters for a field, use the Replace action, not the Add action to
transmit your added or changed information.

Some screens have several pages. On such screens a message like Page 1 of 6
appears in the upper right section of the screen. You can turn the pages with either
the [PAGE] key or the [NEXT_PAGE] key.
The [PAGE] key displays a prompt for the page number you want. When you type
the page number you want and press the [ENTER] key, the page is displayed.
The [NEXT_PAGE] key allows you to leaf through the pages sequentially. The
direction depends on whether you are in Backup or Advance Mode. If you do not
know which physical keys to press, select the Keypad_help action. Then choose to
see the Keypad for your system. Keypads vary from site to site and user to user.
Keypad help automatically reflects your keypad.
For more information about using function keys on screens and how to use screens,
see Screens.

An advantage of using screen mode is that if you enter something that causes a
compilation error, you are informed of this immediately and can correct the definition
on the screen to retransmit your change.

To move from one screen to another, type E in the action box, type the number of the
next screen you want to use in the NEXT_SCREEN box, and press [ENTER]. (For a
list of DMDBA screen names and their numbers, see “DMDBA Screens List.”) If
you want to leave screen mode, type 0 in the NEXT_SCREEN box.
Some Helpful Hints for Statement Mode
ALL
The information in this section applies to BASIS on all operating systems.Steps to follow
in using statement mode to change something in your database include:
326  Changing the Definition Database
1.
Use the DMDDBE utility to extract the definition of the object you want to change.
This lets you start with a syntactically correct definition and helps prevent the
accidental deletion of an existing parameter. For more information about the
DMDDBE utility, see “DMDDBE, Definition Database Extract.”
For example,
=> DMDDBE UID=id, UPW=pw
. . .
database> TOUR
Enter type of object you wish to have extracted.
Type EXIT to leave DMDDBE
object type> VIEW
object name> ALL.EMPLOYEE
object type> EXIT
Performing extraction
NORMAL TERMINATION - DMDDBE
=>
2.
Using your host system editor, edit the extracted file to indicate the change. The
extracted file would look like the following. You could, for example, change the
values for OUTPUT_FORMAT and LABEL.
*-----------------------USER_DATA_MODEL; * TOUR
*-----------------------*
*
MODEL=ALL,+
ACCESS=PUBLIC,+
TYPE=FQM;
*
VIEW=EMPLOYEE,+
PRIVILEGES=(GET,ADD,MOD,DEL),+
SOURCE=(EMPLOYEE),+
FORM=YES;
AT(7:7,15:33)/U/ER,+
SOURCE=EMPLOYEE.COMM,+
SIZE=19,+
OUTPUT_FORMAT=>9.2/C/DC>,+
LABEL='Com/Month',+
NAME=COMM;
.
.
.
Changing the Definition Database  327
3.
Run DMDBA to compile the edited statement file.
For example,
=> DMDBA UID=id,UPW=pw,DB=TOUR,ACTION=UPDATE,GET=DMDDBE.PUT

The statement file must contain one of the following statements: Actual_Data_Model,
Structural_Data_Model, or User_Data_Models, depending on where the object to be
changed resides. If you are changing objects in all three models, then all three
statements are required.

In statement mode, the unique key is defined by your supplying the statement for the
“higher level” as well as the statement for the desired change. For example, to
change the SALARY field of the EMPLOYEE view in the ALL User Data Model,
you must include:
1.
A MODEL statement to identify the UDM
2.
A VIEW statement to identify the view
3.
The FIELD statement for the field you want to change
Each of these statements must be complete. For example, if you leave off some
parameters of the VIEW and MODEL statement, because you think the system
knows about them anyway, the parameter values are replaced by defaults when you
compile your statement file. You do not have to include all the other view fields or
other views in the model.

When you are compiling a file of statements and do not specify an output file in your
DMDBA command, the file as it is being compiled is displayed on the terminal. You
should be ready to press the key on your terminal that “freezes the screen” to jot
down information about any errors. (There is no BASIS keypad function for freezing
the screen but many terminals have them.)
Table 8-1: Keys for “freezing” and “unfreezing” the screen
UNIX or VMS
NT
[CTRL]/[S] to stop display and
[CTRL]/[Q] to resume display
[Pause] or [CTRL]/[S] to stop
display and [any key] to resume
display
328  Changing the Definition Database
Applying Changes to the DDB
The “apply” process is the crucial step in getting your definition changes to take effect.
Most changes, whether made in the data definition language (DDL) of statement mode or
changed data transmitted in screen mode, create statement records. As statement records
are created, they post change orders which accumulate until an apply is performed.
Note: Not all changes automatically generate change orders. If you add a new field list
or backup set, for example, no system records are affected; therefore, no change orders
are posted and no apply is required to implement the change.
The change orders posted by changing the OUTPUT_FORMAT for the
EMPLOYEE.NAME field from <14/VR2< to <25< look like this:
71
Change code: NEXT APPLY
Change the output format for an ADM element.
Element: EMPLOYEE.NAME
Old value(s): <14/VR2<
New value(s): <25<
72
Change code: NEXT APPLY
Complete RED record and validate it.
Element: EMPLOYEE.NAME
73
Change code: NEXT APPLY
Complete INDXD record and validate it.
Index: EMPLOYEE.NAME
Change orders are numbered consecutively in the life of a database. The above change
orders have change codes stating “NEXT APPLY.” For explanations of this and other T
change codes like RES-N/A and RECOMPILE, see Database Definition and
Development, “Change Codes.” RED and INDXD are names of record types in the
MDDB.
Displaying Change Orders
You can review pending change orders at any time by choosing the “Show or cancel
change orders” option from the DMDBA Administrative Tasks Menu. It is always a good
idea to review change orders before doing an apply, particularly if several users have
DBA privilege for the database.
Assume, for example, that one DBA changes some objects, causing creation of change
orders, but does not apply them. He exits the DMDBA session. Another DBA changes
other objects (or even the same objects), also creating change orders in a subsequent
session. When the second DBA performs an apply, her apply processes the first DBA’s
change orders and her own.
Changing the Definition Database  329
Canceling Change Orders
Canceling change orders undoes changes made to statement records before they are
incorporated into system records. You can cancel selected or all change orders at any
time by choosing the “Show or cancel change orders” option from the DMDBA
Administrative Tasks Menu. Although selected change orders can be canceled, it is not
recommended that you routinely manipulate individual change orders.
Selectively canceling what you believe to be “extraneous” change orders could lead to
problems. Note that canceling a change order often results in the creation of more change
orders; for example, if an existing change order to add a new view is canceled, the result
is the posting of another change order to delete the view.
Performing the Apply
Change orders created by compiling statements in a DDL file or transmitting screen
contents accumulate until an apply is performed. Unapplied change orders do not
disappear at the end of a session.
If the changes require an apply, they will not be seen in DMDBA screens until a
successful apply. DMDBA will display the original version of the object with a message
that it has pending changes.
The apply process is performed with an EXCLUSIVE database lock that locks both the
DDB and the RDB. The apply cannot start until all users are out of the database, and
once the apply starts, no one can enter the database.
If you attempt an apply and are blocked because one or more users have the database
open, you can choose to wait until they finish. Meanwhile no other users can use the
database. To these waiting users, the system may seem unresponsive. For this reason, it
is wise to do applies when it is unlikely that users will be accessing the database.
To perform an apply, choose the “Apply changes made to the definitions” option from the
main DMDBA menu.
The apply is an all-or-none transaction. Either all change orders are processed, or they
are all rejected. You cannot selectively apply just a portion of the changes.
If the apply is successful, you will see the following message: APPLY successfully
completed After a successful apply, all posted changes are incorporated into the system
records, and the system deletes their change orders.
To undo a particular change, you must again use the DMDBA utility to make the change,
thereby creating one or more statement records and posting one or more change orders,
and you must do another apply.
330  Changing the Definition Database
If the apply fails, all the change orders are still there and pending, and it is not necessary
to make the changes again other than any changes to correct whatever caused the apply to
fail.
Types of Changes
Types of changes you can make to objects in your DDB include additions, deletions, and
revisions. Change codes on change orders created in the process of your entering changes
in screen mode or compiling a statement file tell you whether the changes will take effect
on the next apply or whether you need to do some additional processing like dumping and
reloading data or restructuring the RDB before the change is fully implemented.
Some things can never be changed, most notably the name of an object or the number of
an RDB file.
The rest of this section describes types of changes in general. Specific changes to the
ADM, UDM, and SDM are described in following sections.
Additions
Adding new objects to the DDB is usually very easy and the change orders are typically
IMMEDIATE or NEXT APPLY. Adding new indexes will require running DMR after
the apply to populate the index. (The exception is adding an indirect, primary-key
index—this type of index cannot be built by DMR.) Multifield indexes can also be
added, but remember also to update any appropriate views to include them. New objects
(such as a new record type or a new field in an existing record) can be added at any time
to populated databases without requiring a dump and reload. New validation rules—a
REVL statement, for example—can also be added to a loaded database with no reloading
required. For more information about adding REVL statements, see “Non-Retroactive
Changes” below.
Deletions
Deleting objects is often more involved than adding objects. Some objects can never be
deleted after they are applied. Often deleting one thing, such as a record type, will cause
a number of other things to be deleted, such as a word list or a code list, REVL
statements, and indexes.
Changing the Definition Database  331
To delete objects from the DDB when you are using statement mode, use the appropriate
DELETE statement: DELETE RECORD, DELETE FIELD, etc. For information about
DELETE statements, see Database Definition and Development.
DELETE FIELD TEL;
deletes a field from a record, but
DELETE FIELD ALL.EMPLOYEE.TEL
deletes a field from a view. In the first example, every view field that references the
deleted field will also be deleted.
If a field is explicitly deleted and then referenced in a RECORD/REPLACE or
VIEW/REPLACE statement, the change order to delete the field is canceled. Reference
to a deleted field at any other time causes an error message.
Unlike adding a new object, deleting an object such as an ADM FIELD definition may
require dumping and reloading the data. In this case, it may be easier to delete only the
view field definitions, which does not require a reload. Since no views will contain the
field, no more data can be loaded into it and users will never see it. If the ADM field that
must be deleted is optional, you can first define a view which does NOT contain the field
to be deleted, and then you can export via that view. This way the export file does not
contain references to the deleted field and will reload without problem.
Validation and UDM objects can be deleted at any time without ever having to reload.
Indexes that are active cannot be deleted. You must first use DMR to DROP the index,
then the apply for the delete will be successful. Because you are deleting the definition of
an index but not the contents of the index, the index file size does not decrease. Indexes
for fields used in referential assertions cannot be deleted.
Revisions
When planning definition updates, you should be aware about their impact. For
information about the implications of changing various parts of the database, see
Database Definition and Development, “Change Codes.” Changing existing objects can
generate many types of change orders, ranging from IMMEDIATE to RES-N/A. If your
change requires a reload of a production database, you may have to schedule some of the
steps.
Changes to the definition of most objects are processed as a delete then an add, so you
must respecify all parameters you intend to keep. RECORDs and VIEWs have
/UPDATE and /REPLACE qualifiers. For information about the implications of these
qualifiers, see “/UPDATE” or “/REPLACE” earlier in this chapter.
332  Changing the Definition Database
Non-Retroactive Changes
Many changes to validation-oriented parameters have a NON-RETRO change code.
These changes will affect new incoming data but will not affect existing data. They do
not require dumping or reindexing. Some examples of non-retroactive changes are
deleting words from a word list or code list, changing a REVL statement or assertion, and
changing initial values.
For performance reasons, when you update a data record, the Kernel revalidates only
fields that have changed. If you change validation other than REVL, an assertion, or
thesaurus validation for field A (changing a value in a word list or code list governing
field A, for example), it is possible that existing records will have “invalid” data
according to the new rules. These records can continue to go in and out of the database,
until data in field A is changed. At that point, the record must conform to the new
validation rules. If you want to immediately force all existing records to adhere to the
new rules, you must dump the records and reload them. See “Changes Requiring Dump
and Reload” below.
REVL, assertions, and thesaurus validation are always executed, so changes to these
definitions will be enforced regardless of whether or not a particular field’s data is
modified.
Changes Requiring a Dump and Reload
Changes to FIELD parameters such as PRECISION, TYPE, UNIQUE, and FORMAT,
and to RECORD STYLE affect the internal storage format or layout of the data and
require a dump, deletion, and reload of the affected record types. The changes create
RES-N/A change orders. The apply for these changes cannot be completed as long as
there is data in the RDB for the affected record type(s). If such data exists, you must
“dump” it to a holding file called a “dump file” prior to applying the change.
If a queue area is used for your database, dumping and reloading records may require
emptying the queue, but in most cases both queue and database records must be dumped.
Queue records can either be dumped and reloaded back into the queue, or you can first
run DMQ to get the records into the database. Then they can be dumped along with the
other database records. (DMQ is not available on Windows.) For information about
DMQ, see “DMQ, Queue Area Manager.”
Occasionally, a restructure calls for dumping and reloading data for one or more record
types. Data files may need to be reinitialized and reloaded.
If you are journaling changes to the database, turn off journaling prior to dumping and
reloading the data. You can choose the “Control journal usage” option from the
Administrative Tasks menu to display a menu of options for deactivating and activating
various journals.
Changing the Definition Database  333
You can use the HVU utility to dump (EXPORT) the data to a holding file and delete the
data from the database and/or queue. The same HVU utility lets you reload (IMPORT)
the data from the dump file after the apply. In the HVU EXPORT and IMPORT
commands, reference a view that contains all fields for the record type unless you want to
delete one or more fields.
Note: If you need to retain your original system keys when you reload your documents,
specify RELOAD=YES on the HVU OPEN command. RELOAD=YES causes field
values that would ordinarily be calculated dynamically when a document is added (e.g.
system keys and set-on-add fields) to be taken verbatim from the dump file.
For more information about using HVU, see “Using HVU.” For information about the
syntax of various HVU commands, see “HVU, High Volume Update.”
After dumping and reloading, the content of any existing journal files is useless because
the journal cannot be replayed after the data has been reloaded. This is another reason for
backing up the RDB prior to changing the database definition.
For information about performance considerations in dumping and reloading data for
large databases, see “Indexing and Loading Large Amounts of Data.”
Changes Requiring Index Restructure
When you change something affecting the index structure or content, such as proximity,
search filter, break list, or singularization, the current index will no longer correspond to
the new definition. Before the new definition can be applied, the index must be dropped.
After the apply, the index must be recreated. The same process is used to change an
index from EXACT to INCLUSIVE, or vice versa. While the index is dropped, searches
can still be performed, but they will be sequential scans of the data. Unless a UNIQUE
index is dropped, data can continue to be added and modified as well. No dumping is
needed when changing an index.
Change orders with the change code RES require you to drop the index before the apply.
You can use the DMR utility to drop the index and, after the apply, to rebuild the index.
For information about using DMR, see “DMR, Restructure.”
Note: If multiple versions of a database exist and you want to drop or create an index,
you must user VERSION=* on the DMR command even if other versions are not
initialized.
Changes Requiring Recompiling Programs
Change orders with the change code RECOMPILE require you to recompile COBOL or
FORTRAN recompiler application programs that use the changed object. Recompile
them after the apply.
334  Changing the Definition Database
For programs originally precompiled with TRACE=YES, you can use the DMPT utility
to learn which of these programs use the object. For more information about using
DMPT, display its online help file; for information about how to display online help files,
see “Introduction.”
The INCLUDE record is a special DDB system record that contains host language
declaration statements which are included in COBOL and FORTRAN precompiler
application programs. Changes affecting the layout of the INCLUDE record will require
the application program to be recompiled, but no restructure is needed.
Journaling Changes to the DDB and Backup
Journaling capability is provided for the DDB in the form of journal files A and B. DDB
journaling is very useful if there are multiple DBAs making changes and/or the volume of
changes is high. You can use DMDBA to initialize the DDB journals. They are not
accessible or readable by users. You can replay the journals by using the DMJ utility.
You should make sure your backup schemes will allow you to restore compatible versions
of your DDB and RDB files. Be sure to back up your DDB after you make changes to it
because the current DDB may not always work with your backup RDB. Just as in the
RDB journals, you can save before images in addition to after images. The volume of
activity for DDB journals is usually less than that of RDB journals so you may not have to
allocate as many pages. Nevertheless, you should still avoid regularly filling them and
having them alternate automatically. If both journals fill up, no further changes can be
made to the DDB until the journal files are reinitialized.
After any change requiring a dump/reload, you should always make a backup of the DDB
and all RDB files and reinitialize all the journals, both DDB and RDB.
Examples:
1.
Your database datafile (RDB) becomes damaged and you must restore last week’s
backup copy. During the week you have made changes to the definition and added
lots of new data. The current online DDB and RDB journals contain all the relevant
changes. None of your changes required restructures (this is a key point). Since the
current definition is compatible in structure with your backup (because you have not
made any restructure changes), you do not need to replay DDB journals.
Use host system facilities to restore the RDB file from the most recent backup.
Use DMJ to replay the RDB journals up to the current time:
DMJ UID=id UPW=pw DB=db ACTION=REPLAY JOURNAL=journalfile
Changing the Definition Database  335
2.
The DDB file is damaged and must be restored from backup. You have not made
any restructure changes since the last DDB backup.
Use host facilities to restore the DDB from your last backup.
Restore any DDB journals that were filled since the time of the last backup.
Depending on how fast journals are filling up, the current journals may contain all the
changes made since the backup, in which case you do not need to restore any
journals. If the RDB file is not damaged, after replaying the DDB journals
everything should be back in sync and accessible.
Replay the DDB journals to bring the definition up to date.
DMJ UID=id UPW=pw DB=Xdb ACTION=REPLAY JOURNAL=journalfile
If you do not make backup copies and reinitialize journals after a RES-N/A change or any
other dump/reload operation, replaying journals becomes very complicated. You now
have to replay the DDB journals up to the point of restructure, then replay RDB journals
up to the point of restructure, including the delete of the data. Then replay the DDB
journals for the restructure and up to the current time, then go back and replay RDB
journals for the reload up to the current time. Figuring out the sync points for all of this
could be difficult. If you omitted journaling the delete or reload, as is often the case, you
will be blocked at some point during the journal replay and will not be able to completely
restore the database to its most recent state.
IMPORTANT: After any RES-N/A (or any other non-journalled activity), it is always
advised that you make fresh backup copies of all database files and reinitialize the journal
files.
Changing the Actual Data Model
UNIX, VMS
IMPORTANT: The information in this section applies only to BASIS the UNIX, and
VMS operating systems. For information about using statement mode to change ADM
definitions on Windows operating systems, see Database Definition and Development,
“Overview of Database Definition and Development.”
This section discusses specific changes to the Actual Data Model. Many of these involve
adjusting the User Data Model or Structural Data Model as well.
336  Changing the Definition Database
Changes to the ADM are not automatically propagated to the UDM. You must
specifically add the new item or COPY the ADM object to the UDM. It is not a good
idea to routinely regenerate the UDM or recopy all the views after making ADM changes
because this can be a large overhead.
On UNIX, and VMS operating systems, recopying views will overwrite any custom UDM
screen formatting that has been done. In this case, it is better to add the field to the
appropriate place in the screen view, using DMFORM, for example.
Adding a New Record Definition to the Database in Screen
Mode
If the fields of the record need only the basic parameters like TYPE, SIZE, and OCCURS
to be defined, use the Record and Fields screen (Screen 12). Screen 12 is a summary
screen that allows you to define several objects at once—namely, a record and its fields—
instead of defining the record and each field separately.
To make the new record definition accessible to users, at least one view definition must
be created with the new record as its source.
Each record definition must have at least one unique key field or index. In the example
that follows, a unique index is created for this field. You may create indexes for
additional fields as well. You can use the Indexes of a Record Type screen (Screen 89) to
have the indexes generated for you, or you can use the Index screen (Screen 81) to define
one index at a time.
The new record and its indexes will be stored in the areas that are designated as the
DEFAULT_RECORD_AREA and the DEFAULT_INDEX_AREA unless you specify
differently by using the Record Storage screen (Screen 82) and the Index screen (Screen
81).
1.
After logging into DMDBA, go to Screen 12.
2.
Enter the name of the new record and define the fields
Changing the Definition Database  337
In this example, the new record, LIGHTS_ON, is being added so that the receptionist of
the travel agency can notify an employee that he left his or her vehicle’s lights on.
Figure 8-1: Record and fields screen
3.
Press the [ENTER] key. Because a Y has been typed in the “More Parameters” box
for the KEY field, Screen 11, the multi-page screen for defining one field, is
automatically displayed.
In this example, a virtual unique key is created from two fields described on Screen
12. Screen 11 consists of 7 pages, and page 6 has the set expression definition; you
can either use the [NEXT PAGE] key to page to the sixth page or the [PAGE] key
and type 6 at the prompt. (The actual physical keys that perform this function vary
from site to site. Use the Keypad_help to find out which key to press.)
4.
Show the field by typing an S in the action box and pressing the [ENTER] key.
5.
Type an R in the action box and press the [ENTER] key.
6.
Make the necessary changes to the definition and press the [ENTER] key. (If you
had more than one field marked with Y for More Parameters, Screen 11 would
reappear for you to continuing defining the next marked field. This would continue
to occur until all fields marked with Y for More Parameters were defined.)
338  Changing the Definition Database
Figure 8-2: Set expression screen
7.
Go to Screen 81 to define an index for the record. (Notice on this and other screens
that default values appear in data boxes that are governed by defaults.) Define an
index for the unique key field. Since we are defining one index for the record, we are
using Screen 81 instead of Screen 80. If you want the new index placed in the
DEFAULT_INDEX_AREA, do not specify the area for the new index.
8.
Type A in the action box and then press the [ENTER] key.
9.
Define the index. Press the [ENTER] key when finished.
Changing the Definition Database  339
Figure 8-3: Index screen
10. If you want the new record stored in a specific area other than the
DEFAULT_RECORD_AREA, go to Screen 82.
11. Type A in the action box, and press the [ENTER] key.
340  Changing the Definition Database
Figure 8-4: Record storage screen
12. Type the name of the area and type 0 in the NEXT_SCREEN box. Press the
[ENTER] key.
13. Apply the change (option L in the DMDBA main menu).
Adding One or More Fields to an Existing Record in Screen
Mode
When one or more fields are added to a record, all views based on the changed record
should be modified to incorporate the new fields. If the new fields are required, and you
apply the change to the record before changing these views, your apply displays a
warning like this one for each affected view:
** WARNING **
The ADD privilege has been removed from view: ALL.EMPLOYEE
Adding a field to a record does not require that the data already in the record be dumped
and reloaded.
If you define an index for the new field, the index will automatically be “dropped” by the
system. (DMDBA only knows that the record definition as a whole has data in it; it does
not realize that your new field is empty.) To “create” the index, use the DMR utility
before you load the data.
Changing the Definition Database  341
If the new field is a required field, it is required only in records added after the change has
been made to the database. It does not affect existing records unless you replace them or
delete and then attempt to re-add them.
The easiest way to change a non-screen form view to reflect the new fields is with the
COPY/UPDATE statement or screen. If you should choose to add a field in statement
mode, the DDL file would use RECORD/UPDATE (the default) instead of
RECORD/REPLACE.
Use these steps to add a field to an existing record:
1.
Use the DMDDBR utility to find out which views are based on the record definition
you are changing. You will need this information for Step 4, and it is easier to get it
before you log into DMDBA. See “DMDDBR” in the “Using Database Maintenance
Utilities” section later in this chapter for a sample interactive DMDDBR session.
2.
Log into DMDBA. Go to the Field screen (Screen 11) to add parameter values as
appropriate for each new field. Note that default values are present for many data
boxes. Choosing a USAGE like DATE also fills in defaults.
If you want the new field to have an index, type YES in the
SEARCHED_FREQUENTLY box.
If the field has special search requirements (for example, you want it to be searchable
in uppercase or lowercase, or you want singular or plural forms of a search term, or
you want to be able to perform inclusive searches), type the name of an existing
SEARCH_CONTROL_SET in the SEARCH_CONTROL box.
If the field is controlled by a Thesaurus, in the THESAURUS_DATA_CONTROL
box type the name of a THESAURUS_DATA_CONTROL_SET that is already
defined.
3.
Type A in the action box, and then press the [ENTER] key.
4.
Update all existing views that are based on EMPLOYEE. If the view to be changed:
-
is not a screen form view or
-
is in the default screen format created by COPY or
-
can be replaced by the default screen format created by COPY
use Screen 49. (Otherwise, you will need to use DMFORM to change each of the
form views that you want to incorporate the field. For information abut using the
DMFORM utility, see Screens.)
342  Changing the Definition Database
5.
Type B in the action box, and press the [ENTER] key.
6.
Enter the names of the source record, model and view. You get the view name from
the DMDDBR listing. Press the [ENTER] key. Repeat steps 5 and 6 for each view.
7.
If you specified SEARCHED_FREQUENTLY=Y, go to Screen 88 to generate an
index. Any special characteristics of the index described in the
SEARCH_CONTROL_SET will be implemented by the GENERATE_INDEXES.
When you are finished with this screen, press the [ENTER] key.
8.
If you went to Screen 88 to generate an index, enter the record name and press the
[ENTER] key.
9.
Apply the change (option L in the main menu).
10. Exit DMDBA (option Z).
11. If you have defined an index for the new field, you need to use the DMR utility to
create that index.
=>DMR UID=id,UPW=pw,DB=TOUR, +
INDEX=EMPLOYEE.START_DATE,ACTION=CREATE
. . .
NORMAL TERMINATION - DMR
=>
12. You will need to precompile any precompiled FORTRAN or COBOL programs that
use the changed view definitions. If programs were originally precompiled with the
parameter TRACE=YES, you can use the DMPT utility to find out which of these
programs use the changed views. For more information about using DMPT, display
its online help file; for information about how to display online help files, see
“Introduction.”
Adding a Field List or Changing the Contents of an Existing
Field List in Screen Mode
Field lists can be added to the ADM or the UDM. A field list in the ADM cannot be used
by anyone unless it is explicitly made available in the UDM.
You can create a field list at the view level by COPYing it, provided the names of the
view fields are the same as the names of the record fields. If you change the contents of a
field list in the ADM, the field list must be COPYed again to all views that use it; the
view field list is not automatically changed. If, however, the record field list is deleted
after it has been COPYed, the COPYed view field list remains intact until it is explicitly
deleted.
If the field names of a view are different from the names of the source record fields, the
COPY command cannot be used to create the view field list. You need to create a
separate field list for each view.
Changing the Definition Database  343
With one exception, field lists can be added, deleted, or their contents changed without
doing an apply. The exception is that if you change a field list that appears in a WHERE
clause of a restricted view, you must apply the change.
Steps 1, 2, and 3 assume you want to create or change a field list in the ADM and copy it
to a view in the UDM that has the same field names. If this is not the case, go directly to
Step 4 and create or change a view field list.
1.
Go to the Field List screen (Screen 32) and create or change a field list.
2.
To copy the field list to all views with field names that are identical to the field
names in the field list, go to Screen 49. Choose option D.
3.
Type C in the action box. Type the name of the record, the field list to be copied, the
model, the view, and the new view field list. Press the [ENTER] key.
4.
If you used Steps 1, 2, and 3, skip this Step and Step 5. Go to the View Field List
screen (Screen 69) to create or change a view field list.
5.
Type the appropriate action in the action box. Type the name of the model, the view,
and the field list to be created or changed.
6.
Exit DMDBA (OPTION Z).
Adding a Referential Assertion to a Database in Screen Mode
You can add a referential assertion for records that already contain data; it does not affect
records that already exist in the owner and member records.
You can use the DMSACK utility to check existing records for violations of referential
assertions. You can then correct the violations one at a time. For more information about
DMSACK, see “DMSACK, Stand-alone Checker.”
Using the example in Step 5 below, one violation is posted, because one owner is missing.
To correct the violation, you can either add an owner record occurrence or delete all the
members.
The unique key field of the assertion is its number. When you add an assertion, you must
supply a number for this field that is unique among all the assertions in the database:
conditional, unconditional, and unique, as well as referential.
Typing a Y in the Defer check box allows you to temporarily violate the assertion within
a transaction. Checking for compliance is deferred until just before the transaction is
finished. This is useful for very complicated transactions involving records from many
record definitions.
344  Changing the Definition Database
To add a referential assertion, follow these steps:
1.
Browse through the assertions using the > action on the Referential Assertion screen
(Screen 20) to determine the next unused number. (The system does not require that
the numbers be consecutive, but it’s a good idea unless you have a particular
numbering scheme in mind.)
2.
Type A in the action box. Define the new assertion. Press the [ENTER] key.
3.
Apply the change (option L in the main menu).
4.
Exit from DMDBA (option Z in the main menu).
5.
(Optional) To see if any existing records violate the new assertion, use the
DMSACK utility.
=> DMSACK,uid=id,upw=pw,db=tour.all
. . .
ASSERTIONs > 5
Assertion 5 is being checked.
It is a referential integrity constraint where
owner field=EMPLOYEE.ENO
member field=DEPENDENT.ENO
Assertion 5 holds.
Out of 1 assertions checked, 0 are violated.
NORMAL TERMINATION - DMSACK
Deleting a Record Definition from the Database in Screen
Mode
All view definitions, assertions, indexes, and field lists that refer to the deleted record are
implicitly deleted at the apply. You do not have to delete them explicitly.
Word lists referenced by fields in the deleted records are not implicitly deleted when the
record is deleted, even if no other field in the database refers to them.
You may want to dump from all the files in the file set where the deleted record is stored,
instead of dumping only the record to be deleted. The system optimizes storage of the
remaining records in the file when the data is reloaded.
1.
Using HVU, dump all data from the file(s) that contains the record and its indexes.
2.
Use DMDBA to delete and reinitialize the file(s).
3.
Go to the Record screen (Screen 10) and display the record definition to be deleted.
4.
Delete the record.
5.
Apply the change (option L in the main menu).
Changing the Definition Database  345
6.
Exit DMDBA (option Z in the main menu).
Note: If the record type consumed a large amount of space, you may want to edit the
dump file to remove data and use HVU to reload the dump file.
Deleting One or More Fields from a Record Definition
Deleting an ADM field is a RES-N/A change, and deleting an index is a RES/INDEX
change. Both of these require some preparatory work on the RDB files before the apply
can be successful. First, since only a dropped index can be deleted, the index must be
dropped. Notice that the statement file below creates a view that does not contain the
field to be deleted. This view will be used to export the data. All the occurrences of this
record type must be deleted before this change can be applied.
1.
Use DMR to drop the field’s index.
DMR UID=id, UPW=pw, DB=TOUR, ACTION=DROP, +
INDEX=EMPLOYEE.MGR_NO
2.
Create a statement file that contains the following definitions:
USER_DATA_MODEL;
MODEL=DUMP;
COPY RECORD DEPARTMENT TO VIEW DEPTDEL, FORM=NO;
DELETE FIELD DUMP.DEPARTMENT.NAME;
3.
Use DMDBA to run in changes and apply them.
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, AIDS=NO,+
APPLY_IF_OK=YES, GET=statementfile, TALK=0, OUTPUT=logfile
4.
Now we have a view, DEPTDEL, that does not contain the DEPARTMENT.NAME
field. Use that to export data.
HVU uid=id upw=pw
HVU> OPEN/DB tour.dump
HVU> SET/OPTIONS FORMLIB=formlibfile
HVU> FIND DEPTDEL
HVU> EXPORT/FORM/DOC [0,*]DEPTDEL, FORM=DEPTSTRM, +
DATA_FILE=filenm,DELETE=YES
HVU> EXIT
5.
After the data has been deleted, the delete change orders can be applied. Create a
statement file that contains the following:
DELETE FIELD DEPARTMENT.NAME;
DELETE INDEX EMPLOYEE.MGR_NO;
6.
Use DMDBA to run in changes and apply them.
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, AIDS=NO,+
APPLY_IF_OK=YES, GET=statementfile, TALK=0, +
OUTPUT=logfile, MODE=STATEMENT
346  Changing the Definition Database
7.
Now you can reimport your data without the NAME field.
HVU uid=id upw=pw
HVU> OPEN/DB TOUR.DUMP
HVU> SET/OPTIONS FORMLIB=formlib
HVU> IMPORT/FORM/DOC filenm FORM=DEPTSTRM, COMMAND=ADD
Note: There are some performance choices here regarding how the data is best deleted
and reloaded, and whether or not you should use forms processing methods. If you are
dealing with large amounts of data, see “Indexing and Loading Large Amounts of Data.”
The view fields based on the deleted record field are automatically deleted from all views
in all User Data Models by the apply.
If the field occurs in precompiled views found in FORTRAN or COBOL User Data
Models, any programs that use those views must be precompiled.
If the field is indexed, the index definition is deleted automatically at the apply.
If the deleted field is referenced in an assertion, the assertion is automatically deleted.
Changing the Name of a Record or Field
Because the name of an object such as a record or field is its unique identifier, you cannot
rename it directly. The object must be deleted and re-added, which can be difficult if the
database is loaded. If you want to change the name of an ADM RECORD or FIELD, you
might consider instead just changing the UDM label or UDM field name. Changing the
ADM field name will require a dump/reload if the record type has data; changing the
UDM name will not.
The following statement file and DMDBA command can be used to change the UDM
view name instead of changing the ADM record name.
USER_DATA_MODEL;
MODEL=FQMA;
COPY VIEW FQMA.EMPLOYEE TO VIEW STAFF, FORM=NO;
DELETE VIEW FQMA.EMPLOYEE;
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, AIDS=NO, +
APPLY_IF_OK=YES, GET=statementfile, TALK=0, +
OUTPUT=logfile, MODE=STATEMENT
Changing the Definition Database  347
Changing the Definition of a Domain, Usage, or Parameter Set
Domains, usages and parameter sets all represent a set of parameters, and updating them
differs slightly.
Domain
When you change something in a domain, it is propagated
automatically to all fields that reference the domain. Since
domains contain value-specific parameters, changes here (for
example, changing the precision) may require a dump and
reload. If it is a change like RAISE_DATA, it may be a nonretroactive change.
If a field references a domain, you CANNOT add or change
any of the potential domain parameters on the field itself
(whether they are specified in the domain or not); they must
be changed via the DOMAIN. Any changes at the field level
will be ignored. You must either change/add the parameter
in the domain, in which case all fields using the domain will
be affected, or you must remove the domain from that
particular field and then specify all relevant parameters on
the field itself.
Usage
A USAGE is like a system-defined domain. In this case, you
not only cannot change any of the parameters that make up
the USAGE, but you cannot change the definition of the
USAGE either. You have to remove the USAGE and
specifically add the relevant parameters, just as you would
for a DOMAIN.
For example, if you have a field originally defined with
USAGE=MONEY, and you find that the default maximum
number of digits (precision) is not large enough, you can no
longer define the field with USAGE=MONEY. You must
use the TYPE, PRECISION, OUTPUT_FORMAT and
SCALE parameters explicitly.
There are some exceptions to the above restrictions on
changing USAGEs:
348  Changing the Definition Database
Parameter set
-
You can change the pattern for a field defined with the
PERSON_NAME usage
-
You can change the dates in the legal list associated with
the DATE usage
-
You can change the size and output format of fields with
the CHARACTER usage
-
You can change the output format of fields with the
MONEY usage
Changes to parameter sets take effect immediately for all
fields using the parameter set, and never require a dump and
reload. Unlike DOMAINS, parameters that may appear in a
parameter set CAN be added and/or changed on the field
itself, and the parameter set will still be in effect. For
example, if field XXX is governed by a parameter set that
controls settings for OUTPUT_FORMAT and OCCURS,
you can add a value for a parameter like INIT or set
SEARCHED_FREQUENTLY to YES by changing the
ADM FIELD definition. A field can have some parameters
defined by a parameter set and other defined by parameters
in the FIELD definition. The same parameter, however,
CANNOT be defined in both places.
Suppose you have domains and parameter sets for salary-related fields. Assume that both
your EMPLOYEE records and EXECUTIVE records have salary fields and that you want
to change the salary domain to include a legal range of values for EMPLOYEE records
only. In EXECUTIVE records the salary field will no longer continue to use the domain.
Note that the salary field in the EXECUTIVE record must now specify all the parameters
that were defined in the domain. In addition to making domain-related changes, also
modify the parameter set to include a privacy test, and update the two fields to have their
own privacy code value.
Changing the Definition Database  349
Existing definition:
ACTUAL_DATA_MODEL;
DOMAIN=SAL_DOM, TYPE=EXACT_DECIMAL, PRECISION=7, SCALE=2;
PARAMETER_SET=SAL_PS, OUTPUT_FORMAT=>10.2/C/DC>;
*
RECORD=EMPLOYEE;
FIELD=SALARY, DOMAIN=SAL_DOM, OCCURS=1:1, +
PARAMETER_SET=SAL_PS;
*
RECORD=EXECUTIVE;
FIELD=SALARY, DOMAIN=SAL_DOM, OCCURS=1:1, +
PARAMETER_SET=SAL_PS;
New DDL file with desired modifications:
ACTUAL_DATA_MODEL;
DOMAIN=SAL_DOM, TYPE=EXACT_DECIMAL, PRECISION=7, +
SCALE=2, LEGAL=(1000.00:6000.00);
PARAMETER_SET=SAL_PS, OUTPUT_FORMAT=>10.2/C/DC>, +
PRIVACY_TEST=GT;
*
RECORD=EMPLOYEE;
*employee will be affected by new legal list in domain.
*it sets its own privacy code level of 5.
FIELD=SALARY, DOMAIN=SAL_DOM, OCCURS=1:1, +
PARAMETER_SET=SAL_PS, PRIVACY_CODE=5;
RECORD=EXECUTIVE;
*don't want to use legal salary range,
*so respecify all domain parameters.
*set privacy code level of 10.
FIELD=SALARY, TYPE=EXACT_DECIMAL, PRECISION=7, +
SCALE=2, PARAMETER_SET=SAL_PS, PRIVACY_CODE=10;
Run this statement file in and apply it. The apply should go through, even with existing
data.
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, AIDS=NO, +
APPLY_IF_OK=YES, GET=statementfile, TALK=0, +
OUTPUT=logfile, MODE=STATEMENT
It is very important when removing a domain and including its individual parameters (as
on the EXECUTIVE.SALARY field) that you do NOT change the values of the
parameters; for example, if you decide to make the precision 10 instead of 7 at this point,
it would be a RES-N/A change.
Domains, usages and parameter sets are shorthand features. The system records look the
same whether a domain was used or separate parameters, so changing a parameter,
whether it came from a domain or the field, will generate the same type of change order.
350  Changing the Definition Database
Because changes to a domain affect inherent characteristics of the data, these changes
sometimes require the data to be dumped from the database to file(s), the data to be
deleted from the database, the changes applied, and the data reloaded.
Changes to a domain automatically affect all record fields that reference that domain.
The change to the fields, however, is not automatically reflected in all view fields derived
from the record fields.
For information about how to change the definition of a domain in statement mode, see
the first part of this subsection. Following are steps for changing the definition of a
domain in screen mode:
1.
After you log into DMDBA, go to the Domain screen (Screen 15). To display the
domain you want to change, use either the S or > action.
2.
Revise the domain.
3.
Exit from the Domain screen and from DMDBA (option Z).
4.
Use HVU to dump the data of each record that contains fields that point to the
changed domain. Dump and delete data through a view that contains all the fields in
the record. For example,
HVU> EXPORT/DOC/FORM [O,*] EMPLOYEE, FORM=FORM1, +
DATAFILE=EMP.DAT, DELETE=YES
For more information about using HVU, see “Using HVU.”
5.
Log back into DMDBA and apply the change (option L in the main menu).
6.
Exit DMDBA and use HVU to reload the data from the dump file to the database. If
your records are used in assertions, you may have to specify CHECKREF=NO.
Changing the Characteristics of a Pattern in a Domain
Changing a pattern does not always require that the data be dumped. The new pattern is
enforced only on records added after the apply, however. If you want all the data to
conform to the new pattern, you will have to delete the record, edit the data in the dump
file to conform to the new pattern, and reload the data. For information about how to set
up a pattern in statement mode, see Database Definition and Development, “Field
Validation.”
If you change a pattern from numeric to non-numeric or vice versa, you should use the
DMR utility to drop the indexes and then re-create them for fields that have indexes and
reference the domain.
Changing the Definition Database  351
Changing a pattern in a domain automatically affects every field that points to the domain.
To change a pattern in a domain in screen mode:
1.
Go to the Domain screen (Screen 15). To display the domain that you want to
change, use either the S or > action.
2.
Go to page 2 of that screen and revise the pattern.
3.
Exit DMDBA (option Z in the main menu).
4.
If you want existing data to conform to the change, use HVU to dump and delete the
data from all views that contain a field which references the changed domain. Stream
format is recommended for easier editing.
5.
Edit the data in the dump file to conform to the new pattern.
6.
Log into DMDBA, apply the change (option L in the DMDBA main menu), and exit
DMDBA (option 2).
7.
Reload the data.
Changing the Style of a Record
Changing the style of a record is a RES-N/A change. If the record type has data, you
must dump and reload it.
Note:
Sectioned records are not available on Windows.
If you change a record’s style from conventional or continuous to sectioned, you must
redefine one field with USAGE=TEXT_STREAM. You must also add at least one
section-level field, the unique section identifier. It must be defined specifying
USAGE=SECTION_NAME. This implies: SIZE=1:31, OCCURS=1,
SECTION_FIELD=YES.
If you change a record’s style to sectioned, you can also specify a section title
(USAGE=SECTION_TITLE), a section number (USAGE=SECTION_NUMBER) and a
section level (USAGE=SECTION_LEVEL). A section level determines how much the
title is indented in the table of contents. The table of contents is automatically generated
for sectioned documents. Copy these changes to any UDM views referencing the record.
To make the changes using screen mode, see the next subsection. To make the changes
using statement mode, see the subsection after that.
352  Changing the Definition Database
Screen Mode
Following are steps for changing the style of a record in screen mode:
1.
Go to the Record screen (Screen 10). To display the definition of the record you
want to change, use either the S or > action.
2.
Revise the style of the record and make any other necessary changes to the record
definition in the ADM and definitions of views in the UDM. (See “Changing the
User Data Model” later in this chapter.)
3.
Exit DMDBA (option Z).
4.
Using HVU, dump and delete the data for the record.
5.
Log back into DMDBA.
6.
If you added sectioned-level fields, go to Screen 49 and copy the new definition of
the record to all views that use this record as the source.
7.
Apply the change (option L in the main menu).
8.
Exit DMDBA (option Z).
9.
Using HVU, reload the data.
Statement Mode
Following is a statement mode example that shows steps for changing a record style from
continuous to conventional. Note that this example uses FQM to delete all the records.
This method would be appropriate only when the number of records being deleted is
small.
UNIX, VMS
1.
Using the DMQ utility, update any queue records to the database:
DMQ UID=id UPW=pw DB=TOUR MODEL=FQMA ACTION=UPDATE VIEW=SCHED
2.
Export the records:
HVU UID=id UPW=pw
HVU> OPEN/DB TOUR.FQMA
HVU> FIND SCHED
HVU> EXPORT/DOC [0,*]SCHED, DATA_DIR=directory_spec
HVU> EXIT
3.
Drop all the indexes before doing the delete, because it makes the delete faster:
DMR UID=id UPW=pw DB=TOUR ACTION=DROP INDEX=SCHED.*
Changing the Definition Database  353
4.
Use FQM to find and delete all the SCHED records so the change can be applied:
FQM UID=id UPW=pw DB=TOUR.FQMA
START/TRANSACTION PW=SCHED
FIND SCHED
DELETE/VIEW [0,*]SCHED
FINISH/TRANSACTION
5.
Run in the following DDL file and apply it using the DMDBA command. The apply
should work because all data is deleted.
ACTUAL_DATA_MODEL;
RECORD=SCHED, STYLE=CONVENTIONAL, +
PRIMARY_KEY=CLIENTDATE;
FIELD=NOTES, TYPE=CHARACTER, SIZE=0:16000, +
OCCURS=0:1, OUTPUT_FORMAT=<60/VR250<, +
SEARCH_CONTROL=TEXT_SEARCH, +
SEARCHED_FREQUENTLY=YES;
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, +
AIDS=NO, APPLY_IF_OK=YES, GET=statementfile, +
TALK=0, OUTPUT=logfile, MODE=STATEMENT
6.
Recreate the indexes. They will be empty but will be populated when HVU reloads
the records.
DMR UID=id UPW=pw DB=TOUR ACTION=CREATE INDEX=SCHED.*
7.
Reload the records:
HVU UID=id UPW=pw
OPEN/DIRECT TOUR.FQMA
IMPORT/DOC directory_spec:wildcard_filespec
Changing the Definition of a Field in a Record
If a field references a domain, you CANNOT add or change any of the potential domain
parameters on the field itself (whether they are specified in the domain or not); they must
be changed via the DOMAIN. See “Changing the Definition of a Domain, Usage, or
Parameter Set” above.
Many changes made to a field at the record level do not automatically affect the view
fields derived from that record field. The definition of each view field that is based on the
changed field must be explicitly updated.
As a rule of thumb, if the parameter you changed in the record field also appears on the
view field screen, you must explicitly change the view field definition.
Some ADM field characteristics can be changed by merely displaying the field, filling in
the appropriate parameter boxes, and using the Replace action to commit the change.
Examples are making changes to the LABEL parameter and adding a comment.
354  Changing the Definition Database
Other field characteristics require an apply after the field definition has been changed.
Some examples are

Changing the output format

Increasing the maximum number of subfields (OCCURS)

Increasing the maximum size (SIZE)

Changing the pattern (unless changing the pattern from numeric to non-numeric, or
vice versa.)
Some field changes are implemented after the apply but are not retroactive to record
occurrences. Examples are

Decreasing the minimum SIZE

Decreasing the minimum OCCURS (minimum number of subfields)

Starting use of a word or code list or using a different word or code list
In general, validation parameters fall into this category. Another example is raising the
data to uppercase. You can perform the apply, but records already in the database are not
subject to the new changes. If you want the existing records to conform to the new
definition, you must dump the records, delete the old records, edit the dump file to
conform to the new definition and, reload the data.
Some changes can never be retroactive; for example, you cannot change uppercase data to
uppercase and lowercase data (RAISE=YES to RAISE=NO) retroactively. How would
the system know what characters were originally in lowercase?
Finally, some changes always require the data to be dumped and deleted, prior to the
apply. The apply will not process the change orders affected unless you delete the
records first. After deleting them, you can apply the changes, and then reload the data.
Examples are

Changing FORMAT from STRING to TEXT_IMAGE (or vice versa)

Changing the scale or precision of a numeric field
If you delete, add or change the SEARCH_CONTROL_SET or
THESAURUS_DATA_CONTROL_SET referenced by a field, whether you have to
dump and reload the data depends on the contents of the Search Control Set or Thesaurus
Data Control Set referenced. For details, see the “Changing the Contents of a Search
Control Set” and “Changing the Contents of a Thesaurus Data Control Set” sections
below.
To change a field definition in statement mode, use your host system editor to access the
statement file that contains the field definition. Make the necessary changes to the field
Changing the Definition Database  355
definition, and then recompile and apply the statement file. To change the definition of a
field in screen mode, follow these steps:
1.
Go to Screen 11. To display the definition of the field to be changed, use either the S
or > action.
2.
Make the appropriate changes to the definition of the field.
3.
Exit DMDBA (option Z)
4.
Using HVU, dump and delete the data from the record.
5.
Log back into DMDBA and apply the change (option L in the main menu).
6.
Exit from DMDBA (option Z).
7.
Reload the data from the dump file to the database. If your records are used in
assertions, you may have to specify CHECKREF=NO.
Changing the Contents of an Existing Word List or Code List
Changes to word lists or code lists are not retroactive. Current data is revalidated only if
the record is replaced. Unlike assertions and REVL which validate a record any time a
value in any field is changed, word and code lists are checked only if the value for a field
referencing them is changed.
When you change a word list in statement mode, any term in the existing word list that is
not in the statement file is automatically deleted. You cannot add an entry to the list by
giving just that single value; in statement mode that would result in a new word list
definition with just that single word.
To add a new term to the following word list:
WORD_LIST=RELATIONSHIP, TYPE=CHARACTER,
WORDS=('CHILD','FATHER','HUSBAND','MOTHER','WIFE','OTHER');
you would need a statement file like:
ACTUAL_DATA_MODEL;
WORD_LIST=RELATIONSHIP, TYPE=CHARACTER,
WORDS=('CHILD','FATHER','HUSBAND','MOTHER','WIFE', 'OTHER', +
'SIGNIFICANT_OTHER');
You can insert the new term anywhere in the list.
356  Changing the Definition Database
To change a word list in screen mode, use the Word List screen (Screen 30). To change a
code list in screen mode, use the Code List screen (Screen 31). You can use the
[SCROLL_LINE] or the [SCROLL_BOX] key to display and change any of the terms in
the Entries box. Enclose terms in single quotation marks (' ') and separate terms with
commas (,). If you are adding a new term to the first column in the next line, be sure to
place a comma at the end of the last entry on the previous line.
DMDBA does not prevent you from defining a term if the new term exceeds the
maximum size specified in the definition of a field that uses the word list. However,
when you attempt to add a record to the database with the new value, a data validation
error will occur because the data value is truncated to the maximum size, and then it does
not match any of the legal values. To prevent this, change the SIZE or PRECISION and
change the SORT_SIZE and OUTPUT_FORMAT in all record fields that use the word
list. Use the Field screen (Screen 11) to make these changes. Increasing the maximum
size of the field does not require dumping data.
If the length of terms added requires changing FIELD parameters, you may also need to
change the SIZE and OUTPUT_FORMAT of the fields in form views that contain the
field. If the FIELD SIZE of a BOX statement is smaller than the ADM FIELD size, data
for the field may be truncated.
For screen form views, you may also need to increase the size of the data box. If you do
not increase the size of the box and the maximum SIZE or PRECISION of the field
exceeds the size of the box, the box becomes scrollable. For non-screen views, use
Screen 52 (FQM), 53 (COBOL), or 54 (FORTRAN). For screen views, use Screen 61,
no matter what type User Data Model is involved.
Changing a word list or code list that is used by an index for stopwords or plural
exceptions will require the index to be dropped and rebuilt using DMR.
Suppose you notice that certain words in an inclusive index are not being singularized as
you might expect. You can specify your own rules by adding or changing a
SINGULAR_EXCEPTIONS_ENGLISH code list. To make sure that the singular of
“clothes” stays as “clothes,” for example, you could use the following statement file:
ACTUAL_DATA_MODEL;
CODE_LIST=SINGULAR_EXCEPTIONS_ENGLISH, +
CODES=('CLOTHES'='CLOTHES');
For more information about using a code list to aid in searches for singular and plural
forms of words, see Database Definition and Development, “Field Indexing, Searching,
and Groupings of Characters.”
Changing the Definition Database  357
Indexes that are using singularization, PAPER.ABSTRACT, for example, will need to be
rebuilt:
DMR UID=id UPW=pw DB=TOUR ACTION=DROP +
INDEX=PAPER.ABSTRACT
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE,+
AIDS=NO, APPLY_IF_OK=YES, GET=statementfile,+
TALK=0, OUTPUT=logfile, MODE=STATEMENT
DMR UID=id UPW=pw DB=TOUR ACTION=CREATE +
INDEX=PAPER.ABSTRACT
Now if you look at the index, you will see the term CLOTHES (instead of CLOTHE).
Note that each index that has singularization specified in its search control set should be
dropped and created to take advantage of the new singularization rules.
Changing the Contents of a Thesaurus Data Control Set
The thesaurus data control set controls the relation between a thesaurus and a field in the
database. It does not affect the thesaurus itself. To change the content of the thesaurus,
you must use the Thesaurus Manager (TM) utility. For information about how to use TM,
see Thesaurus.
With one exception, all changes to the thesaurus data control set require you to dump and
delete the data before the apply and reload the data after the apply. The exception is that
if you are changing the VERIFY_DATA_ALL parameter, dumping and reloading is
optional. If you do not choose to dump the data and reload it, the change does not affect
data entered in the database prior to this change.
To change the contents of a thesaurus data control set in statement mode, use your host
system editor to access the statement file that contains the thesaurus data control set
parameter. Make the necessary change, and then perform steps 4 through 7 below.
To change the thesaurus data control set in screen mode, follow these steps:
1.
Go to Screen 26. To display the Thesaurus Data Control Set that you want to
change, use either the S or > action.
2.
Make the change.
3.
Exit DMDBA (option Z).
4.
Using HVU and specifying DELETE=YES, dump the data of each record that
contains fields that refer to the changed THESAURUS_DATA_CONTROL_SET. If
the fields are involved in assertions as “owners”, use CHECKREF=NO to bypass
referential integrity constraints.
5.
Log back into DMDBA and perform the apply (option L in the main menu).
358  Changing the Definition Database
6.
Exit DMDBA again (option Z in the main menu).
7.
Reload the data specifying CHECKREF=NO if the fields are involved in assertions.
Changing the Contents of a Search Control Set
Search control sets provide a way of supplying different kinds of parameters—like break
lists, search filters, and singularization—that affect searching. The parameters in the
SEARCH_CONTROL_SET can be translated to an INDEX definition in the SDM by the
SDM GENERATE_INDEXES statement or by the Generate Indexes screen (Screen 88).

If only unindexed fields reference the search control set, the change needs only to be
applied.

If indexed fields reference a search control set, their indexes must be dropped and
created by using the DMR utility. When you do the apply, DMDBA will tell you
which indexes need to be created or dropped.

If you change the SWITCH_SEARCH, NOTIFY, or COMBINE parameters, you do
not need to do an apply. Because these parameters affect the thesaurus instead of an
index, whether or not a field is indexed does not matter.

The TEXT parameter is a special case. If you want to change an existing index from
EXACT to INCLUSIVE or vice versa, you cannot do so by changing the TEXT
parameter of the search control set. Instead, you must use the Index screen (Screen
81). Specify EXACT or INCLUSIVE in the Type box. (TEXT is meaningful only to
the GENERATE_INDEXES or GENERATE_SDM statements. Since the index
already exists, you cannot “generate” it again.)
SEARCH_CONTROL_SET parameters can affect the index of a field, but they do not
affect the data in the field itself. That is why it is never necessary to dump and reload the
data to change a search control set.
Assume you built a legal list of words you do not want indexed—a stopword list—and
you want to change the TEXT_SEARCH control set to use this new stop list called
MYSTOPLIST. The following steps describe what to do:
1.
Using the DMDDBE utility, extract the existing definition of the search control set.
DMDDBE UID=id UPW=pw DB=TOUR, +
OBJECT_TYPE=SEARCH_CONTROL +
OBJECT_NAME=TEXT_SEARCH PUT=oldddl
Changing the Definition Database  359
2.
The list of stopwords in the WORD_LIST definition could contain words like ‘A’,
‘AN’,’THE’. Keeping all the existing parameters of the search control set (assuming
you still want them) and changing only the STOP value to become the name of the
new stopword list, edit the DDL:
ACTUAL_DATA_MODEL;
WORD_LIST=MYSTOPLIST, TYPE=CHARACTER, +
WORDS=(list of stopwords);
SEARCH_CONTROL_SET=TEXT_SEARCH, BLANK_CONTROL=YES, +
BREAK_LIST=(NON_GRAPHIC,'|_+={}[]:-;"\<>!!@,#$%^&*()'), +
SUB_BREAK_LIST=('/'''), +
TEXT=YES, +
STOP=MYSTOPLIST, +
SINGULAR=YES, +
RAISE_TERMS=YES;
3.
Drop all the indexes that are affected. (You can determine which indexes these are
by using DMDDBR, if available to your operating system, or DMDDBE, or doing
the apply and watching the warning messages.)
DMR UID=id UPW=pw DB=TOUR ACTION=DROP INDEX=PLACE.OVERVIEW
DMR UID=id UPW=pw DB=TOUR ACTION=DROP INDEX=PLACE.TEXT
DMR UID=id UPW=pw DB=TOUR ACTION=DROP INDEX=SCHED.NOTES
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, +
AIDS=NO, APPLY_IF_OK=YES, GET=statementfile, +
TALK=0, OUTPUT=logfile, MODE=STATEMENT
4.
Recreate the indexes:
DMR UID=id UPW=pw DB=TOUR ACTION=CREATE INDEX=PLACE.OVERVIEW
DMR UID=id UPW=pw DB=TOUR ACTION=CREATE INDEX=PLACE.TEXT
DMR UID=id UPW=pw DB=TOUR ACTION=CREATE INDEX=SCHED.NOTES
Changing the Privacy Code or Privacy Test
Changing the privacy code or privacy test of a record or a record field can have farreaching and unanticipated consequences governing which users can read and/or update
records or fields. A change at the record level overrides the privacy code or privacy tests
of views or view fields derived from the record. Changing privacy code or privacy test is
a NEXT APPLY change; it affects user access the next time a user opens the database.
If a user’s read or write access code does not allow him to see all the fields in a record
definition, he cannot update the database via any view definition derived from the record.
To change a record’s privacy code or test in statement mode, perform step 1 below, but
skip step 2. Instead of step 2, use your host system editor to access the statement file that
contains the privacy code or test. Make the desired changes to the file, and proceed with
steps 3 and 4.
360  Changing the Definition Database
To change a record’s privacy code or test in screen mode, use Screen 10. To change the
privacy code or privacy test on a record field, use Screen 11. The steps for changing the
privacy code or test are the same for records and for fields.
1.
Draw up a master plan for security or consult the existing security plan. Determine
the implications of changing the privacy code or test of the record before you do it.
For information about security plans, see Database Definition and Development,
“Security.”
2.
Go to Screen 10 or 11. To display the record definition, use either the S or > action.
Revise the definition.
3.
Apply the change (option L in the main menu).
4.
Exit from DMDBA (option Z in the main menu).
Changing a REVL Statement
Adding or changing a REVL statement will not affect any existing data, but records that
are replaced will be subject to the new REVL and may now be invalid. REVL validation
is always run when the record is updated, regardless of which fields were altered.
Suppose you want to extend a REVL paragraph for CLIENT to make sure that 9-digit zip
codes are entered for U.S. clients. The existing REVL has nothing to do with zip codes.
ACTUAL_DATA_MODEL;
REVL RECORD=CLIENT;
IF ($EXISTS(STATE) NE 0)
SET COUNTRY = 'USA'
ELSE
SET STATE='N/A';
CHECK COUNTRY, REQUIRED, +
MESSAGE='You must enter the name of country';
END_IF;
END_REVL;
Changing the Definition Database  361
You modify this to be as follows:
ACTUAL_DATA_MODEL;
REVL RECORD=CLIENT;
IF ($EXISTS(STATE) NE 0)
SET COUNTRY = 'USA'
ELSE
SET STATE='N/A';
CHECK COUNTRY, REQUIRED, +
MESSAGE='You must enter the name of country';
END_IF;
IF (COUNTRY EQ 'USA')
CHECK ZIP, PATTERN='99999-9999', +
MESSAGE='9 digit zip code required';
END_IF;
END_REVL;
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, +
AIDS=NO, APPLY_IF_OK=YES, GET=statementfile, +
TALK=0, OUTPUT=logfile, MODE=STATEMENT
If you run the FQM module and display a CLIENT record, there is no problem. But if
you replace a CLIENT record by changing the STREET, which has nothing to do with
any REVL validation, you will get an error on replacing the record because the ZIP no
longer complies with the new REVL.
To verify that the changed REVL statement has taken effect, run FQM and test it.
ADDRESS
Street
City:
Zip Code:
33 Maple Drive
Erie
2345-6789
State:
Country:
PA
USA
9 digit zip code required
(860) Data conversion error or data validation error.
Enter C to cancel, H for ? for help, or > for next ADD. ___
Press [ENTER] to perform the ADD.
Figure 8-5: Successful test for invalid zip code format
362  Changing the Definition Database
Changing an Assertion
Like changes to or additions of REVL statements, changes to or additions of assertions
are not retroactive, so some of the existing data could now be “invalid” according to the
new definition. Assertions are always checked when a record is updated, regardless of
what is changed If you change the definition of a referential assertion by altering the
owner/member fields, you can use DMSACK to check existing data and determine
immediately if there are any violations. Owner/member fields must have an exact or
unique index, so changing them may require adding an index also. Conditional,
unconditional, and unique assertions cannot be checked with a separate utility; you must
either correct the records as they are encountered, or write a procedure to access and
check them.
The following statement file contains a modified assertion definition and a new index
definition (since owner/member fields must be indexed):
ACTUAL_DATA_MODEL;
ASSERT(10) ADD_MEMBER='Cannot add client without an +
employee number assigned to it.'
DEL_OWNER='Cannot delete employee while they still have +
clients assigned to them.'
EMPLOYEE OWNS CLIENT IF EMPLOYEE.ENO = CLIENT.ENO;
*
STRUCTURAL_DATA_MODEL;
INDEX=CLIENT.ENO, TYPE=EXACT;
Add your changes:
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE,+
AIDS=NO, APPLY_IF_OK=YES, GET=statementfile,+
TALK=0, OUTPUT=logfile MODE=STATEMENT
Build the new index:
DMR UID=id UPW=pw DB=TOUR ACTION=CREATE INDEX=CLIENT.ENO;
Run DMSACK to check your existing records. If everything checks out you should get
something like:
DMSACK UID=id UPW=pw DB=TOUR.FQMA ASSERTION=10
. . .
Assertion
10 is being checked.
It is a referential integrity constraint where
owner field=EMPLOYEE.ENO
member field=CLIENT.ENO
Assertion
10 holds.
Out of 1 assertions checked, 0 are violated.
NORMAL TERMINATION - DMSACK
Changing the Definition Database  363
Changing the User Data Model
Changes to the User Data Model are usually meant to

Customize the view of the database for a certain group of users for convenience and
security

Adapt the database for use with precompiled FORTRAN or COBOL programs
Changes to the UDM require fewer steps than changes to the ADM because they affect
fewer layers. Changes to view restrictions, composite views, view privileges, and view
processing routines happen at the next apply, and will start affecting users upon their next
login to the database. UDM changes never require dumping, reloading or reindexing, but
they may require application programs to be recompiled.
Note: When implementing view restrictions, remember to check the setting for
BYPASS privilege in DMSA. Users with BYPASS privilege will be able to circumvent
any view restrictions. For more information about using the DMSA utility to change
authorizations, see “Authorizing, Unauthorizing, or Changing the Authorization of a
User” later in this chapter.
You can never change a screen view to a non-screen view or vice versa (except by
deleting it and re-adding it).
WARNING: If your database uses screen mode, please take note. After you have
formatted any screens, performing a COPY ADM to UDM will overwrite your
formatting and leave you with the default screen layout again. You can, however,
copy your formatted views from one view to another, retaining the formatting. For
more information about the best way to define screen views, see Screens. Generally,
DMFORM is the appropriate tool to use.
Creating a New User Data Model
You can create a UDM that contains all of the fields of the ADM by using the
GENERATE_UDM statement. You can also create a UDM by copying some or all views
from a UDM and making the necessary revisions to it to suit your needs. You can use the
Copy from UDM to UDM screen (Screen 50) to do this. To copy selected views to
another UDM, you an use the Copy selected views screen. For information about creating
User Data Models, see Database Definition and Development, “Creating Models and
Views.”
For information about authorizing a user or group of users to use a UDM, see Database
Definition and Development, “DMDBA Module.”
364  Changing the Definition Database
Note: You can also use the DMSA utility to authorize programmers. To do this, you
need to be using Kernel 1 of the Kernel Set. For more information about the DMSA
utility, see System Administration.
Creating a View by Joining Records
Note:
Sectioned records are not available on Windows.
You can define composite views to contain joins of conventional to conventional,
conventional to sectioned, and conventional to continuous records, but you cannot define
composite views to join continuous to sectioned, sectioned to sectioned or continuous to
continuous records; in other words, only one of the component records can have a text
stream. These types of UDM composite views will have their document-level field group
limited to the maximum record size, but they can also handle text-stream fields.
Composite views can be used for retrieving and displaying information, but they cannot
be used for updating the database.
Composite views can be created in two ways:

Either by defining them in your UDM

Or by defining them when you do a join using the FIND command
There is a very notable difference: composite views defined in the UDM have a
predefined structure built to hold them, and if all the associated record types are
conventional, this structure has a maximum size that is the same as the maximum size of a
single conventional record. This size is 65408 characters. If all the component records
are quite large, it is possible that some retrievals will fail because the joined records
exceed the size limit.
Unlike changes to the ADM which may require making changes to the UDM or SDM,
changes to the UDM never involve a change in the ADM or the SDM.
Most UDM changes require only an apply. They never involve dumping and reloading
the data.
If the model is FORTRAN or COBOL, some changes may require that all programs using
the view be re-precompiled. This is required because the precompile process creates a
FORTRAN or COBOL data structure based on the view definition at the time the
precompile occurred. If the view definition has changed, the program must reflect that
change. For more information about characteristics of FORTRAN or COBOL User Data
Models, see Programming for BASIS Conventional Records.
For information about creating a view by joining fields from 2 to 12 records, see
Database Definition and Development, “Creating Models and Views.” For information
about changing screen formats by means of the DMFORM utility, see Screens.
Changing the Definition Database  365
Creating a View with Selected Fields
For information about creating views that contain selected fields, see Database Definition
and Development, “Creating Models and Views.”
WARNING: On UNIX, and VMS operating systems, once a view is defined as
either a screen view or not a screen view—by typing Y or N for Screen_form on the
View screen (Screen 44) in screen mode, or entering FORM=YES or FORM=NO in
the View definition in statement mode—you cannot change the view from a screen
view to a non-screen view or vice versa. Instead, you need to delete the view and
recreate it. Note that Windows operating systems supports statement mode only.
For screen views, the DMFORM utility lets you lay out the format in an edit file and then
translate the contents of the edit file to a statement file. You can then compile and apply
the statement file invoking DMDBA from within DMFORM. For an example of creating
a screen view via the DMFORM utility, see “DMFORM” later in this chapter. For
information about DMFORM, see Screens.
Creating or Changing a Field List for a View
A field list provides an alternative to entering several field names to be searched or
displayed. Usually you will create field lists at the view level rather than the record level.
Adding a field list or changing the contents of an existing field list does not require an
apply. You cannot, however, rename a field list. To create or change a field list for a
view, use the View Field List screen (Screen 69).
Note:
A field list cannot be displayed on, defined for, or searched from a screen view.
Adding or Changing a View Restriction
You can restrict access to information in a view by a selection of fields or field values.
For example, a view containing the NAME, SALARY, and TEL fields can be restricted to
displaying information only for employees whose DNO=101 and whose JOB is not
Secretary, assuming that the source record contains the fields DNO and JOB.
For information about how to add or change a view restriction in statement mode, see
Database Definition and Development, “UDM Definitions.” Following are steps for
adding or changing a view restriction in screen mode:
1.
Go to the View screen (Screen 44). To display the view that you want to change, use
either the S or > action.
2.
To add or change the restriction on the view, go to page 3, and use the R action.
3.
Add or change the restriction on the view. Press the [ENTER] key.
366  Changing the Definition Database
4.
Apply the change (option L in the main menu).
Changing the Definition of a View
A screen view cannot be changed to a non-screen view or vice-versa. Screen view is
available only on the UNIX, and VMS operating systems.
Changing the DEFAULT_DISPLAY_FIELD, the DEFAULT_SEARCH_FIELD or the
COMMENT requires no apply. Changing any other parameter requires an apply.
Changing the View Processing Routine parameters, which are applicable only to
FORTRAN or COBOL programs, requires that all programs that use the view be
recompiled.
To change a privacy code or test on a view in statement mode, use your host system editor
to access the statement file that contains the view definition. Make the necessary changes
to the view definition, and then recompile and apply the statement file as necessary.
The following steps show how to place a privacy code and privacy test on a view in
screen mode.
1.
Develop a security scheme. For information about security schemes, see Database
Definition and Development, “Security.”
2.
Go to the View screen (Screen 44). To display the view that you want to change, use
either the S or > action.
3.
Using the R action, change the Data privacy code and/or Privacy test values. Press
the [ENTER] key.
4.
Apply the change (option L in the main menu).
Changing a Screen View
To make minor changes to screens, you can use the Screen-form Field screen (Screen 61).
To make more extensive changes, you will probably want to use the DMFORM utility.
Screen view is available only on the UNIX, and VMS operating systems. For more
information about the DMFORM utility, see Screens.
Changing the Definition Database  367
Using the Screen-form Field Screen
Following are some guidelines about using the Screen-form Field screen:

The LABEL parameter on the field refers to the label produced by an FQM TYPE
display; it does not refer to the label shown on the screen, which is a special box
called a form label.

The SIZE and OCCURS parameters of a view field should be identical to the SIZE
and OCCURS in the source record field; otherwise truncation or loss of data may
occur. There are a few exceptions:
-
If a screen has a box with the /RR option, the SIZE should be 10% larger
than the source field size to allow the screen handler to insert blanks to
produce the ragged right margin..
-
If you have a compound field displayed horizontally, the SIZE should be
larger to allow for the semicolons that separate each subfield.

The TYPE of a view field should be the same as that of the record field in most
cases. Exceptions are fields in FORTRAN or COBOL UDMs where FORTRAN or
COBOL has no counterpart data type. For information about data types in
FORTRAN and COBOL, see Programming for BASIS Conventional Records,
“Defining Views for Use by COBOL and FORTRAN Programs.”

In moving a form label and/or data box for a field, it is extremely important to avoid
overlapping areas on the screen already occupied by form labels and data boxes.
You may find it helpful to work from a screen layout copied to a grid with numbered
columns and rows.
Note: If you display on Screen 61 a screen view that has been created in DMFORM,
the label boxes have names like L01001 and L01002. They change each time the screen
view is reformatted in DMFORM. If you do not know the name of the label box, specify
only the User Data Model and view names and use the > action to display the screen-form
fields until you see the one with the appropriate Rows and Columns coordinates.
Using DMFORM
The DMFORM utility allows you to make your changes by editing a copy of the screen
view in an edit file. You do not have to describe coordinates. Overlaps are less likely
when you see the actual format. Use DMFORM for all but the most trivial changes. For
more information about using DMFORM to change a screen view, see “DMFORM” later
in this chapter. Also, see Screens.
368  Changing the Definition Database
Whenever you change a screen view in DMFORM, you should always use
VIEW/REPLACE instead of VIEW/UPDATE.
Changing a Field in a Non-Screen View Definition
Fields in non-screen view definitions are changed on different DMDBA screens,
depending on whether they belong to FQM, COBOL or FORTRAN User Data Models.
Following are some guidelines:

The SIZE and OCCURS parameters of a view field should be identical to the SIZE
and OCCURS in the source record field. Otherwise truncation or loss of data may
occur.

Changing an OUTPUT_FORMAT or an ALIAS requires an apply but does not
require that programs be precompiled again.

Changing a label does not require an apply.

The TYPE of a view field should be the same as that of the record field in most
cases. Exceptions are fields in FORTRAN or COBOL UDMs where FORTRAN or
COBOL has no counterpart data type. For information about data types in
FORTRAN and COBOL, see Programming for BASIS Conventional Records,
“Defining Views for Use by COBOL and FORTRAN Programs.”

In FORTRAN UDMs, changing any of the following parameters requires that all
programs be precompiled again: TYPE, SIZE, OCCURS, LENGTH_VARIABLE,
OCCURRENCES_VARIABLE, DIMENSIONS.

In COBOL UDMs, changing any of the following parameters requires that all
programs be precompiled again: OCCURS, USAGE, DEPENDING ON,
subordinates, kind of field (group, elementary, or 77, PICTURE, VALUE (for 77
item) and SIZE.
Changing the Structural Data Model
You may need to change the Structural Data Model in performing any of the following
database maintenance tasks

Describe the new location of database files

Enhance retrieval performance

Facilitate updates

Change loading method
Changing the Definition Database  369

Enlarge the database storage area

Delete an index
WARNING: Before reconfiguring your SDM, make sure you have backup copies
of the DDB and all RDB files.
If users frequently update certain records but rarely update others, you may decide to put
the rarely updated records in a special file to facilitate updates. Another update
consideration is batch versus online. If you do not need to perform updates immediately,
you can defer them. (The disadvantage of deferred updating is that queries may need to
be done against the queue as well as against the database. If you change to deferred
updating, be sure to tell users of your database.)
Note:
Deferred updating is not available on Windows.
If you find that many users of your database frequently search on certain fields, or would
like to “browse” through them, you may want to create an index to facilitate searching.
You may have to enlarge the maximum number of pages in an AREA or divide your data
into several areas (or files) to accommodate growth.
Some SDM reconfigurations will require dumping all the data, reinitializing the files and
reloading. For instance, splitting the RDB into multiple files would require this type of
rework.
In reinitializing files, it is very important to keep all files containing related data in sync
with each other, and all RDB files must be kept in sync with the DDB. For example, you
cannot reinitialize just the file containing the data and forget about the file(s) containing
the indexes for that record.
Creating Another Version of the Database
A version is a Record Database that is governed by the same ADM and UDM as another
Record Database. Differing versions also conform to the same SDM, except the file(s)
that contain the RDB (File 1, File 2, etc.) have different file names. A database can have
as many as 100 versions (#0 through #99).
A typical use of different versions of the database is storing data pertaining to different
years in different RDB files. Another use of a different version might be to maintain a
training database for new users to experiment with.
370  Changing the Definition Database
By default, BASIS commands always point to the 0 version of the database. However,
you can use the VERSION parameter to specify a different version. For example:
=> FQM UID=id,UPW=pw,DB=TOUR.ALL,VERSION=1,AIDS=NO
If you always use a version other than 0, you can make that version the default by creating
a symbol or an environment variable. For example,
BASIS Symbol Manager
*****************************
Symbol name:
: DM_DBVER
:
:
:
:
:
:
:----:
:----:
:----:
:----:
:----:
:----:
:----:
PF1=RESTART
Symbol value:
3
:
:
:
:
:
:
:
PF3=QUIT
Figure 8-6: BASIS symbol manager screen
Windows
=> SET DM_DBVER_TOUR=3
UNIX Bourne-shell
=> DM_DBVER_TOUR="3"; export DM_DBVER_TOUR
Changing the Definition Database  371
UNIX C-shell
=> setenv DM_DBVER_TOUR "3"
VMS
=> DM_DBVER_TOUR="3"
You can open two versions of the same database concurrently, but they must be opened
via different User Data Models.
Note: For information about environment variables, see BASIS Reference,
“Environment Variables.”
Following are steps for creating
1.
Go to the Record Database File screen (Screen 84).
2.
Enter an A in the action box and press the [ENTER] key.
3.
Change the version number and the file descriptor. Press the [ENTER] key.
4.
To see if there is another file to change, use the > action If so, repeat steps 2 and 3.
Note: If, for example, you are creating a version 1 based on the 0 version, you must
also create file descriptors for as many data file in the new version as there are in the 0
version.
5.
If you want to journal the new version, define journal files for the new version of the
database.
When information for the old journal files is displayed, edit the names of the existing
journal files and the names of the backup jobs. Use the Add action to enter this
change.
6.
Using the Backup Set screen (Screen 86), create enough backup sets to accommodate
the number of backup cycles specified for the new RDB and journal files. For
information about creating backup sets, see Database Definition and Development,
“Providing Backup and Recovery Capability for a Complex SDM.”
7.
This step is required only if you expect users to open the new version of the database
concurrently with the original version. If so, you will need to create a new User Data
Model that is like the current one except for having a different name. Then you need
to define it with views using the Copy all views screen (Screen 50).
8.
Apply the changes (option L in the main menu).
9.
Initialize the new RDB files and the journal files (option T in the main menu
followed by option F in the administrative task menu). For more information about
initializing files, see Database Definition and Development, “DMDBA Module.”
372  Changing the Definition Database
Adding a Multifield Index to a Record Definition
A multifield index is an index that merges the index terms for several fields. Terms from
as many as 64 fields indexes can be merged into a multifield index. The Kernel uses the
multifield index to optimize searches.
In a view, you can create a field to reference the multifield index so that users can use the
multifield index to shorten FIND commands. You can use the UDM FIELD statement or
the appropriate Field screen (if available on your operating system) to create the view
field for the multifield index. It uses the name of the index as the name of the view field.
If a view has a multifield index field, the user can search only those fields of the
multifield index that are explicitly defined in the view.
One record definition can contain many multifield indexes.
The terms in a multifield index can be merged by one of two methods: $COMBINE or
$CONCATENATE.
$COMBINE merges two or more fields. For example, assume a multifield index
references two compound fields, DESCRIPTORS and AUTHORS.
$COMBINE(DESCRIPTORS, AUTHORS)
For a record occurrence that has three DESCRIPTOR values: CALIFORNIA,
FREEWAY, SMOG and two AUTHOR values, JONES and SMITH, the index terms
would look like this:
CALIFORNIA
FREEWAY
JONES
SMITH
SMOG
The $CONCATENATE method would produce the following index terms.
CALIFORNIA
JONES
FREEWAY
SMITH
WARNING: There is no index entry for SMOG. With this method any index term
that lacks a counterpart in all the corresponding subfields of compound fields in the
multifield index “disappears.”
Changing the Definition Database  373
Spaces appear after CALIFORNIA and FREEWAY because $CONCATENATE pads
with blanks to the maximum size of a character field, and pads with 0s to the maximum
precision of a numeric field. The example assumes the maximum size of the
DESCRIPTOR field is 15, and the maximum size of the AUTHOR field is 20. The
trailing blanks on the AUTHOR field are trimmed.
If the record also contains a simple field, JOURNAL, and the record occurrence has a
value, TIMES, then $CONCATENATE(DESCRIPTOR, JOURNAL) produces the
following terms in the multifield index because the value of a simple field is concatenated
with each subfield:
CALIFORNIA
TIMES
FREEWAY
TIMES
SMOG
TIMES
Document-level fields and section-level fields cannot be placed in the same multifield
index. (Sectioned records are not available on Windows.)
Note: The following instructions apply only to the UNIX, and VMS operating systems.
For information about adding a multifield index on Windows operating systems, see
Database Definition and Development, “Indexes.”
UNIX, VMS
To add a multifield index in screen mode, perform these steps:
1.
Go to the Index screen (Screen 81) and add information for the multifield index.
2.
Go to the Record Storage screen (Screen 82). To display the record definition that
you want to change, use either the S or > action.
3.
Revise the information for the record definition, entering a Y as response to the
question Multi_field_index? and making any other changes.
4.
To define an index field in each view whose users may want to search via the index,
go to the appropriate Field Screen(s).
5.
Add information to define the index field.
6.
Apply the change (option L in the main menu).
7.
Exit from DMDBA (option Z in the main menu).
8.
Use the DMR utility to create the multifield index.
374  Changing the Definition Database
Moving DDB and RDB Files to a New Location
The file descriptor of the DDB file is stored in the Authority Database. When a user
opens the database, the system looks in the Authority Database for the location of the
DDB file . Therefore, if you change the DDB file descriptor, you will not be able to
access the definition in DMDBA to change it unless the location has first been updated in
the Authority Database. The DDB file descriptor is in both the ADB and the DDB.
Following are steps for moving the DDB and RDB files to a new location. The first set of
steps is for moving the DDB. The second set of steps is for moving the RDB files and/or
RDB journals. The third set of steps is for moving DDB and RDB files and journals.
Note: Techniques discussed below can also be used when the logical names or symbols
that designate where the database is located have been changed.
To move the DDB to a new location using screen mode:
1.
Using your host operating system command to move files, move the files to the new
location.
2.
Log into the DMSA utility. Use the ASSIGN/DB command. Enter the corrected
name of the file on the DDB parameter. Exit from DMSA.
=> DMSA
. . .
user id> id
user pw> pw
Do you want to review the user aids of this program
(YES or NO)? > N
DMSA> ASSIGN/DB
DB= TOUR
Change defaults (Y/N)? > Y
OWNer=
ACcount=
DDB= new file descriptor
PRIORity=
SALOCK=
DEACTivate=
REMOTE=
DMRLOCK=
READonly=
DMSA> EXIT
3.
Log into DMDBA. You will be told that the journals are not available, but you can,
nevertheless, update the database with exclusive use.
=> DMDBA UID=id,UPW=pw,DB=TOUR,MODE=SCREEN
. . .
The journal files for the definition database could not be
opened.
The database can be opened without journals but it will be
opened for exclusive update.
Changing the Definition Database  375
Would you like to use the database without journals
(Y/N)? > Y
4.
Use the Definition Database file screen (Screen 90) and the Definition Database
Journal Files screen (Screen 91) to correct the descriptors of the DDB file and DDB
journal files. Display the old descriptors with the S action. Revise the description.
5.
Apply the changes (option L in the main menu).
To move only the RDB files or the RDB journals using screen mode:
1.
Using your host operating system command to move files, move the files to the new
location.
2.
Go to the Data Files for Record Database screen (Screen 84) to correct the
descriptors of all the affected RDB files. To display the descriptor that you want to
change, use either the S or > action. Revise the descriptors.
3.
Go to the Journal Files for Record Database screen (Screen 85) to correct the
descriptors of the RDB journal files. If the location of the backup job files or dual
journals is affected, change them as well.
4.
Apply the changes (option L in the main menu).
To move DDB and RDB files to a new location using screen mode:
1.
Using your host operating system command to move files, move the files to the new
location.
2.
Log into the DMSA utility. Use the ASSIGN/DB command. Enter the corrected
name of the file on the DDB parameter. Exit from DMSA.
=>
DMSA
. . .
user id> id
user pw> pw
Do you want to review the user aids of this program +
(YES or NO)? > N
DMSA> ASSIGN/DB
DB= TOUR
Change defaults (Y/N)? > Y
OWNer=
ACcount=
DDB= new file descriptor
PRIORity=
SALOCK=
DEACTivate=
REMOTE=
DMRLOCK=
READonly=
DMSA> EXIT
3.
Log into DMDBA. You will be told that the journals are not available, but you can
update the database with exclusive use. That's okay.
376  Changing the Definition Database
=> DMDBA UID=id,UPW=pw,DB=TOUR,MODE=SCREEN
. . .
The journal files for the definition database could not be
opened.
The database can be opened without journals but it will be
opened for exclusive update.
Would you like to use the database without journals
(Y/N)? > Y
4.
Use the Definition Database file screen (Screen 90) and the Definition Database
Journal Files screen (Screen 91) to correct the descriptors of the DDB file and DDB
journal files. Display the old descriptors with the S action. Revise the descriptors.
5.
Go to the Data Files for Record Database screen (Screen 84) to correct the
descriptors of all the affected RDB files. To display the descriptor that you want to
change, use either the S or > action. Revise the descriptors.
6.
Go to the Journal Files for Record Database screen (Screen 85) to correct the
descriptors of the RDB journal files. If the location of the backup job files or dual
journals is affected, change them as well.
7.
Apply the changes (option L in the main menu).
Changing an Existing Index from Exact to Inclusive
To change an exact index to an inclusive index, you do not need to dump and reload the
data, but you do need to drop the exact index before the new index definition is applied
and then rebuild or create the index.
The DMR utility helps you drop and create indexes. DMR can be used to drop and create
unique indexes if the RECORD_STORAGE INDEX_STRUCTURE=DIRECT. It can
also be used to create only non-unique indexes.
Creating a unique index requires that the data be exported to a dump file, deleted from the
database, then reloaded.
For information about how to change an existing index from exact to inclusive in
statement mode, see Database Definition and Development, “Indexes.”
To change an index from exact to inclusive in screen mode:
1.
Go to the Index screen (Screen 81). To display the index that you want to change,
use either the S or > action.
2.
Revise the index by changing EXACT to INCLUSIVE and changing other
parameters if necessary.
3.
Exit DMDBA (option Z in the main menu).
4.
Use the DMR utility to drop the index.
Changing the Definition Database  377
=> DMR UID=id,UPW=pw,DB=TOUR,INDEX=CLIENT.CNAME,ACTION=DROP
5.
Log back into DMDBA and perform the apply (option L in the main menu).
6.
Exit from DMDBA.
7.
Rebuild the index using DMR. For information about the DMR utility, see “DMR,
Restructure.” For more information about rebuilding the index of a large database,
see “Indexing and Loading Large Amounts of Data.”
=> DMR UID=id,UPW=pw,DB=TOUR,INDEX=CLIENT.CNAME,ACTION=CREATE
Changing from a Direct to an Indirect Index Structure
If your users require ordered sets by primary key or need to use the STORE/SET and
RESTORE/SET commands to save result sets, the record must have an indirect index
structure. (Index structure applies to an entire record rather than just a field.) To change
from a direct to indirect index or vice versa requires all records of the record type to be
dumped to a dump file, deleted from the database, and reloaded.
If you prefer to change the index structure using screen mode, the screen to use is the
Record storage screen (Screen 82).
The following steps describe use of statement mode to change the index structure to
INDIRECT:
1.
Extract the current SDM definition:
DMDDBE UID=id UPW=pw DB=TOUR OBJECT_TYPE=SDM_ALL PUT=oldddl
2.
Modify the old ddl file, deleting everything except the record storage statement for
the employee record. Update this by changing only the INDEX_STRUCTURE
parameter save this file as newddl.
STRUCTURAL_DATA_MODEL;
RECORD_STORAGE=EMPLOYEE, AREA=DMAREA, +
UPDATE=IMMEDIATE, QUEUE_AREA=DMQAREA, +
INDEX_STRUCTURE=INDIRECT;
3.
Drop the indexes of the record being deleted, to speed up the delete:
DMR UID=id UPW=pw DB=TOUR INDEX=EMPLOYEE.* ACTION=DROP
4.
Dump the data to a dump file and delete the data from the database:
HVU UID=id UPW=pw
HVU> OPEN/DB TOUR.FQMA
HVU> SET/OPTIONS FORMLIB=formlib
HVU> FIND EMPLOYEE
HVU> EXPORT/FORM/DOC [0,*]EMPLOYEE +
DATA_FILE=empdump, DELETE=YES, FORM=EMPSTRM
HVU> EXIT
378  Changing the Definition Database
5.
Apply the changes:
DMDBA UID=id, UPW=pw, DB=TOUR, ACTION=UPDATE, +
AIDS=NO, APPLY_IF_OK=YES, GET=newddl, TALK=0, +
OUTPUT=logfile, MODE=STATEMENT
6.
Activate the indexes:
DMR UID=id UPW=pw DB=TOUR ACTION=CREATE INDEX=EMPLOYEE.*
7.
Reload the data, and let HVU build the indexes:
HVU UID=id UPW=pw
HVU> OPEN/DIRECT TOUR.FQMA
HVU> SET/OPTIONS FORMLIB=formlib
HVU> IMPORT/FORM/DOC data_file, FORM=EMPSTRM
HVU> EXIT
If you did not change any validation or you do not want the data revalidated, use
VALIDATE=NO and CHECKREF=NO when reloading. These are the defaults when
using OPEN/DIRECT.
For more information about dumping and reloading indexes, see “Changes Requiring a
Dump and Reload” earlier in this chapter. For information about working with large
databases, see “Indexing and Loading Large Amounts of Data.”
Delete an Index
Before you can delete an index, you must first drop the index for the field. To do so:
1.
Use the DMR utility to drop the index.
=> DMR UID=id,UPW=pw,DB=TOUR, +
INDEX=DEPARTMENT.MANAGER,ACTION=DROP
2.
Log into DMDBA. Go to the Index screen (81). To display the index you want to
delete, use either the S or > action.
3.
After you have the proper index displayed on the screen, enter D to delete the index.
4.
Return to the main menu and select option L to apply the change.
Note: Before an index definition can be deleted, the index for that field and any related
multifield indexes must be dropped using DMR.
Changing the Definition Database  379
For example, consider the following index definitions:
INDEX SCHED.CLIENTDATE=$CONCATENATE(ID,DEPARTURE), +
AREA=DMAREA, +
TERMS=(INDEX_NULLS=NO,INSERT_METHOD=RANDOM,SIZE=8:18), +
REFERENCES=(INSERT_METHOD=RANDOM,PROXIMITY=NONE), +
TYPE=UNIQUE;
*
INDEX SCHED.DEPARTURE, +
AREA=DMAREA, +
TERMS=(INDEX_NULLS=NO,INSERT_METHOD=RANDOM,SIZE=8:18), +
REFERENCES=(INSERT_METHOD=RANDOM,PROXIMITY=NONE), +
TYPE=UNIQUE;
In this case you must drop the indexes for both SCHED.CLIENTDATE and
SCHED.DEPARTURE in order to delete the SCHED.DEPARTURE index definition.
After the index definition for SCHED.DEPARTURE has been deleted, you must use
DMR ACTION=CREATE if you want to recreate the index for CLIENTDATE.
Reconfiguring the Structural Data Model Created by the
GENERATE_SDM Statement
GENERATE_SDM and GENERATE_INDEXES put all data and all indexes in one file.
This is adequate for relatively small databases. When a database is expected to become
very large, however, the indexes should be moved to files other than those storing data.
Indexes for text-stream fields should be stored in a separate file. This optimizes
performance and makes maintenance easier.
To reconfigure the SDM:
1.
Examine the current SDM so you know the general structure. Use the DMDDBE
utility to extract it.
=> DMDDBE
. . .
user id> id
user pw> pw
database> TOUR
Enter type of object you wish to have extracted.
Type EXIT to leave DMDDBE
object type> SDM_ALL
object type> EXIT
Performing extraction
NORMAL TERMINATION - DMDDBE
=>
380  Changing the Definition Database
The relevant statements of the SDM created by GENERATE_SDM for the TOUR
database look like this:
*---------------------------------------STRUCTURAL_DATA_MODEL;*
TOUR
*---------------------------------------AREA=DMQAREA,+
PAGES_IN_AREA=1048575,+
DEFAULT_QUEUE_AREA=YES;
*
AREA=DMAREA,+
PAGES_IN_AREA=1048575,+
DEFAULT_RECORD_AREA=YES,+
DEFAULT_INDEX_AREA=YES;
*
FILE(1)='/basis/db/dm_tour/rdb_f01',+
AREAS=(DMAREA),+
BACKUP_CYCLES=10;
:
:
INDEX SCHED.CLIENTDATE=$CONCATENATE(ID,DEPARTURE),TYPE=UNIQUE;
*
INDEX CLIENT.NAME_CO=$COMBINE(CNAME/SPEEDSEARCH,CO),TYPE=EXACT;
INDEX CLIENT.CO,TYPE=INCLUSIVE,TERMS=(SIZE=0:50);
:
:
*
RECORD_STORAGE=CLIENT,INDEX_STRUCTURE=INDIRECT;
:
:
Your goal is to create two new files. One will store CLIENT indexes. Another will
store the remaining indexes. They will not store any data.
2.
Edit the statement file, making the following changes.
a.
Change the DEFAULT_INDEX_AREA parameter to NO in the area DMAREA.
b.
Define a new area to hold indexes for non-textual fields:
AREA=CLINDX, ALLOCATION=DYNAMIC, +
DEFAULT_RECORD_AREA=NO, DEFAULT_INDEX_AREA=YES,+
PAGES_IN_AREA=25000;
c.
Define a new area for indexes for text-stream fields:
AREA=OTINDX, ALLOCATION=DYNAMIC, +
DEFAULT_RECORD_AREA=NO, DEFAULT_INDEX_AREA=NO, +
PAGES_IN_AREA=25000;
d.
Leave the existing file definitions as is.
Changing the Definition Database  381
e.
Define a new file to hold the CLINDX area:
FILE(3)='/basis/db/dm_tour/rdb_f03', +
BACKUP_CYCLES=10, AREA=DMINDX;
f.
Define a new file to hold the OTINDX area:
FILE(4)='/basis/db/dm_tour/rdb_f04', +
BACKUP_CYCLES=10, AREA=LTINDX;
g.
Change the definitions of indexes, specifying the appropriate new area for each
instead of the old one.
INDEX SCHED.CLIENTDATE=$CONCATENATE(ID,DEPARTURE), +
AREA=OTINDX,TYPE=UNIQUE;
*
INDEX CLIENT.NAME_CO=$COMBINE(CNAME/SPEEDSEARCH,CO), +
AREA=CLINDX,TYPE=EXACT;
INDEX CLIENT.CO,TYPE=INCLUSIVE, +
AREA=CLINDX,TERMS=(SIZE=0:50);
3.
If there are no unique fields in the indexes or if there are unique fields in indexes
defined as direct (RECORD_STRUCTURE INDEX=DIRECT), use the DMR utility
to drop the indexes. If there are unique fields, you will have to dump and delete the
data from all records that contain indexes affected by the change.
4.
Compile the edited file from Step 2 in DMDBA. If there are no errors, apply the
definition:
=> DMDBA UID=id, UPW=pw, DB=TOUR, MODE=STATEMENT, +
GET=DMDDBE.PUT, AIDS=NO, APPLY_IF_OK=YES ...
5.
If in step 3 you dropped the indexes, use the DMR utility to create the new indexes.
If in step 3 you dumped the data, use HVU to reload the data for each record affected
by the change.
Changing an RDB File to Multiple Files
The following guidelines pertain to changing a one-file RDB to a multiple file RDB,
keeping the indexes with the record they belong to and renaming the original file:

Before reconfiguring your SDM, make sure you have backup copies of the DDB and
all RDB files.

You cannot change the number of a file.

You can never delete File 1.

Each area name must be unique. You cannot have an Area A in both File 1 and File
2.
382  Changing the Definition Database

Adding new files will also mean adding new areas, and potentially reassigning
records and/or indexes to these new areas (if you don’t, nothing will go into your new
files).

Adding a new area does not require an apply.

If you try to delete an existing file, you must be privileged to do so in the host
operating system.

When a database has more than one file, the system arranges the files in file sets.
These are RDB files that contain related structures. Related structures, for example,
are a record and its indexes. When you back up or recover the database, you should
always process the entire file set at once.
UNIX, VMS
Following are steps for changing an RDB file to multiple files:
1.
Back up the RDB.
2.
Run DMQ to make sure the queue is empty.
DMQ UID=id, UPW=pw, DB=TOUR, MODEL=FQMA, +
ACTION=UPDATE, VIEW=*
3.
Use the HVU utility to dump all data from the existing database. Let the run default
to DELETE=NO because you will delete the file later.
HVU UID=id UPW=pw
OPEN/DB TOUR.ALL
SET/OPTIONS FORMLIB=formlib
FIND EMPLOYEE
EXPORT/FORM/DOC [0,*]EMPLOYEE, FORM=EMPSTRM, +
DATA_FILE=empdump
FIND CLIENT
EXPORT/FORM/DOC [0,*]CLIENT, FORM=CLISTRM, +
DATA_FILE=clientdump
etc for all records
EXIT
4.
Use the DMDBA module to delete the existing data file (option G on the
Administrative Tasks menu). In the interactive dialog indicate that you want to
delete all the data files but none of the journal files.
5.
When the Administrative Tasks menu reappears, exit from it back to the main menu
and select screen mode (option C).
6.
Go to the Area screen (Screen 83) and add the definition for a new area.
7.
Go to the Record Database File screen (Screen 84). To display the RDB file that you
want to change, use either the S or > action.
8.
Revise the information about the original RDB file as necessary.
Changing the Definition Database  383
9.
Add one or more definitions for the new RDB files.
10. Go to the Record storage screen (Screen 82). To display the record that you want to
move to this new file, use either the S or > action.
11. Revise the record by entering the name of the new area in the Single_area data box.
12. Repeat steps 10 and 11 for each record to be moved.
13. If you want to store indexes that correspond to the records you just moved in the
same file, go to the Index screen (Screen 81). To display the index that you want to
move, use either the S or > action.
14. Revise the information by entering the name of the new area in the Area data box.
15. Repeat steps 13 and 14 for each index that you want to move.
16. Apply the change (option L in the main menu).
17. Initialize the new data files (option F from the Administrative Tasks menu). In the
interactive dialog indicate that you want to initialize all the data files but none of the
journal files.
18. When the Administrative Tasks menu reappears, exit from the program (option Z).
19. Reload the data, using HVU OPEN/DIRECT. If your database has referential
assertions, you will probably want to specify CHECKREF=NO to expedite loading.
(You can also use VALIDATE=NO to speed up the reloading process if you are
certain that the data is clean.)
UNIX, VMS
Changing from Immediate Updating to Deferred Updating
You might want to change your update scheme for a particular record type from
immediate to deferred or vice versa. Deferred updating will require a queue file and a
queue area. Suppose you want the PLACE record to now be deferred; you will need to
add a queue_area parameter to the record storage and define the new queue area. If you
make this area the default queue area, then all record types can potentially use it for
SAVing, which may not be what you want.
A separate file must be maintained for the queue file. This makes reinitializing the queue
area simpler (delete and reinitialize the file if it contains just one queue area). Adding a
queue area will be a next apply.
Deleting a queue will first require emptying the queue.
For more information about the queue, its use, and its maintenance, see “Using Queues.”
For information about changing from immediate to deferred updating using statement
mode, see Database Definition and Development, “SDM Overview.”
384  Changing the Definition Database
Following are steps for changing from immediate updating to deferred updating in screen
mode:
1.
Go to the Record Database File screen (Screen 84) and add a file to hold the queue
area for the text-stream fields. Add the file number, file descriptor, and the name of
the queue area.
2.
Go to the Area screen (Screen 83) and add the new area.
3.
Go to the Record storage screen (Screen 82). To display the record storage
information for the record that you want to change, use either the S or > action.
4.
Change Update from IMMEDIATE to DEFERRED and enter the name of the queue
area. Press the [ENTER] key. (Repeat steps 3 and 4 for each record that has textstream fields.
5.
Apply the change (option L in the main menu).
Performing Administrative Tasks
Strictly speaking, administrative changes are those that appear on the Administrative
Tasks menu in the DMDBA module. These tasks involve such activities as:

Authorizing new users to the database

Changing the authorization of existing users

Limiting access to the database

Regenerating system records when a new release is installed

Controlling journal usage
Administrative tasks can be performed interactively, by selecting menu choices from the
Administrative Tasks menu. Respond to prompts and questions, based on the task you
want to accomplish. For information about performing administrative tasks interactively,
see Database Definition and Development, “DMDBA Module.”
The alternate mode of performing administrative tasks is statement mode. This requires
you to know some syntax. You enter the statements in a file that you create in your
editor. Then you compile the file using the GET parameter of DMDBA. For information
about the syntax for performing administrative tasks in statement mode, see Database
Definition and Development, “Administrative Statements.”
In addition to the administrative tasks described in the next pages, there are several more
tasks. For more information, see Database Definition and Development, “DMDBA
Module.” Also see Database Definition and Development, “Administrative Statements.”
Changing the Definition Database  385
With one exception, regenerating system records, administrative tasks do not require an
apply. They never require dumping the data.
Authorizing, Unauthorizing, or Changing the Authorization of a
User
Before users can access a database, the system administrator must register them to use
BASIS and you or the system administrator must authorize them with various privileges
for one or more databases. You can specify read and write access codes and privileges
for various users and user groups.
Users and user groups are always authorized to use the database via a User Data Model.
If you want to authorize a user to use all UDMs, specify $ALL for the UDM.
In authorizing users, you are creating a record in the Authority Database for each new
user. You can also use the DMBBA module or the DMSA module to authorize users.
If the user is to be allowed to do many DBA tasks, such as extract the definition of a view
or change the definition, he should be authorized for both the DDB and the RDB:
Xdatabase.$ALL
database.$ALL
where database is the name of the database.
The Database Administrator privilege allows a user to use the DMDBA module and a few
utilities. If a user is going to be able to perform meaningful DBA functions, he should be
given GET, ADD, MOD, DEL, PROT, and EXCL privileges for the DDB as well.
If you are the owner (creator) of the database, but your authorizations have been deleted,
you are still considered a DBA for your database and can authorize others. Giving a user
Database Administrator privilege does not mean that he automatically gets all the other
privileges.
Programmers should be authorized to use the TRACE model of the DDB
(Xdatabase.TRACE). This allows precompiled programs to store and access information
about which programs use which views.
386  Changing the Definition Database
A Read Access Code and a Write Access Code should be given only in accordance with a
carefully thought out plan for the database. These codes, identified with a user, are
compared with a privacy code on a record or view definition according to a test, also
specified on the definition. They should not be assigned at random. For more
information about these codes and database security, see Database Definition and
Development, “Security.”
A new authorization completely replaces the current authorization parameters for an
existing user. Thus, if a user already has GET, ADD, MOD, and DELETE privileges,
and you want the user to have ASSIGN and HOLD privileges as well, your statement
must specify: GET, ADD, MOD, DELETE, ASSIGN, HOLD.
The entry
database.$ALL
is a default entry. When a user attempts to open a database, the Kernel looks to see if the
user is authorized to the specific User Data Model he is trying to access. If a match is
found, the user is given the privileges for that entry. If no match is found, the Kernel
looks to see if the user is authorized to use
database.$ALL
If one is found, the user is able to open the model with the privileges specified in the
database.$ALL entry.
When BASIS is first installed, the system administrator is given $ALL.$ALL privilege,
meaning access to all models of all databases. A site may decide it does not want system
administrators to have access to all databases. The system administrator can eliminate
this “superauthorization.” Once superauthorization is eliminated at a site, nobody can
ever have $ALL.$ALL authorization again. (Only a user who has $ALL.$ALL privilege
himself can grant it to others.)
The following steps describe changing user authorizations:
1.
Using your host system editor, create a statement file called newuser that contains an
authorization statement or unauthorization statement for each user affected by the
change. In the example, a new programmer (ABEL) is authorized to use both the
TRACE UDM (which is part of the DDB) and the FTNA UDM, which is part of the
RDB. Another programmer (BAKER) is unauthorized from the DDB and the RDB
of the same database. The statement file looks like this:
Changing the Definition Database  387
PERFORM/TASK AUTHORIZE, UID=ABEL,DDB=YES, +
MODEL=TRACE,PRIVILEGES=(DELETE,MODIFY,ADD,GET)
PERFORM/TASK AUTHORIZE, UID=ABEL,DDB=NO,MODEL=FTNA,+
PRIVILEGES=(GET,ADD,MODIFY,DEL,ASSIGN,PROT)
PERFORM/TASK UNAUTHORIZE,UID=BAKER,MODEL=TRACE,DDB=YES
PERFORM/TASK UNAUTHORIZE,UID=BAKER,MODEL=FTNA
2.
Use DMDBA in statement mode, supplying the name of the edited file as the GET
file.
=> DMDBA,UID=id,UPW=pw,DB=database,MODE=STATEMENTS +
ACTION=ADMIN,GET=newuser,AIDS=NO
Extracting a List of User Authorizations
To produce a printable list of user authorizations for a database, in screen mode select the
Extract authorization (option D in the Administrative Tasks menu) or in statement mode
use the PERFORM/TASK EXTRACT/AUTHORIZATION statement. For more
information about extracting authorizations in screen mode, see Database Definition and
Development, “DMDBA Module.” For more information about extracting authorizations
in statement mode, see Database Definition and Development, “Administrative
Statements.”
Limiting User Access to the Database to Read Only
The following steps demonstrate how to make your database “read only.” By making
your database “read only,” you prevent all users from adding, deleting, or changing
information in the database.
1.
In the editor, create a file named getfile that contains this statement:
PERFORM/TASK CHANGE/DB_ACCESS, ACCESS=READ_ONLY;
2.
This file is the getfile in the following DMDBA command. Enter the following
command:
=> DMDBA UID=id,UPW=pw,DB=database,MODE=STATEMENTS, +
ACTION=ADMIN,GET=getfile,AIDS=NO
Renaming a Database
To rename a database, use the PERFORM/MAINT RENAME/DB statement. For
information about the PERFORM/MAINT RENEW/DB statement, see Database
Definition and Development, “Administrative Statements.”
388  Changing the Definition Database
Copying a Database to a New Database
To make a copy of a database, you can use the PERFORM/MAINT RENEW/DB and
PERFORM/MAINT FIX/DB statements. For information about how to copy a database,
see Database Definition and Development, “Administrative Statements.”
Moving a Database to a Different Kernel within the Same
Kernel Set
How you move a database from one Kernel to another depends on whether the source and
destination Kernels are in the same Kernel set. To find out whether your source and
destination Kernels are in the same set, see your system administrator.
Kernels are designated by their number. If Kernels are in the same Kernel set, they share
the same Authority Database.
To reassign a database to a different Kernel, log into the DMSA utility and use the
ASSIGN/DB command to specify a new Kernel number:
=> DMSA UID=id,UPW=pw,AIDS=NO
DMSA> ASSIGN/DB DB=TOUR,KERNEL=5
DMSA> EXIT
Moving a Database to a Kernel in Another Kernel Set
For information about how to move a database to another Kernel set, see Database
Definition and Development, “Administrative Statements.”
Deactivating the Database or a File Set of the Database
You can temporarily prevent others from having read access or write access to the
database or file set, a set of related database files. You can do this by using the
appropriate set of commands:
PERFORM/TASK DEACTIVATE/DB
and
PERFORM/TASK ACTIVATE/DB
or
PERFORM/TASK DEACTIVATE/FILESET,NUMBER=n
and
PERFORM/TASK ACTIVATE/FILESET,NUMBER=n
where n is the number of the file set.
Changing the Definition Database  389
For more information about these commands, see Database Definition and Development,
“Administrative Statements.”
Erasing the Database or a Version of the Database
Erasing a database as a DMDBA administrative task removes all entries for the database
from the Authority Database and deletes all DDB and RDB files and their journals.
The database and journal files are owned by the DBA who created them from the point of
view of the host operating system. If they are protected so that only the owner can delete
them and you are not the owner, the owner must change the file protection.
To erase a database using screen mode, select Erase a database (option K) from the
Administrative Tasks menu. To erase a version of the database using screen mode, select
Erase a version of the database (option L) from the Administrative Tasks
menu, and you will be prompted for the number of the version you wish to delete.
You can accomplish the same thing in statement mode by using the appropriate statement
in a DMDBA getfile.
PERFORM/TASK ERASE/DB
or
PERFORM/TASK ERASE/VERSION, VERSION=n
where n is the number of the version you want to erase.
You can accomplish the same thing in statement mode by using the appropriate statement
in a DMDBA getfile.
Regenerating the System Records
When a new release is installed at your site, you may have to recreate the system records
for all databases. Depending on the changes made for the release, installation instructions
will specify whether to recreate all system records or only the UDM system records.
In screen mode, select Recreate DDB system records (option P) from the
Administrative Tasks menu. You will be prompted to tell which system records you want
to be regenerated:
390  Changing the Definition Database
Which DDB system records would you like to be
regenerated?
A. All (user programs will need to be re-compiled)
(recreates:
RLM,RMD,POST,VEET,AET,FET,REVLET,VSM,VMD,SMD,
INCLUD,QVD)
B. UDM records only (user programs will not need
to be re-compiled)
(recreates: VSM,VMD,SMD,INCLUD,QVD)
C.
None of the above
> A
The DDB system records will be recreated at the next apply.
In statement mode, use the appropriate statement in a DMDBA getfile.
PERFORM/TASK REGENERATE/SYSTEM_RECORDS
Whether you use screen mode or statement mode, you will need to apply the change
(option L in the DMDBA main menu). If you regenerated all DDB system records, you
will need to notify programmers to re-precompile any necessary programs that use your
database.
Reclaiming a Database from an Archive Tape
For information about how to reclaim or reactivate a database that has been archived to
tape or another medium, see Database Definition and Development, “Administrative
Statements.”
Activating and Deactivating Journals for the Database and
Monitoring Database Usage
Before journaling can be activated, journal files must have been defined for the RDB and
initialized. If you used GENERATE_SDM to create your Structural Data Model, your
database does not have journals unless you specifically indicated JOURNAL=YES in the
GENERATE_SDM statement. (JOURNAL=NO is the default.)
Monitoring causes usage statistics to be collected in a journal. This information can be
used to analyze the usage patterns of a database. Monitoring is possible only when
journaling is activated.
Journal usage and monitoring are activated or deactivated for a particular version. The
default is version 0.
Monitoring database usage is costly in terms of resources. Monitoring should be
activated for short periods of time unless the information is always needed.
Changing the Definition Database  391
Monitor data can be extracted from the journal by using the DMJ utility. For more
information about the DMJ utility, see “DMJ, Journal Processor.”
In screen mode, activating, deactivating, showing the status of the journal, and
monitoring, all come under the same administrative task, Control journal usage,
option E in the Administrative Tasks menu. In statement mode each is a distinct
statement:
PERFORM/TASK ACTivate/Journals;
PERFORM/TASK DEACTivate/Journals;
PERFORM/TASK SHow/Journal_status;
PERFORM/TASK ACTivate/Monitoring;
PERFORM/TASK DEACTivate/Monitoring;
To see if journaling is activated or not, choose Control journal usage, option E in
the Administrative Tasks menu and then choose Display status information
about the journals, option G in the journal usage menu.
Creating and Updating a Definition Database for a Remote
Database
A database is always controlled by a single Kernel. All retrieval and update activity is
controlled by that Kernel.
However, more than one Kernel can read the database. In this case, the database must
first be marked read-only. This means that no Kernel, not even the Kernel that owns it,
can perform updates on it.
Use the ASSIGN command in the DMSA module to make a database Read-Only. The
following command indicates that the TOUR database can be read by all the Kernels that
are in the same Kernel set as its primary Kernel:
ASSIGN TOUR,KERNEL=$ALL,READONLY=Y
Kernels that share an Authority Database form a Kernel set. From 1 to 9 Kernels can
form a set. Whenever a database is created and whenever a user is authorized to use a
database, the ADB is updated. Only Kernel 1 of the set can update the ADB. Thus, you
must be using Kernel 1 when you want to update the ADB.
392  Changing the Definition Database
The host variable DM_PRIMARY_KERNEL specifies the name of the Kernel used by
DMDBA. DM_PRIMARY_KERNEL must be set to the name of Kernel 1 of the Kernel
set to update the ADB. If it is not, DMDBA functions that update the ADB (creating a
new database and authorizing a user for a database) cannot be performed. The value of
this symbol is used to search the Kernel Directory to find the node on which the primary
Kernel is running. When DM_PRIMARY_KERNEL has no value, the user’s default
Kernel (established by the DM$COMMANDS command) is used.
Using Database Maintenance Utilities
In addition to the DMDBA and DMSA modules, other modules and utilities can aid you
in the maintenance and upkeep of databases. Several—DMDDBE, DMDDBR, and
DMFORM—are described below. For full documentation of DMDDBE, see
“DMDDBE, Definition Database Extract.” For full documentation of DMDDBR, see
“DMDDBR, Definition Database Report.” For full documentation of DMFORM, see
Screens, “Creating Screen Form Definitions.”
DMDDBE
The DMDDBE utility is used to create a syntactically correct DDL file from an existing
DDB. You can extract the definition for the entire database or specific objects. This is
very useful when making changes, because you can extract the current definition and have
a source that specifies all the existing parameters. When you run this modified source
back in, you won’t inadvertently delete part of the old definition. The examples in this
chapter were done by starting with a DMDDBE extracted source, whenever possible.
This method is recommended when making changes via statement mode. It is also useful
when you are creating new objects; you can extract a similar one and have the skeleton
syntax there to edit. DMDDBE ensures that you can always get back the source DDL
needed to recreate an object.
The RECORD_ALL option is very useful for getting a broad view of the entire impact of
a single record type. This will extract all objects associated with the record, such as word
lists, indexes, views, and assertions.
Note: Because DMDDBE accesses the statement records to produce its output, running
DMDDBE when there are unapplied changes may give curious results.
DMDDBE requires READ access to the Definition Database (Xdb.$ALL).
For more information about DMDDBE, see “DMDDBE, Definition Database Extract.”
Changing the Definition Database  393
DMDDBR
UNIX, VMS
The DMDDBR utility (available only on the UNIX, and VMS operating systems) uses the
BASIS Report Writer (RW) to read statement records and generate formatted reports of
DDB objects. It can produce cross-reference reports which help you see linkages and
identify objects that are no longer needed or are not defined correctly. The output of this
module may be easier to interpret than a DDL file. The source for the reports is provided,
so their format can be modified. Use of the DMDDBR utility requires that you have the
RW module on your system.
DMDDBR requires READ access to the Definition Database (Xdb.$ALL).
For more information about DMDDBR, see “DMDDBR, Definition Database Report.”
Following is a sample interactive DMDDBR session:
=>DMDDBR
user id> id
user pw> pw
BASIS Definition Database Reports Utility . . .
Enter the name of the Definition Database> XTOUR
BASIS Definition Database Reports Utility . . .
DDB = XTOUR
13:18:45
Report Output Specification
A.
B.
C.
Terminal Output -Each report is displayed on the
terminal
File Output - Each report is written to a new file
Both Terminal and File Output - Each report is
displayed on the terminal and written to a new file
Enter your choice> B
394  Changing the Definition Database
BASIS Definition Database Reports Utility
DDB = XTOUR
A.
B.
C.
D.
E.
F.
G.
W.
X.
Y.
Z.
. . .
13:18:45
Main Menu
Basic ADM Reports
ADM Cross Reference Reports
Basic UDM Reports
UDM Cross Reference Reports
ADM/UDM Cross Reference Reports
Basic SDM Reports
ADM/SDM Cross Reference Reports
Display a File
Change to Another DDB
Change the Report Output Specification
Exit this program
Enter your choice> E
BASIS Definition Database Reports Utility
DDB = XTOUR
A.
B.
Z.
. . .
13:18:45
ADM/UDM Cross Reference Reports
Record Usage By View Report
Record Field Usage By View Report
Return to Main Menu
Enter your choice> A
Output from this report will be directed
to: RECORDXREF.LST
A RECORD may be selected in the following ways:
- As a list of one or more RECORD names
(separated by commas)
- As a range of RECORD names (separated by colon)
- As a pattern for the RECORD name to match
(patterns may also be used in conjunction
with lists or single names.)
Enter the desired RECORD specification EMPLOYEE
Changing the Definition Database  395
BASIS Definition Database Reports Utility
DDB = XTOUR
. . .
13:18:45
ADM/UDM Cross Reference Reports
A.
B.
Z.
Record Usage By View Report
Record Element Usage By View Report
Return to Main Menu
Enter your choice> Z
DMFORM
UNIX, VMS
In DMDBA the UDM COPY RECORD statement creates a standard screen format
suitable for prototypes but often not the desired layout. You can use the DMFORM
utility (available only on the UNIX and VMS operating systems) to extract the view
created by the COPY RECORD command and generate a Form Definition Language
(FDL) file which you edit, moving the labels and boxes around as needed. When you are
finished editing the file, you can translate the FDL file back into valid DDL and run it
through DMDBA. DMFORM lets you design the screen without worrying about
counting out row and column positions.
Extracting DDL, editing, and reapplying can all be done from within the DMFORM
module. Reapplying the DDL requires DBA privilege.
Following are steps to use for changing a screen view. For complete information about
creating and changing screen views, see Screens, “Creating Screen Form Definitions.”
1.
Log into the DMFORM utility. You do not have to be a DBA to do this.
=> DMFORM AIDS=NO
396  Changing the Definition Database
2.
Use the EXTRACT command to obtain the DDL for the DEPENDENT screen view
in its current format. You do need to be a DBA to use this command. (You must be
authorized with GET privilege for the Definition Database, i.e., XTOUR.) If no PUT
parameter is specified, DMFORM creates a file called dmform with a ddl extension,
depending on your operating system.
DMFORM> EXTRACT DB=TOUR,MODEL=ALL,VIEW=DEPENDENT, +
...PUT=DEPENDENT.DDL,UID=id,UPW=pw
. . .
Performing extraction
NORMAL TERMINATION - DMDDBE
DMFORM>
3.
Translate the file created in Step 2 to Form Definition Language. If you do not
specify a different file name on the PUT parameter, the name will be the same as the
file created in Step 2, but it will end in fdl, or have a file type, fdl. The ECHO=NO is
used to suppress the display of the file as it is translated.
Note: If your operating system uses a file type, DMFORM assumes the file type ddl. If
you have a file name ending in _ddl, you must specify _ddl, e.g., dependent_ddl.
DMFORM> TRANSLATE/DDL DEPENDENT,ECHO=NO
*** TRANSLATE Completion Status ***
VIEWS processed >
1
WARNINGS generated > 0
ERRORS generated >
0
CONCLUSION > Generated FDL statements are complete.
DMFORM>
4.
Exit DMFORM and, using your host system editor, edit the FDL file created in Step
3. Save the file when you finish. The FDL file for the original DEPENDENT screen
view looks like this:
Changing the Definition Database  397
FORM VIEW=DEPENDENT, MODEL=ALL, MODEL_TYPE=FQM, SOURCE=(DEPENDENT), +
PRIVILEGES=(GET,ADD,MOD,DEL), ACCESS=PUBLIC, CONT=(+), +
DATA=(-=/DEFault/EReverse/Underscore), IV=(%=/DEFault/EReverse), +
FL=(UNMARKED=/DEFault,!!=/Reverse,@=/Intensity)
*
START_LAYOUT PAGE=1
! DEPENDENT !
@Dependent's Name:@-------------------------------------------------@Dependent's Number:@------------------
@Employee's Number:@-----------------@Relationship@
@to Employee:@-------------------------------------------------END_LAYOUT
*
BOX NAME=NAME, SOURCE=DEPENDENT.UDNO, SIZE=8, OUTPUT_FORMAT=>8>, +
LABEL='Unique Depno', VIEW_ONLY=YES
*
BOX NAME=NAME, SOURCE=DEPENDENT.NAME, SIZE=50, OUTPUT_FORMAT=<28/VR2<, +
LABEL='Dependent Name', OPTIONS=/Intensity
BOX NAME=DEP_NO, SOURCE=DEPENDENT.DEP_NO, SIZE=20, OUTPUT_FORMAT=>5>, +
LABEL='Depno'
BOX NAME=ENO, SOURCE=DEPENDENT.ENO, SIZE=20, OUTPUT_FORMAT=>5>, +
LABEL='ENO'
BOX NAME=RELATIONSHIP, SOURCE=DEPENDENT.RELATIONSHIP, SIZE=50, +
OUTPUT_FORMAT=<12<, LABEL='Relationship', OPTIONS=/Intensity
Note that the @ symbol is used to mark the form label and the - symbol is used to
mark the data box.
398  Changing the Definition Database
The FDL file after the changes looks like this:
FORM VIEW=DEPENDENT, MODEL=ALL, MODEL_TYPE=FQM, SOURCE=(DEPENDENT), +
PRIVILEGES=(GET,ADD,MOD,DEL), ACCESS=PUBLIC, CONT=(+), +
DATA= (-=/DEFault/EReverse/Underscore), IV=(%=/DEFault/EReverse), +
FL=(UNMARKED=/DEFault,!!=/Reverse,@=/Intensity), +
BORDER=(.=/Intensity)
*
START_LAYOUT PAGE=1
! DEPENDENT !
.....................................................................
.
.
.@Dependent's Name:@------------------------------------------------.
.
.
.....................................................................
@Dependent's Number:@-------------- @Employee's Number:@--------------
@Relationship@
@to Employee:@------------------------------------------------END_LAYOUT
*
BOX NAME=UDNO, SOURCE=DEPENDENT.UDNO, SIZE=8, OUTPUT_FORMAT=>8>, +
LABEL='Unique Depno', VIEW_ONLY=YES
*
BOX NAME=NAME, SOURCE=DEPENDENT.NAME, SIZE=50, OUTPUT_FORMAT=<28/VR2<, +
LABEL='Dependent Name', OPTIONS=/Intensity
BOX NAME=DEP_NO, SOURCE=DEPENDENT.DEP_NO, SIZE=20, OUTPUT_FORMAT=>5>, +
LABEL='Depno'
BOX NAME=ENO, SOURCE=DEPENDENT.ENO, SIZE=20, OUTPUT_FORMAT=>5>, +
LABEL='ENO'
BOX NAME=RELATIONSHIP, SOURCE=DEPENDENT.RELATIONSHIP,SIZE=50, +
OUTPUT_FORMAT=<12<, LABEL='Relationship', OPTIONS=/Intensity
Note that the symbol . is used to create a border.
Changing the Definition Database  399
5.
Translate the FDL file back to DDL. This creates a new version or updates the DDL
file. It contains your changes. If your operating system uses a file type, DMFORM
assumes a file type fdl. Otherwise you must specify the file type.
DMFORM> TRANSLATE/FDL DEPENDENT,ECHO=NO
*** TRANSLATE Completion Status ***
VIEWS processed >
1
WARNINGS generated > 0
ERRORS generated >
0
CONCLUSION >
Generated DDL statements are complete and
ready for DMFORM COMPILE/DDL.
DMFORM>
6.
Compile the new version of the DDL file and apply it. The DDL file is displayed as
it is being compiled. You must have DBA privilege for the User Data Model to use
this command. Notice on the apply that all the old label boxes are deleted. This is
because DMFORM generates a VIEW/REPLACE as opposed to VIEW/UPDATE.
You don’t want any leftover boxes.
DMFORM> COMPILE/DDL DEPENDENT,APPLY=YES,DB=TOUR,UPW=id,UPW=pw
Performing APPLY ...
** WARNING **
View field: ALL.DEPENDENT.NAME
has a maximum size specification which differs from +
that of its source
- field values may be truncated.
** WARNING **
View field: ALL.DEPENDENT.RELATIONSHIP
has a maximum size specification which differs from +
that of its source
-field values may be truncated.
APPLY successfully completed.
DMFORM>
7.
Log out of DMFORM.
DMFORM> EXIT
NORMAL TERMINATION - DMFORM
400  Changing the Definition Database
Troubleshooting
1.
You know the database exists, but you receive this message:
Message:
The definition database file is absent.
Would you like to recreate the XACME75 Definition Database
(Y/N)?
Probable cause:
Either the DDB file has been deleted, or, more likely, the Kernel is looking in the
wrong place for the file. Very possibly someone changed the file descriptor that
describes your DDB file. You should exit from DMDBA and use the DMSA
module. Check the database file descriptor using the SHOW/DB command
(DDB=yes parameter), Use the ASSIGN/DB command in the DMSA utility to
replace the old file descriptor with the new one.
Once you have done this, you can use the DMDBA utility (screen mode option) to
correct the names of all your files so they reflect the correct qualifier as well. Correct
the names of the DDB and DDB journal files on Screens 90 and 91. Correct the
RDB and RDB journal files on Screens 84 and 85. Apply the changes. (If you use
statement mode, make the necessary file name corrections through the host editor and
apply the changes as usual.)
2.
Upon logging into DMDBA or using DMDDBE:
Message:
Unable to open the database.
USER ERROR( 725). The view (if applicable, program, and user
have no privilege in common.
ABNORMAL TERMINATION - DMDBA
Probable Cause:
It is possible that you have been given only DBA privilege for the Xdatabase (i.e., the
DDB). You need GET, ADD, MOD, DEL, PROT, and EXCL privileges to function
“normally” as a DBA. Each privilege must be granted explicitly. The DBA privilege
allows you to use DMDBA, but you cannot use the definition database.
Changing the Definition Database  401
Another possible cause: although authorized with all privileges for all UDM’s (a
standard operation), at some point the DBA was authorized for a specific UDM with
fewer privileges. For example:
Userid
-----SMITH
Database.Model
-------------TOUR.ALL
TOUR.$ALL
Prior
----8
8
Read
---0
15
Write
----0
15
Privileges
---------DBA,GET,
ADD,MOD,
DEL,ASSIGN,
HOLD,UNHOLD,
EXCL,DBA,
PROT,BYPASS
For the FQM User Data Model, the system disregards the TOUR.$ALL entry and
looks at the more restrictive one.
3.
Upon Applying a new view definition, you get this message:
Message:
** WARNING ** The add privilege has been removed from view:
COBS.EMP as it does not contain all the required elements
for the source record.
APPLY successfully completed.
Probable Cause:
You cannot add a new user record to the database via a view that does not contain all
the required fields. (How would the required fields get there?)
Either you have just created a view that contains some, but not all, of the fields in the
source record, on purpose, or you have just added one or more required fields to an
existing record definition.
If the latter is true, the views derived from the modified record definition do not
automatically reflect the added field. The system sees that they do not contain all the
required fields of the source, so it removes the add privilege.
To correct this, change each view (add the required field) that is based on the source
to restore the ADD privilege.
Use the DMDDBE utility to see which views are derived from a particular record
(RECORD_ALL).
4.
Upon logging into FQM or RW, one of your users encounters this problem:
402  Changing the Definition Database
Message:
USER ERROR( 819). A database datafile does not exist.
Possible reasons:
1. The file is absent.
2. The file has not been initialized.
3. A logical name used in the file descriptor is unknown
to DMK. The logical name must be a system level
logical name or must be made known to DMK via the
kernel input file described in the CCF. See your
Probable Cause:
If you have just defined the database or changed the definition of the RDB file, the
most likely explanation is that you forgot to initialize the RDB file. This is
Administrative Task “F”.
It is also possible that you either did not specify the full file descriptor or that you
specified it incorrectly.
Another frequent cause is that you moved the RDB file. In this case, the system does not
know where to look for it. You can move it back where it was, or you can use the RDB
File Screen (Screen 84) or your host system to change the file descriptor to match the
current location of the RDB file and apply the change.
Changing the Definition Database  403
404  Changing the Definition Database