Digital PDFs

AA-C742B-TC

July 1980

352 pages

Original

12MB

Document:	DATATRIEVE-11 2.0 Users Guide Jul80
Order Number:	AA-C742B-TC
Revision:	0
Pages:	352
Original Filename:	AA-C742B-TC_DATATRIEVE-11_2.0_Users_Guide_Jul80.pdf

OCR Text

July 1980

This manual describes DATATRlEVE-ll V2.0. It provides detailed
reference information and describes how to use DATATRlEVE.

DATATRIEVE-11 V2.0
User's Guide
Order No. AA-C7 428-TC

OPERATING SYSTEM AND VERSION: RSX-llM

RSTS/E
lAS
RSX-llM-PLUS
VMS
SOFTWARE VERSION:

V3.2
V7.0
V3.0
V1.0
V2.0

Version 2.0

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

The information in this document is subject to change without notice and
should not be construed as a commitment by Digital Equipment Corporation.
Digital Equipment Corporation assumes no responsibility for any errors that
may appear in this document.
The software described in this document is furnished under a license, and
may only be used or copied in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied by DIGITAL or its affiliated companies.

The postage-paid READER'S COMMENTS form on the last page of this
document requests your critical evaluation to assist us in preparing future
documentation.

The following are trademarks of Digital Equipment Corporation:
DEC
DECnet
DECsystem-10
DECSYSTEM-20
DECtape
DECUS
DIBOL
DIGITAL

3/81-14

FOCAL
lAS
MASSBUS
PDP
RSX
UNIBUS
VAX
VMS

Contents
Page

Preface

Chapter 1 Introduction to DATATRIEVE-11
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8·

A Full Command Language .
The Report Writer and Print.
Procedures....
Description Tables
Defining Records .
Password Tables .
Hierarchies and Views .
HELP, GUIDE Mode, and More.

· 1-1
· 1-2
· 1-2
· 1-3
· 1-3
· 1-3
· 1-4
· 1-4

Chapter 2 DATATRIEVE Concepts
2.1
2.2
2.3
2.4
2.5
2.6
2.7

Records, Files, and Fields
Domains....·...
The Data Dictionary. .
The READY Command
Collections...
Record Streams.
Summary...

, 2-1
.2-4
.2-6
.2-7
.2-7
.2-8
.2-8

Chapter 3 Sample Session
Chapter 4 Introduction to Commands and Statements
4.1
4.2
4.3
4.4
4.5
4.6

Command and Statement Elements
Character Set.
Keywords . . . . . . . . . . . . .
Names . . . . . . . . . . . . . .
Termination and Continuation Characters
Comments...............

.4-2
.4-2
.4-3
.4-3.
.4-4
.4-5

Chapter 5 Commands and Statements
5.1
5.2
5.3

5.4
5.5
5.6
5.7

ABORT Statement . .
ADT Command . . . .
Assignment Statement.

.5-6
.5-8
.5-9

5.3.1
5.3.2
5.3.3

.5-9
5-11
5-12

Assigning a Value to an Elementary Field.
Assigning to a Group Field . . .
Assigning a Value to a Variable.

BEGIN-END Statement. . . . . .
DECLARE Statement. . . . . . .
DEFINE DICTIONARY Command.
DEFINE DOMAIN Command . . .

5-15
5-17
5-19
5-21

5.7.1
5.7.2

5-21
5-22

Defining an RMS Domain .
Defining a Domain as a View.

5.8
DEFINE FILE Command.
DEFINE PROCEDURE Command.
5.9
5.10 DEFINE RECORD Command .
5.11 DEFINE TABLE Command.
5.12 DEFINEP Command
5.13 DELETE Command.
5.14 DELETEP Command .
5.15 EDIT Command
5.16 ERASE Statement
5.17 EXIT (CTRL/Z) Command
5.18 EXTRACT Command.
5.19 FIND Statement
5.20 FINISH Command
5.21 FOR Statement.
5.22 HELP Command .
5.23 IF-THEN-ELSE Statement.
5.24 MODIFY Statement.
5.25 PRINT Statement.
5.26 READY Command
5.27 RELEASE Command .
5.28 REPEAT Statement.
5.29 REPORT Command.
5.30 SELECT Statement.
5.31 SET Command .
5.32 SHOW Command.
5.33 SHOWP Command .
5.34 SORT Statement .
5.35 STORE Statement
5.36 SUM Statement.
5.37 THEN Statement.

5-25
5-29
5-32
5-34
5-36
5-39
5-41
5-43
5-45

5-47
5-48
5-50
5-52
5-53
5-55
5-56
5-57
5-61
5-67
5-71
5-73
5-74
5-77
5-79
5-81
5-84
5-85
5-87
5-90
5-93

Chapter 6 Expressions
6.1

6.2

6.3

Value Expressions.

.6-1

6.1.1
6.1.2
6.1.3
6.1.4
6.1.5
6.1.6
6.1.7
6.1.8

. 6-1
.6-2
.6-3
.6-4
.6-5
.6-5
.6-6
.6-7

Literals
Field Names .
Variables
Prompting Value Expressions.
Values from a Table .
Statistical Functions .
Arithmetic Expressions .
Concatenated Expressions

Boolean Expressions.

.6-8

6.2.1
6.2.2

Relational Operators .
Boolean Operators .

.6-9
6-11

Record Selection Expressions.

6-13

6.3.1
6.3.2
6.3.3
6.3.4
6.3.5

6-13
6-14
6-15
6-15

Specifying the Source of the Records
Specifying the Number of Records
Naming a Record Stream.
Restricting the Records.
Sorting the Records

6-16

Chapter 7 Using the Report Writer
7.1
7.2
7.3

Introduction.
A Sample DATATRIEVE Report.
Creating a Report Specification
7.3.1
7.3.2
7.3.3
7.3.4

7.4

Report Writer Statements .
7.4.1
7.4.2
7.4.3
7.4.4
7.4.5

""h~l"\t8. vA

_IIW..,"".

Choosing Direct or Indirect Creation of a
Report Specification .
Invoking the Report Writer.
The Order and Function of Report Statements An Overview.
Using Control Groups
REPORT Command
SET Statement
PRINT Statement .
AT Statement .
END-REPORT Statement .

· 7-1
· 7-1
· 7-2
.7-3
· 7-3
.7-4
.7-6
· 7-9
.7-9
7-13
7-18
7-21
7-27

IIC!inl"l
n4T4TCI~V~
~"'itnr
•• I:' th8
••• ..., ....
,.,.,., •••• _ .. _ _
...........
...,~

8.1
8.2
8.3
8.4
8.5

8.6

Invoking the Editor .
Editor Modes.
Line Pointer
Range Specification.
Editor Commands.

· 8-1
.8-2
.8-2
.8-3
.8-5

8.5.1
8.5.2
8.5.3
8.5.4
8.5.5
8.5.6
8.5.7

.8-7
.8-7
.8-8
8-10
8-10
8-11
8-13

DELETE Command
EXIT Command .
INSERT Command
QUIT Command.
REPLACE Command
SUBSTITUTE Command
TYPE Command.

Sample Editing Session .

8-14

Chapter 9 Application Design Tool
9.1
9.2
9.3

9.4
9.5

ADT Features . . . . . .
Invoking and Terminating ADT
ADT Dialog. . . . . . . . . .

.9-1
.9-2
.9-3

9.3.1
9.3.2

Responding to ADT Questions
Sample ADT Dialog . . . . .

.9-3
.9-4

Output from ADT . . . . . . . . . .
Executing the Indirect Command File

.9-6
.9-8

Chapter 10 Creating and Maintaining Data Dictionaries
10.1
10.2
10.3

Contents of a Data Dictionary .
Creating a Data Dictionary
Changing Dictionaries. . . . .

10-1
10-2
10-2

10.4

10.5

Chapter 11

Maintaining a Data Dictionary. . . . .

10-4

10.4.1 Displaying Dictionary Contents.
10.4.2 Modifying Dictionary Contents
10.4.3 Deleting Dictionary Contents.

10-4
10-4
10-5

Compressing a Dictionary . . .

10-5

Creating Record Definitions
11.1
11.2
11.3

11.4

11.5
11.6
11.7
11.8

11.9

The Parts of a Record Definition.
Elementary and Group Fields . .
Field Levels and Level Numbers.

11-1
11-2
11-4

11.3.1 Field Levels . .
11.3.2 Level Numbers.

11-4
11-4

Field Names . . . . .

11-6

11.4.1 Qualifying Field Names
11.4.2 FILLER Field Name.

11-6
11-8

Field Classes . . . . . .
Field Definition Clauses .
COMPUTED BY Clause.
Edit-String Clause. . . .

11-8
11-9
· 11-11
· 11-12

11.8.1 Alphanumeric Fields.
11.8.2 Numeric Fields.
11.8.3 Date Fields:

· 11-15
· 11-17
· 11-21

OCCURS Clause . . .

· 11-23

11.9.1 Fixed Number of Occurrences.
11.9.2 Variable Number of Occurrences

· 11-23
· 11-24

11.10 PICTURE Clause . . . . . .

· 11-26

11.10.1 Alphanumeric Fields.
11.10.2 Numeric Fields. . .

· 11-27
· 11-28

11.11 QUERY-HEADER Clause.
11.12 QUERY-NAME. Clause
11.13 REDEFINES Clause
11.14 SIGN Clause . . . . .
11.15 USAGE Clause . . . .
11.15.1 COMP (or INTEGER) Fields:
11.15.2 COMP-1 (or REAL) Fields . .
11.15.3 COMP-2 (or DOUBLE) Fields
11.15.4 COMP-3 (or PACKED) Fields
11.15.5 COMP-5 (or ZONED) Fields.
11.15.6 COMP-6 Fields
11.15.7 DATE Fields,
11.16 VALID IF Clause . . .

· 11-30
· 11-32
· 11-33
· 11-35
· 11-36
· 11-37
· 11-38
· 11-38
· 11-38
· 11-38
· 11-38
· 11-39
· 11-40

Chapter 12 Procedures and Indirect Command Files
12.1

Procedures . . . . . . . . . .

12-1

12.1.1 Creating a Procedure. .
12.1.2 Contents of a Procedure

12-1
12-2

12.1.3
12.1.4
12.1.5
12.1.6
12.1.7
12.1.8

12.2

12.1.2.1 Commands and Statements
12.1.2.2 Clauses and Arguments
12.1.2.3 Comments . . . . . . . .

12-2
12-3
12-3

Invoking a Procedure. . . . . . . .
Debugging and Editing a Procedure.
Nesting Procedures. . . . .
Using a Procedure in a Loop
Aborting Procedures . . . .
Maintaining Procedures . .

12-4
12-4
12-5
12-6
12-7
12-8

12.1.8.1 Displaying Procedure Names Stored in the
Data Dictionary. . . .
12.1.8.2 Displaying Procedures.
12.1.8.3 Deleting Procedures.

12-8
12-8
12-8

12.1.9 Protecting Procedures
12'.1.10 A Sample Procedure . . . . .

12-8
12-9

Indirect Command Files. . . . . . .

· 12-11

12.2.1 Creating an Indirect Command File.
'12.2.2 Contents of an Indirect Command File

· 12-11
· 12-11

12.2.3
12.2.4
12.2.5
12.2.6
12.2.7
12.2.8

12.2.2.1 ADT, EDIT, and SET GUIDE.
12.2.2.2 Incomplete Commands and Statements.
12.2.2.3 Comments . . . . . . . . . . . . . .

· 12-11
· 12-11
· 12-13

Invoking an Indirect Command File. . . . . . .
Debugging and Editing an Indirect Command File.
Nesting Indirect Command Files . . . . .
Using an Indirect Command File in a Loop
Aborting Indirect Command Files . . . . .
Maintaining Indirect Command Files . . .

· 12-13
· 12-14
· 12-15
· 12-15
· 12-15
· 12-15

12.2.8.1 Displaying the Names of Indirect Command Files.
12.2.8.2 Displaying Indirect Command Files
12.2.8.3 Deleting Indirect Command Files.

· 12-15
· 12-15
· 12-15

12.2.9 Protecting Indirect Command Files
12.2.10 Sample Indirect Command File . . . . . .

· 12-15
· 12-16

Chapter 13 Description Tables
13.1
13.2

Creating a Description Table.
Using a Description Table. .

13-3
13-5

Vll

13.3

13.2.1 Using IN with a Description Table . . . . . . . .
13.2.2 Using VIA with a Description Table. . . . . . . .
13.2.3 Description Tables and DATATRIEVE Workspace.

13-5
13-6
13-7

Maintaining Description Tables . . . . . . . . .

13-7

13.3.1
13.3.2
13.3.3
13.3.4

13-7
13-7
13-8
13-8

Displaying Description Table Information.
Displaying Description Tables.
Modifying Description Tables.
Deleting Description Tables.

13.4 Protecting Description Tables
13.5 Example . . . . . . . .

13-8
13-9

Chapter 14 Security and Protection
14.1

Contents of a Password Table
14.1.1
14.1.2
14.1.3
14.1.4

Sequence Numbers.
Lock Types . . .
Keys . . . . . .
Access Privileges.

14.2 Creating Password Tables
14.3 DATATRIEVE's Processing of Password Tables.
14.4 Maintaining a Password Table. . . . .
14.4.1
14.4.2
14.4.3
14.4.4
14.4.5

Guidelines for Ordering Entries.
Assigning Privileges . . . . . .
Displaying a Password Table . .
Adding Entries to a Password Table.
Deleting Entries from a Password Table.

14-1
14-2
14-2
14-2
14-3
14-6
14-7
14-9
· 14-10
· 14-10
· 14-11
· 14-11
· 14-11

Chapter 15 Hierarchies and Views
15.1

15.2

Hierarchies . . . . . . .

15-1

15.1.1
15.1.2
15.1.3
15.1.4

15-2
15-3
15-5
15-8

A Sample Hierarchy: FAMILIES
Creating a Hierarchy. . . . .
Referring to a List . . . . . .
Changing the Length of a List

Views . . . . . . . . . . . . . . . .

15.2.1 Two Sample Views: KETCHES and SAILBOATS.
15.2.2 Defining a View
15.2.3 Using a View. . . . . . . . . . . . . . . . . . .

15-9
· 15-11
· 15-13
· 15-14

Chapter 16 Creating New Domains from Old
16.1 The Current Domain . . .
16.2 Defining the New Domain.
16.3 Creating the New Domain.
16.4 Using a Record Subset. . .
16.5 Combining Data from Two or More Domains.

()

.lV-I:.;

16-2
16-2
16-3
16-4

Appendix A DATATRIEVE Error Messages
A.l
A.2
A.3

Common Error Messages.
Severe Error Messages . .
Reporting Severe Errors.

. A-I
.A-2
.A-2

A.3.1
A.3.2
A.3.3

.A-2
.A-3
.A-3

Making a Trace File.
Copying Definitions
Error Submission. .

Appendix B Optimization Techniques
B.l
B.2
B.3

DATATRIEVE Pool Space.
Space Saving Techniques
Time Saving Techniques.

.B-l
. B-3
.B-5

Appendix C Keywords
Appendix D Differences from Version 1.1
D.1
D.2
D.3

Changes in the Report Writer
Changes in Data Types
Other Changes . . .

.D-l
.D-l
.D-2

Appendix E Alignment of Fields

Appendix F DAiAiRiEVE Sorting Order
Glossary
Index
Figures
2-1
7-1
9-1
9-2
9-3
9-4
11-1
12-2
12-1
13-1
13-2
14-1
14-2
15-1
15-2
B-1
B-2
B-3
B-4

Portion of Sample Yachts File . . . . . . .
A DATATRIEVE Report . . . . . . . . . .
A Sample ADT Dialog . . . . . . . . . . .
General Format of Command File Contents.
Sample Command File Contents . . . . . .
Execution of Sample Indirect Command File.
Three Parts of YACHT Record.
Sample Indirect Command File
Sample Procedure. . . . . . .
Summary of DEFINE TABLE .
Creating RIG-TABLE. . . .
Sam pIe Password Table . . . .
Processing of Password Table .
Record Definition for FAMILIES.
FAMILIES . . . . .
DATATRIEVE Task. . . . . . .
DATATRIEVE Task. . . . . . .
Output of SHOW SPACE Command.
Alternate Definition for YACHTS . .

.2-4
.7-2
.9-4
.9-6
.9-7
.9-8
11-2
. 12-16
12-9
13-4
13-4
14-1
14-8
15-2
15-4
. B-1
. B-2
. B-2
. . B-4

Tables
4-1
5-1
5-2

5-3
5-4

5-5
5-6
5-7
5-8

5-9
6-1
6-2
6-3
6-4

8-1
8-2
8-3

9-1
11-1
11-2
11-3
11-4
14-1
14-2

i4-3
F-1

DATATRIEVE Character Set . . . . . . . . . . . .
Alphabetical Summary of Commands and Statements.
Summary of Commands and Statements by Function .
Default Values for KEY Fields. . . .
Allowed Combinations for KEY Fields
Print-List Elements.
Print-List Modifiers. .
Domain "A.Jlow Types .
Domain Access Modes.
Access Mode Required by Commands/Statements.
Context Types . . .
Statistical Functions.
Arithmetic Operators
Relational Operators.
Range Specifiers. . .
Examples of Range Specifiers
Summary of DATATRIEVE Editor Commands.
ADT Question Types and Responses .
Field Classes . . . . . . . . . . . .
SU,mmary of Field Definition Clauses.
Edit-String Characters. .
Picture-String Characters . . . . .
Access Privileges . . . . . . . . .
Commands/Statements by Privilege
Privilege Requirements by Command/Statement
DATATRIEVE Sorting Sequence. . . . . . . .

.4-2
.5-2
.5-4

5-26
5-26
5-65
5-66
5-68
5-68

5-69
.6-2
.6-5
.6-7

.6-9
.8-3
.8-5
.8-6
.9-3

11-9
· 11-10
· 11-13
· 11-27

· 14-4
· 14-4
· 14-10
· . F-1

I Commercial Engineering Publications typeset this manual using DIGITAL's
I TMS-ll Text Management System.
,

742ALL

Preface

Manual Objectives
This manual describes DATATRIEVE-ll Version 2.0 and provides usage and
reference information on DATATRIEVE.

Intended Audience
This manual is intended for:
• Users who have read the DATATRIEVE Primer
• Advanced users who are responsible for more than data entry and update
• Applications programmers who are unfamiliar with DATATRIEVE
The DATATRIEVE Primer is a tutorial manual that introduces
DATATRIEVE. New users ofDATATRIEVE should read the DATATRIEVE
Primer before using this manual.

Structure of This Manual
The first six chapters of this manual contain information of interest to all
DATATRIEVE users. The remaInIng chapters explain specific
DATATRIEVE features, such as description tables, and more advanced functions such as defining records.
Chapter 5 lists all DATATRIEVE commands and statements alphabetically.
It is intended primarily as a reference section. Chapter 11 also contains a
reference section, which lists the field definition clauses alphabetically.

Documentation Conventions
[]

Square brackets indicate that the enclosed item is
optional. If there is more than possible choice, the possibilities are stacked vertically within the brackets.

{}

Braces indicate that one of the items stacked within the
braces must be included.
Ellipses, either vertical or horizontal, indicate that the
preceding item in brackets may be repeated.

UPPERCASE

Uppercase indicates a DATATRIEVE language element.
Inside a format, uppercase indicates keywords that you
enter as shown.

lowercase

Lowercase inside a format indicates variable information
that you supply.

OOJ

The symbol OOJ represents the non-printing carriage
return key.

The symbol CTRL means that you must press the key
labeled CTRL while pressing another key at the same
time. Within examples a circumflex (') is used to represent a control character, Thus ,..z is the same as CTRL/Z,

Chapter 1
Introduction to DATATRIEVE-11

DATATRIEVE-ll is an inquiry language and report writing system that
provides direct, easy access to data contained in RMS files. DAT ATRIEVE
operates under the lAS, RSTS!E; RSX-ll, RSX-IIM PLUS, and Vl\1S operating systems, using RMS record management services,
DATATRIEVE lets you look at data, change it, or sort it interactively, You
can add new records to a file, delete old ones, or modify existing ones to
maintain an accurate, up-to-date file. In addition to its extensive facilities for
file maintenance, DATATRIEVE provides report generation aids for creating
simple or complex reports in a wide variety of formats.
DATATRIEVE requires no programming skills. Its simple-to-use interactive command language means that even novice users can learn to use
DATATRIEVE easily and be productive in a short time.

1.1 A Full Command Language
You direct DATATRIEVE's operation using a series of commands. The command language is simple to use: each command name describes its function
(such as MODIFY, SORT, and PRINT) and the syntax of each command is
similar to that of English. For example, the following command requests that
the data on all yachts with a price greater than $35,000 be displayed on the
terminal:
PRINT ALL OF YACHTS WITH PRICE GREATER-THAN 35000

DATATRIEVE carries out each command as you enter it, so you see the
results immediately. You can then continue by issuing more commands, correcting an error, or stopping. DATATRIEVE is forgiving of many common
errors if your meaning is clear. And, if DATATRIEVE cannot interpret your
instructions, it issues a clear, easy to understand error message. If you omit
certain parts of a command, DATATRIEVE even prompts you for the missing
information.

1-1

DATATRIEVE commands range from the simple, which can be invoked to
produce immediate results, to the complex, which combine many functions in
a single operation. Like a programming language, the DATATRIEVE command language allows you to group some commands in a loop for repeated
execution. Commands which can be nested are called statements. But you do
not have to be an experienced programmer to use DATATRIEVE. You can
choose a number of different command sequences to produce the same results.
The "right" solution to a DATATRIEVE problem is the solution that works.
Commands for retrieving records let you select just the data you want. You
can retrieve all records in a file or only those that meet the selection criteria
you specify. You can look at any field in a record or any combination of fields.
Commands for manipulating records let you sort them based on the contents
of one or more fields. The records can be sorted in ascending or descending
order. And, the data entry and modification statements let you store data in
new records or change data in existing ones.

1.2 The Report Writer and PRINT
The DATATRIEVE Report Writer creates and prints reports in a variety of
formats. You select not only the data and records to be included in the report,
but also the report's title, headings, and if desired, summary lines.
DATATRIEVE can calculate some common statistics (such as averages, totals, and high and low values) and include them where you specify. Every
page in the report can be numbered and dated. You can display the report
immediately on your terminal, print it on a line printer, or store it in a file (for
printing at a Jater time).
You can also produce simpler reports using a single DATATRIEVE statement: PRINT. While PRINT does not provide the full formatting and statistical capabilities of the Report Writer, it allows you to display selective data on
your terminal. While you are updating files, you can use PRINT to display
intermediate results or to verify the contents of records.

1.3 Procedures
At every installation, some sequences of commands and statements will be
issued on a recurring basis. To avoid retyping the command sequence each
time it is needed, you can create a procedure. A procedure is a sequence of
commands stored under a procedure name. To execute the commands, you
merely call out the procedure by its name. A procedure can save a great deal
of time because you need not reenter commonly used commands or "reinvent"
corI1plex command sequences.
A procedure can be made available to all users at an installation or only an
authorized few. Thus, by invoking a procedure created by someone else, even
less experienced users can perform complex operations.
You can use the DATATRIEVE editor, a subset of the DEC Standard Editor,
to modify procedures once they are stored. So, you can change a procedure as
the needs of your installation change.

1-2

Introduction to DATATRIEVE-ll

1.4 Description Tables
A description table is a group of code-and-description pairs you create and
store under a description table name. Using the description table facility, you
can store a code in a record, but when you print the record you can print a
descriptive character string, and not the code itself. The character string is
the description that you stored in the description table. Because the code can
be a single character and its description a much longer character string,
description tables can save a great deal of record space.
For example, you could create a description table containing the following
code-and-description pair:
S: "Single, widowed, or divorced"
Then you could store the code S in a field containing marital status. If you
print the field without referring to the description table, DATATRIEVE
prints the letter S. But if you use the description table to refer to the field,
DATATRIEVE prints the description "Single, widowed, or divorced".
Description tables can save the time involved in creating some complex command sequences. And, description tables can be expanded to accommodate
new code-and-description pairs. The DATATRIEVE editor is available for
modifying description tables.

1.5 Defining Records
DATATRIEVE uses data stored in an RMS file. The data file organization
can be relative, indexed, or sequential.
DATATRIEVE provides automatic conversion between data types used in
other languages. Files created in other languages can be used by
DATATRIEVE and files created with DATATRIEVE can be accessed by
other programs.
You define the format of the records in a data file with a series of COBOL-like
statements. But you need not be familiar with COBOL to create record definitions for DATATRIEVE's use. Complete instructions for creating record
definitions are included in Chapter 11 of this manual.
DATATRIEVE also provides an alternative method for defining records: the
Application Design Tool (ADT). ADT is an easy-to-use part ofDATATRIEVE
that creates the data file and its record definition using your responses to its
questions. ADT lets you create the necessary definitions quickly so that you
can begin storing your data in the file.

1.6 Password Tables
DATATRIEVE provides for data protection, beyond the protection offered by
your operating system, through password tables. A password table restricts
the use of data, procedures, and description tables to authorized users only.
Even authorized users can be prevented from performing highly sensitive
Introduction to DATATRIEVE-ll

1-3

operations such as modifying data or deleting records. The system manager is
responsible for overall system security, but all users can protect their own
private data, procedures, and description tables with the password facility.

1.7 Hierarchies and Views
DATATRIEVE provides two ways of looking at data in a manner different
from the way you normally see it: hierarchies and views. A hierarchy lets you
define a record so that its data is structured in a tree-like fashion. l·.. hierarchy
arranges data in a way that shows the subordination of one item of data to
another.
A view lets you look at data in related records that have different definitions.
A view provides a "window" into selected records and selected data of these
records, allowing you to work with them as if they were stored in the same file.

1.8 HELP, GUIDE Mode, and More
When you need help using DATATRIEVE, use the HELP command. On-line
assistance with DATATRIEVE commands and some concepts is available as
soon as you invoke DATATRIEVE and remains available throughout a
session.
GUIDE Mode, available if you use a VT52 or VT100 terminal, p:r:ompts you for
every operation you want to perform and leads you through a session. To start
GUIDE Mode, use the command SET GUIDE.
DATATRIEVE's clear error messages and prompting for missing statement
elements also help you form complete, syntactically correct statements. The
sample data provided with DATATRIEVE gives you the chance to practice
using DATATRIEVE before you use it on your own data.

1-4

Introduction to DATATRIEVE-l1

Chapter 2
DATATRIEVE Concepts

DATATRIEVE conIes with three groups of sanlple data:
• Data on yachts
• Data on the owners of yachts
• Data on families
Most of this manual uses the data on yachts to explain the use of
DATATRIEVE. (The data on yacht owners and families is used only with the
more advanced topics of hierarchies and views.) This chapter uses the yachts
data to introduce some basic concepts essential to the use ofDATATRIEVE.
If you have read theDATATRIEVE Primer, many of the terms in this chapter
will be familiar to you. This chapter is intended to supplement that information so you can perform operations more complex than those explained in the
DATATRIEVE Primer. If you are an experienced DATATRIEVE user, you
may want to go directly to the summary at the end of this chapter.

As you read this chapter, you can refer to the glossary at the back of this book
to refresh your memory of some terms.

2.1 Records, Files, and Fields
The basis for any system that maintains data is a record. Just as a manual
system for maintaining data consists of records, stored perhaps in a file folder
and locked in a file drawer, DATATRIEVE maintains records that are stored
in a file.

2-1

A file is any logically related group of data. For example, all the sample yacht
data used in the examples in this manual are grouped into one file. The data
in the file is stored in a series of records. A record consists of related data
treated as a unit. For instance, all information for an individual yacht makes
up that yacht's record.

A record can contain any type of data: numbers (such as a price, a salary, or a
part number), letters (such as the name of a person, company, or state), or
any other combination of characters. Each item of data in a record is stored in
a Held. A record might contain only one field (that is, only one item of data);
usually, though, a record contains many fields.

2-2

DATATRIEVE Concepts

Each recQrd for a y-acht; torex-a-mpl-e, contains data on th-e foll-owing items:

• Manufacturer (or the builder of the yacht)
• Model
• Rig type (such as ketch or sloop)
• Length
• Weight
• Beam
• Price
Each of these data items is stored in its own field in a record. If you stored this
information in a manual system, it might look like the following:

(
TYPE
MANUFACTURER =
ALBERG
MODEL = 37 MK II
SPECIFICATIONS
RIG = KETCH
LENGTH-OVER-ALL = 37
WEIGHT = 20,000
BEAM = 12
PRICE = $36,951

This simple record is, in fact, similar to the way DATATRIEVE stores data.
Each field of data has a name (such as MANUFACTURER and MODEL).
Some fields are grouped together because they are generally used together and
are often referred to by a single name (such as TYPE). For instance, the
type of yacht is determined by its builder's name and its model. Therefore,
MANUFACTURER and MObEL are grouped under the name TYPE. The
specifications for a yacht include its rig type, length, weight, beam, and price.
The record lists the fields for this data under the SPECIFICATIONS field.

DATATRIEVE Concepts

2-3

2.2 Domains
The sample yachts inventory contains over 100 records, each with the same
categories of information. Figure 2-1 shows a portion of the sample data. Each
line in that figure represents one record in the file. Every record contains the
same fields.
Figure 2-1: Portion of Sample Yachts File
DTR) PRINT YACHTS

MANUFACTURER

MODEL

RIG

ALBERG
ALBIN
ALBIN
ALBIN
AMERICAN
AMERICAN
BAYFIELD
BLOCK I.
BOMBAY
BUCCANEER
BUCCANEER
CABOT
CAL
CAL
CAL
CAL
CAL
CAPE DORY
CAPE DORY
CAPE nORY
CAPITAL
CARIBBEAN
CHALLENGER
CHALLENGER
CHALLENGER
CHRIS-CRAF
CLIPPER
CLIPPER
COLUMBIA
COLUMBIA
COLUMBIA
DOUGLAS
DOWN EAST
DOWN EAST
DUFOUR
EASTWARD
ENCHILADA
ENDEAVOUR
ERICSON
ERICSON
FISHER
FISHER
FJORD

37 MK II
79

KETCH
SLOOP
SLOOP
SLOOP
SLOOP
MS
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
KETCH
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP

BALLAD
VEGA
26

26-MS
30/32

CLIPPER
270
320
36

2-27
2-34
29
3-30
35
25
28

TYPHOON
NEWPORT
35

32
35
41

CARIBBEAN
CM 30
CM 32
35
41

PAYNE 9.6
32
32

LENGTH
OVER
ALL
WEIGHT BEAM

PRICE

20,000
4,200
7,276
5,070
4,000
5,500
9,500
18,500
9,400
5,000
12,500
15,000
6,700
9,500
8,000
10,500
l~j, 000
4,000
9,000
1,900
7,000
18,000
12,800
14,800
26,700
18,000
3,800
4,500
11,350
20,700
10,200
10,500
15,000
19,500
2,700
7,000
2,300
11,700
3,100
16,000
14,500
30,000
14,000

$36,000
$17,900
$27,500
$18,600
$9,890
$18,890
$32,870
$29,050
$23,950
$11,500
$21,250
$24,500
$13,710
$17,350
$15,400
$18,650
$24,500
$8,990
$21,990
$4,290
$14,100
$37,850
$31,830
$39,210
$51,220
$37,850
$9,500
$12,950
$19,755
$48,490
$18,260
$18,650
$24,500
$30,350
$8,510
$15,900
$7,990
$20,210
$9,030
$25,800
$23,850
$44,000
$23,200

37
26
30
27
26
26

32
39
31
27

32
36
27
33
29
30
35
25
28
19
28
35
32
35
41
35
30

32
35
41

SLOOP

SLOOP
SLOOP
38
SLOOP
25
SLOOP
HO
MS
20
SLOOP
32
SLOOP
231 SPECIA SLOOP
CRUISING/3 SLOOP
30
KETCH
37
KETCH
MS 33
MS

32
32
38
25
24
20

32
23
36
30
37
33

12
10
10
08
08
08
10
12
11
08
10
12
09
10
09
10
11
07
09
06
09
11
11
12
13
11
08
08
10
11
10
09
11
12
08
09
07
10
08
12
09
12
11

Of course, the data in any field may be different from one record to
the next, but the type of information in a field is always the same: The
MANUF ACTURER field always contains the name of the builder; the PRICE
field always contains a dollar amount.

2-4

DATATRIEVE Concepts

The fields that a record contains and the type of information a field can hold
is specified in the record's definition. Basically, a record definition lists all the
fields in a record and indicates the type of data (such as numbers, letters, or
other characters) that the field can contain.
All records with yachts data have the same record definition. As a group, the
records form a DATATRIEVE domain. A domain is simply a complete
set of records that have the same record definition. Thus, the sample
DATATRIEVE data contains three domains:
• YACHTS, which is the set of all records containing yacht data
• OWNERS, which is the set of all records containing yacht owner data
• FAMILIES, which is the set of all records containing family data

I I I
I VA "'H"PS I
I"''' I
I
I

I I I
[FAMILIES]

I I]
[OWNERS]

DATATRIEVE Concepts

2-5

2.3 The Data Dictionary
Every domain has a name that uniquely identifies it. For instance, the
domain containing all records of yachts is called YACHTS. To keep track of
all domains and other pertinent information, DATATRIEVE maintains a
data dictionary. Like a dictionary you use to look up the definition of a word,
the data dictionary contains definitions. The definitions in the data dictionary, however, are not of words but of records, domains, procedures, and description tables. Records, domains, procedures, and description tables are
called dictionary objects because their definitions are kept in the data
dictionary .
We have seen that the definition of a record is similar to a list of field names
and the type of data each field contains. This record definition is stored in the
data dictionary under a record name. A domain definition, stored under its
domain name, consists of its associated record definition and the name of the
file containing its data. (The data is not stored in the data dictionary. Only
the definition of its records is stored there. Data resides in a file outside of
DATATRIEVE.)

YA CRT a record containing
DISPLACEMENT (J)'

these fields.

(up to 5 digits)

TYPE
MANUFACTURER (Bui'd.
., er)
(uP to 10 characters)

MODEL
(uP to 10 characters)

SPECIFICATIONS (Specs)
BIG (up to 6 characters)
f,NGTH-OVER-ALL (LOA)
L her between 1-:J and 50')

(Nu'"

18p)

BEAM (up to 2 digitS)
PRICE (up to 5 dig,t l1,
but printed like III

Oney)

YACHTS a domain co ..t .
•• Q1n'
the records defined
I'll{
by YA CHT and stored .
In tlz
file YACHT,DAT. See
e
also YACHT.

When you invoke DATATRIEVE; you are automatically connected to a data
dictionary. It is only through the data dictionary that you can gain access to
records and their data. But, you may not be able to access every dictionary
object.
Password tables, which are like locks on a file drawer, may prevent you from
accessing some information. The person who creates a dictionary object determines who is allowed to access that dictionary object, and how they can use it.
For example, you may be able to read the records in a domain but not change
them. Password tables are also stored in the data dictionary.
2-6

DATATRIEVE Concepts

2.4 The READY Command
If you invoke DATATRIEVE to work with records, generally the first thing
you do is ready a domain. You ready a domain by issuing the READY command. READY signals your intention to use a domain and the records it
contains. When you ready the domain you also indicate whether you will be
reading records, modifying data in records, deleting records, or adding new
records to the file.

2.5 Collections
A collection is a group of records from a domain, brought together for a
specific purpose. A collection can contain all the records in a domain or just a
few. For example, if you want to print the record of any yacht manufactured
by Cape Dory, you could establish a collection of those records, then print
them. Working with a small collection of records is more convenient and
efficient than working with an entire domain.
The FIND statement establishes a collection. For instance, the following
statement establishes a collection of all records for all yachts built by Cape
Dory:
DTR> READY YACHTS READ
DTR> FIND YACHTS WITH MANUFACTURER="CAPE DORY"
[3 records found)

DATATRIEVE indicates that the collection contains three records.
Processing records generally includes sorting records, printing complete records (or just some fields in the records),and printing the whole collection or
just selected records in the collection. To keep track of your place in the
collection as you process it, DATATRIEVE provides a collection cursor. The
collection cursor is a pointer that points to a single record in a collection.
When you establish a collection with the FIND statement, the collection
cursor is null. This means that the collection cursor does not point to any of
the records. To make the collection cursor point to the record of your choice,
use the SELECT statement.
As you would expect, the FIRST record of a collection is the first one encountered when the collection was established. The record that the collection
cursor points to is the selected record. (There can be only one selected record
at anyone time.) The record following the selected record is the NEXT record
in the collection. The LAST record is the one located at the end of the
collection.
The following figure shows the collection of three records for Cape Dory. The
circled numbers'in the bottom right corner of each record indicate the record's
position in the collection. These digits (like the words FIRST, NEXT, and
LAST) allow you to refer to the specific record you want in the collection.
DATATRIEVE Concepts

2-7

CAPE DORY
CAPE DORY
CAPE DORY

28
SLOOP

28
9,000
09
$21,990

LAST

FIRST

2.6 Record Streams
Like a collection, a record stream is a group of records from the same domain.
A record stream is used only once, however. You create a record stream with a
record selection expression. Only the command or statement containing the
record selection expression uses the record stream . You can sort the record
stream and specify conditions that the records must meet.

2.7 Summary
A record consists of related data treated as a whole. Each category of data in a
record is stored in a field. The record definition lists the fields in the record
and the type of data each field can contain. Related records are stored in a
data file, which resides outside of DATATRIEVE.
A domain is a complete set of records with the same record definition. The
domain definition lists the name of its associated record definition and the
name of the data file containing the actual records.
Record and domain definitions (as well as procedure and description table
definitions) are catalogued in the data dictionary. The dictionary also contains password tables that restrict the use of definitions to authorized users
only.

2-8

DAT ATRIEVE Concepts

Chapter 3
Sample Session

This chapter shows how to use DATATRIEVE to keep a telephone
directory for a company. You start a DATATRIEVE session by invoking
DATATRIEVE. On all operating systems except VMS, you invoke
DATATRIEVE by typing the command DTR. On VMS type the command
MCR DTR. DATATRIEVE responds with an identification message and a
DTR> prompt.
>DTR
Datatrieve-11 t DEC Query and Report SYsteM
Version: V02.00t 2-JUN-80
Type HELP for help
DTR>

If you cannot invoke DATATRIEVE with the command DTR (or MCR DTR
on VAXNMS) see your system manager. After invoking DATATRIEVE, define a domain for your telephone directory. Next, define the record and the
data file that the domain will use.
DTR> DEFINE DDMAIN PHONES USING PHONE-REC ON PHONE.DAT;
DTR> DEFINE RECORD PHONE-REC USING
DFN> 01 PHONE.
DFN>
02 NAME PIC X(20).
DFN>
02 NUMBER PIC S(7) EDIT-STRING IS XXX-XXXX.
DFN>
02 LOCATION PIC xes).
DFN>
02 DEPARTMENT PIC xx.
DFN>
[Record PHONE-REC is 38 bytes IonS]
DTR> DEFINE FILE FOR PHONES KEY=NAME;

You may have noticed that the prompt changed to DFN> in the preceding
example. DATATRIEVE issues the DFN> prompt whenever you are defining
a record, domain, table, or procedure. When you finish a record definition
DATATRIEVE tells you how long the record is and returns to DATATRIEVE
command level.

3-1

The domain uses an indexed file, with the field NAME as the primary key.
This means that the field NAME cannot have the same value in two records,
and the value of NAME cannot be changed without erasing the record and
storing a new one. The department is stored as a two-letter code. Now, create
a description table to interpret the code.
DTR>
DFN>
DFN>
DFN:>
DFN>
DFN>
DFN>
DFN>
DTR>

DEFINE TABLE DEPT-TABLE
"CE": "ColTllTlercial Engineering" t
"PE":"Plant Engineering" t
CS
Cu s t 0 IT! e r SUP P 0 r t;; t
"RD": "Research and Deve 1 oPITlent" t
"SO": "Sales DepartlTlent" t
ELSE "UNKNOWN DEPARTMENT"
END-TABLE
ii

To test the table, use it to print the description associated with a department
code. You must put quotation marks around the code so that DATATRIEVE
will recognize the code as a character string, and not try to interpret it as a
field name. Also, to print out the entire description, you must use an editstring. DATATRIEVE uses a default edit-string of X(10) for strings stored in
tables, which means only the first 10 characters are printed unless you include
an edit-string in the PRINT statement. (See Section 11.7 for more information on edit-strings.) The following examples show what happens if you leave
out the quotation marks around the code or do not use an edit-string.
DTR> PRINT CE VIA DEPT-TABLE
Field "CE" is not defined or used out of context
DTR> PRINT "CE" !,IIA DEPT-TABLE
COITlmercial

The next example shows how to print the entire description.
DTR> PRINT "CE" !,IIA DEPT-TABLE USING
ComMercial Engineering

>«25)

To store information in the domain, use the STORE statement. You can
prevent storing a nonexistent departTilent code by using a VERIFY clause.
Make the entire operation into a procedure which you can use any time.
DTR>
DTR>
DFN>
DFN>
DFN>
DFN>
DTR>

READY PHONES WRITE
DEFINE PROCEDURE STORE-PHONE
STORE PHONES VERIFY USING
IF DEPARTMENT NOT IN DEPT-TABLE THEN
ABORT "BAD DEPARTMENT CODE"
END-PROCEDURE

Because the procedure STORE-PHONE contains only one statement you can
use it inside a REPEAT statement. This allows you to store as many records
as you want with a single statement. After you type in the REPEAT statement DATATRIEVE prompts you for the data to be stored in each record.

3-2

Sam ple Session

The following example shows how DATATRIEVE reprompts for data if your
original response was not in an acceptable format.
DTR) REPEAT 20 :STORE-PHONE
Enter NAME: Sauaset Joseph
Enter NUMBER: 854-2744
IlleSal placelTlent of ITlinus sisn in strins 11854-274411
Re-enter NUMBER: 8542744
Enter LOCATION: MB1-H5
Enter DEPARTMENT: RD
Enter NAME: Schneidert Henry
Enter NUMBER: 8542342
Enter LOCATION: MB1-H7
Enter DEPARTMENT: RD
Enter NAME: Krueser t WillialTl
Enter NUMBER: 8546818
Enter LOCATION: MB2-J5
Enter DEPARTMENT: CE
Enter NAME: Mooret Nancy
Enter NUMBER: 8545654
Enter LOCATION: MB1-J8
ENTER DEPARTMENT: CD
ABORT: BAD DEPARTMENT CODE
Execution terlTlinated b}' IIABORT II StatelTlent

At the end of the preceding example, DATATRIEVE stopped storing records
because the VERIFY clause detected a bad department code. To check that
DATATRIEVE did not store the record with the bad department code, use
the PRINT command to see what records are in the domain PHONES.
DTR) PRINT ALL

PHONE~

NAME

NUMBER

KrueSert WillialTl
Sal.laSe t Joseph
Schneidert Henry

LOCATION DEPARTMENT

854-6818 MB2-J5
854-2744 MB1-H5
854-2342 MB1-H7

CE
RD
RD

Instead of storing more records now, you may want to use the following
DATATRIEVE statements on the records you have.
DTR) FOR

PHON~S

PRINT NAMEt NUMBER

NAME
KrueSert WillialTl
Sal.laSe t Joseph
Schneider t Henn'

NUMBER
854-6818
854-2744
854-2342

DTR) FIND PHONES
[3 records found]
DTR) SORT BY NUMBER
DTR> PRINT ALL
NAME
J

Schneider t Henry
SavaSet Joseph
KrueSert WillialTl

NUMBER

LOCATION DEPARTMENT

854-2342 MB1-H7
854-2744 MB1-H5
854-6818 MB2-J5

RD
RD
CE
(continued on next page)

Sample Session

3-3

DTR> PRINT MAX NUMBER
NUMBER
854-8919
DTR> FOR CURRENT PRINT THEN MODIFY NUMBER
NAME

NUMBER

LOCATION DEPARTMENT

Schneidert Henry
854-2342 MB1-H7
Enter NUMBER: 8542341
SauaSet Joseph
854-2744 MB1-H5
Enter NUMBER: 8542744
KrueSert William
854-8919 MB2-J5
En t e r NUMBER: .'. Z
Execution terminated by operator
DTR>

RD
RD
CE

In the preceding example the CTRL/Z character caused DATATRIEVE to
return to DAT ATRIEVE command level without modifying the last record.
Whenever you are storing or modifying records and type CTRL/Z in response
to an ENTER prompt DAT ATRIEVE will return you to command level. The
next example shows how DATATRIEVE responds if you refer to a field without creating a "context."
DTR> FIND PHONES WITH NAME EQ "Schneider t Henr}'"
[1 Record found]
DTR> PRINT NUMBER
Field "NUMBER" is not defined or used out of context

Even though only one record is in the collection, there is no "selected" record.
To create a context for the PRINT statement, you may either select the record
or use the keyword ALL to refer to the whole collection.
DTR> PRINT ALL NUMBER

NUMBER
854-2341

The following procedure produces a report on employees' locations and telephone numbers, with employees grouped by department.
DTR> DEFINE PROCEDURE REPORT-BY-DEPT
DFN> REPORT PHONES SORTED BY DEPARTMENT
DF N >- SET REP 0 R T - N A ME = ;; COM PAN Y PH 0 NED IRE CTOR Y ;;

DFN>
DFN>
DFN>
DFN>
DTR>
DTR>

AT TOP OF DEPARTMENT PRINT DEPARTMENT VIA DEPT-TABLE USING X(25)
PRINT NAMEt NUMBERt LOCATION
END-REPORT
END-PROCEDURE
:REPORT-BY-DEPT

(continued on next page)

3-4

Sample Session

COMPANY PHONE DIRECTORY
1-Apr-80
Pase 1
DEPARTMENT
COMMercial Engineerins

NAME

NUMBER

LOCATION

Kruesert WilliaM

•

854-6919

MB2-J5

Savaset Joseph
Schneider t Henn'

854-2744
854-2341

MB1-H5
MB1-H7

Research and DeveloPMent

To end a DATATRIEVE session, use the EXIT command. DATATRIEVE
returns you to your operating system.
DTR> E>{IT
:>

Sample Session

3-5

Chapter 4
Introduction to Commands and Statements

Using DATATRIEVE interactively, you issue a series of commands and statements that direct DATATRIEVE's operation.
A command consists of a command name (such as READY or SHOW), and
may include additional elements. A command can be issued only at the
DAT ATRIEVE command level. Command level means that DAT ATRIEVE
is not in the middle of a command or statement. The command level prompt
is DTR> ; however, DATATRIEVE also issues this prompt when it is waiting
for you to finish a command or statement. You cannot combine a command
with another command or statement to form a compound command.
A statement consists of a statement name and may include additional elements. Unlike commands, however, statements can be nested within other
statements to perform more complex operations. Statements can be repeated
in a loop, and you can carry out statements conditionally by putting them
within an IF-THEN-ELSE statement.
Statements are of two types: simple and compound. A simple statement is a
single statement used alone. A compound statement is two statements combined with the word THEN or several statements placed within a
BEGIN-END block. A compound statement can be used anywhere a simple
statement is allowed. The format of a compound statement is:
statement-l THEN statement-2
or
BEGIN
statement-l
statement-2

statement-n
END
DATATRIEVE executes the statements in the order in which they appear.

4-1

4.1 Command and Statement Elements
Every DATATRIEVE command and statement consists of one or more of the
following elements:
• Command or statement name
• Other keywords
• Names, which identify an item containing a value
• Terminator, which signals the end of a command or statement
• Continuation character, which allows a command or statement to be continued on the next input line
• Comment, which allows you to enter text with a command or statement
• Expressions, which specify values or records
Every element of a DATATRIEVE command or statement must be constructed from characters in the DATATRIEVE character set.
The remainder of this chapter discusses the DATATRIEVE character set and
all command and statement elements except expressions. Chapter 6 is devoted to a discussion of DATATRIEVE expressions.

4.2 Character Set
The DATATRIEVE character set consists of the upper- and lowercase letters
A through Z, the digits 0 through 9, and special characters. Table 4-1 lists the
characters in the DATATRIEVE set.

Table 4-1: DATATRIEVE Character Set
Uppercase Letters:
A through Z
Lowercase Letters:
a through z
Digits:
o through 9
Special Characters:
(period)
(comma)
(semicolon)
(colon)
(left parenthesis)
(right parenthesis)
(left bracket)
(right bracket)
(plus sign)
+
(hyphen or minus sign)
* (asterisk)
(slash)
/
(8ITl (Carriage return)

4-2

(quotation mark)
(vertical line)
(equal sign)
<
(less-than sign)
>
(greater-than sign)
$
(dollar sign)
(exclamation point)
(underscore)
%
(percent sign)
?
(question mark)
@
(at sign)
(space)
@ID (tab)

Introduction to Commands and Statements

NOTE
DATATRIEVE treats all letters that you enter as upper case
unless you are storing data or enclose the letters in quotation
marks.

4.3 Keywords
A keyword is a command or statement element that can be used only as
indicated in the format of a command or statement. (Most keywords appear
in commands or statements; however, some are used in record definitions and
description tables.) In this manual, keywords are written in all uppercase
letters in command and statement formats.
The use of keywords is restricted only to where shown in these formats; therefore, do not use a keyword as the name of a domain, record, field, description
table, collection, procedure, variable, or view.
Appendix C contains a list of all DATATRIEVE keywords.

4.4 Names
A name is a character string used to identify any of the following items.
domain

collection

record

procedure

field

variable

description table

view

A name can consist of from 1 through 30 characters. The characters can be a
letter, digit, hyphen(-}, or underscore(_}. The following restrictions apply to
the construction of names:
1. A name must begin with a letter.
2. A name must end with a letter or digit.
3. A name cannot be a keyword.
4. A name must be 30 characters or less.
The following are all valid DATATRIEVE names:
TOTAL-SALARY
YACHTS
PRICE-PER-POUND
YEAR-TO-DATE-EARNINGS-FOR-1980
Introduction to Commands and Statements

4-3

The following are all invalid DATATRIEVE names:
TOTAL
(Duplicates a keyword)
1980-EARNINGS
(Does not begin with a letter)
PRICE-PER-POUND($/LB)
(Contains illegal characters)
YEAR-TO-DATE-EARNINGS-FOR--FY_1980
(Contains too many characters)

4.5 Termination and Continuation Characters
A terminator signals the end of a command or statement. The formal terminator in DATATRIEVE is the semicolon (;). However, most commands and
statements (except the DEFINE and DELETE commands) can be terminated by a carriage return (without a semicolon). You can enter multiple
commands on a single input line by separating the commands with a semicolon. In this case, DATATRIEVE does not begin processing the commands on
that line until you enter a carriage return.
If you enter a carriage return before a statement is logically complete,
DATATRIEVE displays the following message on your terminal.
[LOOKING FOR eleMent]

DATATRIEVE prompts for additional elements, if any, until the statement is
logically complete. You can continue statements from one line to the next by
entering carriage returns. However, DATATRIEVE does not prompt for an
optional element if the line entered is already a complete statement. You can
prevent DATATRIEVE from printing these statement prompts with the following command:
DTR> SET NO PROMPT

The continuation character hyphen (-) also lets you continue commands and
statements on more than one input line. The hyphen lets you put optional
elements on the next line, and DATATRIEVE does not issue any statement
prompts between the two lines. You cannot continue a statement or command
on more than two successive lines using a hyphen.
(The total number of characters for one input line may not exceed 132
characters. )
You must use a hyphen if you want to continue a literal expression or a name.

4-4

Introduction to Commands and Statements

4.6 Comments
You can include a comment with a line of input by preceding the comment
with an exclamation point (!) and terminating it with a carriage return. The
comment can include any characters.
The primary use of comments is in indirect command files. During an interactive DATATRIEVE session, DATATRIEVE does not store comments, so they
are of limited use.

Introduction to Commands and Statements

4-5

Chapter 5
Commands and Statements

This chapter describes all DATATRIEVE commands and statements. Table
5-1 lists these commands and statements in alphabetical order. Table 5-2
lists several frequently performed functions and indicates the commands and
statements you can issue to perform those functions.
The remainder of this chapter describes each command and statement, in
alphabetical order. Before you issue a command or statement, you should
read its description completely. Pay special attention to the following parts of
the description:
• Format of the command or statement, including the spelling of keywords.
As a rule, command and statement names and other keywords cannot be
abbreviated. The sequence of command and statement elements is also
critical. You must follow the sequence shown in the format. If you omit an
optional element, just leave its relative position in the command or statement empty and proceed to the remaining elements in a left-to-right order.
If necessary, review the documentation conventions listed in the front of this
manual.
• Restrictions, which tell you the type of privilege you must have to issue the
command or statement. A restriction could also indicate requirements for
the correct operation of the command or statement.
• Usage Notes, which give you some common uses of the command or statement and its elements and indicates whether you can use other commands
or statements with this command or statement.
• Examples, which show the command or statement syntax as well as some
typical command and statement sequences.

5-1

Table 5-1: Alphabetical Summary of Commands and Statements

Section

Command/Statement
(C = Command, S = Statement)

5.1

ABORT (S)

Ends statement, procedure, or command
file execution

5.2

ADT (C)

Invokes Application Design Tool (ADT)

5.3

ASSIGNMENT (S)

Establishes the value of a field or variable

5.4

BEGIN-END (S)

Groups statements into a compound
statement

5.5

DECLARE (S)

Defines a variable

5.6

DEFINE DICTIONARY (C)

Creates a private data dictionary

5.7

DEFINE DOMAIN (C)

Creates a domain definition

5.8

DEFINE FILE (C)

Creates a data file for a domain

5.9

DEFINE PROCEDURE (C)

Creates a procedure definition

5.10

DEFINE RECORD (C)

Creates a record definition

5.11

DEFINE TABLE (C)

Creates a description table definition

5.12

DEFINEP (C)

Adds an entry to a password table

5.13

DELETE (C)

Removes a definition from. a data
dictionary

5.14

DELETEP (C)

Removes an entry from a password table

5.15

EDIT (C)

Invokes the DATATRIEVE editor

5.16

ERASE (S)

Deletes record(s) from a data file

5.17

EXIT (CTRL/Z) (C)

Ends a DATATRIEVE session

5.18

EXTRACT (C)

Copies a definition to an indirect command file

5.19

FIND (S)

Retrieves records and establishes current
collection

5.20

FINISH (C)

Releases domain(s) and associated
coilections

5.21

FOR (S)

Applies statement(s) to selected records

5.22

HELP (C)

Provides online assistance
commands/statements

5.23

IF-THEN-ELSE (S)

Executes either of 2 statements, depending on evaluation of a Boolean expression

<),1
U."''':t

r::

l\JrnnT14'V fe;;;!\

Changes field(s) contents in specified
record(s)

5.25

PRINT (S)

Prints specified field(s) of specified
record(s)

5.26

READY (C)

Readies a domain for use

5.27

RELEASE (C)

Releases named collections, description
tables, or global variables

"''I'.L'-'.LJ.L.L'.L

\U/

Function

with

(continued on next page)

5-2

Commands and Statements

Table 5-1: Alphabetical Summary of Commands and Statements (Cont.)

Section

Command/Statement
(C = Command, S = Statement)

5.28

REPEAT (S)

Executes a statement a specified number
of times

5.29

REPORT (C)

Invokes the Report Writer

5.30

SELECT (S)

Selects a record from a collection

5.31

SET (C)

Establishes the current data dictionary,
sets the maximum number of columns
per page, controls the scope of aborts,
starts Guide Mode, and inhibits or permits statement prompting

5.32

SHOW (C)

Prints information about the data dictionary and its contents

1 5 .33

SHOWP (C)

Prints a password table

I 5.34

SORT (S)

Sorts records in a collection

5.35

STORE (S)

Stores a record in a domain

5.36

SUM (S)

Prints the total of contents of specified
field(s)

5.37

THEN (S)

Creates a compound statement

Function

Commands and Statements

5-3

Table 5-2: Summary of Commands and Statements by Function
Command/Statement

Topic/Function
Online Assistance
Printing command/statement
information
Starting Guide Mode
Enabling/disabling
statement prompting
Terminating a Session
Data Dictionaries
Creating a data dictionary
Establishing current
dictionary
Displaying dictionary
contents
Displaying dictionary file
specification
Deleting a definition
Domains
Readying a domain for use
Creating a domain definition
I

I
I

Section

HELP

5.22

SET GUIDE
SET PROMPT

5.31
5.31

EXIT (CTRL/Z)

5.17

DEFINE DICTIONARY
SET DICTIONARY

5.6
5.31

SHOW ALL

,5.32

SHOW DICTIONARY

5.32

DELETE

5.13

READY
DEFINE DOMAIN
ADT

5.26
5.7
5.2

Creating a data file for a domain
Deleting a domain definition

FILE
I DEFINE
DELETE

5.8
5.13

Copying a domain definition
to an indirect command file
Releasing control of a domain
Displaying domain names or
definitions

EXTRACT

5.18
5.20
5.32

Records
Creating a record definition
Deleting a record definition

I Procedures

Creating a procedure
Deleting a procedure
Modifying a procedure
Copying a procedure to
an indirect command file
Displaying procedure names

Deleting a record from a file
Copying a record definition
to an indirect command file
Changing field contents
Printing records/field values

Adding records
Selecting records
Sorting records
Displaying record names and
definitions

FINISH
SHOW

I
I

DEFINE RECORD
ADT

5.10
5.2

DELETE
ERASE

5.13
5.16

EXTRACT
MODIFY
PRINT
REPORT
SUM
STORE
SELECT
SORT
SHOW

5.18
5.24
5.25
5.29
5.36
5.35
5.30
5.34
5.32

I
I

5.9

DEFINE PROCEDURE
DELETE
EDIT
EXTRACT

5.15
5.18

SHOW

,S.:t~

,).1:~

and definitions

(continued on next page)

5-4

Commands and Statements

Table 5-2: Summary of Commands and Statements by Function (Cont.)
Topic1FtriictiOD
Description Tables
Creating a description table
Deleting a description table
Modifying a description table
Copying a description table
to an indirect command file
Releasing a description table
Displaying description table
names and definitions
Password Tables
Creating a password table
for a domain
for a procedure
for a record
for a description table
Adding an entry to a password
table
Deleting an entry from a
password table
Displaying a password table
Variables
Defining a variable
Assigning a value to a
variable
Releasing a variable
CombininglRepeating Statements
Creating a compound statement
Creating a block of statements
Repeating a statement
Executing a statement
conditionally
Applying statements to records

Command/Statemellt

Section

DEFINE TABLE
DELETE
EDIT
EXTRACT

5.11
5.13
5.15
5.18

RELEASE
SHOW

5.27
5.32

DEFINE DOMAI~
DEFINE PROCEDURE
DEFINE RECORD
DEFINE TABLE
DEFINEP

5.7
5.9
5.10
5.11
5.12

I DELETEP

5.14

SHOWP

5.33

DECLARE
ASSIGNMENT

5.5
5.3.3

RELEASE

5.27

THEN
BEGIN-END
REPEAT
IF-THEN-ELSE

5.37
5.4
5.28
5.23

FOR

5.21

Commands and Statements

5-5

5.1

ABORT Statement
Function

Provides a means of stopping execution of either a single statement (during an
interactive session) or an entire procedure or indirect command file.
Format
p. "HORT val-exp

Arguments

val-exp
Is a value expression. If an abort occurs, DATATRIEVE prints a message
containing this value expression.
Restrictions

None.
Results

1. If the abort conditions are met, DATATRIEVE prints the following message on the calling terminal:
ABORT:

l.Ial-exp

Execution terlTlinated b}' IIABORT II statelTlent

2. If the abort occurs during an interactive session, DATATRIEVE stops
executing the statement containing the ABORT statement and returns
control to its command level. The ABORT statement does not end the
interactive session.
3. If the abort occurs within a STORE or MODIFY statement the STORE or
MODIFY is not carried out.
4. If the abort occurs in a procedure or indirect command file the results
depend on whether SET ABORT is in effect. If SET ABORT is in effect
DATATRIEVE returns to command level without executing the rest of the
procedure or indirect command file. If SET NO ABORT is in effect
DATATRIEVE executes any remaining statements and commands in the
procedure or indirect command file. (At the start of a DATATRIEVE
session SET NO ABORT is in effect. To change this setting use the SET
ABORT command. See Section 5.31.)
Usage Notes

Use the ABORT statement within an IF-THEN-ELSE statement to abort if
certain conditions are met.

5-6

Commands and Statements

Examples

1. Store a record in the YACHTS domain, but if the value of the BEAM field

is 0, abort the operation and display a message.
DTR) STORE YACHTS VERIFY USING
[Lookin~ for verification stateMent]
DTR:> I F BEAM EQ 0 THEN ABORT BAD 1.IALUE FOR BEAM
Enter MANUFACTURER: AMERICAN
Enter MODEL: 1880
Enter RIG: SLOOP
Enter LENGTH-OVER-ALL: 25
Enter BEAM: 0
Enter PRICE: 10000
ABORT: BAD VALUE FOR BEAM
Execution terlTlinated by "ABORT" statelTlent
DTR)
II

2. Define a procedure to write a report on the current collection. Abort the
entire procedure if there is no current collection to report on.
DTR) DEFINE PROCEDURE YACHT-REPORT
DFN) SET ABORT
DFN) PRINT "THIS PROCEDURE REQUIRES A CURRENT COLLECTION"
DFN) IF *."N to abort" CONTAINING "N" ABORT "TOO BAD"
DFN) REPORT
DFN) PRINT BOAT
DFN:> AT BOTTOM OF REPORT PRINT COUNTt TOTAL PRICE
DFN) END-REPORT
DFN) END-PROCEDURE
DTR)
DTR) :YACHT-REPORT
THIS PROCEDURE REQUIRES A CURRENT COLLECTION
Enter N to abort: N
ABORT: TOO BAD
Execution terlTiinated b}' "ABORT" statelTlent
DTR)

Commands and Statements

5-7

5.2 ADT Command
Function

Invokes the Application Design Tool (ADT) , which aids in the creation of a
domain definition, its associated record definition, and its data file.
Format
ATVl'

l"\..LJ .L

Arguments

None.
Restrictions

ADT is an option when DATATRIEVE is installed. If DATATRIEVE is installed without ADT you cannot invoke ADT.
Results

DATATRIEVE invokes ADT, which asks you a series of questions about the
domain and its field definitions. Refer to Chapter 11 for more information on
ADT.
Example

Invoke the Application Design Tool.
DTR> ADT
Do

5-8

YOU

want help? (VES or NO)

Commands and Statements

5.3 Assignment Statement
The assignment statement assigns a value to an elementary field, a group
field, or a variable.

5.3.1 Assigning a Value to an Elementary Field
Function

Assigns a value to an elementary field in a MODIFY or STORE statement.
Format
fld-name = val-exp

Arguments

fld-name
Is the name of an elementary field.
Must be an equal sign, and not the relational operator EQ or EQUAL.
val-exp
Is the value to be assigned to the field. This argument can be any value
expression.
Restrictions

1. This format or tne assignment statement can be used only in a
MODIFY ... USING or STORE ... USING statement. (See Section 5.25 or
5.36.)
2. To use the assignment statement inside a STORE ... USING statement,
you must ready the domain for WRITE or EXTEND access. To use this
statement inside a MODIFY ... USING statement, you must ready the
domain for WRITE or MODIFY access. (See the READY command, Section 5.25.)
3. You cannot assign a value to a COMPUTED BY field.
Results

1. DAT ATRIEVE stores the value of the value expression in the specified
field, performing any datatype conversions necessary.

2. If the argument val-exp is a prompting value expression (* .prompt-name)
DATATRIEVE prompts for the value of the field. DATATRIEVE rejects
your input and reprompts for the value if any of the following occurs:
• Truncation error . You have entered more characters than the field definition allows.
• Conversion error. You have entered a character that is inappropriate for
the field, such as a letter for a numeric field.

Commands and Statements

5-9

• Sign error. You have entered a minus sign for an unsigned numeric field.
• VALID IF failure. You have entered an invalid value for the field. That
is, the value results in a Boolean expression (specified in the record
definition clause VALID IF bool-exp) that is "False." (See Section 11.16
for more information on record definitions.)
3. If the argument val-exp is not a prompting value expression and a truncation, conversion, or sign error occurs, DATATRIEVE accepts the value
wi th a warning.
• If you enter too many digits for a numeric field, DATATRIEVE truncates the high-order digits, stores the remaining digits in the field, and
issues an error message.
• If you enter too many characters for an alphanumeric field,
DATATRIEVE truncates the rightmost characters, stores the remaining
characters in the field, and issues an error message.
• If a VALID IF failure occurs, DATATRIEVE does not execute the assignment statement. The STORE or MODIFY statement containing the
assignment statement is not executed.
Usage Notes

1. When using this format of the assignment statement, you may want
DATATRIEVE to check your values for validity and give you·the opportunity to recover from an error caused by invalid input. The prompting
value expression, shown in the assignment statement below, provides the
only means for you to recover from a truncation, conversion, or sign error,
or a VALID IF failure. This facility is especially useful when you are
creating records with the STORE ... USING statement.
fld-narTle = *.prorT1Pt-narTle

2. If you are unsure of the name of a field or its valid contents, use the
SHOW FIELDS command (Section 5.33). SHOW FIELDS displays a
brief description of each field in a readied domain.
Exampies

1. Ready the YACHTS domain for WRITE access, then store a record in the
domain for the manufacturer CHALLENGER.
DTR) READY YACHTS WRITE
DTR) STORE YACHTS USING MANUFACTURER="CHALLENGER"
DTR> PRINT YACHTS WITH MANUFACTURER EQ "CHALLENGER"

5-10

MANUFACTURER

MODEL

RIG

LENGTH
OVER
ALL

CHALLENGER
CHALLENGER
CHALLENGER
CHALLENGER

32
35
41

SLOOP
SLOOP
KETCH

32
35
41

WEIGHT

12t800
14t800
28t700

Commands and Statements

BEAM PRICE
00

11 $31t835
12 $38t215
13 $51 t228

2. Ready the YACHTS domain for MODIFY access, then change the value of
the -P-RlCEfield to a new value-specified -by the user.
DTR) READY YACHTS MODIFY
DTR) FIND YACHTS
[113 records found]
DTR) SELECT 1
DTR) PRINT PRICE THEN MODIFY USING PRICE=*."NEW PRICE"
PRICE
$36,951
Enter NEW PRICE: 39000

5.3.2 Assigning to a Group Field
Function

Assigns values to the elementary fields in a group field in a MODIFY or
STORE statement.
Format
group-fld-name-l = group-fld-name-2

Arguments

group-fld-name-l
Is the name of a group field.
Must be an equal sign, and not the Boolean operator EQ or EQUAL.
group-fld-name-2
Is the name of a group field.
Restrictions

1. This format of the assignment statement can be used only in a
MODIFY ... USING or STORE ... USING statement. (See Section 5.25 or
5.36.)

2. To use the assignment statement in a MODIFY ... USING statement, you
must ready the domain containing group-fld-name-l for MODIFY or
WRITE access. To use it in a STORE ... USING statement, you must
ready the domain for WRITE or EXTEND access. (See the READY command, Section 5.27.)
3. Both group-fld-name-l and group-fld-name-2 must have at least one
elementary field with the same defined name or query name.
Commands and Statements

5-11

Results

DATATRIEVE changes the values of all fields in group-fld-name-l to the
values of identically named fields in group-fld-name-2. All other elementary
fields in group-fld-l are set to zero or blank in a STORE statement, or remain
unchanged in a MODIFY statement.
Examples

1. Store a record in the YACHTS domain with the same values in the group
field SPECIFICATIONS as the selected record.
DTR> READY YACHTS (SHHHH) WRITE
DTR> FIND YACHTS
[113 records found]
DTR> SELECT 1
DTR> STORE YACHTS USING BEGIN
[LooK ins for stateMent]
DTR) BUILDER=*.BUILDER
[Loo~\inS for
statelTlent or "end"]
DTR> SPECS=SPECS
[Loo~\inS for statelTlent or "end"]
DTR> END
Enter BUILDER:

2. Store records into the new domain PRICED-YACHTS. Store only those
yachts which have a price.
DTR> READY PRICED-YACHTS WRITE
DTR> FOR YACHTS WITH PRICE NE 0
[LooK inS for stateMent]
DTR> STORE PRICED-YACHTS USING BOAT=BOAT
DTR>

5.3.3 Assigning a Value to a Variable
Function

Assigns a value to a variable.
Format
variable-name = val-exp

Arguments

variable-name
Is the name of a variable that has been defined with a DECLARE
statement.

Must be an equal sign, and not the relational operator EQ or EQUAL.
val-exp
Is a value expression, the value of which is to be assigned to variablename.

5-12

Commands and Statements

Restrictions

1. This format of the assignment statement can be used anywhere a statement is allowed.
2. The argument variable-name must be defined with the DECLARE statement (see Section 5.5).
Results

1. DATATRIEVE assigns the specified value to the variable.
2. If the argument val-exp is a prompting value expression (* .prompt-name)
DATATRIEVE prompts for the value of the field. DATATRIEVE rejects
your input and reprompts for the value if any of the following occurs:
• Truncation error. You have entered more characters than the field definition allows.
• Conversion error. You have entered a character that is inappropriate for
the field, such as a letter for a numeric field.
• Sign error. You have entered a minus sign for an unsigned numeric field.
• VALID IF failure. You have entered an invalid value for the field. That
is, the value results in a Boolean expression (specified in the record
definition clause VALID IF bool-exp) that is "False." (See Section 11.16
for more information on record definitions.)
3. If the argument val-exp is not a prompting value expression and a truncation,conversion, or sign error occurs, DATATRIEVE accepts the value
with a warning.
• If you enter too many digits for a numeric field, DATATRIEVE truncates the high-order digits, stores the remaining digits in the field, and
issues an error message.
• If you enter too many characters for an alphanumeric field,
DATATRIEVE truncates the rightmost characters, stores the remaining
characters in the field, and issues an error message.
• If a VALID IF failure occurs DATATRIEVE does not execute the assign- 'ment statement.
Usage Notes

When using this format of the assignment statement, you may want
DATATRIEVE to check your values for validity and give you the opportunity
to recover from an error caused by invalid input. The prompting value expression shown in the assignment statement below provides the only means for
you to recover from a truncation, conversion, or sign error or VALID IF failure.
variable-name = *.prompt-nafTle

Commands and Statements

5-13

Examples

1. Declare the global variable NEWPRICE. Assign a value to it.
DTR) DECLARE NEWPRICE PIC 88888 EDIT-STRING IS $$$t$$$.
DTR) NEWPRICE = $25000

2. Declare two global variables, then assign the value of OLD PRICE to
NEWPRICE.
DTR) DECLARE NEWPRICE PIC 88888.
DTR) DECLARE OLDPRICE PIC 88888.

DTR) NEWPRICE = OLDPRICE

5-14

Commands and Statements

5.4 BEGIN-END Statement
Function

Groups statements into a single compound statement, called a BEGIN-END
block.
Format

BEGIN statement-l

[statement-2] :.. END

Arguments

statement
Is a DATATRIEVE statement. If you enter more than one statement use
carriage returns or semicolons to separate them.
END

Restrictions

1. You can use a BEGIN-END block anywhere you can use a statement.
2. You must observe any restriction on the statements included in the
BEGIN-E:r--.~D block that is listed in their descriptions.
3. You cannot use a FIND or SELECT statement in a BEGIN-END block.
Results

1. DATATRIEVE executes the statements in the BEGIN-END block in the
order in which you enter them.
2.. If the BEGIN-END block includes a DECLARE statement, the variable
defined by the DECLARE is a local variable and cannot be referenced
outside the BEGIN-END block. The variable is automatically released
when the END statement is executed. See Se~tion 6.1.3 for more information on variables.

Commands and Statements

5-15

Examples

1. Store five records in the domain PHONES, each having LOCATION

MBI-H2 and DEPARTMENT CEo
DTR) READY PHONES WRITE
DTR) REPEAT 5 STORE PHONES USING
[LooKinS for assisnMent stateMent(s)]
DTR) BEGIN
[Leek ins for stateMent]
DTR) NAME= *.NAME
[Loo~\ins for staterrlent or "end"]
DTR) NUMBER= *.NUMBER
[Loo~\ins for staterrlent or "end"]
DTR> LOCATION= "MB1-H2"
[Loo~\ins for staterrlent or "end"]
DTR) DEPARTMENT= "CE"
[Loo~\ins for statelrlent or "end"]
DTR) END
Enter NAME:

2. This example shows how a BEGIN-END block is treated as a single
statement.
DTR)
DFN>
DFN>
DFN>
DTR>
DTR)
SHOW
SHOW

DEFINE PROCEDURE LOOP-EXAMPLE
PRINT "SHOW HOW A BEGIN-END WORKS WITH REPEAT"
PRINT "AND MORE THAN ONE STATEMENT"
END-PROCEDURE
REPEAT 2 :LOOP-EXAMPLE
HOW A BEGIN-END WORKS WITH REPEAT
HOW A BEGIN-END WORKS WITH REPEAT

AND MORE THAN ONE STATEMENT
DTR>
DTR> REPEAT 2 BEGIN :LOOP-EXAMPLE END
SHOW HOW A BEGIN-END WORKS WITH REPEAT
AND MORE THAN ONE STATEMENT
SHOW HOW A BEGIN-END WORKS WITH REPEAT
AND MORE THAN ONE STATEMENT

5-16

Commands and Statements

5.5 DECLARE Statement
Function

Defines a global or local variable.
Format
DECLARE variable-name variable-defn.

Arguments

variable-name
Is the name of the variable being defined. The name must conform to the
rules for names listed in Section 4.5.
variable-defn
Is the definition of the variable. The definition consists of field definition
clauses. It must include at least a COMPUTED BY, PICTURE (PIC), or
USAGE clause to define the type and size of the variable. (Refer to Section 11.6 for more information on field definition clauses.) If you include
more than one clause, separate them with spaces .
. (period)
Ends the DECLARE statement.
Restrictions

None.
Results

The DECLARE statement defines either a global variable or a local variable.
A variable defined within a BEGIN-END block (see Section 5.4) is a local
variable. You can reference a local variable only within the BEGIN-END
block containing the DECLARE statement. DATATRIEVE releases local variables when it encounters the END statement of the BEGIN-END block.
If you are not inside a BEGIN-END block when you issue the DECLARE

statement, DATATRIEVE creates a global variable. A global variable exists
until you end a DATATRIEVE session (with the EXIT command or CTRL/Z)
or until you release the variable with the RELEASE command.

Commands and Statements

5-17

Usage Notes

The DECLARE statement defines a variable; it does not assign a value to the
variable. To assign a value to the variable, use the following format of the
assignment statement:
variable-name = val-exp
See Section 5.3.2 for more information on assigning a value to a variable.
Examples

1. Declare the global variable NEWBEAM as a two-digit numeric field.
DTR> DECLARE NEWBEAM PIC 99.

2. Declare the variable NOW as a date. Assign today's date to NOW.
DTR> DECLARE NOW USAGE IS DATE.
DTR> NOW= IITODAYII
DTR> PRINT NOW(-)
22-Ma}'-BO

5-18

Commands and Statements

5.6 DEFINE DICTIONARY Command
Function

Creates a file for DATATRIEVE to use as a data dictionary and connects you
to the new dictionary.
Format
DEFINE DICTIONARY file-spec

Arguments

file-spec
Is the file specification for the data dictionary, in the format:
dev: [UFD]filename.ext;ver
You must specify at least one field. If you omit fields in the file specification, DATATRIEVE uses the following defaults:

dev:

SY: (the system device)

[UFDl

Your default UFD

filename

QUERY

.ext

.DIC

;ver

1 or 1 higher than current version number
(non-RSTSIE systems only)

Restrictions

You must have write access to the specified directory.
Results

1. DATATRIEVE creates an empty indexed file for use as a data dictionary.

2. If you do not enter file-spec on the same input line as DEFINE
DICTIONARY, DATATRIEVE prompts with DFN>. After you enter the
file specification, control returns to the DATATRIEVE command level.
3. The new data dictionary becomes the current data dictionary.

Commands and Statements

5-19

Usage Notes

1. You can verify the name of the new data dictionary with the following
format of the SHOW command:

SHOW DICTIONARY
SHOW DICTIONARY prints the complete file specification of the current
data dictionary.
2. DATATRIEVE does not automatically enter definitions in a private data
dictionary. You can add definitions and associated password tables
to the dictionary with the DEFINE DOMAIN, DEFINE PROCEDURE,
DEFINE RECORD, and DEFINE TABLE commands.
Examples

1. Define a file named NEWDIC on the system device for use as a data
dictionary. The file will have the same UFD as your default UFD and an
extension of DIC.
DTR> DEFINE DICTIONARY NEWDIC

2. Define the file SY:[42,43]DATA.DIC for use as a data dictionary.
DTR> DEFINE DICTIONARY [42,43JDATA

5-20

Commands and Statements

5.7 DEFINE DOMAIN Command
The DEFINE DOMAIN command stores a domain definition in a data dictionary. The definition can be for an RMS domain or a view.

5.7.1 Defining an RMS Domain
Function

Stores a domain definition in the current data dictionary for an RMS domain
and creates a password table for the domain.
Format

DEFINE DOMAIN domain-name USING record-name

[(paSSWOrd)

ON file-spec;

(*)

Arguments

domain-name
--nnot a upl11·cat e a
DATATRIEVE keyword or any other name in the current data dictionary.

....Ts

t,h
_ .... p'
_

n.... p.
_ .............. p.
_

n:f
V.L

....IJUC;;
1-."

,.l.n.~,,~~
uvu~a~u

h~~_~
ut;Ul
b

.J_L'~

__ .J
U~llH~U.

T.L
~L

(;C1

record -name
Is the name of the record definition to be associated with the domain. This
record definition must be defined before you ready the domain.
pass\vord
Is the password DATATRIEVE will use to check that you
have E (execute) privilege for the record definition. Use (*) to have
DATATRIEVE prompt you for the password.

file-spec
Is the file specification of a file containing the data for the domain. This
file does not have to exist until you try to ready the domain. The file
specification has the following format:
dey: [UFD]filename.ext;ver
You must specify at least a file name. All other fields are optional.
; (semicolon) .
Ends the domain definition.
Restrictions

1. You cannot use a DEFINE DOMAIN command in a procedure.
2. You cannot invoke a procedure in a domain definition.

Commands and Statements

5-21

Results

1. If you do not end the DEFINE DOMAIN command with a semicolon,
DATATRIEVE prompts with DFN>, indicating it is expecting a continuation of the domain definition. DATATRIEVE continues to prompt with
DFN> until you enter a semicolon followed by a carriage return or until it
detects an error. If a syntax error occurs while you are entering the domain
definition, DATATRIEVE returns to command level without creating a
domain definition.

2. DATATRIEVE enters the domain definition in the current data dictionary and creates a password table for -the domain. DATATRIEVE enters a
UIC/pPN in the password table with full access privileges (RWMEC). The
actual UIC/PPN stored in the password table is installation-dependent.
Refer to Chapter 14 for more information.
Usage Notes

1. The record or data file associated with the domain need not be defined
when you issue a DEFINE DOMAIN command.

2. You cannot modify a domain definition with the DEFINE DOMAIN command. To change an existing domain definition, use the DATATRIEVE
editor, explained in Chapter 8. You can also use the EXTRACr command
to copy the domain definition to an indirect command file for editing. See
Section 5.18 for more information on EXTRACT.
Examples

1. Define the domain PHONES. Use PHONE-REC as the associated record
and store the data in the file PHONE.DAT.
DTR) DEFINE DOMAIN PHONES USING PHONE-REC ON PHONE.DAT;

2. Define the domain YACHTS. Use YACHT as the associated record and
store the data in the file [202,202]YACHT.DAT.
DTR) DEFINE DOMAIN YACHTS USING YACHT ON [202t202JYACHT.DAT;

5.7.2 Defining a Domain as a View
Function

Stores a domain definition for a view in the current data dictionary and
creates a password table for the domain.

5-22

Commands and Statements

Format
DEFINE DOMAIN view-name OF domain-name [,domain-name-2] ... USING
01

fld-name-1

OCCURS FOR rse-1 .
OCCURS FOR rse-n

lev-no-m fld-name-n

{

}

FROM domain-name-n

Arguments

view-name
Is the name of the view being defined. It cannot duplicate a
DATATRIEVE keyword or any other name in the current data dictionary.
domain-name
Is the name of a domain containing the records to be inciuded in the view.
You cannot use the name of a view . Use commas to separate domain
names.
lev-no
Is the level number for a field in the view.
fld-name
Is the name of a field in the view. If fld-name is followed by a FROM
domain-name clause, fld-name must be the name of a field in a domainname specified in the OF clause.
OCCURS FOR rse
Indicates that the associated field is to be included in the view for only
those records that are identified by the record selection expression (RSE).
The RSE must contain a reference to one of the domains specified in the
OF clause.
FROM domain-name
Indicates that the associated field is identical to the field of the same
name in domain-name. The argument domain-name must be the same as
the domain used in the last OCCURS FOR clause .
. (period)
Ends a field definition.
; (semicolon)
Ends the domain definition.

Commands and Statements

5-23

Restrictions

1. You cannot use a DEFINE DOMAIN command in a procedure.

2. You cannot invoke a procedure in a domain definition.
Results

1. If you do not end the DEFINE DOMAIN command with a semicolon,

DATATRIEVE prompts with DFN>, indicating it is expecting a continuation of the domain definition. DATATRIEVE continues to prompt with
DFN> until you enter a semicolon followed by a carriage return or until it
detects an error. If a syntax error occurs while you are entering the domain
definition, DATATRIEVE returns to command level without creating a
domain definition.
2. DATATRIEVE enters the domain definition in the current data dictionary and creates a password table for the domain. DATATRIEVE enters a
UIC/PPN in the password table with full access privileges (RWMEC). The
actual UIC/PPN stored in the password table is installation-dependent.
Refer to Chapter 14 for more information.
Usage Notes

Refer to Chapter 15 for more information on views.
Example

Define a view of big yachts.
DTR>
DFN>
DFN>
DFN>
DFN>
DFN>
DTR>

DEFINE DOMAIN BIGGEST-YACHTS OF YACHTS USING
01 BIGGEST-YACHT OCCURS FOR YACHTS WITH LOA GT
03 BUILDER
FROM YACHTS.
03 MODEL
FROM YACHTS.
03 PRICE
FROM YACHTS.

See Chapter 15 for more examples.

5-24

Commands and Statements

ao.

,.. -

5.8 DEFINE FILE Command
Function

Creates a sequential or indexed sequential data file for an RMS domain
defined in the current data dictionary. The data file has the same file specification as the domain definition.
Format
DEFINE FILE [FOR] domain-name [ALLOCATION = n] [SUPERSEDE,] [ MAX,]

KEY = fld-name

~({

CHANGE
]
[ NO CHANGE [, ]

[ DUP
]
NO DUP

})~

[, ... ]

Arguments

domain-name
Is the name of an RMS domain for which a file is to be created. The
domain and its associated record must be in the current data dictionary
when you issue this command.
ALLOCATION = n
Specifies the number of disk blocks to be allocated for the file. The argument n must be an unsigned, nonzero integer, and not a value expression.
If omitted, an allocation of 0 (zero) disk blocks is used.
SUPERSEDE
Indicates that any file with the same file specification as the domain's file
specification should be deleted and replaced with a new file.
MAX
Indicates that DATATRIEVE should create a fixed-length record file for a
domain with a record definition containing an OCCURS ... DEPENDING
clause. The length of a record in the file is the maximum possible size.

KEY = fld-name

~({

]
CHANGE
]
[ DUP
[ NO CHANGE [,J
NO DUP

})~

Indicates that the file is an indexed sequential file and specifies the
field(s) to be used as key field(s). You can specify more than one key field;
the first key you specify is the primary key; all others are alternate keys. If
you specify more than one KEY clause, then the clauses must be separated by a comma (,). If you omit this clause, the file is sequential.

Commands and Statements

5-25

fld-name
Is the name of the field to be used as a key field.

(CHANGE)
(NO CHANGE)
Indicates if the associated key field can be modified. A primary key cannot
be modified. See Tables 5-3 and 5-4 for defaults and allowed
combinations.
(DUP)

(NO DUP)
Indicates if the associated key field can have a duplicate value; that is, if
two or more records can have the same value for this field. See Tables 5-3
and 5-4 for defaults and allowed combinations.
Table 5-3: Default Values for KEY Fields
Default Values
Option

Primary Key

Alternate Key(s)

NO CHANGE

CHANGE

NODUP

DUP

CHANGE
NO CHANGE
DUP
NODUP

Table 5-4: Allowed Combinations for KEY Fields

Combinations
CHANGE

CHANGE

NO CHANGE

Key Type

DUP

NODUP

DUP

NODUP

Primary

Not Allowed

Allowed

Alternate

Allowed

Not Allowed

Allowed

NO CHANGE

Restrictions

1. You must have control access privilege to the domain and execute access
privilege to the record.

5-26

Commands and Statements

2. The domain and record must both be in the current data dictionary before
you issue this command.
3. The domain must be an RMS domain, and not a view.
Results

1. DATATRIEVE prompts with DFN>, indicating it is expecting a defini-

tion. DATATRIEVE continues to prompt with DFN> until you enter a
. semicolon (;) followed by a carriage return or until it detects an error. If a
syntax error occurs while you are entering· the file definition,
DATATRIEVE aborts the DEFINE FILE command and returns control
to the DATATRIEVE command leveL No file is created.
2. DATATRIEVE creates a sequential file or indexed sequential file. The file
specification is the same as the file specification in the domain definition
in the current data dictionary. If the domain definition omits a field in the
file specification, DATATRIEVE uses the following defaults:
Field

Default

dev:

SY: (the system device)

[UFD]

Your default UFD

filename

No default. Must be specified .

.ext

.DAT

;ver

1 or 1 higher than current version number
(non-RSTS/E systems only)

3. The file is either fixed- or variable-length, depending on the record definition referenced in the domain definition, and on whether you include the
MAX clause.
4. Under all operating systems but RSTS/E, if the file specification in the
domain definition includes a version number and you specified the
SUPERSEDE argument, the existing file is deleted and replaced with the
new file. The new file has the same file specification (including version
number) as the deleted file.
RSTS/E does not support multiple versions of the same file. If there is
already a file with the same file specification you must include the
SUPERSEDE argument to define a new file. If you include
the SUPERSEDE clause, DATATRIEVE deletes any file with the same
file specification and replaces it with a new file for the domain.

Commands and Statements

5-27

Examples

1. Define an indexed file for the domain PHONES. Use the field NAME as
the primary key.
DTR) DEFINE FILE FOR PHONES KEY= NAME;

2. Define a sequential file for the domain FAMILIES.
DTR) DEFINE FILE FOR FAMILIES;

3. Define a new indexed file for the domain YACHTS. Use the group field
TYPE as the primary key, and allow duplicate values for this key. This
command replaces the previous data file for YACHTS.
DTR> DEFINE FILE FOR YACHTS SUPERSEDE KEY=TYPE (DUP);

5-28

Commands and Statements

5.9 DEFINE PROCEDURE Command
Function

Enters a procedure in the current data dictionary and creates a password
table for the procedure.
Format

DEFINE PROCEDURE proc-name

END-PROCEDURE
Arguments

proc-name
Is the name of the procedure being defined. It cannot duplicate a
DATATRIEVE keyword or any other name in the current data dictionary.
END-PROCEDURE
Ends the procedure definition.
Restrictions

The procedure cannot contain the following commands:
DEFINE DOMAIN
DEFINE PROCEDURE
DEFINE RECORD
DEFINE TABLE
Results

1. When you issue this command, DATATRIEVE prompts with DFN>, indicating that it is expecting a procedure definition; that is, the commands,
statements, and clauses included in the procedure. DATATRIEVE treats
all your input as input to the procedure and continues to prompt with
DFN> until you end the procedure definition with END-PROCEDURE.

2. DATATRIEVE enters the procedure in the current data dictionary and
creates a password table for the procedure. DATATRIEVE enters a
mC/PPN in the password table with full access privileges (RWMEC). The
actual mC/PPN stored on the password table is installation-dependent.
Refer to Chapter 14 for more information.
3. DATATRIEVE does not store any comments specified within a procedure.

Commands and Statements

5-29

Usage Notes

1. For more information on procedures, see Chapter 13.

2. This command creates a procedure, but does not modify an existing procedure. To modify a procedure once it is stored in the data dictionary, use
the DATATRIEVE editor, explained in Chapter 8. You can also use
the EXTRACT command to copy the procedure definition to an indirect
command file for editing. See Section 5.18 for more information on
EXTRACT.
Examples

1. Define a procedure to procedure to prevent DATATRIEVE prompting you
for missing statement elements, connect you to your private data dictionary, and then display the dictionary to which you are connected.
DTR> DEFINE PROCEDURE SET-UP
DFN> SET NO PROMPT
DFN> SET DICTIONARY MYOWN.DIC
DFN> SHOW DICTIONARY
DFN> END-PROCEDURE
DTR) :SET-UP
The current dictionarY is SY:[202,202JMYOWN.DIC
DTR>

2. Define a procedure to write a report on all yachts with a given builder.
DTR) DEFINE PROCEDURE BUILDER-REPORT
DFN) READY YACHTS
DFN) REPORT YACHTS WITH BUILDER *.BUILDER ON *.DEVICE
DFN> SET REPORT-NAME = "REPORT OF YACHTS BY ONE BUILDER"
DFN> AT TOP OF REPORT PRINT REPORT-HEADER, BUILDER, SKIP2
DFN> PRINT MODEL, LOA, PRICE
DFN> AT BOTTOM OF REPORT PRINT "AVERAGE PRICE", AI.,IERAGE PRICE
DFN) END-REPORT
DFN) END-PROCEDURE
DTR> :BUILDER-REPORT
Enter DEVICE: TI:
Enter BUILDER: AMERICAN
REPORT OF YACHTS BY ONE BUILDER
22-Ma}'-80
Pase 1
AMERICAN
28
28-MS
AI.IERAGE PR I CE
DTR>

5-30

Commands and Statements

$8,885

$18,885
$14,385

3. Define a procedure to simplify looking up phone numbers.
DTR> DEFINE PROCEDURE GET-NUMBER
DFN> READY PHONES
DFN> FOR PHONES WITH NAME CONTAINING *."WHoSE NUMBER DO YOU NEEo?"
DFN> PR I NT NAME (-) t NUMBER (-)
DFN> FINISH PHONES
DFN> END-PROCEDURE
DTR>
DTR>
DTR> :GET-NUMBER
Enter WHOSE NUMBER DO YOU NEED?: HENRY
Schneidert Henry
854-2341
DTR>

Commands and Statements

5-31

5.10 DEFINE RECORD Command
Function

Enters a record definition in the current data dictionary and creates a password table for the record.
Format

DEFINE RECORD record-name USING fld-def-l. fld-def-21. ..
L

Arguments

record -name
Is the name of the record being defined. It cannot duplicate a
DATATRIEVE keyword or any other name in the current data dictionary.
fld-def
Is a field definition. A record definition consists of at least one field definition. Each field definition must be ended with a period (.). (Refer to
Chapter 12 for a full description of record definitions.)
; (semicolon)
Ends the record definition. You must enter the semicolon on a line by
itself.
Restrictions

1. You cannot use a DEFINE RECORD command in a procedure.
2. You cannot invoke a procedure in a record definition.
Results

1. After you issue this command, DATATRIEVE prompts with DFN>, indicating it is expecting a record definition. DATATRIEVE continues to
prompt with DFN> until you end the record definition with a line consisting of only a semicolon or until it detects an error. If a syntax error occurs
\vhile you are entering the record definition, DATATRIEVE returns to
command level without creating a record definition.

2. When you terminate the record definition, DATATRIEVE prints the following message on your terminal, indicating the length (in bytes) of the
new record.
[Record record-naMe is n bytes IonS]

3. DATATRIEVE enters the record definition in the current data dictionary
and creates a password table for the record. DATATRIEVE enters a
UIC/PPN in the password table with full access privileges (RWMEC). The
actual UIC/PPN stored in the password table is installation-dependent.
Refer to Chapter 14 for more information.

5-32

Commands and Statements

Usage Notes

This command creates a record, but does not modify an existing record. To
modify a record once it is stored in the data dictionary, use the
DATATRIEVE editor, explained in Chapter 8. You can also use the
EXTRACT command to copy the record definition to an indirect command
file forediting. See Section 5.18 for more information on EXTRACT.
If you change a record definition, you may not be able to use old data files. If
the new record definition is not the same length, you will have to define a new
data file.
Examples

1. Define the record PHONE-REC.
DTR> DEFINE RECORD PHONE-REC USING
DFN> 01 PHONE.
DFN>
VL NAME PIC X(20).
DFN>
02 NUMBER PIC 8(7) EDIT-~TRING IS XXX-XXXX.
DFN>
02 LOCATION PIC X(8).
DFN>
02 DEPARTMENT PIC xx.
DFN>
[Record PHONE-REC is 38 bytes Ions.]
DTR>

2. Define the recorci fAMILY.
DTR> DEFINE RECORD FAMILY USING
DFN) 01 FAMILY.
DFN> 03 PARENTS.
DFN>
08 FATHER PIC X(10).
DFN>
08 MOTHER PIC X(10).
DFN) 03 NUMBER-KIDS PIC 88 EDIT-STRING IS 28.
DFN> 03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER-KIDS.
DFN>
08 EACH-KID.
DFN>
08 KID-NAME PIC X(10) QUERY-NAME IS KID.
DFN)
08 AGE PIC 88 EDIT-STRING IS 28.
DFN>

Commands and Statements

5-33

5.11 DEFINE TABLE Command
Function

Enters a description table in the current data dictionary and creates a password table for the description table.
Format
DEFINE TABLE table-name
"descriP-l"}
"COde-I"} :
{ descrip-l ,
{ code-l

{ "descr~p-2"}

"COde-2"}:
[ { code-2

[

descnp-2

ELSE

]
,

"descr~p-n"} ]

{ descnp-n
END-TABLE

Arguments

table-name
Is the name of the description table to be defined. It cannot duplicate a
DATATRIEVE keyword or any other name in the current data dictionary.
"code-1 ,,}: {" descri P-1"}
{ code-1
descrip-1
Is a code-and-description pair. You must separate the pair with a colon,
and you must put a comma after each pair but the last. If you include an
ELSE, you must put a comma after the last pair. If the code or description
conforms to the rules for names given in Section 4.4, you do not have to
enclose it in quotation marks. However, DATATRIEVE will convert any
lowercase letters in the code or description to uppercase.
If the code or description does not conform to these rules or if you want to
preserve lowercase letters, you must enclose it in quotation marks and the
rules for character string literals (Section 6.1.1) apply. (That is, the code
or description cannot exceed 250 characters and cannot contain a carriage
return, line feed, or control character.)
.(

ELSE

~ "~escr~p-n" ~

{ descrip-n ;
Is the description to be used if you specify a code that is not defined in the
description table. The rules for specifying this description are the same as
for the description in the code-and-description pairs.
END-TABLE
Terminates the description table definition.

5-34

Commands and Statements

Restrictions

1. You cannot use a DEFINE TABLE command in a procedure.

2. You cannot invoke a procedure in a description table definition.
Results

1. Mter you issue this command, DATATRIEVE prompts with DFN>,
indicating it expects a description table definition; that is, the code-anddescription pairs. DATATRIEVE continues to prompt with DFN> until
you terminate the description table definition with a line consisting of the
keyword END-TABLE.

2. DATATRIEVE enters the description table in the current data dictionary
and creates a password table for the table. DATATRIEVE enters a
UIC/PPN in the password table with full access privilege (RWMEC). The
actual UIC/PPN stored in the password table is installation-dependent.
Refer to Chapter 14 for more information.
Usage Notes

1. For more information on description tables; see Chapter 13.

2. This command creates a description table but does not modify an existing
table. To modify a description table once it is stored in the data dictionary, use the DATATRIEVE editor, explained in Chapter 8. Or, you can
use the EXTRACT command to copy the description table definition to
an indirect command file for editing. See Section 5.18 for more information on EXTRACT.
Examples

1. Define a table of department codes.
DTR> DEFINE TABLE DEPT-TABLE
DFN> IICEII:IICommercial Engineering
DFN> IIPEII: IIPlant Engineering
DFN> IICS II : IICustofTler Support
DFN> IIRD II : IIResearch and DelJeloPfrlent
DFN> IISD II : IISal es DepartfTlent
DFN> ELSE IIUNKNOWN DEPARTMENT II
DFN> END-TABLE
DTR>
ll

2. Define a table with a description of each possible rig.
DTR) DEFINE TABLE RIG-TABLE
DFN> IISLOOplI: IIONE MAST II ,
DFN) IIKETCH II : IITWO MASTS, BIG ONE IN FRONT II t
DFN) IIYAWL": IISIMILAR TO KETCH II ,
DFN) IIMS": "SAILS AND A BIG MOTOR II ,
DFN> ELSE "SOMETHING ELSE II
DFN) END-TABLE
DTR)

Commands and Statements

5-35

5.12 DEFINEP Command
Function

Adds an entry to the password table for a domain, record, procedure, or
description table.
Format

DEFINEP

domain-name
record -name
paSSWdl]
proc-name
[ (*)
table-name

PW, new-passwd
seq-no,

,priv
VIC, [m,n]

Arguments

domain-name
record-name
proc-name
table-name
Is the name of the domain, record, procedure, or description table whose
password table you want to modify.
(passwd)
(*)

Is an asterisk enclosed in parentheses (*) or the password necessary to gain
C (control) access to the dictionary object. If you specify a password, you
must enclose it in parentheses. If you specify (*), DATATRIEVE prompts
for the password, but does not print your response on the terminal. If you
omit this argument, DATATRIEVE uses your log-in UIC/pPN to verify
that you have C (control) access privilege.
seq-no
Is the sequence number of the entry to be added to the password table.
This argument must be an unsigned integer and must be followed by a
comma (,).
PW, new-password

mc, [m,n]

Specifies the lock type and key for the entry. If the lock type is PW,
specify a one- to ten-character password. If it is mc, specify a UIC/PPN,
enclosed in square brackets. You must put a comma after the lock type
and another comma after the key.
priv
Is a letter or string of letters indicating the type of access privilege to be
granted. You can also use a space enclosed in quotation marks to indicate
that the user is not granted any access privileges.

5-36

Commands and Statements

Letter

Privilege

Read

Execute or Extend

Modify

Write

Control
No privilege

You can specify more than one privilege by including a string of letters
(such as RW for read and write access).
Restrictions

You must have control access privilege to the dictionary object.
Results

DATATRIEVE creates an entry in the password table. Depending on the
sequence number you supply, DATATRIEVE may change the sequence number of other entries in the password table.
• If the sequence number already exists in the password table, DATATRIEVE
adds the entry immediately before the existing entry with the same number.
DATATRIEVE then increments the sequence number of all entries after the
new entry by one.
• If the sequence number you supply is greater than the last sequence number
plus one, DATATRIEVE ignores your sequence number and adds the entry
to the end of the table. Its sequence number becomes the next sequential
number in the table.
Usage Notes

1. To avoid errors when making an addition, print a copy of the current
password table with the SHOWP command before issuing the DEFINEP
command. See Section 5.34 for a description of the SHOWP command.
Because of the way DATATRIEVE processes sequence numbers, a new
entry can affect the numbering of other table entries.

2. For more information on password tables see Chapter 14.

Commands and Statements

5-37

Examples

1. Add an entry to the password table of PHONES show that everyone can

show the domain definition. Look at the password table to see that the
new entry is there.
OTR> SHOWP PHONES
1 ,UlC, [202 ,*J, IIRWMEC II
OTR) OEFlNEP PHONES 2 ,UlC ,[* ,*J ,IIR II

OTR) SHOWP PHONES

1 ,UlC, [202 ,*J, IIRWMEC II
2,UlC, [*,*,J IIRII

OTR>

2. Add an entry to the password table of PHONES to prohibit UIC/PPN
[204,202] from accessing PHONES.
OTR> OEFlNEP PHONES 1 ,UlC,[204,202J,1I
OTR> SHOWP PHONES
l,UlC, [204,202J, II"
2,UlC, [202,*J, IIRWMEC II
3 ,UlC, [* ,*J, IIRII
OTR)

5-38

Commands and Statements

5.13 DELETE Command
Function

Deletes the definition of a domain, procedure, record, or description table
(and its associated password table) from. the current data dictionary.
Format

DELETE

domain -name
record-name
proc-name
table-name

[

(paSSWd~;
(*)

Arguments

domain-name
record-name
proc-name
table-name
Is the naine of the domain, record, procedure, or description table to be
deleted.
(passwd)
(*)

Is an asterisk enclosed in parentheses (*) or the password necessary to gain
C (control) access to the dictionary object. If you specify a password, you
must enclose it in parentheses. If you specify (*), DATATRIEVE prompts
for the password, but does not print your response on the terminal. If you
omit this argument, DATATRIEVE uses your log-in UIC/PPN to verify
that you have C (control) access privilege.
; (semicolon)
Ends the DELETE command.
Restrictions

1. You must have C (control) access privilege to the domain, record, procedure, or description table.

2. The object must be defined in the current data dictionary.

Commands and Statements

5-39

Results

DATATRIEVE deletes only the definition of a domain or record from the
current data dictionary. The data or records in the corresponding file are not
affected by this command. If you specify a procedure or description table
name in the DELETE command, DATATRIEVE deletes the procedure or
table from the data dictionary. DATATRIEVE also deletes the password table
associated with the dictionary object from the data dictionary.
Examples

1. Delete the domain PHONES and the record PHONE-REC.
DTR) DELETE PHONES;
DTR) DELETE PHONE-REC;
DTR)

2. Delete the table RIG-TABLE.
DTR) DELETE RIG-TABLE;
DTR>

5-40

Commands and Statements

5.14 DELETEP Command
j

Function

Deletes an entry from a password table associated with a domain, record,
procedure, or description table, defined in the current data dictionary.
Format

DELETEP

domain -name
record -name
proc-name
table-name

rpaSSWd~
~') J

seq-no

Arguments

domain -name
record-name
proc-name
table-name
Is the name of the domain, record, procedure, or description table whose
password table is to be modified.
(passwd)
(*)

Is an asterisk enclosed in parentheses (*) or the password necessary to gain
C (control) access to the dictionary object. If you specify a password, you
must enclose it in parentheses. If you specify (*), DATATRIEVE prompts
for the password, but does not print your response on the terminal. If you
omit this argument, DATATRIEVE uses your log-in UIC/PPN to verify
that you have C (control) access privilege.
seq-no
Is the sequence number of the entry to be deleted. This argument must be
an unsigned integer.
Restrictions

1. You must have C (control) access privilege to the domain, record, procedure, or description table.

2. You can delete only one password table entry each time you issue
DELETEP. To delete more than one entry, you must issue multiple
DELETEP commands.
3. There must be an entry with the sequence number you specify.
4. If there is only one entry in the password table, you cannot delete that
entry.

Commands and Statements

5-41

Results

DATATRIEVE deletes the password table entry, as long as there is at least
one other entry in the table.
Usage Notes

1. For more information on password tables, see Chapter 14.
2. To ensure that you delete the correct entry, print a- copy of the password
table using the SHOWP command (Section 5.33) before issuing
DELETEP.
3. DATATRIEVE renumbers the remaInIng entries so that the sequence
numbers begin at one and increase in steps of one.
4. If only one entry has C (control) access, be careful not to delete it.
Examples

1. Look at the password table for PHONES, and delete the first entry.
DTR) SHOWP PHONES
l,UIC,
2 ,UIC,
3 ,UIC,

[20Ll,202],
[202,*], "RWMEC"
[* ,*] "R"

OTR) OELETEP PHONES 1
OTR) SHOWP PHONES
1 ,UIC,
2,UIC,

[202,*], IIRWMEC"
[*,*] "R"

2. Delete the entry which allows everyone R (read) access to PHONES.
OTR) OELETEP PHONES 2
OTR) SHOWP PHONES
1 tUIC,

[202 t*],

"RWMEC"

OTR>

3. Attempt to delete the last entry in the password table.
OTR> SHOWP PHONES
1 tUIC,

[202,*],

"RWMEC"

OTR) OELETEP PHONES 1
Attempt to delete last priuileSe entrY

OTR> SHOWP PHONES
1 ,UIC,

[202,*],

OTR)

5-42

Commands and Statements

"RWMEC"

5.15 EDIT Command
Function

Invokes the DATATRIEVE editor to edit a procedure or description table
defined in the current data dictionary.
Format

EDIT

domain-name
paSSWdJ
[ADVANCED]
record -name
(*)
proc-name
[
table-name

Arguments

domain-name
record -name
proc-name
table-name
Is the name of the domain, record, procedure, or description table to be
edited.
(passwd)
(*)

Is an asterisk enclosed in parentheses (*) or the password necessary to gain
C (control) access to the dictionary object. If you specify a password, you
must enclose it in parentheses. If you specify (*), DATATRIEVE prompts
for the password, but does not print your response on the terminal. If you
omit this argument, DATATRIEVE uses your log-in UIC/pPN to verify
that you have C (control) access privilege.
ADVANCED
Must be included in the EDIT command if you are editing a domain or
record definition.
Restrictions

You must have C (control) access privilege to the dictionary object.
Results

DATATRIEVE invokes its editor, which prompts for an editor command with
QED>. To terminate the editor, type EXIT (or CTRL/Z), which updates the
dictionary object, or QUIT, which leaves the dictionary object unchanged.

Commands and Statements

5-43

Usage Notes

1. Refer to Chapter 8 for a complete description of the DATATRIEVE editor.

2. Be when careful editing record definitions. You may not be able to ready
the associated domain without defining a new file.
3. The DATATRIEVE editor does not check syntax. If you make syntax
errors, you can end up with invalid definitions.
Examples

1. Edit the table DEPT-TABLE.
DTR> EDIT DEPT-TABLE
QED>

2. Edit the record PHONE-REC.
DTR> EDIT PHDNE-REC ADVANCED
QED)

5-44

Commands and Statements

5.16 ERASE Statement
Function

Deletes one or more records from a data file.
Format

ERASE [ALL [OF rsel]
Arguments

ALL
Causes DATATRIEVE to delete every record in the current collection.
ALL OF rse
Causes DATATRIEVE to delete every record identified by the record
selection expression.
Restrictions

1. The domain containing the record must be readied for WRITE access.
(See the READY command, Section 5.26.)

2. The domain containing the record must use an indexed file. You cannot
delete a record from a domain that uses a sequential file. You cannot
delete a record from a view.
Results

1. If you use the argument ALL OF rse, each record in the record stream is
deleted from the data file.

2. If you use the argument ALL, each record in the current collection is
deleted from the data file.
3. If you nest the ERASE statement in a FOR statement and do not supply
an argument, DATATRIEVE deletes each record specified by the FOR
statement from the data file.
4. If you do not nest the ERASE statement in a FOR statement and do not
supply an argument, DATATRIEVE deletes the selected record from the
data file. If there is no selected record DATATRIEVE issues an error
message.

Commands and Statements

5-45

Usage Notes

Before deleting a record with this command, you can check the current collection and selected record with the SHOW CURRENT command (Section 5.32)
or the PRINT statement (Section 5.25).
Examples

1. Erase all the yachts built by Albin.
DTR> FIND YACHTS WITH BUILDER EQ IIALBINII
[3 records found]

DTR> ERASE ALL

2. Define a procedure to erase selected yachts.
DTR> DEFINE PROCEDURE SELL-BOAT
DFN> FIND YACHTS WITH BUILDER EQ *.BUILDER AND
DFN> MODEL EQ *.MODEL
DFN> PRINT ALL
DFN> IF *.IISELL?II EQ 11'1'11 THEN ERASE ALL
DFN> END-PROCEDURE
DTR>

5-46

Commands and Statements

5 . 17 EXIT (CTRL/Z) Command
Function

Terminates a DATATRIEVE session.
Format

EXIT
{

}

CTRL/Z

Arguments

None.
Restrictions

None.
Results

EXIT stops a DATATRIEVE session and returns control to the operating
system. DATATRIEVE automatically releases all readied domains and all
established collections.
CTRL/Z acts as an EXIT command and stops a DATATRIEVE session if you
enter it in response to the following prompts: DTR> , DFN>, and RW>.
CTRL/Z does not stop a DATATRIEVE session if you are in ADT or the
DATATRIEVE editor. CRTL/Z does not stop a session if you enter it when
DATATRIEVE prompts you to enter a value.
Example

End a DATATRIEVE session.
OTR> EXIT

Commands and Statements

5-47

5.18 EXTRACT Command
Function

Copies a domain, record, procedure, or description table definition from the
current data dictionary to an indirect command file.
Format

( domain-name) [
EXTRACT ON file-spec

1~:::~~~::e ! I:~~SSWd)J [, ...
table-name ) L

Arguments

file-spec
Is the file specification of the file to contain the definition(s), in the following format:
dev: [UFD]filename.ext;ver
You must specify at least a file name. All other fields are optional. If you
omit a field in the file specification, DATATRIEVE uses the following
defaults.
Field

Default

dev:

SY: (the system device)

[UFDJ

Your default UFD

filename

No default. Must be specified .

.ext

. CMD

;ver

1 or 1 higher than current version number
(non-RSTS/E systems only)

domain-name
record-name
proc-name
table-name
Is the name of the domain, record, procedure, or description table whose
definition is to be copied. If you specify more than one name, separate the
names with a comma.
Restrictions

You must have read access privilege to the domain, record, procedure, or
description table,
Results

1. DATATRIEVE creates a file with the file specification you enter. For each
dictionary object you name, DATATRIEVE writes a DELETE command
and a DEFINE command into the file. The DEFINE command contains a
copy of the definition in the current data dictionary.

5-48

Commands and Statements

2. DATATRIEVE does not delete the definition(s) from the data dictionary

.····wneii-yotr·e~tecute--t1ris·cofiffilaiI(t·
3. When you invoke the file as an indirect command file, DATATRIEVE
deletes the definitions from the dictionary and replaces them with the
definitions in the file.
Usage Notes

1. EXTRACT allows you to modify or restructure a data dictionary entry
without affecting the data dictionary itself. You can first copy definitions
to be modified, edit the definitions in the indirect command file using
your operating system's editor, then invoke the command file to replace
the old definitions.
2. EXTRACT is also useful for creating a backup copy of data dictionary
entries and copying definitions to another data dictionary.
3. To invoke the indirect command file, type the following at the
nATAT~T"R.V1?
" .........

~""'.L"'&'''&'..&.'',,&,~

N\nHY'lOnrl

'-'''-J ...... .&.&..L.&''''''.I..I.'-'I.

1£1"'£11·
.I.'"""''''' ....

DTR> @file-spec

4. The EXTRACT command does not copy the password table of a dictionary object. Mter you invoke the indirect command file, the password table
will have only one entry. To change this password table, use the
DEFINEP and DELETEP commands.
Examples

1. Extract the definitions of the domain YACHTS and the record YACHT so

that you can copy them into your private data dictionary.
DTR> EXTRACT ON YACHTS.CMD YACHTSt YACHT
DTR>

2. Copy all the definitions for the company phone directory to keep as a
backup.
DTR> EXTRACT·ON PHONE.CMD PHONESt PHONE-RECt DEPT-TABLEt

~TORE-PHONE

Commands and Statements

5-49

5.19 FIND Statement
Function

Establishes a collection of records from a domain, view, collection, or list. The
collection established with FIND becomes the current collection, replacing
any existing current collection.
Format
FIND rse

Arguments

rse
Is a record selection expression (RSE) specifying the records to be included in the collection.
Restrictions

1. The domain containing the records to be selected must be readied for
READ, WRITE, or MODIFY access, but not EXTEND access. (See the
READY command, Section 5.27.)

2. You cannot use a FIND and SELECT statement in the same compound
statement.
3. You cannot use a FIND statement in a BEGIN-END block or a FOR
statement.
Results

1. DAT ATRIEVE establishes a current collection. If you specify a context
variable in the RSE, the collection has two names: CURRENT and the
context variable.

2. DATATRIEVE displays the following message on your terminal, indicating the number of records in the collection:
Cn records found]

If the FIND statement is inside a procedure, DATATRIEVE does not
display the number of records found unless the FIND statement is the last
statement of the procedure.

3. DATATRIEVE collects the records in the order in which they are found.
Do not assume that there is any order to the collection unless you include
the SORTED BY clause in the record selection expression, or unless the
domain uses an indexed file.
4. There is no selected record in the collection. To select a record, use the
SELECT statement.

5-50

Commands and Statements

Examples

1. Form a collection of yachts longer than 30 feet. Give the collection the
name BIG-ONES.
DTR) FIND BIG-ONES IN YACHTS WITH LOA GT 30
[57 records

f~und]

DTR)

2. Form a collection of the ten most expensive yachts.
DTR) FIND FIRST 10 YACHTS SORTED BY DESC PRICE
[10 records found]
DTR>

Commands and Statements

5-51

5.20 FINISH Command
Function

Relinquishes control of a domain and releases any collections associated with
that domain.
Format
FINISH domain-name-l [,domain-name-2 ... J

Arguments

domain-name
Is the name of a readied domain to be released. If omitted, DATATRIEVE
ends your control of all readied domains. If more than one domain name is
specified, they must be separated by a comma (,).
Restrictions

None.
Results

D-ATATRIEVE ends your control of the domain(s) and any collections you
established with the domain(s) during this session.
Usage Notes

1. The FINISH command frees resources used by readied domains.

2. Readying a domain affects how other users can access it. Finishing a
domain releases this control. If you ready a domain for exclusive use, no
one else can ready that domain until you finish it.
3. It is not necessary to issue a FINISH command before an EXIT command.
EXIT automatically releases all readied domains and collections.
Examples

1. Release control of the domain YACHTS.
DTR> FINISH YACHTS

2. Free more workspace by finishing all readied domains. Then ready
YAeHTS so that you can work with it.
OTR> FINISH
DTR) SHOW READY
No

read}'

dOlrlains

DTR) READY YACHTS
DTR>

5-52

Commands and Statements

5.21 FOR Statement
Function

Executes a statement or group of statements once for each record in a group of
records.
Format
FOR rse statement

Arguments

rse
Is a record selection expression (RSE) specifying the records that the
statement(s) are to act on.
statement
Is a simple or compound statement (except a FIND or SELECT) to be
applied to the records specified by the record selection expression.
Restrictions

L The domain associated with the record selection expression must be readied for READ, WRITE, or MODIFY access.
2. A FOR statement cannot include a FIND or SELECT statement.
Results

For each record specified in the record selection expression, DATATRIEVE
executes the statement once, using that record as the context record for the
statement. If the statement is a BEGIN-END block, DATATRIEVE executes
the statements of the BEGIN-END block in order for each record specified.

Commands and Statements

5-53

Examples

1. Increase the age of each child in each record of the domain FAMILIES by

one year.
DTR) PRINT FIRST 1 FAMILIES
FATHER
JIM

MOTHER
ANN

NUMBER
KIDS

KID
NAME

AGE

URSULA
RALPH

7
3

DTR> FOR FAMILIES FOR KIDS MODIFY USING AGE
DTR> PRINT FIRST 1 FAMILIES
FATHER
JIM

MOTHER
ANN

NUMBER
KIDS

KID
NAME

URSULA
RALPH

AGE +

AGE
8

2. Assign a value to the field PRICE for all yachts that do not have a value in
this field.
DTR> FIND YACHTS WITH PRICE = 0
[83 records found]

DTR> FOR CURRENT MODIFY USING PRICE

5-54

Commands and Statements

DISP * 1.3

5000

5.22 HELP Command
Function

Provides on-line assistance in the use of DATATRIEVE commands, state- .
ments, and language elements.
Format
HELP [[ADVANCED] [topic] ... ] ...

Arguments

ADVANCED
Provides additional information about the specified topic.
topic
Is a DATATRIEVE command, statement, or statement element. Use commas to separate topics.

NOTE
If no topic is specified, DATATRIEVE displays information on
the type of help available and how to get it.
Restrictions

None.
Results

1. DATATRIEVE displays the requested help on your terminal.

2. If you specify HELP ADVANCED, DATATRIEVE displays the advanced
help message for each topic listed.
Examples

1. Ask for a list of the help that is available.
DTR> HELP HELP

2. Ask for help in using the FIND command.
DTR> HELP FIND

3. Ask for the advanced help message for the PRINT statement.
DTR> HELP ADVANCED PRINT

Commands and Statements

5-55

5.23 IF-THEN-ELSE Statement
Function

Executes statements conditionally.
Format
IF bool-exp [THEN] statement-l [ELSE statement-2]

Arguments

bool-exp
Is a Boolean expression.
statement-l
Is a simple or compound statement to be executed if bool-exp evaluates to
"True."
ELSE statement-2
Specifies that statement-2 is to be executed if bool-exp evaluates to
"False."
Restrictions

None.
Results

DATATRIEVE executes statement-l if the Boolean expression is "True". If
you specify ELSE statement-2 and the Boolean expression is "False"
DATATRIEVE executes statement-2.
Example
Print each yacht built by Pearsont and modify the price if you want to.

DTR> FOR YACHTS WITH BUILDER EQ "PEARSON"
[Look ins for statement]

DTR> BEGIN
[Look ins for statement]

DTR> PRINT
[Loor,lnE for- stateiTient or "end"]

DTR> IF *."CHANGE EQ
[Loo~,ins

'1'''

EQ "'I''' MODIFY PRICE ELSE PRINT "NOT CHANGED"

for statelTlen.t or "end"]

DTR> END

MANUFACTURER
PEARSON

MODEL

RIG

10M

SLOOP

Enter CHANGE EQ Y:

5-56

Commands and Statements

LENGTH
OI)ER
ALL
WEIGHT BEAM
33

12t441

PRICE
$21 d 73

5.24 MODIFY Statement
-

.,/

Function

Changes the value of all fields or selected fields in any or all records in a
collection.
Format

USING statement-l
MODIFY [ALL]

[VERIFY [USING] statement-2] [OF rse]

[ fld-name-l [,fld-name-2 ... ]
Arguments

ALL
Specifies that all records in the current collection are to be modified.
USING statement-l
Specifies a statement to be used to modify the field values in the record(s).
Typically, statement-l is an assignment statement or a BEGIN-END
block containing a series of assignment statements.
fld-name
Specifies the name of the field to be modified. Use commas to separate
field names. DATATRIEVE prompts for the value of each field you specify. VERIFY [USING] statement-2 causes DATATRIEVE to execute
statement-2 before modifying the record. If DATATRIEVE executes an
ABORT statement in statement-2, then the record is not changed. Typically, statement-2 contains an IF-THEN-ELSE statement and an
ABORT statement. The keyword USING is optional and is included only
for similarity to English language syntax.
OF rse
Is a record selection expression identifying the records to be modified.
Restrictions

1. The domain containing the records to be modified must be readied for
WRITE or MODIFY access. (See the READY command, Section 5.26.)

2. In an RMS indexed sequential file, you cannot modify a primary key or
any alternate key with the NO CHANGE option.
3. You cannot modify a COMPUTED BY field.
Results

The results of this command are highly dependent on the arguments you
specify.

Commands and Statements

5-57

1. If you include a list of field names, DATATRIEVE prompts for each
elementary field contained in them. If you do not include a list of field

names or a USING clause, DATATRIEVE prompts for each elementary
field in the record. DATATRIEVE prompts for field values with the following message:
ENTER fld-naITle:

2. If you specify a USING clause, DATATRl~V~ uses statement-l to modify the field values and does not prompt for any field values.
3. If you specify the argument ALL, DATATRIEVE modifies each record in
the current collection similarly .. Unless you specify the USING clause,
DATATRIEVE prompts for field values only once and uses the same field
value in modifying each record. If you specify the USING clause, you can
make similar changes in each record without storing identical field values
in each record. (See Example 1.)
4. If you specify a record selection expression, DATATRIEVE modifies each
record in the record stream similarly. Unless you specify the USING
clause, DATATRIEVE prompts for field values only once and uses the
same field value in modifying each record. If you specify the USING
clause, you can make similar changes in each record without storing identical field values in each record. (See Example 2.)
5. If you nest MODIFY within a FOR statement, DATATRIEVE modifies
the context record resulting from the FOR statement. When you want
DATATRIEVE to prompt for field values for each record that it modifies,
nest the MODIFY statement within a FOR statement.
6. If you do not nest the MODIFY statement within a FOR statement, and
you do not specify the argument ALL or OF rse, DATATRIEVE modifies
the selected record. If there is no selected record, DATATRIEVE issues an
error message.
7. If you specify a VERIFY clause, DATATRIEVE executes statement-2
before changing the record. If statement-2 contains an ABORT statement
and the abort conditions are met, DATATRIEVE aborts the MODIFY
statement without changing the record. If the MODIFY statement is in a
prOCedure or command file and SET :NO ABORT is in effect,
DATATRIEVE executes the next statement. If SET ABORT is in effect,
DATATRIEVE returns to command level without executing the rest of the
procedure or command file.

5-58

Commands and Statements

Usage Notes

1. If you specify the USING statement-l clause, statement-l will generally
be an assignment statement or a BEGIN-END block containing assignment statements. The formats of the assignment statement are:
fld-name =

val-exp

group-fld-name-l = group-fld-name-2
You should review the description of the assignment statement for elementary fields (Section 5.3.1) or group fields (Section 5.3.2) before using
this format of the MODIFY statement.
If you put a BEGIN-END block in the USING clause, you can include

statements other than assignment statements. To see what you are modifying, include a PRINT statement in the BEGIN-END block. Section 5.4
describes the BEGIN-END block.

2. If DATATRIEVE prompts for a field value, you can perform any of the
following functions in response to the prompt.

• Leave the value unchanged by entering a tab character followed by a
carriage return.
• Change the value of the field by typing a new value, followed by a
carriage return. The new value should conform to the data description
for the field, as defined in the record definition.
• Change the value to blank (or 0 if the field is numeric) by entering a
space followed by a carriage return.
• Terminate the prompting cycle by entering a CTRL/Z. In this case, the
record being modified is unchanged, but previously modified records are
changed. CTRL/Z has the same effect as an ABORT statement in this
case.
If you enter just a carriage return in response to a prompt, DATATRIEVE

reprompts for the field value.
3. The MODIFY statement can be very dangerous if you make a mistake. If
DATATRIEVE prompts you for an unexpected field, enter CTRL/Z to
prevent changing records that you do not wish to change. It is safest to
print each record before you modify it.

Commands and Statements

5-59

Examples

1. Form a collection of yachts with a specific builder, and increase the price
of each yacht in the collection.
DrR> FIND YACHTS WITH BUILDER EQ "GRAMPIAN"
[5 records found]

DTR> PRINT ALL PRICE
PRICE
$28t875
$11t485
$14t475
$17t775
$28t875

DTR> MODIFY ALL USING PRICE
DTR> PRINT ALL PRICE

PRICE + 700

PRICE
$30t375
$12 ti85
$15ti75
$18t475
$30t375

DTR>

2. Form a collection of yachts. Modify all the elementary fields within the

group field SPECIFICATIONS for the first record.
DTR> FIND YACHTS
[113 records found]

DTR> SELECT 1
DTR> MODIFY SPECS
Enter RIG:

5-60

Commands and Statements

5.25 PRINT Statement
Function

Provides output of one or more field values in a record or a group of records.
Format

[ALL] [printlist]
PRINT

[ [printlist OF] rse

dev:
file-spec
*.prompt-name

Arguments

ALL
Specifies that the records in the current collection are to be used in the
output.
print-list
Is a list of value expressions and formatting information. Print-list elements are described in Table 5-5. Use connnas to separate print-list
elements. If you sPecify a print-list and a record Selection expression, you
must separate them with the keyword OF.
rse
Is a record selection expression that specifies the records to be used in the
output.
file-spec
*.prom pt-name
Is a prompting value expression or the name of the file-spec file or device
to which DATATRIEVE sends the output. By specifying a device name in
the PRINT command, you can tell DATATRIEVE to send the output to
any system device to which you have access, such as a line printer, a tape
drive, or your terminal. On RSTS/E systems, if you specify the line printer
for output and it is busy, nothing will be printed. To send your output to a
tape drive, you must mount your tape and assign the tape drive to your
process before specifying the tape drive in the PRINT command. If you
specify a file, the file specification must be in the following format:
dev: [UFD]filename.ext;ver
You must specify at least a file name. All other fields are optional. If you
omit a field in the file specification, DATATRIEVE uses the following
defaults.

Commands and Statements

5-61

Field

Default

dev:

SY: (the system device)

[UFDl

Your default UFD

filename

No default. Must be specified.

.ext

.LST

;ver

1 or 1 higher than current version number
(non-RSTS/E systems only)

If you

specify a prompting value expression (* .prompt-name),
DATATRIEVE will prompt for the output file or device when this command is executed. If you omit this argument, the output is printed on your
terminal.

Restrictions

The domain must be readied for READ, WRITE, or MODIFY access. You
cannot use a PRINT statement if the domain is readied for EXTEND access.
(See the READY command, Section 5.26.)
Results

DATATRIEVE writes the specified data on the file or device which you specify. The format and content of the output depends on the optional arguments
you choose.
1. If you include a record selection expression, DATATRIEVE prints data
from each record in the record stream.

2. If you specify the argument ALL, DATATRIEVE prints data from each
record in the current collection.
3. If you nest PRINT within a FOR statement, DATATRIEVE prints data
from the context record resulting from the FOR statement.
4. If you do not nest the PRINT statement inside a" FOR statement and do
not include a record selection expression or the argument ALL,
DATATRIEVE prints data from the selected record. If there is no selected
record and you do not include any arguments, DATATRIEVE prints the
current collection.

5-62

Commands and Statements

5. .r4.epript-U~tal"gl,1PJe.Il,t . Jl.llows_ YQU .to . specify the.JQUQwiuK kinds . QL .
information:
• The data to be included in the output. Data can be the contents of a
field, the value of a variable, or any other value expression.
• The format of the data in the output. You can specify an edit string to
override any edit string in the field or variable definition or to format a
value expression.
• The spacing (both horizontal and vertical) for the output. You can insert
tabs or spaces between columns or skip lines between lines of output.
• Column headers for each column of data in the output. You can also
indicate that no header is to be printed above a column.

If you omit the print-list argument, DATATRIEVE automatically formats

the output for you. DATATRIEVE uses the following defaults when you
omit the print list.
• The data included in the output is the contents of all fields in the
records.
• The format of the field contents is determined by the record
definition.
• The horizontal spacing is based on the length of the header and the field
contents. The output begins in column 1. The output is single-spaced
with a single blank line following the header line.
• Column headers for fields are the query headers, or the field names if
there is no query header. If the field name contains a hyphen,
DATATRIEVE ignores the hyphen and places each part of the field
name on a separate line. The header is centered above the column of
data. If the query header contains only a hyphen, DATATRIEVE does
not print any header.

Commands and Statements

5-63

Examples

1. Write to a file the builder and length over all of each yacht.
DTR> PRINT BUILDERJ LOA OF YACHTS ON REPORT.LST
DTR>

2. Display the yachts that are 30 or 31 feet long on your terminal.
DTR> FIND YACHTS WITH LOA BETWEEN 31 AND j3
[Za records found]
DTR> PRINT ALL BUILDERJ RIG VIA RIG-TABLE (-) USING X(30)
MANUFACTURER
BAYFIELD
BOMBAY
BUCCANEER
CC
CAL
CHALLENGER
COLUMBIA
DOUGLAS
DOWN EAST
ENDEAI.IOUR
FJORD
GRAMPIAN
MARIEHOLD
METALMAST
MOODY
NICHOLSON
O'DAY
ONTARIO
PEARSON
RANGER
RHODES
RYDER
WESTSAIL
WRIGHT

ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
SOMETHING ELSE
TWO MASTSt BIG ONE IN FRONT
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST
ONE MAST

DTR> RELEASE DEPT-TABLE

5-64

Commands and Statements

Table 5-5: Print-List Elements

Element

Function

fld-name [modifier]

Specifies the name of the field whose contents are to be output.
The optional modifier (see Table 5-6) describes the format of
the output and/or column header for the field. If the field name
is the name of a group field, DATATRIEVE prints all fields
subordinate to the group field. If you omit this element, all
fields are output.

val-exp [modifier]

Specifies a value expression to be evaluated and output. The
optional modifier (see Table 5-6) describes the format of the
output and/or column header for the value expression.

SPACE [n]

Inserts n horizontal spaces before the next entry in the print list.
If you omit n, DATATRIEVE inserts one space before the next
entry.

I TAB In]
I

Inserts n tab characters before the next entry in the print list.
(Tabs are set at every 8 spaces.) If you omit n, DATATRIEVE
inserts one tab before the next entry.

COLn

Advances across the line to column n before outputting the next
entry in the print list. If n is less than the current column
number, DATATRIEVE skips a line.

SKIP [n]

Skips n blank lines to start a new line before outputting the next
entry. If you omit n, DATATRIEVE skips one line. If you omit
this element, DATATRIEVE outputs entries on consecutive
lines. All output begins at column 1 unless another print-list
element modifies the position.

NEW-PAGE

Begins a new print page, without column headers. Printing
starts at column 1 unless another print-list element modifies the
position.

ALL [print-list OF] rse

Nests a print list within a print list. If you omit the print-list OF
argument, all records specified by the RSE are printed.

Commands and Statements

5-65

Table 5-6: Print-List Modifiers
("header-I" [/"header-2"1 ... )

(-)
Indicates the column header to be printed above the immediately preceding field name or
value expres,sion. You must place this modifier before the USING edit-string modifier.
This modifier must be enclosed in parentheses. If you specify a character string literal
("header"), the character string is printed above the column. If you specify more thall,:pne
character string literal ("header-l"\"header-2", etc.), the literals are printed on successive lines, centered above the column of data.
If you specify a hyphen (-), no header is printed above the column of data. If you specify a
hyphen for a group field, no column headers are printed for any fields contained in the
group field.
If you omit this modifier, DATATRIEVE uses either the query header or the field name
as the column header for a field. The column header for value expressions formed with
statistical functions (MAX, MIN, AVERAGE, and TOTAL) and a field name (such as
MAX PRICE) is the field name (such as PRICE). For all other value expressions,
DATATRIEVE does not use a column header.

USING edit-string
Imposes the characteristics of the specified edit string on the immediately preceding field
or value expression. The edit string must conform to the rules for edit strings in the
EDIT-STRING clause of a record definition. (See Section 11.8.) This modifier has no
effect if you use it with a group field.
If you omit this modifier for a field, DATATRIEVE uses the edit string specified for the
field in the record definition or the PICTURE (or PIC) clause if no edit string is given.

5-66

Commands and Statements

5.26 READY Command
Function

Readies a domain for use.
Format
(paSSWd)]

READY domain-name
[

(*)

~SHARED l~~~FY]
]
PROTECTED
EXCLUSIVE

WRITE
EXTEND.

Arguments

domain-name
Is the name of a domain in the current data dictionary to be readied for
use.
(passwd)
(*)

Is the password required to access the domain or an asterisk enclosed in
parentheses (*). If you specify a password, you must enclose it in
parentheses. If you specify (*), DATATRIEVE prompts for the password
but does not print it on the terminaL If you omit this argument,
DATATRIEVE uses your log-in UIC/pPN to verify that you have appropriate access privilege.
SHARED
PROTECTED
EXCLUSIVE
Indicates how you allow other users to access this domain. (See Table 5- 7
for an explanation of allow types.) If you omit this argument, your access
is Protected, and other users can read, but not write or modify, records in
the domain.
READ
MODIFY
WRITE
EXTEND
Is the access mode, indicating the type of access you require. (See Table
5-8 for access modes and the access privilege required for each mode.) If
you omit this argument, your access mode is READ and you can retrieve
records, but you cannot modify or store them.
Restrictions

1. You must have E (execute) privilege to the associated record definition.

2. You must have an access privilege to the domain that permits the access
mode you specify. See Table 5-8 for a list of privileges you must have for
each access mode.
3. You can ready only one domain each time you issue the READY command. However, you can ready more than one domain in a session by
issuing multiple READY commands.
Commands and Statements

5-67

4. You must have operating-system-Ievel access to the data file.
5. If another user has readied the domain for exclusive use, you cannot ready
the domain. If another user has readied the domain for protected use then
you can ready the domain for READ access only.
6. The file specified in the domain definition must exist.
Results
1. DATATRIEVE readies the specified domain. DATATRIEVE uses the file

specification in the domain definition. If the domain definition omits a
field in the file specification, DATATRIEVE uses the following defaults:
Default

Field

dev:

SY: (the system device)

[UFDl

Your default UFD

filename

No default. Must be specified.

.ext

.DAT

;ver

Highest version number
(non-RSTS/E'systems only)

2. If you issue more than one READY command for a domain without an

intervening FINISH command, DATATRIEVE preserves your collections.

Table 5-7: Domain Allow Types

Allow Type

Meaning

SHARED

Any other user can have concurrent access to the records in this domain,
for any purpose.

PROTECTED

Any other user can read, but not write or modify, records in the domain.
(Default)

EXCLUSIVE
I

No other user can access this domain at the same time, for any purpose.
I

Table 5-8: Domain Access Modes

II Access Mode I

5-68

Meaning

Privilege Required

READ

You can retrieve records only. (Default)

Read, write, or modify

MODIFY

You can retrieve and modify .records.

Modify or write

WRITE

You can retrieve, modify, store, and erase
records.

Write

EXTEND

You can store records only.

Extend, write, or modify

Commands and Statements

Usage Notes

1. To verify that a domain is ready, use the following format of the SHOW
command:
SHOW READY

SHOW READY prints the name, file type, access type, and access mode
of all readied domains. (See Section 5.32 for more information on SHOW
READY.)
2. The access mode you specify determines the commands and statements
you can use on this domain. If you will be issuing any command or statement listed in Table 5-9, be sure to request the appropriate access mode.

Table 5-9: Access Mode Required by Commands/Statements

I Command/Statement I

Access Mode Reoui:red
--&

ERASE

WRITE

FIND

MODIFY, READ, or WRITE

MODIFY

MODIFY or WRITE

MODIFY, READ, or WRITE

STORE

WRITE or EXTEND

3. When specifying the access allowed to other users, be as nonrestrictive as
possible. For example, if you specify EXCLUSIVE access, no other user
can access the domain.
4. When specifying the type of access you require, be as restrictive as possible. For example, if you will only be retrieving records, specify READ
access, which is more efficient than MODIFY or WRITE access.
5. You can issue more than one READY command for the same domain in a
single session. This facility allows you to change the allow type or access
mode you require. However, when you re-ready a domain without finishing it, DATATRIEVE ignores the optional password argument and uses
the original access information.
For example, during a session you might modify records, then output
records with the PRINT command. In this case, you can ready the domain

Commands and Statements

5-69

for WRITE access, modify the records with the MODIFY statement, and
then ready the domain for READ access before issuing the PRINT
statement.
DTR)
DTR)

READY YACHTS (PASSWD) EXCLUSIVE WRITE
MODIFY

DTR)
DTR)

READY YACHTS PROTECTED READ
PRINT

6. A domain remains ready until you release it with the FINISH command or
terminate the session with EXIT or CTRL/Z.lfyou have no further use for
a domain, but do not want to terminate a session, issue the following
FINISH command for the domain:
FINISH dOMain-naMe

FINISH releases your control of a domain and its collections, allowing other
users access to the domain and freeing up the resources utilized by the
domain. (See Section 5.20 for more information on FINISH.)
Examples

1. Ready the domain YACHTS for WRITE access.
DTR) READY YACHTS WRITE

2. Ready the domain PHONES for EXTEND access.
DTR) READY PHONES (*) EXTEND
Enter password for PHONES:
DTR)

5-70

Commands and Statements

5.27 RELEASE Comrnand__
Function

Releases a collection, a description table, or a global variable, freeing its
workspace for other use.
Format

RELEASE

collectn-name }
table-name
...
{
variable-name

Arguments

collectn -name
table-name
variable-name
Is the name of a collection, a description table, or a global variable to be
released. To release variable-name more than one item~ separate them
with commas.
Restrictions

None.
Results

1. DATATRIEVE releases the collection, description table, or global varia-

ble and frees its workspace. The records and domain from which a collection originated are unaffected by this command.
2. If you specify more than one item to be released, DATATRIEVE releases
the workspace of each item in the order specified in the command. If the
command fails before the last item is processed, DATATRIEVE prints an
error message indicating which item failed to be released. All items before
that item in the command were released.

Commands and Statements

5-71

Usage Notes

1. You cannot reference a global variable once it is released. If necessary, you
can redefine the variable with the DECLARE statement. (See Section
5.5.)
2. Use of the RELEASE command can be redundant, as in the following
instances:
• A FIND statenlent that successfully establishes a collection ieleases an
existing collection of the same name.
• Ending a session (with EXIT or CTRL/Z) releases all global variables
and all collections established during a session.
• A FINISH command releases all collections associated with the
domain(s) specified in the command.
Examples

1. Release the collection BIG-ONES.
DTR> SHOW COLLECTIONS
Collections:
BIG-ONES (also CURRENT)
DTR> RELEASE BIG-ONES
DTR> SHOW COLLECTIONS
No established c~llections
DTR>

2. Release the table DEPT-TABLE.
DTR> RELEASE DEPT-TABLE

5-72

Commands and Statements

5.28 REPEAT Statement
Function

Causes DATATRIEVE to execute a statement a specified number of times.
Format

REPEAT val-exp statement
Arguments

val-exp
Is a value expression indicating the number of times to execute the statement. This argument must evaluate to a positive, nonzero integer.
statement
Is any simple or compound statement (except a FIND or SELECT
statement).
Restrictions

1. Do not inciude a FIND or SELECT statement in a REPEAT statement.

2. You must observe any restriction on the statement included in a REPEAT
statement that is listed in its description.
Results

DATATRIEVE executes the specified statement the indicated number of
times. DATATRIEVE then executes the command or statement following the
REPEAT statement.
Examples

1. Print "TEST REPEAT" three times.
OTR> REPEAT 3 PRINT "TEST REPEAT"
TEST REPEAT
TEST REPEAT
TEST REPEAT
OTR>

2; Store five new records in the YACHTS domain.
OTR> REPEAT 5 STORE YACHTS

Commands and Statements

5-73

5.29 REPORT Command
Function

Invokes the Report Writer.
Format

REPORT [rse] ON {

~;:-:SDeC
*opro:npt-name

{

Arguments

rse
Is a record selection expression specifying the data for your report. You
can make reports on the following kinds of data:
• Readied domains
• Collections
• Sublists
See Chapter 6 for detailed information on record selection expressions. See
Chapter 15 for information on sublists. If you omit this argument, the
Report Writer uses all records in the current collection for your report.
dev:
file-spec
*.prompt-name
Is the name of the file or device to contain the report or a prompting value
expression. By specifying a device name in the REPORT command, you
can tell the Report Writer to send the report to any system device to which
you have access, such as a line printer, a tape drive, or your terminal. On
RSTSIE systems, if you specify the line printer for output and it is busy,
the Report Writer may not produce the report. If no report is produced for
this reason, you may have to consult with your system manager to work
around the problem. To send your report to a tape drive~ you must mount
your tape and assign the tape drive to your process before specifying the
tape drive in the REPORT command. If you specify a file, the file specification must be in the following format:
dev: [UFD]filename.ext;ver

5-74

Commands and Statements

You must specify at least a file name. All other fields are optional. If you
omit a field,DATA-rrRIEVE uses the following defaults:
Field

Default

dev:

SY: (the system device)

[UFD]

Your default UFD

filename

No default. Must be specified.

.ext

.LST

;ver

1 or 1 higher than current version number
(non-RSTSIE systems only)

If you

specify a prompting value expression (* .prompt-name) ,
DATATRIEVE will prompt for the output file or device when this command is executed.

If you omit this argument~ the report is printed on your input terminaL
Restrictions

None.
Results

When this command is executed, DATATRIEVE prompts with RW>, indicating that the Report Writer is executing and is expecting a report definition.
The Report Writer continues to prompt with RW> until you either enter a line
consisting of END-REPORT or enter a syntax error. After you enter
END-REPORT, DATATRIEVE writes your report to the device or file you
specify. If you make a syntax error, DATATRIEVE returns to command level
without writing any report.
Usage Notes

Refer to Chapter 7 for a full description of the Report Writer.

Commands and Statements

5-75

Example

Use the Report Writer to display data from the domain FAMILIES.
DTR)
RW>
RW>
RW>
RW>

REPORT FAMILIES
SET REPORT-NAME = "REPORT ON FAMILIES"
PRINT FATHERt MOTHERt KIDSt SKIP
AT BOTTOM OF REPORT PRINT TOTAL NUMBER-KIDS (-)
END-REPORT

t COUNT (-)

REPORT ON FAMILIES
2G-Ma}'-80
PaSe 1

FATHER
JIM

MOTHER
ANN

KID
NAME

AGE

URSULA
RALPH

8
4

JIM

LOUISE

ANNE
JIM
ELLEN
DAVID
ROBERT

32
30
27
25
17

JOHN

JULIE

ANN
JEAN

30
27

5-76

Commands and Statements

5.30 SELECT Statement
Function

Selects a record from the CURRENT collection or any named collection.
Format

FIRST
NEXT
SELECT LAST

[collectn -name]

val-exp

Arguments

FIRST
LAST
NEXT
val-exp
Indicates which record in the collection is to be selected. If you specify a
value expression, the expression must evaluate to a positive integer that
does not exceed the number of records in the collection. If this argument is
omitted, DATATRIEVE selects either the first record (if this is the first
time SELECT is issued for the collection) or the next record in the
collection.
collectn -name
Is the name of the collection containing the records to be selected. If
omitted, the record is selected from the current collection.
Restrictions

1. You must establish the named collection or a current collection before
issuing this statement.

2. The collection cannot be empty.
3. You cannot use a SELECT and FIND statement in the s~me compound
statement.
4. You cannot use a SELECT statement in a BEGIN-END block or in a
FOR or REPEAT statement.
Results

1. SELECT establishes the current record. The actual record selected is
dependent on the arguments you supply, the state of the collection, and
the position of the collection cursor when this command is issued.
2. If you specify SELECT NEXT and the collection cursor points to the last
record, DATATRIEVE prints an error message. The collection cursor is
unchanged.
3. Selecting a record does not make the collection current if it was not already current.

Commands and Statements

5-77

Usage Notes

1. If you want to know the record number of the record selected, use the
SHOW command (Section 5.32) in the following format:
SHOW collectn-naMe

This command prints the domain name of the collection, the number of
records in the collection, and the record number of the selected record.
2. To ascertain the na.me and attributes of the current collection, you can use
the SHOW CURRENT command (Section 5.32).
3. Fields of the selected record can be referenced like global variables.
4. If you want to perform the same set of statements on .each record in the
current collection you cannot do the following:
REPEAT 50
BEGIN
SELECT NEHT
END

The proper way to do this is:
FOR CURRENT
BEGIN
END
Examples

1. Select the last record in the current collection.
DTR) SELECT LAST
DTR>

2. Select the fifth record in the collection BIG-ONES.
DTR) SELECT 5 BIG-ONES
DTR>

5-78

Commands and Statements

5.31 SET Command
Function

Establishes the current data dictionary, sets the maximum number of columns per page, inhibits or permits aborts, starts Guide Mode, and inhibits or
permits statement prompting.
Format

SET

DICTIONARY [file-spec]
COLUMNS-PAGE=n
ABORT
NO ABORT
GUIDE
PROMPT
NO PROMPT

[, ... ]

Arguments

DICTIONARY [file-spec]
Causes DATATRIEVE to connect you to a specific data dictionary. If you
do not include a file-spec, DATATRIEVE connects you to the data
dictionary that was your current data dictionary when you started the
session. If you include a file-spec, DATATRIEVE connects you to the data
dictionary with that file specification. Use the following format for a filespec:
dey: [UFD]filename .ext;ver
If you omit a field in the file specification, DATATRIEVE uses the following defaults.
Field

Default

dev:

SY: (the system device)

[UFD]

Your default UFD

filename

QUERY

.ext

.DIC

;ver

Highest version number
(non-RSTS/E systems only)

COLUMNS-PAGE=n
Establishes the number of columns per page for DATATRIEVE output
and the default page width for the Report Writer. The argument n must be
an unsigned integer that is less than 256. The default number of columns
per page is established at installation time.

Commands and Statements

5-79

ABORT
NO ABORT
Determines the effect of an ABORT statement or CTRL/Z inside a procedure or indirect command file. If SET ABORT is in effect and
DATATRIEVE executes an ABORT statement or you enter a CTRL/Z in
response to a prompt, DATATRIEVE aborts the entire procedure or command file. If SET NO ABORT is in effect, DATATRIEVE continues with
the next statement of the procedure or command file. At the start of a
DATATRIEVE session, SET NO ABORT is in effect.
GUIDE
Starts GUIDE Mode. To terminate GUIDE Mode, type L. (Refer to the
DA TA TRIEVE Primer for more information.)
PROMPT
NO PROMPT
Determines whether DATATRIEVE prompts for missing statement elements with the following message:
[Look ins for eleMentJ

At the start of a DATATRIEVE session, SET PROMPT is in effect.
Restrictions

None.
Results

If you specify SET DICTIONARY file-spec and the command fails because
the specified file does not exist, cannot be accessed, or is not a valid dictionary, the current data dictionary is unchanged. That is, the dictionary in effect
before the SET command was issued is still in effect.
Examples

1. Set the number of columns per page to 80.
DTR> SET COLUMNSrPAGE =80
DTR>

2. Connect to your private data dictionary.
DTR> SET DICTIONARY [ZOZ,ZOZJMYOWN.DIC

5-80

Commands and Statements

5.32 SHOW Command
Function

Prints information about the data dictionary and its contents.
Format

CURRENT
ALL
READY
DOMAINS
RECORDS
PROCEDURES
TABLES
FIELDS [FOR domain-name]
COLLECTIONS

SHOW

[, ••• J

DICTIONARY

rdomain-name1
Jrecord-name l

proc-name
.r table-name )
collectn-name

L(*)

l(passwd)1

Arguments
CURREt~T

Prints the domain name, the number of records in, and the number of the
selected records in the current collection.
ALL
Prints the names of all domains, records, description tables, collections,
procedures, views, and readied domains in the current data dictionary.
READY
Prints the names, file types, access types, and access modes of all readied
domains in the current data dictionary.
DOMAINS
Prints the names of all domains defined in the current data dictionary.
RECORDS
Prints the names of all records defined in the current data dictionary.
PROCEDURES
Prints the names of all procedures defined in the current data dictionary.
TABLES
Prints the names of all description tables defined in the current data
dictionary and all description tables in the DATATRIEVE workspace.

Commands and Statements

5-81

FIELDS [FOR domain-namel
Prints the names of all fields in the specified domain or in all readied
domains. This also prints the names of all global variables. (If a domain
name is specified, it must be the name of a readied domain.)
COLLECTIONS
Prints the names of all collections.
DICTIONARY
Prints the complete file specification of the current data dictionary.
domain-name
record -name
proc-name
table-name
Prints the dictionary definition of the named domain, record, procedure,
or description table.
(passwd)
(*)

Is an asterisk enclosed in parentheses (*) or the password necessary to gain
R (read) access to the dictionary object. If you specify a. password, you
must enclose it in parentheses. If you specify (*), DATATRIEVE prompts
for the password, but does not print your response on the terminal. If you
omit this argument, DATATRIEVE uses your log-in UIC/PPN to verify
that you have R (read) access privilege.
collectn -name
Prints the domain name, the number of records in, and the number of the
selected record in the specified collection.

5-82

Commands and Statements

Restrictions

You must have read access to a domain, record, procedure, or description
table to print its definition.
Results

DATATRIEVE prints the requested information on your terminal, in the
order requested.
Examples

1. Display the names of all the entries in the current data dictionary.
DTR> SHOW ALL

2. Display the definition of the record YACHT.
DTR> SHOW YACHT

3. Display the names of all global variables, and the field names of all readied domains.
DTR> SHOW FIELDS

Commands and Statements

5-83

5.33 SHOWP Command
Function

Prints a password table on your terminal.
Format

Arguments

domain-name
record-name
proc-name
table-name
Is the name of the domain, record, procedure, or description table whose
password table is to be printed.
(passwd)
(*)

Is an asterisk enclosed in parentheses (*) or the password necessary to gain
C (control) access to the dictionary object. If you specify a password, you
must enclose it in parentheses. If you specify (*), DATATRIEVE prompts
for the password, but does not print your response on the terminal. If you
omit this argument, DATATRIEVE uses your log-in UIC/PPN to verify
that you have C (control) access privilege.
Restrictions

You must have C (control) access privilege to the domain,record, procedure,
or description table.
Results

DATATRIEVE prints the entire password table for the specified domain,
record, procedure, or description table.
Examples

1. Display the password table for the YACRTS domain.
OTR) SHOWP YACHTS

2. Use a password to gain C (control) access to the record YACHT and
display its password table.
OTR) SHOWP YACHT <*>
Enter password for YACHT:

5-84

Commands and Statements

5.34 SORT Statement
Function

Sorts records in a collection according to the contents of one or more fields.
Format
SORT [collectn-name](BY] sort-key-l [,sort-keY-2} ..
Arguments

collectn -name
Is the name of the collection to be sorted. If you omit the collection name,
records in the current collection are sorted.
BY
Is included with the command to preserve English-language-like syntax. It
serves no other purpose.
sort-key
Is a sort key indicating both the order of the sort and the field to be used
for the sort. Each sort key must be in the following format:
ASC[ENDING]
DESC[ENDING]
INCREASING
DECREASING

fld-name

If more than one sort key is specified, they must be separated by a comma
(,) .
Restrictions

1. You must have established the collection to be sorted before issuing this
statement.

2. You cannot sort COMPUTED BY fields.
Results

1. DATATRIEVE sorts the collection based on the contents of the field(s)
you specify. Appendix F describes the order by which alphanumeric fields
are sorted.

2. If you specify ASC[ENDING] (or INCREASING), DATATRIEVE places
the lowest value first and the highest value last in the collection.
If you specify DESC[ENDING] (or DECREASING), DATATRIEVE
places the highest value first and the lowest value last in the collection.

3. You can specify any number of sort keys. If you specify more than one,
DATATRIEVE treats the first field name as the major sort key and each
successive field name as increasingly minor keys.

Commands and Statements

5-85

4. If you omit a sorting direction (ASCENDING, INCREASING, etc.) for
the first sort key, DATATRIEVE sorts the field in ascending order.
If you omit a sorting direction on the second or subsequent sort keys,
DATATRIEVE uses the preceding sort direction (implied or specified) for
the field.

5. The collection cursor is null at the completion of this command.
Usage Notes

If you will be sorting large amounts of data or will be specifying several sort
keys, it is a good practice to free as much workspace as possible before issuing
the SORT statement. You can free workspace in the following ways.

• Relinquish any domains you can with the FINISH command (Section 5.20).
• Relinquish any collections, description tables, or global variables you can
with the RELEASE command (Section 5.27).
• Change the access mode of all readied domains from WRITE or MODIFY to
READ, which uses less buffer space. (See the READY command, Section
5.26.)
Examples

1. Form a collection of families. Sort the collection by decreasing number of
children.
DTR) READY FAMILIES
DTR) FIND FAMILIES
[1a records found]

DTR) SORT BY DECREASING NUMBER-KIDS
DTR) PRINT ALL
FATHER
BASIL

MOTHER

NUMBER
KIDS

MERIDETH

JIM

LOUISE

ROB

0101

KID
NAME
BEAU
BROOKS
ROBIN
JAY
WREN
JILL
ANNE
JIM

AGE
29
27
25
23
18

32
30

2. Form a collection of yachts. Sort the collection using the builder as the
primary key and the length over all as the second key.
DTR) FIND YACHTS
[113 records found]

DTR)SoRT BY BUILDERt LOA

5-86

Commands and Statements

5.35 STORE Statement
Function

Creates a record in a domain and stores values in all fields or selected fields in
the record.
Format
STORE domain-name [[USING] statement-I] [VERIFY [USING] statement-2]

Arguments

domain-name
Is the name of the domain to contain the new record. The domain must be
readied for WRITE or EXTEND access.
USING
Is included in the command to preserve English-language-like syntax. It
serves no other purpose. If specified, the keyword USING must be on the
same input line as the keyword STORE.
statement-l
Is a statement to be used to store field values in the record. Typically,
statement-l is an assignment statement or a BEGIN-END block containing a series of assignment statements. If omitted, DATATRIEVE prompts
for all elementary field values in the record.
VERIFY [USING]
statement-2
Indicates that no value is to be stored in a field unless the condition
specified by statement-2 is met. Typically, statement-2 is an
IF-THEN-ELSE statement or a BEGIN-END block containing a series
of IF-THEN-ELSE statements.
Restrictions

1. The domain to contain the new record must be readied for WRITE or
EXTEND access. (See the READY command, Section 5.26.)

2. You cannot store a new record in an RMS relative file or a view.
Results

1. If you omit the USING statement-l clause, DATATRIEVE prompts for a
value for the first elementary field in the record with the following
message.
ENTER

f 1 d-nalrle:

Mter you enter a value, DATATRIEVE prompts for the next field value in
the record until you have entered a value for every field in the record.
Commands and Statements

5-87

To leave a field empty, enter a single space followed by a carriage return.
If you enter only carriage return in response to a prompt, DATATRIEVE

repeats the prompt.
If you enter data that is inappropriate for a field, DATATRIEVE

reprompts for valid data.
2. If you include a USING clause, DATATRIEVE does not reprompt for
data.
If you enter too many digits for a numeric field, DATATRIEVE truncates

the high-order digits, stores the remaining digits in the field, and issues an
error message.
If you

enter too many characters for an alphanumeric field,
DATATRIEVE truncates the rightmost characters, stores the remaining
characters in the field, and issues an error message.

3. If you specify a VERIFY USING clause, no data is stored until statement-2 is successfully executed.
Usage Notes

1. If you include the USING statement-l clause, statement-l will generally
be an assignment statement or a BEGIN-END block containing a series of
assignment statements. The formats of the assignment statement are:
fld-name = val-exp
group-fld-name-l = group-fld-name-2
You should review the description of the assignment statement for elementary fields (Section 5.3.1) or group fields (Section 5.3.2) before using
this format of the STORE statement.
If you put a BEGIN-END block in the USING clause, you can include

statements other than assignment statements. To see what you are storing, include a PRINT statement in the BEGIN-END block. Section 5.4
describes the BEGIN-END block.
2. To store more than one record in a domain, you can use the following
format of the REPEAT statement:
REPEAT n STORE domain-name
The argument n represents the number of records to be stored in the
domain.

5-88

Commands and Statements

Examples

1. Store a record in the FAMILIES domain.
DTR) READY FAMILIES WRITE
DTR) STORE FAMILIES
Enter FATHER:

2. Store a record in the YACHTS domain.
DTR) READY YACHTS WRITE
DTR) REPEAT 3 STORE YACHTS USING
[Look ins for assiSnment statement(s)]
DTR) BEGIN
[Look inS for statement]
DTR) BUILDER="AMERICAN"
[Loo.~inS for statelTlent or "end"]
DTR> MODEL = *.MODEL
(L 0 0 .~ inS for s tat e ITI e n tor end" ]
DTR) END
Enter MODEL: 1980
II

En t e r

MODEL:

i 880-A

Enter MODEL~ 1qRO-B
DTR) PRINT YACHTS WITH BUILDER EQ "AMERICAN"

MANUFACTURER
AMERICAN
AMERICAN
AMERICAN
AMERICAN
AMERICAN

MODEL
1980
1980-A
1980-B
26
26-MS

RIG

LENGTH
OljER
ALL WEIGHT
0
0

SLOOP
MS

26
26

BEAM
00
00

4tOOO
5t500

08
08

PRICE

$9t895
$18t895

DTR>

Commands and Statements

5-89

5.36 SUM Statement
Function

Provides a summary report of the total of the contents of any number of
numeric fields in the current collection. The output can be sorted by the
contents of one or more fields and can be directed to any device or file.
Format

SUM print-list BY sort-key ON

dev:
file-spec
* .prompt-name

Arguments

print-list
Is a list of numeric fields or other value expressions for DAT ATRIEVE to
use. The format of the print-list is:
val-exp-l [modifier-I] ,val-exp-2 [modifier-2] ...
Modifiers are the same as the print-list modifiers described in Section 5.25
and summarized in Table 5-6.
sort-key
Determines the order of the sort and the fields for DATATRIEVE to sort
by. See Section 5.34 for the format and effect of sort keys.
dev:
file-spec
*.prompt-name
Is the name of the file or device to contain the summary report or a
prompting value expression. If you specify a file, the file specification
must be in the following format:
dev: [UFD] filename .ext;ver
You must specify at least a file name. All other fields are optional. If you
. . A1TRIEVE
.
uses the follov:ing defaults:
omit a field, D. A1T
Field

Default

dev:

SY: (the system device)

UFD

Your default UFD

filename

No default. Must be specified

.ext

.LST

;ver

1 or 1 higher than current version number
(non-RSTS/E systems only)

If you specify a prompting value expression (* .prompt-name) ,
DATATRIEVE prompts for the output file or device when this command
is executed. If you omit this argument, the output is printed on your
terminal.

5-90

Commands and Statements

Results

1. DATATRIEVE sorts the CURRENT collection according to the fields you
specify and outputs a summary report on the specified (or default) device.
The summary report includes the total of the contents of the fields specified by the print list.
2. The order and format of the data in the report depends on the arguments
you select. For more information on the sort order, refer to the description
of the SORT command, Section 5.34. For more information on the format
of the data, refer to the description of print-list modifiers in Section 5.25
and Table 5-6.

Usage Notes

You can use the SUN! statement to get a count of the number of records in the
collection by field name with the following format:

SUM 1 BY sort-list
Examples

1. Form a collection of yachts. Use the SUM statement to summarize the
prices of yachts in the collection.
OTR) FINO YACHTS
[113 records found]
OTR) SELECT 1
OTR) MOOIFY SPECS
Enter RIG:
OTR>
OTR)
OTR) FINO YACHTS
[113 records found]
OTR) SUM PRICE BY BUILDER
MANUFACTURER
ALBERG
ALBIN
AMERICAN
BAYFIELD
BLOCK I •
BOMBAY
BUCCANEER
CC
CABOT
CAL

PRICE
36951
6aooo
28790
32875
0

23950
0
0

0
0

1272933

Commands and Statements

5-91

2. Use the SUM statement to display the number of yachts built by each
builder.
DTR> SUM 1 BY BUILDER
MANUFACTURER
ALBERG
ALBIN
AMERICAN
BAYFIELD
BLOCK I.
BOMBAY
BUCCANEER
CC
CABOT
CAL
CAPE DORY
CAPITAL

113

5-92

Commands and Statements

1
3

5
3
1

5.37 THEN Statement
Function

Joins two statements into a compound statement.
Format
statement-l THEN statement-2
Arguments

statement-l
Is any DATATRIEVE statement.
statement-2
Is any DATATRIEVE statement.
Restrictions

You cannot include FIND and SELECT ~n the same compound statement.
Results

DATATRIEVE executes statement-l and statement-2. You can use a compound statement anywhere you can use a single statement.
Example

Make a compound statement by using THEN to join a PRINT statement and
a rv10DIFY statement. Nest the compound statement within a FOR statement.
DTR> FOR YACHTS WITH BUILDER EQ "ALBIN" PRINT THEN MODIFY

Commands and Statements

5-93

Chapter 6
Expressions

An expression is a statement element that represents a value or that specifies
the record (or records) that statements are to operate on. DATATRIEVE
provides three types of expressions:
• Value expressions, which represent values
• Boolean expressions, which are either "True" or "False"
• Record selection expressions, which specify a record stream

6.1

Value Expressions
A value expression is a means of specifying a value, which DATATRIEVE
computes. DATATRIEVE provides several methods for specifying value
expressions. The methods for specifying value expressions are explained in
Sections 6.1.1 through 6.1.8.

6.1.1

Literals

The simplest way to specify a value is with a literal. A literal is a character
string enclosed in quotation marks or a number. A character string literal can
contain up to 132 characters. You can continue a character string literal on
more than one line by using the continuation character hyphen. To specify
character strings longer than 132 characters use concatenated expressions
(Section 6.1.8). You can include a quotation mark in a character string literal
by directly preceding it with a quotation mark. Examples of character string
literals are:
"Invalid value for this field"
"MAXIMUM PRICE IS $1400. PLEASE REENTER PRICE."
"Capt. Jack says, " "Time to reorder." " "
A numeric literal is a string of digits that DATATRIEVE interprets as a
decimal number. A numeric literal can contain up to 18 digits and may
contain a decimal point. A numeric literal cannot begin with a decimal point.
Thus, for example, 0.5 is a valid numeric literal while .5 is not.

6-1

6.1.2 Field Names
You can use a field name as a value expression. The value that you specify is
the value stored in a field of a record. If the record definition contains a query
name for a field, the query name is used just like a field name.
Use the following format to qualify field names.
[context-variable.] [record-name.] [group-name.] ... field-name
The context-variable qualifier allows you to distinguish between fields from
different record streams. The record-name qualifier allows you to distinguish
between fields in different domains which have the same field name. The
group-name qualifier allows you to distinguish between fields that are contained in different group fields and have the same field name.
To refer to the fields within a record, you must create a context. Table 6-1
lists the different ways to create contexts, and how long each context lasts.

Table 6-1: Context Types

Statement
or Clause

Context

Valid for

SELECT

Selected record

Any statement

FOR

Record in record stream

Statements nested within
FOR statement

VERIFY

Record being stored or
modified

Statements within VERIFY clause

Record stream

Statement containing the
OF clause

WITH

Domain, collection, or list
that the rse refers to

Boolean expression in the WITH
clause of an rse

If there is more than one valid context for a field name, DATATRIEVE uses
the most recent valid context, If there is no valid context for a field name,
DATATRIEVE issues an error message. The following examples show how
field names are used as value expressions:
Use a selected record to show how you include qualifiers in field names. Use a
query name to print the length.
DTR) FIND YACHTS
,. .. of II
L~.L'"

records found]

DTR) SELECT 9
DTR) PRINT MODEL
MODEL
CLIPPER
DTR) PRINT TYPE.MODEL
(continued on next page)

6-2

Expressions

MODEL
CLIPPER
DTR> PRINT BOAT.TYPE.MODEL
MODEL
CLIPPER
DTR> PRINT LOA
LENGTH
OI.IER
ALL
31

Increase the price of each yacht by $500.
DTR> FOR YACHTS MODIFY USING PRICE
DTR>

PRICE + 500

In the previous example the field name PRICE is used twice. On the left side
of the equal sign it specifies the field being modified, on the right side of the
equal sign it is a value expression, representing the value originally stored in
the field.

6.1.3 Variables
DATATRIEVE allows you to declare both global and local variables. Global
variables are all variables that are not declared within BEGIN-END blocks.
You can use a global variable as a value expression in any statement.
Local variables are all variables declared within BEGIN-END blocks. You
can only use a local variable within the BEGIN-END block where you declare
it. You can give a local variable the same name as a variable declared outside
of that BEGIN-END block. DATATRIEVE resolves any ambiguous variable
name by using the most recently declared variable with that name.
If a variable name is the same as a field name, DATATRIEVE uses the most
recent valid context for a name. The context of a local variable is more recent
than any context created outside the BEGIN-END block. The context of a
global variable is less recent than all other possible contexts. To avoid trouble,
do not use variable names that duplicate field names.

The following example shows how to use a variable as a value expression.
DTR> DECLARE PRICE-PER-POUNO COMPUTED BY PRICE / DISP
DTR> EDIT-STRING IS 8.88.
DTR> FOR FIRST5 YACHTS PRINT BOATtPRICE-PER-POUNO
(continued on next page)

Expressions

6-3

MANUFACTURER

MODEL

RIG

LENGTH
OVER
ALL WEIGHT

ALBERG
ALBIN
ALBIN
ALBIN
AMERICAN

37 MK I I
79
BALLAD
I.IEGA
26

KETCH
SLOOP
SLOOP
SLOOP
SLOOP

37
26
30
27
26

20tOOO
4t200
7t276
5t070
4tOOO

BEAM

PRICE

PRICE
PER
POUND

12
10
10
08
08

$36t951
$17t900
$27t500
$18t600
$9t895

1. 84
4.26
3.77
3.66
2.47

DTR) PRINT MAX PRICE-PER-POUND OF YACHTS
PRICE
PER
POUND
5.00
DTR)

6.1.4 Prompting Value Expressions
If you want DATATRIEVE to prompt you for a value, use a prompting value
expression. This feature is especially useful in procedures, as it allows you to
use different values each time you invoke your procedures. The basic format
of a prompting value expression is:

*. "prompt-name"
You specify a prompt name, preceded by an asterisk and period. If the prompt
name you select conforms to the rules for names given in Section 4.4, you do
not have to enclose it in quotation marks. If the prompt name does not
conform to those rules, you must enclose it in quotation marks. If you place a
prompting value expression in a REPEAT or FOR statement, you can have
DATATRIEVE prompt you only once by using two asterisks. If you include
only a single asterisk, DATATRIEVE prompts you for a value each time the
statement is executed.
The following example shows the difference between * .prompt and ** .prompt:
DTR) READY PHONES WRITE
DTR) REPEAT 5 STORE PHONES USING BEGIN
DTR) DEPARTMENT = **.DEPARTMENT
DTR) LOCATION = **.LOCATION
DtR) NAME = *.NAME
DTR) NUMBER = *.NUMBER
Enter DEPARTMENT: SD
Enter LOCATION: PK5
Enter NAME: Sales, John
Enter NUMBER: 8543477
Enter NAME: HaMMOndt Ken
Enter NUMBER: 8541010
Enter NAME:

You can use a prompting value expression anywhere that a value expression is
required. You can also use it in place of a device narne or file name in the
REPORT command and the PRINT statement.

6-4

Expressions

The following example shows how to use *.prompt in a REPORT command:
DTR> DEFINE PROCEDURE REPORT1
DFN> REPORT ON *."Device or File name"
DFN>
DFN>
DFN> END-REPORT
DFN> END-PROCEDURE
DTR>
DTR> :REPORTl
Enter Device or File name: REPORT.DAT
DTR>

6.1.5 Values from a Table
You can use a value stored in a description table anywhere a value expression
is required. The format for using a value from a description table is:
value-expression VIA table-name
If the value expression you specify is stored as a code in the table you specify,
then the value of the entire expression is the corresponding description in the
table. If the value expression you specify does not match any code in the
table, then the value of the entire expression is the description stored in the
ELSE clause. If the value expression is not found and there is no ELSE
clause, DATATRIEVE issues an error message. See Chapter 13 for more information on using tables.

6.1.6 Statistical Functions
DATATRIEVE provides several statistical functions which can be used anywhere a value expression is required. The statistical functions are MAX,
MIN, AVERAGE, TOTAL and COUNT. The format for using statistical
functions is:
function val-exp [OF rse]
You must include a value expression for all statistical functions except
COUNT. Do not include a value expression with COUNT. The value expression is usually a field name. Table 6-2 shows the results of each statistical
function.

Table 6-2: Statistical Functions

Function

Value of Function

MAX

The largest value of the value expression

MIN

The smallest value of the value expression

AVERAGE

The average value of the value expression

TOTAL

The total value of the value expression

COUNT

The number of records in the record stream

Expressions

6-5

If you include a record selection expression, DATATRIEVE uses all records in
the resulting record stream to compute the value of the function. If you do not
include a record selection expression, DATATRIEVE uses all records in the
current collection to compute the value of the function.

The following examples show how to use the statistical functions:
DTR> FIND YACHTS WITH PRICE GT 0
[50 records found]
DTR> PRINT AVERAGE PRICE
PRICE
$25t388
DTR> PRINT AVERAGE PRICE OF YACHTS
PRICE
$11t233
DTR> PRINT YACHTS WITH PRICE EQ MIN PRICE

MANUFACTURER
I)ENTURE

MODEL
21

RIG

LENGTH
OVER
ALL WEIGHT

BEAM

PRICE

SLOOP

$2t823

1 t500

DTR> READY FAMILIES
DTR> PRINT TOTAL NUMBER-KIDS OF FAMILIES
NUMBER
KIDS
35
DTR> PRINT COUNT OF FAMILIES WITH NUMBER-KIDS EQ 2
6

DTR> PRINT FAMILIES WITH
[Lookin~

for Boolean expression]

DTR} NUMBER-KIDS EQ MAX NUMBER-KIDS OF FAMILIES
FATHER
BASIL

MOTHER

NUMBER
KIDS

KID
NAME

MERIDETH

BEAU
BROOKS
ROBIN
JAY
WREN

28
26

I T I I
-.1.1. ........

2C)

AGE

6.1.7 Arithmetic Expressions
An arithmetic expression consists of value expressions and arithmetic operators, The value expressions must all represent numbers. You can use an

6-6

Expressions

arithmetic expression anywhere a value expression is allowed. DATATRIEVE
provides four arithmetic operators. Table 6-3 shows the arithmetic operators
and the operation performed.

Table 6-3: Arithmetic Operators

Operator

Operation

addition

subtraction or negation

multiplication

division

Use spaces to separate arithmetic operators from value expressions. You
can use parentheses to make DATATRIEVE perform some operations first.
DATATRIEVE uses the normal rules of precedence in evaluating arithmetic
expressions. That is, first DATATRIEVE evaluates any value expressions that
are in parentheses, then DATATRIEVEperforms multiplications and
divisions from left to right, and finally DATATRIEVE performs additions and
subtractions from left to right. The following examples show how
DATATRIEVE evaluates arithmetic expressions:
DTR) PRINT (8
a7

* 7) + 5

OTR) PRINT G * (5

+ 8)

OTR) PRINT 5 +

a * 3

OTR) PRINT 12 - G * 2

OTR) PRINT 5 + 10
10

6.1.8 Concatenated Expressions
DATATRIEVE allows you to join value expressions to form concatenated
expressions. Concatenated expressions can be used anywhere a character
string literal is allowed. The two formats for concatenated expressions are:
value-expression I value-expression
value-expression I I value-expression
If you use I (one vertical line), DATATRIEVE joins the two value expressions
to form a longer string, the first character of the second value expression

Expressions

6-7

following the last character of the first value expression. If you use I I
(two vertical lines), DATATRIEVE removes all trailing spaces from the first
value expression and then joins the second value expression to it. The following examples show how DAT ATRIEVE evaluates concatenated
expressions:
DTR> PRINT "HELLO":"THERE"
HELLOTHERE
DTR .,:' PR I NT "S I NGLE BAR " : "LEAl.JES TRA I LING SPACES"
LEAVES TRAILING SPACES
SINGLE BARDTR> PRINT "DOUBLE BARDOUBLE BAR-DOES NOT

" : : "DOES NOT"

DTR> PRINT "GOOD"::" BYE"
GOOD BYE

The following example shows how concatenation expressions can be used to
assign values to long variables. You can use similar assignment statements
in a STORE ... USING or MODIFY ... USING statement to handle long field
values.
DTR> DECLARE LONG-STRING PIC X(ZOO) EDIT-STRING IS T(SO).
DTR> LONG-STRING = *.LINE1:*.LINEZ:*.LINE3
Enter LINE1: This line contains the first part of a very Ions strinS.
Enter LINEZ:
This strinS is too IonS to use a character strins literal
Enter LINE3:
to assiSn it. You need concatenation expressions.
DTR> PRINT LONG-STRING
LONG
STRING
This is the first part of a very IonS strins.
This strins is too Ions to use a character strins
literal to assiSn it. You need concatenation
expressions.
DTR>

6.2 Boolean Expressions
Boolean expressions are expressions that DATATRIEVE evaluates to either
"True" or "False". You use Boolean expressions in the following places:
• a WITH clause in a record selection expression (Section 6.3)
• an IF-THEN-ELSE statement (Section 5.23)
• a VALID IF clause in a record definition (Section 1l.16)
All Boolean expressions contain relational operators and some contain Boolean operators.

6-8

Expressions

6.2.1

Relational Operators

Relational operators compare value expressions, check whether a code is contained in a table, and check whether a record stream is empty. Table 6-4
shows the format for using each relational operator, and explains when the
Boolean expression containing it is "True".
Table 6-4: Relational Operators
Boolean Expression Format
field name J;Q

~EQUAL

field name

}

val-exp-l [, val-exp-2l. ..

{~~T EQUAL l

I
I
(>
I field name ~ GT

Evaluation of Expression
"True" if value of the field is
equal to any value expression
in the list.

val-exp-l

"True" if value of the field is
not equal to val-exp-l.

val-exp-l

"True" if value of the field is
greater than val-exp-l.

NOT-EQUALJ
-)

I
I

(GREATER-THAN'

field name {GE

} val-exp-l

GREATER-EQUAL

field name \ LT

)

val-exp-l

}
( LESS-THAN'

field name { LE

}

val-exp-l

LESS-EQUAL

field name {BT

} val-exp-l [AND] val-exp-2

BETWEEN

"True" if value of the field is
greater than, or equal to
val-exp-l.
"True" if value of the field is
less than val-exp-l.
"True" if value of the field is
less than or equal to val-exp-l.
"True" if value of the field is
between val-exp-l and
val-exp-2. Val-exp-l must be
less than val-exp-2.

}val-exP-l [AND] val-exp-2

"True" if value of the field is
not between val-exp-l and
val-exp-2. Val-exp-l must be
less than val-exp-2.

field name CONTAINING

val-exp-l

"True" if value of the field
contains val-exp-l.

field name NOT CONTAINING

val-exp-l

"True" if value of the field
does not contain val-exp-l.

field name {NOT BT
NOT BETWEEN

field name IN

table-name

"True" if value of the field is a
code in the table.

field name NOT IN

table-name

"True" if value of the field is
not a code in the table.

ANY

rse

"True" if the record stream is
not empty.

Expressions

6-9

Most of the relational operators compare field values to value expressions.
You can use a prompting value expression instead of a field name. You can
also use a variable name. You cannot use any other value expressions.
DATATRIEVE considers lowercase letters to have a greater value than uppercase letters. Within each case letters are sorted alphabetically, thus "ALBIN"
is less than "AMERICAN".
The relational operator CONTAINING is case insensitive. DATATRIEVE
treats all the characters as uppercase when you use CONTAINING.
The following examples show how to use relational operators which compare
field values to value expressions:
DTR) FIND YACHTS WITH BEAM EQ 9t10t14
[50 records found]

DTR) PRINT CURRENT WITH RIG NE "SLOOP"

MANUFACTURER
EASTWARD
FISHER
GRAMPIAN

MODEL
HO
30
34

RIG

LENGTH
OI.IER
ALL WEIGHT

BEAM

PRICE

MS
KETCH
KETCH

24
30
33

09
09
10

$15t900

BEAM

PRICE

$27,500
$23t950

7tOOO
14t500
12tOOO

$29t875

DTR) PRINT YACHTS WITH LOA BT 30 AND 31

MODEL

RIG

LENGTH
OllER
ALL WEIGHT

ALBIN
BOMBAY
CC

BALLAD
CLIPPER
CORVETTE

SLOOP
SLOOP
SLOOP

30
31
31

7,278
9,400
8t850

11
09

SOLNA CORP

SCAMPI

SLOOP

8t800

MANUFACTURER

DTR> PRINT COUNT OF YACHTS WITH BUILDER CONTAINING "a"
78

DTR) FIND YACHTS WITH LOA

< 20

[2 records found]

The relational operator IN compares a the contents of a field with the codes in
a description table. This is very useful in automatic data validation. The
following example shows you can change the record definition PHONE-REC
to take advantage of this:
DTR) DEFINE RECORD PHONE-REC USING
DFN) 01 PHONE.
DFN)
02 NAME PIC X(20).
DFN)
02 NUMBER PIC 9(7) EDIT-STRING IS XXX-XXXX.
DFN)
02 LOCATION PIC X(9).
DFN)
02 DEPARTMENT PIC XX VALID IF
DFN)
DEPARTMENT IN DEPT-TABLE.
DFN)

6-10

Expressions

The relational operator ANY checks whether a record stream is empty. This is
very useful if you want to work with records in a hierarchy. The record
selection expression following any typically uses a sublist in the hierarchy.
The following examples show how to use ANY. For more information on
hierarchies and lists, see Chapter 15.
DTR) PRINT FAMILIES WITH ANY KIDS WITH AGE
MOTHER

NUMBER
KIDS

KID
NAME

MERIDETH

BEAU
BROOKS
ROBIN
JAY
WREN
JILL
ERIC
CISSY
NANCY
MICHAEL

FATHER
BASIL

JEROME

RUTH

= 20
AGE
28
28
2a
22
17

20
32
2a
22

OTR) PRINT FAMILIES WITH
[LooKin~

for Boolean expression]

DTR> ANY

~:IDS

FATHER
JIM

j..HTH KID-NAME CONTAINING "RALP"
MOTHER

NUMBER
KIDS

KID
NAME

AGE

URSULA
RALPH

ANN

6.2.2 Boolean Operators
There are three Boolean operators: AND, OR, and NOT. AND and OR allow
you to join two or more Boolean expressions together to form a single Boolean
expression. NOT allows you to reverse the value of a Boolean expression.
If you link Boolean expressions with AND, the resulting Boolean expression is

"True" only if all the Booleans linked with AND are "True".
If you link Boolean expressions with OR, the resulting Boolean expression is

"True" if any of the Booleans linked with OR are "True".
If you precede a Boolean expression with NOT, the resulting Boolean expres-

sion is "True" if the Boolean expression following NOT is "False".
The following examples show the use of Boolean operators:
DTR> PRINT YACHTS WITH BUILDER = "PEARSON" AND LOA

MANUFACTURER
PEARSON

MODEL
30

RIG
SLOOP

LENGTH
OI)ER
ALL WEIGHT

BEAM

8,320

PRICE

(continued on next page)

Expressions

6-11

DTR> FIND YACHTS WITH BUILDER = "PEARSON" OR LOA EQ 30
[21

records found]

DTR> READY FAMILIES
DTR> PRINT FAMILIES WITH NOT ANY KIDS

FATHER
ROB

MOTHER
0101

NUMBER
KIDS

KID
NAME

AGE

You can also group Boolean expression using parentheses. DATATRIEVE
evaluates Boolean expressions in parentheses before evaluating other
Booleans. If a Boolean expression contains Boolean operators as well as
parentheses, DATATRIEVE evaluates the Boolean expression in the following
order:
First:

Expressions enclosed in parentheses

Then:

Expressions preceded by NOT

Then:

Expressions combined with AND

Finally:

Expressions combined with OR

The following examples illustrate the use of parentheses and the evaluation of
a compound Boolean expression:

bool-l AND bool-2 AND bool-3

"True" if all three Boolean
expressions are "True."

bool-l AND (bool-2 OR bool-3)

"True" if bool-l is "True"
and either bool-2 or bool-3
is "True."

(bool-l AND bool-2) OR bool-3

"True" if bool-l and
bool-2 are "True" or if
bool-3 is "True."

(bool-l AND bool-2) OR (bool-3 AND bool-4)

"True" if both bool-l and
bool-2 are "True" or if
both bool-3 and bool-4 are
"True."

NOT (bool-l OR bool-2) AND bool-3

"True" if both bool-l and
bool-2 are "False" and
bool-3 is "True".

The following example shows several Boolean operators in the same
statement.
DTR> PRINT YACHTS WITH
[LooK inS for Boolean expression]

DTR> (MODEL

= "BALLAD" AND BUILDER

"ALBIN") OR

[LooK ins for Boolean expression]

DTR> (BUILDER = "TANZER" AND MODEL

28)

(continued on next page)

6-12

Expressions

MANUFACTURER
TANZER
ALBIN

MODEL
28

BALLAD

RIG
SLOOP
SLOOP

LENGTH
OI.IER
ALL WEIGHT
28
30

BEAM

PRICE

10
10

$17t500
$27t500

Gt800
7t27G

6.3 Record Selection Expressions
A record selection expression (or rse) allows you to create a record stream. The
record stream contains only those records that meet your restrictions. The
records can come from a domain, a collection, or a list. You can specify
whether the record stream contains all records that meet your restrictions or
just a few . You can also sort the records in ascending or descending order
according to the contents of one or more fields. The full format of a record
selection expression is:

rlFIRST
ALL
1
(list-name )
nJ [context-var IN] i domain-name t [WITH Boolean-expression]
I collectn-name J

[SORTED BY sort-key-1 [,sort-key-2] ... J
The rse contains one required element and four optional elements. The following sections describe each element.

6.3.1

Specifying the Source of the Records

Only one element is required in, a record selection expression:
list-name
domain -name
collectn-name
This element tells DATATRIEVE what domain, collection, or list to use in
creating the record stream.
You must ready a domain (with the READY command) before using it in an
rse.
To use a collection in an rse, you must first establish the collection (with the
FIND statement).
To use a list in an rse, you must make the record containing the list the
context record (with the FOR statement, the SELECT statement, or another
rse) . Lists and record selection expressions using lists are explained in
Chapter 15.

Expressions

6-13

The following example has three record selection expressions: one using the
domain FAMILIES, one using the cQllection CURRENT, and one using the
list KIDS:
.
DTR> FIND FAMILIES WITH NUMBER-KIDS> 0
[13 records found]

DTR> FOR CURRENT FOR KIDS MODIFY USING AGE= AGE + 1

6.3.2 Specifying the Number of Records
The ALL or FIRST n element specifies how many records are in the record
stream. If you include the element FIRST n, the record stream has n records.
The argument n must be a value expression that represents a positive integer.
If you also specify a sort order in the rse, DATATRIEVE sorts the records
which meet your restrictions first. Then the first n records become the record
stream.
For example:
DTR> PRINT FIRST 3 YACHTS

MANUFACTURER
ALBERG
ALBIN
ALBIN

MODEL
37 MK
78

NALLAD

RIG
KETCH
SLOOP
SLOOP

LENGTH
OI)ER
ALL WEIGHT
37
26
30

20tOOO
Qt200
7t276

BEAM

PRICE

12
10
10

$36t851
$17t800
$27t500

BEAM

PRICE

07
06
07

$3t500
$Qt285

DTR> PRINT FIRST 3 YACHTS SORTED BY LOA

MANUFACTURER

MODEL

RIG

WINDPOWER
CAPE DORY
ENCHILADA

IMPULSE
TYPHOON

SLOOP
SLOOP
SLOOP

LENGTH
OI)ER
ALL WEIGHT
16
18
20

650
1 t800
2t300

If you use the element ALL, or omit this element, the record stream consists of
all records meeting your restrictions. If you use the element FIRST nand n is
greater than the number of records meeting your restrictions, the record
stream consist of all records meeting your restrictions. Thus, the statements
in the following example all have the same result:
DTR> FIND ALL YACHTS
[ 113 records found]

DTR> FIND YACHTS
[113 records found]

DTR> FIND FIRST 200 YACHTS
[113 records found]

6-14

Expressions

6.3.3 Naming a Record Stream
If you include a context variable in the rse, you give the record stream a name.

This allows you to qualify field names more fully. Using context variables to
qualify field names enables you to refer to fields from different record streams
in the same statement.
The following examples show how you can use context variables.
DTR) FIND A IN YACHTS WITH ANY YACHTS ~ITH
[LooKins for Boolean expression]

DTR) BUILDER= A.BUILDER AND MODEL NE A.MODEL
[7G records found]
DTR) PRINT A IN YACHTS WITH ANY B IN YACHTS WITH
[LooK ins for Boolean expression]

DTR) B.TYPE NE A.TYPE AND B.SPECS = A.SPECS

MANUFACTURER
j\ol\f""J T ' C Q r - A k l

I." M 11; .I. UUC.HI'I

CHRIS-CRAF
SCAMPI
SOLNA CORP

MODEL

RIG

LENGTH
Oi.iER
ALL WEIGHT

35
SLOOP
CARIBBEAN SLOOP
30
SLOOP
SCAMPI
SLOOP

35
30
30

i8tOOO
18tOOO
GtGOO
GtGOO

BEAM

PRICE

$37t850
$37,850

11
10

DTR) FOR A IN YACHTS
[LooKins for statement]

DTR) FOR B IN YACHTS WITH BUILDER EQ A.BUILDER AND RIG GT A.RIG
[LooK inS for statement]

DTR) PRINT BUILDERt A.RIGt B.RIG
MANUFACTURER

RIG

AMERICAN
CHALLENGER
CHALLENGER

MS
KETCH
KETCH

SLOOP
SLOOP
SLOOP

PEARSON

KETCH

SLOOP

If you use a context variable in a FIND statement, the context variable be-

comes the collection name. (The collection -actually has two names:
CURRENT and the context variable.)
For example, the following statement establishes a collection containing the
first four records in YACHTS and names the collection NEW-COLLECT:
DTR) FIND FIRST 4 NEW-COLLECT IN YACHTS
[4 records found]

6.3.4 Restricting the Records
The element WITH Boolean-expression restricts the record stream to those
records for which the Boolean expression is true.

Expressions

6-15

For example, the following statement prints only yachts built by Grampian:
DTR> PRINT YACHTS WITH BUILDER EQ "GRAMPIAN"

MANUFACTURER
GRAMPIAN
GRAMPIAN
GRAMPIAN
GRAMPIAN
GRAMPIAN

MODEL

RIG
SLOOP
SLOOP
SLOOP
SLOOP
KETCH

2-34
28
28
30
34

LENGTH
OI.IER
ALL WEIGHT

BEAM

PRICE

11 ,800
5,800
8,900
8,800
12,800

10
08
10
09
10

$29,875
$11,495
$14,475
$17,775
$29,875

34
28
28
30
33

Refer to Section 6.2 for other examples of Boolean expressions and for the
rules for forming Booleans.

6.3.5 Sorting the Records
The SORTED BY element of the rse lets you sort the records based on the
contents of one or more fields. Its full format is:

ASC [ENDING]
DESC [ENDING]
SORTED [BY] [ INCREASING
DECREASING

[ASC [ENDING]
DESC [ENDING]
fld-name-l, INCREASING
DECREASING

.......... ......----.,/

~~--

1
fld-name-2 ...

¥~

\~--""""~""""----'/
¥

sort-key-l

sort-key-2

To sort records, you must specify the keyword SORTED. The keyword BY is
optional; it is included only to preserve English-language-like syntax. You
must specify at least one sort key, which indicates both the order of the sort
and the field to be used in the sort. If you specify a sort order, it can be
ASCENDING (or its synonyms ASC or INCREASING) or DESCENDING (or
its synonyms DESC or DECREASING). The sort order is described in
Appendix F.
If you omit the sort order for the first field, DATATRIEVE sorts the records in
ascending order. If you omit the sort order on the second or subsequent field,
DATATRIEVE uses the preceding sort order (implied or specified) for the
field.

6-16

Expressions

For example, the following statements are equivalent: They all establish a
collection of all records in YACHTS and sort them in ascending order by
builder name:
DTR> FIND YACHTS SORTED BY MANUFACTURER
[113 records found]

DTR> FIND YACHTS SORTED BY ASC MANUFACTURER
[ 113 records found]

DTR> FIND YACHTS SORTED BY INCREASING MANUFACTURER
[113 records found]

You can specify any number of sort keys. If you specify more than one, you
must separate the sort keys with a comma. DATATRIEVE treats the first
field name as the major sort key and successive field names as minor keys. For
instance, the following statement establishes a collection of all records in
YACHTS. The records are sorted in alphabetical order by builder name. If a
builder has more than one record for a yacht, the records are listed in decreas-

DTR> FIND YACHTS SORTED BY BUILDER, DESC PRICE
[113 records found]

Expressions

6-17

Chapter 7
Using the Report Writer

7.1

Introduction
You can produce simple reports with the PRINT and SUM statements, but,
to produce complex reports, use the DATATRIEVE Report Writer.
Like the PRINT statement; the Report Writer selects and formats data; it
also performs statistical functions, including that of the SUM statement. In
addition, it can number the report pages, print the date at the top of each
page, and give you control over several other formatting capabilities. For
example, you can:
1. Print a heading for the report.

2. Set the page size of the report.
3. Print sorted data that is grouped by values in one field and is sorted
within each group by the values in another field.
4. Print headings above groups of sorted data.
5. Print totals, averages, counts, minimums, and maximums below groups of
sorted data.
This chapter describes how to use the Report Writer statements to create
DATATRIEVE reports.

7.2 A Sample DATATRIEVE Report
A DATATRIEVE report looks like a typewritten report; Figure 7-1 IS an
example.

7-1

Figure 7-1: A DAT ATRIEVE Report
PHONE LISTING

report _ _ _~...
header

report
BY
name ----. [ DE PAR TMEN TAN D L0 CAT ION

DEPARTMENT

LOCATION

header line
for control
group

MBl-2/J11

]

date ---. 2 - J IJ 1"1 - 80
page ---. P a 8 e 1
number

NUMBER

BASSETTt JEAN
DUNCANt ANNE
FITE t DAI.lID
SCHNEIDERt ANDY
1.IANK AN AN t I RENE

555-5678
555-8765
555-4567
555-9999
555-9876

detail line - - - - - - - -•• DIETTERICH t DAN

SADLERt BRENT
STARKEYt JIM

555-3232
555-7676
555-9898

HARRISONt ANN

555-2341

LAWLERt M. B.

555-2222

JONESt WAYNE

555-6789

column
header
line

control
group
based on
department
and location

MBl-2/J12

MBl-2/K11

9 EMPLOYEES
PUBLICATIONS
header line ~ MB 1 - 2 / H 3
for control
group

MBl-2/H8

MBl-2/H9
STOKESt RON

555-8888

HAMMONDt BRAD
METESt GEORGE

555-1234
555-3333

control
group
based on
department

MBl-2/J9
summary line
for control
group

L...I---i.~ 5 EMPLOYEES
7.3 Creating a Report Specification
You create a DATATRIEVE report with a series of Report Writer statements.
These control the format and select the content of a report. The order of
statements in a report specification is important; although the order is not
absolutely rigid, errors in the sequence of statements can either prevent the
production of the report or result in a report with a jumbled format.
7-2

Using the Report Writer

7.3.1 Choosing Direct or Indirect Creation of a Report

Speciflcation
You can create a report specification in two ways:
1. Directly, by invoking the Report Writer and entering statements in re-

sponse to its prompts.
2. Indirectly, by putting Report Writer statements into a procedure.
The differences between these two are important. When you work directly
(that is, interactively) with the Report Writer to create report specifications,
responses to your input are immediate. The Report Writer creates the report
as soon as you end the report specification. When you make syntax errors, a
message indicates the problem, and the Report Writer returns you to the
DATATRIEVE command level. These immediate responses are useful for
creating short report specifications.
However, after the Report Writer creates a report or sends you an error message, it does not save the statements you have entered. You cannot run the
same specification again, and you cannot correct syntax errors unless you
retype the whole sequence of report statements. To avoid this repetition,
many users put their report specifications into procedures.
Although writing procedures is discussed in Section 5.9 and Chapter 12, two
points about procedures need to be made here:
1. The form and sequence of report statements in a procedure are identical to

their form and sequence in a report specification that you create
interactively.
2. Putting report specifications in procedures offers you several advantages,
all of which prevent retyping the whole sequence of report statements:
• You can rerun a procedure.
• You can change report specifications to alter the format and content of
reports.
• You can change syntax errors by using the DATATRIEVE Editor (see
Chapter 8) on the faulty report statements.
• You can share procedures with other users.
For each report, you can decide whether to create the report specification
interactively or to put it into a procedure. In either case, the sequence of
report statements and their syntax will be the same.

7.3.2 Invoking the Report Writer
When you are at the DATATRIEVE command level, you can invoke the
Report Writer with the REPORT command.
DTR> REPORT BIG-YACHTS ON YACHTS.LST
RW>

Using the Report Writer

7-3

The RW> prompt shows that the Report Writer is ready to accept the statements of the report specification.
On the other hand, you can call a procedure that contains a report specification with the REPORT command as its first line.
• First, put a report specification into a procedure:
DTR>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DTR>

DEFINE PROCEDURE SAMPLE-REPORT
REPORT BIG-YACHTS ON YACHTS.LST

END-REPORT
END-PROCEDURE

• Then, invoke the Report Writer indirectly by calling the procedure:
DTR> :SAMPLE-REPORT

If the report specification contains any prompts, the Report Writer prompts

you for the needed information. Then, if you have directed the output of the
report to your terminal, the formatted text is displayed as directed. If you
have directed the output to a file or another device, the Report Writer
returns you to the DATATRIEVE command level, and you see the DTR>
prompt.
In summary, the DATATRIEVE REPORT command invokes the Report
Writer. Remember, whether entered directly as a response to DTR> prompts
or indirectly as part of a procedure, the REPORT command must be the first
entry in the report specification.

7.3.3 The Order and Function of Report Statements An Overview
The following list gives a brief overview of the REPORT command and each
Report Writer statement; the list follows the normal order of statements in a
report specification.
Note that AT and SET statements can be entered both before and after the
PRINT statement. Each report statement is fully described in Section 7.4.
1. REPORT

Always begin a report specification with a REPORT command. You enter
it in response to the DTR> prompt at the DATATRIEVE command level
or put it as the first entry of a report specification in a procedure. The
REPORT command invokes the.Report Writer, and it is part of the report
specification. With REPORT you specify the data you want to report and
the file or device for output. The default data for the report is your current.
collection, and the default output device is your terminal.

7-4

Using the Report Writer

2. SET
Use SET to specify the report header, which consists of the report name,
the page number, and the date. Also use SET to specify the length and
width of the report pages and to limit the maximum number of lines and
pages a report. With SET you can suppress the date and the page number
in the report header. Section 7.4.2 explains the defaults and options of the
SET statement. The Report Writer supplies default values for page-size,
date, and number of lines per page, and it sets no limits to the number of
lines or pages in a report. However, you must always specify a report
name. If you omit the SET REPORT-NAME statement, the Report
Writer prompts you for one before creating the report. You can suppress
the report name only by setting it equal to one or more spaces.
3. AT

The AT statement contains most of the special features that set the
Report Writer apart from the PRINT statement used at the
DATATRIEVE command level. In addition to these special features, the
AT statement contains a PRINT clause that resembles the PRINT statement used at the DATATRIEVE command level.
The AT statement has two forms: AT TOP and AT BOTTOM. Use AT
TOP statements to print either header lines or summary lines at the tops
of reports, pages, and control groups. (See the next section for a description of control groups and their uses.) These lines can contain values and
text, including special column headers.
The AT BOTTOM statement resembles AT TOP, but you use it to print
summary lines at the bottoms of reports, pages, and control groups. In
reports you can use the statistical functions in AT BOTTOM statements.
You can also specify special column headers for values you want to include
in the summary lines. To create a report specification for a summary
report, use an AT BOTTOM statement and omit the Report Writer
PRINT statement.
Both forms of the AT statement allow you to control the formats of headers and summary lines. You can include several AT statements in a report
specification, or you can 'leave them out.
4. PRINT
The Report Writer PRINT statement is similar to the PRINT statement
used at the DATATRIEVE command level. Use PRINT to specify the
format of the reported data. With the PRINT statement you specify two
report parts: the column headers, which are printed above the data, and
the detail lines, which contain the information you want to report and
which may be values, text, or a mixture of both. You can include only one
PRINT statement in a report specification, but you can leave out the
PRINT statement if your specification includes an AT statement.

Using the Report Writer

7-5

5. AT
If your report specification contains a PRINT statement, you can enter AT
statements both before and after the PRINT statement.

NOTE
Every report specification must include at least one PRINT
statement or one AT statement. Each specification can
contain only one PRINT statement, but you can include
several AT statements in the same specification. If you use
an AT BOTTOM statement in a report specification without a PRINT statement, you will produce a summary
report, not a fully detailed one.
6. SET
You can put SET statements anywhere in a report specification between
the REPORT command and the END-REPORT statement.
7. END-REPORT

To end a report specification, you must use END-REPORT as your last
report statement. If your report specification contains no syntax errors,
the Report Writer begins to create the report after you enter the
END-REPORT statement. The Report Writer prompts you for any values
it may need and then directs the report to the file or output device you
have specified.

7.3.4 Using Control Groups
With the Report Writer you can divide collections of sorted data into control
groups. A control group is a series of sorted data records that all have the same
value in at least one field. For example:
The domain YACHTS contains eleven boats with LENGTH-OVER-ALL
(LOA) of 36 or 37. Those boats have:
.. Two values for BEAN!: 11 and 12
• Two values for RIG: KETCH AND SLOOP
If you sort these eleven boats by BEAM, you form two control groups:

• One of six boats with BEAM = 11
.. One of five boats with BEAM = 12
If you sort the first control group of six boats by the key field LOA, you form
two more control groups:

• One of two boats with LOA = 36 (and BEAM = 11)
• One of four boats with LOA = 37 (and BEAM = 11)

7-6

Using the Report Writer

This second control group (with BEAM = 11 and LOA = 37) can be further
divided into two control groups:
• KETCHES (BEAM = 11, LOA = 37)
• SLOOPS (BEAM = 11, LOA = 37)
This example shows that you can nest control groups; that is, you can form
control groups inside other control groups. You form these nested control
groups by using one or more key fields to sort your data.
You can establish the sort order of your data with the REPORT command;
however, you can sort the data with the DATATRIEVE SORT command or
with a sort utility outside of DATATRIEVE. If the data has been sorted prior
to entering the report specification, the Report Writer makes the breaks between control groups just as though you had established the sort order with
the REPORT command. (See Section 7.4.4, Usage Note 3.)
Control groups give you a useful way of dividing data in a report. With the AT
r-r'nD
........ r:J Ar-r' ..LJ'-J..L..L
onr-r'r-r'nl\/f
",f- ... f-o~n ..... f-" .......... ron ..... ,.,.~; ..... f- f-,...",f- ... n1 .. ,...<'O
n ..... .rl h,...n.rl,... ... "
..L '-J..L
U~~U":1...L
'-J~'f..L
'::",JutJ'"'~~~\;;~~tJ'"
~ vu
",a~~
'p.L.L.L~tJ
tJ\;;AtJ,
va.LU\;;"', a.L.LU .L.Lvauv.Li:)

above and below each nested control group. The following example shows a
report specification and report that divides 36 and 37 foot yachts into control
groups based on BEAM, LOA, and RIG (the Report Writer prompt for line
continuation have been omitted from this and succeeding examples):
DTR
DTR

READY YACHTS
FIND YACHTS WITH LOA BETWEEN 36 AND 37

DTR

REPORT CURRENT SORTED BY BEAM, LOA, RIG

RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>
RW>

SET REPORT-NAME = "YACHTS WITH LENGTH-OI.JER-ALL"j
"OF 36 AND 37 FEET"
AT TOP OF BEAM PRINT COL 1, "BEAM = ", COL 7, BEAM
AT TOP OF LOA PRINT COL 12, "LENGTH = ", COL 20, LOA, SKIP
PRINT BUILDER, RIG, DISP
AT BOTTOM OF RIG PRINT SKIP, COL 4, "NUMBER OF ", COL Ul,
LOA (" "), COL 1 7, "FOOT ", COL 22, RIG, COL 28,
"W I TH BEAM OF ", COL 40, BEAM # COL 43, " = ", COL 46,
COUNT USING ZS, SKIP
AT BOTTOM OF REPORT PRINT SKIP, "LIGHTEST = ", MIN (DISP),
SKIP, "HEAI.JIEST = ", MA}-{ (DISP), SKIP,
"AI.JERAGE WE I GHT OF ALL BOATS = ", AI.JERAGE (0 I SP)
SET DATE = "DD-MMM-YY"
SET COLUMNS-PAGE = 60
END-REPORT

(continued on next page)

U sing the Report Writer

7-7

YACHTS WITH LENGTH-OVER-ALL
OF 38 AND 37 FEET
DD-MMM-YY
Paae 1

LENGTH
Ol.JER
ALL

BEAM

MANUFACTURER

RIG

WEIGHT

PEARSON

KETCH

17,700

BEAM = 11
LENGTH = ," 38

NUMBER OF 38 FOOT KETCH WITH BEAM OF 11 = 1
ISLANDER

SLOOP

13,Ll50

NUMBER OF 38 FOOT SLOOP WITH BEAM OF 11 = 1
LENGTH = 37
IRWIN
NORTHERN

KETCH
KETCH

20,000
lLl,OOO

NUMBER OF 37 FOOT KETCH WITH BEAM OF 11 = 2
PEARSON
ROBERTS
NUMBER OF 37 FOOT SLOOP WITH BEAM OF 11

SLOOP
SLOOP

13,500
lLl,750

BEAM = 12
LENGTH

I • TRADER

KETCH

18,800

NUMBER OF 38 FOOT KETCH WITH BEAM OF 12 = 1
CABOT
ERICSON
NUMBER OF 38 FOOT SLOOP WITH BEAM OF 12

SLOOP
SLOOP

15,000
18,000

LENGTH = 37
ALBERG
FISHER
NUMBER OF 37 FOOT KETCH WITH BEAM OF 12
LIGHTEST
HEAl.JI EST
AVERAGE WEIGHT OF ALL BOATS

7-8

Using the Report Writer

I'~ETCH

KETCH

30,000

13,Li50
30,000
17,5Li5

7 . 4 Report Writer Statements
This section describes the statements that make up a report specification.

7.4.1

REPORT Command

Function

The REPORT command invokes the Report Writer and is the first entry in a
report specification. In the REPORT statement you specify:
1. The data you want to report.
2. The output device for the report.
After you enter the REPORT command, the RW> prompt shows that the
Report Writer is ready to accept the statements of a report specification.
Format
REPORT [rse]

rI (

dev:
ON J. file-spec
L ( *.prompt-name)

l I
J

Arguments

rse
Specifies the data for your report. To create a collection for your report,
enter the appropriate record selection expression in the REPORT command. You can make reports on the following kinds of data:
• Readied domains
• Collections
• Lists
When you omit the rse, the Report Writer uses the data in your current
collection for the report. If you omit the rse and you have no current
collection, the Report Writer tells you there is no current collection only
after you have entered the entire report specification.
For detailed information on the record selection expression, see Chapter 6.
For information on lists, see Chapter 15.
dev:
Specifies the output device for your report. By specifying a device name in
the REPORT command, you can tell the Report Writer to send the report
to any system device to which you have access, such as a line printer, a
tape drive, or your own terminal.
•
To specify an output device for a report:
• A line printer:
OTR) REPORT [rse] ON LP:

Using the Report Writer

7-9

On RSTS/E systems, if you specify the line printer for output and it is
busy, the Report Writer may not produce the report. Furthermore, the
Report Writer does not save the report specification when the line printer
is busy, and you must reenter the report specification. If no report is
produced for this reason, you may have to consult with your system manager to work around the problem. To save yourself from retyping report
specifications, put them into procedures.
• A tape drive:
OTR> REPORT [rse] ON mmn:file-spec

where:
mmn
tape drive number
file-spec = the specification of the destination file
Before specifying the tape drive as the output device for your report, you
must mount your tape and assign the tape drive to your task or process.
• Your own terminal:
OTR> REPORT [rse] ON TI:

You can specify you own terminal as the output device by entering TI: as
the device name. Because your terminal is the default output device, you
do not need to specify it explicitly.
file-spec
Specifies a disk file for the output of the report. By supplying a file specification in the REPORT command, you tell the Report Writer to send the
report to a disk file. Putting a report in a disk file allows you to revise the
text, to print multiple copies of your report, or to direct your output to the
printer at another time.
To specify a disk file for output of a report:
• In your own directory:
OTR> REPORT [rse] ON YACHTS.LST

• In another user's directory:
DTR> REPORT [rseJ ON ddn:[ufdJYACHTS.LST

where:
ddn
ufd

7-1 0

Using the Report Writer

disk drive number
user file directory

You must have access privilege to the destination directory.
To revise your report, use a text editor to make the necessary changes to
your disk file.
To print multiple copies of your report, supply the REPORT command
with a file specification for the output of the report:
DTR) REPORT ON YACHTS.LST.

After you exit from DATATRIEVE, print the file using your operating
system routines and specify the number of copies you want.
*.prompt-name
Specifies the text of a prompt for a device name or file specification. If you
supply *.prompt-name in the REPORT command, the Report \Vriter
prompts you for an output file-spec or device name after you enter the
El~D- REPORT statement:
DTR> REPORT [rse] ON *."FILE-SPEC OR DE1nCE NAME"
RW>
RW>
RW>
RW>
END-REPORT
Enter FILE-SPEC OR DEVICE NAME:

When the Report Writer prompts you, it supplies the word "Enter". Make
the text of your prompt-name a word or phrase that completes the
prompt's request:
• Wrong:

Result:
• Right:

Result:

DT R > REP 0 RTON *." P LEA S E SUP PLY F I L E - S P E C "

RW>
END-REPORT
Enter PLEASE SUPPLY FILE-SPEC:
DTR> REPORT ON *.FILE-SPEC

RW>
END-REPORT
Enter FILE-SPEC:

Using the Report Writer

7-11

If your prompt-name contains any spaces, you must enclose it in quotation

marks. For example:
• Wrong:
Result:
• Right:

DTR> REP 0 RTON *. F I LE - S PECOR DE In CE NAME
Expected end of report statelTlent, encountered "OR"
DTR> REPORT ON *."FILE SPECIFICATION OR DE1nCE NAME"

RW>

Result:

END-REPORT

Enter FILE SPECIFICATION OR DElnCE NAME

When you do not specify an output device in the REPORT command, the
Report Writer displays the report on your terminal.
You can specify only one output device in a REPORT command.
Examples

DTR> REPORT YACHTS WITH PRICE NE 0 SORTED BY
DTR> RIG ON RIG.LST

2. DTR> REPORT ALL YACHTS WITH BUILDER = "PEARSON" AND RIG
DTR> NE "KETCH" SORTED BY DESCEND I NG BEAM t DEBC LOA ON T I:

i-12

DTR> REPORT FIRST 10 YACHTS WITH RIG = "KETCH"DTR> SORTED BY BEAM t PRICE ON *. "DEI,IICE NAME"

Using the Report Writer

7.4.2 SET Statement
Function

The Report Writer SET statement produces the report header and defines the
size of report pages and the length of the report. In a SET statement you can
specify:
1. Report header

• Report name
• Date
• Format of date
• Page numbering
2. Size of report pages
• Number of columns per page
• Number of lines per page
3. Length of report
• Maximum number of lines
• Maximum number of pages
Format

SET

REPORT-NAME = "string-I" [/"string-2"] ...
DATE [ = "string"]
NO DATE
NUMBER
NO NUMBER
COLUMNS-PAGE =
LINES-PAGE =
MAX-LINES =
{ :. prompt-name}
MIN-LINES =

[, ... ]

Arguments

REPORT-NAME = "string-I" [/"string-2"1 ...
Specifies the name of your report. The report name consists of one or more
lines of text, and the Report Writer centers this name at the top of each
page of the report. You must enclose the report name in quotation marks:
RiAl> SET REPORT-NAME = IILISTING OF BOATS BY LENGTH AND TYPE II

Result:

LISTING OF BOATS BY LENGTH AND TYPE

Using the Report Writer

7-13

To produce a report name of two or more lines, enclose each line of the
report name in quotation marks and separate each segment of the name
by slashes (/):
RW> SET REPORT-NAME = "LISTING OF BOATS"j"BY"j"LENGTH AND TYPE"

Result:

LIST I NG OF BOATS
BY
LENGTH AND TYPE

If you omit the SET REPORT-NAME statement from the report specification, the Report Writer prompts you for a report name after you enter
the END-REPORT statement:
RW> END-REPORT
Enter REPORT-NAME:

When you respond to this prompt, follow the above rules for the use of
quotation marks and slashes in report names.
To produce a report with no name, set the report name equal to one or
more spaces:
RW>

SET REPORT-NAME

or
Enter

REPORT-NAME:

There is no default report name.
DATE [= "string"]
Can be used to specify a date in the top right corner of each report page.
When you specify a string in the SET DATE statement, you can choose
any format for the date. You can also use the SET DATE statement to
print any single line string in the top right corner of each report page. The
string does not have to contain a date:
RW>

SET

Result:

DATE

= "22 MAR 1981"

22 MAR

1981

RW> SET DATE = "TUESDAYt MARCH i4TH"

Result:
RW>

TUESDAY t

SET DATE

Result:

MARCH

laTH

= "COMPANY CONFIDENTIAL"

COMPANY CONF I DENT I AL

If you supply no string or omit the SET DATE statement from the report
specification, the default value is the current system date in the format
DD-MMM-YY (21-Jan-81).

7-14

Using the Report Writer

NO DATE
Suppresses the printing of a date in the to-P right cn-rner of each report
page. If you put the SET NO DATE statement in a report specification,
either before or after a SET DATE statement, the SET NO DATE takes
precedence, and the string from the SET DATE statement is not printed.
NUMBER
Prints the page numbers in the top right corner of the report page, below
the date or the string you specify in a SET DATE statement. If the report
specification contains a SET NO DATE statement, the page number is
printed by itself in the top right corner of each report page:
RW> SET NUMBER
RW> SET DATE

Result:

22-Mar-81
Pase 1

RL·D· SET NO DATE

RW> SET NUMBER

Result:

Pase 1

Because the Report Writer numbers the pages whether or not you supply a
SET NUMBER statement, you never need put SET NUMBER in a report
s pecification.
NO NUMBER
Suppresses the printing of page numbers in the top right corner of each
report page. If you put SET NO NUMBER in a report specification, either
before or after a SET NUMBER statement, the SET NO NUMBER statement takes precedence, and no page numbers are printed.
COLUMNS-PAGE = { ~.prompt-name }
Specifies the width of the report page in columns. The value n is the
number of columns per page. It must be an unsigned integer one greater
than the length of the longest field in the record definition of the data you
want to report. For example, in YACHTS the longest field is BUILDER
with a field length of 10. You must set COLUMNS-PAGE = 11 to print a
report containing the field BUILDER as the longest field. The maximum
value for COLUMNS-PAGE is 255.
If you use * .prompt-name in place of the unsigned integer n, the Report
Writer prompts you for a COLUMNS-PAGE value after you enter an
END-REPORT statement:
RW>

SET COLUMNS-PAGE = *.COL-PAGE

Result:

Enter COL-PAGE:

If you omit a SET COLUMNS-PAGE statement from your report specification, the default value for your report is the COLUMNS-PAGE value of
the DATATRIEVE command level at the time the report is produced. If
you have not specified a COLUMNS-PAGE value at the DATATRIEVE
command level, the default value is the one set when your DATATRIEVE
Using the Report Writer

7-15

system was installed. Ask your DATATRIEVE system manager for the
default COLUMNS-PAGE value.

{~.prompt-name}

LINES-PAGE =
Specifies the number of lines per report page. To print more than one
detail line per report page, the value n must be an unsigned integer greater
than the total number of lines in the report header, the column-headers,
the first detail line, the summary line, and the blank lines following the
report header and the colurnn headers. Each of these components can
have more than one line, depending on the formats you specify in the
appropriate Report Writer statements. Do not count the blank lines you
specify with SKIP [n] in PRINT or AT statements. The count of a simple
report follows.
Here is the report specification:
DTR>
DTR>
DTR>
RW>
RW>
RW>
RW>
RW>
RW>
RW>

READY YACHTS
FIND YACHTS WITH BUILDER
"ALBIN"
REPORT
SET DATE = "21-0CT-81"
SET COLUMNS-PAGE = ao
SET REPORT-NAME = "YACHTS"j"BY"j"ALBIN"
PRINT RIG, LOA, PRICE("SUGGESTED"j"PRICE")
AT BOTTOM OF REPORT PRINT SKIP, "BUY ONE TODAY!"
SET LINES-PAGE = 13
END-REPORT

The appropriate lines for a report with one record per page are numbered
at the right:
YACHTS
BY
ALBIN

RIG

LENGTH
OI.JER
ALL

SLOOP
SLOOP
SLOOP

28
27
30

BUY ONE TODAY

21-0CT-81
Pase 1

SUGGESTED
PRICE
$17,900
$18t800

$27t500

1
2
3
4
5
6
7
8
9
10
(Not second record)
(Not third record)
(Not this SKIP line)
11

• SET LINES-PAGE = 13 or greater produces a one-page report with all
three records.
• SET LINES-PAGE = 12 produces a two-page report with two records on
the first page and one on the second.
• SET LINES-PAGE = 11 produces a three-page report with one record
per page.
If you omit a SET LINES-PAGE statement from your report specification, the default value is 60 lines per page.

7-16

Using the Report Writer

If you put two or more SET LINES-PAGE statements in a report specification, the last one takes precedence.
If your report contains a list as an element in a PRINT statement or an AT
statement, the entire list is counted as one detail line. Consequently, a
report that prints a list may overflow the report page.

The upper limit of the value you can assign to n is 32,767.
If you use *.prompt-name in place of the unsigned integer n, the Report
Writer prompts you for a LINES-PAGE value after you enter an
END-REPORT statement.
RW>

SET LINES-PAGE

Result:

= *.LINES-PG

Enter LINES-PG

{~.prompt-name}

MAX-LINES =
Specifies the maximum limit on the number of lines in your report. The
value n should be an unsigned integer. The Report Writer counts all lines
of the report, including the blank lines and the form feeds (one at the top
of each page and one at the bottom of the report). The upper limit of the
value you can assign to n is 32,767.
The SET MAX-LINES statement can prevent any infinite loops in report
specifications from tying up system resources. The Report Writer truncates the report when the number of lines in the output equals the number
you have specified in the SET MAX-LINES statement. When the report
exceeds the specified limit, you receive this message:
MaxiMUM nUMber of lines exceeded-report aborted
Execution failed
DTR>

When the report exceeds the maximum nu~ber of lines, the truncated
report is displayed on your terminal or sent to the file or device you have
specified in the REPORT command. If you have specified a disk file for
the output, the Report Writer sends only the truncated report to the file
and does not include the error message noted above.
If you put two or more SET MAX-LINES statements in a report specification, the last one takes precedence.

You can use *.prompt-name in place of the unsigned integer n, and the
Report Writer will prompt you for a MAX-LINES value after you enter an
END-REPORT statement.
RW>

SET MAX-LINES

Result:

= *.MAX-LINES

Enter MAX-LINES:

={~.prompt-name}

MAX-PAGES
Specifies the maximum limit on the number of pages in your report. The
value n should be an unsigned integer. The upper limit of the value you
can assign to n is 32,767.
Using the Report Writer

7-17

The SET MAX-PAGES statement can also prevent any infinite loops in
report specifications from tying up system resources. The Report Writer
truncates the report when the number of pages in the output equals the
number you have specified in the SET MAX-PAGES statement. When
the report exceeds the specified limit, you receive this message:
MaxiMUM nUMber of pales exceeded-report aborted
Execution failed
DTR>

When the report exceeds the maximum number of pages, the truncated
report is displayed on your screen or sent to the file or device you have
specified in the REPORT command. If you have specified a disk file for
the output, the Report Writer sends only the truncated report to the file
and does not include the error message noted above.
If you put two or more SET MAX-PAGES statements in a report specification, the last one takes precedence.

You can use *.prompt-name in place of the unsigned integer n, and the
Report Writer will prompt you for a MAX-PAGES value after you enter
an END-REPORT statement.
RW>

SET MAX-PAGES = *.MAX-PAGES

Result:

Enter MA>~-PAGES:

7.4.3 PRINT Statement
Function

The Report Writer PRINT statement specifies the format for the detail lines
in a report. Detail lines are the formatted data lines of a report. With PRINT
you specify three characteristics of the detail lines:
1. The content of the detail lines
• Values of data fields from records in the current collection or in the
record stream specified by the rse in the REPORT command
• Other desired values and text strings
2. The format of the fields in the detail lines
• Position within the line
• Edit-string for each field
3. The column headers for the fields in the detail line
The Report Writer PRINT statement produces a detail line in the report for
every data record in the current collection or in the record stream. A detail
line can cover several lines on the report page, depending on the format and
columns per page you specify.
7-18

Using the Report Writer

You can include only one PRINT statement in a report specification. If the
specification contains no AT statements, then it must contain a PRINT statement. If your report specification contains an AT statement, then it does not
have to contain a PRINT statement.
Format
PRINT print-list-element-l [,print-list-element-2l ...

Arguments

print-list-element
Specifies the data, its position and format, in the detail line. Table 5-5
describes the available print-list elements in detail. Of the elements listed
in that table, only TAB [n] cannot be used in a Report Writer PRINT
statement.
Unlike the PRINT statement used at the DAT ATRIEVE command level,
the Report Writer PRINT statement must be followed by at least one
print-list element. If you enter PRINT without a print-list element, the
Report Writer prompts you for one:
RW>

[Look ins for a value expression]

The print-list elements you can specify include field names (including
COMPUTED BY fields), value expressions, character strings, and horizontal and vertical spacing instructions.
Usage Notes

1. When the data you are reporting includes a list, use an inner print-list in

the PRINT statement to specify a format for the list. The format of the list
can differ from that of the rest of the data. For details on specifying an
inner print-list, see Section 5.29 on the PRINT statement us~d at the
DATATRIEVE command level. The rules described there also apply to
inner print-lists in the Report Writer PRINT statement.
2. For each data record in the current collection, the Report Writer produces
the detail line by using the print-list elements in the same left-to-right
order you specify.
3. If you specify a group field name as a print-list element, the Report Writer
includes all fields of the group field in the detail line. The order of those
fields follows that in the record definition, and the Report Writer spaces
the fields evenly across the page. If the value of COLUMNS-PAGE is too
small to accommodate all the fields, the Report Writer carries the overflow
fields onto the next line. No field is split between lines, but the column
headers of the overflow fields can be lost.
4. If the detail line occupies more than one line in the report, the Report
Writer checks ahead to make sure that all the lines of the detail line can
be accommodated on the page. If there is not enough room for the whole
unit, the Report Writer carries all the lines of the detail line over to the

Using the Report Writer

7-19

next page, ignoring the LINES-PAGE value. Lists are exceptions; regardless of length they are counted as one line, and can overflow the report
page.
5. If you do not specify a column header for a field in the PRINT statement,
the header is the field name from the record definition of the data in the
current collection or record stream. The query header, if the record definition contains one, is used as the column header, unless you explicitly
define an alternative.
6. To print all the fields of the data in the current collection or record
stream, specify in the print-list the most inclusive group field name (the
group field name with the lowest level number in the record definition).
For example, in the record definition for YACHT, BOAT is the most
inclusive group field:
RECORD YACHT
USING
01 BOAT

To print all the fields in YACHT, enter the following statement in your
report specification:
RW>

PRINT BOAT

7. If you do not specify positions or edit-strings for any of the fields in a
detail line, the Report Writer determines the format for those fields using
these criteria:
• If the record definition contains an edit-string for the field, that editstring determines the format for the field.
• If the record definition has no edit-string for the field, the picture clause
determines the format for the field.
• If the record definition has neither an edit-string nor a picture clause for
the field, the the Report Writer invents a picture clause to accommodate
the data in the field. For instance, in the AT BOTTOM statement, the
Report Writer invents a picture for values supplied by the statistical
function TOTAL, but the picture has no commas and is four digits
longer than the picture of the field whose values it adds. To gain full
control over the formats of the fields of your detail lines, explicitly
define edit-strings with the USING edit-string modifier.

8. In formatting the detai1line, you are not restricted to the order of fields
specified in the record definition, You can specify a different order of fields
by listing the fields (and their column headers and edit-strings) in the
PRINT statement in the desired order. You can also change the order of
fields by interspersing value expressions between fields from the records in
the current collection.

7-20

Using the Report Writer

9. You can use SKIP [nl, SPACE [nl, and COL n in the Report Writer to
specify the position of fields on the report page. Use COL n, not SPACE
[nl, to position the print-list element first specified in the PRINT
statement.
Examples

1. Print the BUILDER, MODEL, DISP, and PRICE fields in the default
format. The column header for BUILDER will be MANUFACTURER
(the field name), and for DISP will be WEIGHT (the query header for the
field) :
RW>

PRINT BUILDER, MODEL, DISP, PRICE

2. Print nine spaces, the fields PRICE and DISP, then the result of the value
expression PRICEIDISP under the heading PRICE PER POUND.
RW>
RW>

PRINT COL 8t DISP, PRICE,
PRICE/DISP ("PRICE PER POUND") USING $ZZ,ZZZ.99

3. Print the model, current price, and a new price 10% higher than the
current price, and print the column headers CURRENT PRICE and
SUGGESTED PRICE each on two lines:

RW>

PRINT MODEL, PRICE( "CURRENT"/"PRICE") ,PRICE*l. 1 ("SUGGESTED"/"PRICE")

7 .4.4 AT Statement
Function

The AT statement prints header and summary lines at the tops and bottoms
of units of sorted data:
• The AT TOP statement prints header or summary lines at the top of reports, report pages, and control groups (see Section 7.3.4 for details on using
control groups). You can include values, text, and special column headers in
these header or summary lines.
• The AT BOTTOM statement prints summary lines at the bottoms of reports, report pages,and control groups. You can include values, text, special
column headers, and statistical values in these summary lines.
For these header and summary lines, you can also specify the following with
the two forms of the AT statement:
• Position of fields within the lines
• Format of fields within the lines

Using the Report Writer

7-21

Format

AT TOP OF

REPORT
PAGE
fld-name

header-element-l
[,header-element-21 ...
summary-element-l [,summary-element-21 ...

AT BOTTOM OF

REPORT
PAGE
fld-name

summary-element-l

[,summary-element-21 ...

Arguments

REPORT
1. In an AT TOP statement, prints the header or summary line at the top
of the first page of the report.

2. In an AT BOTTOM statement, prints the summary line at the bottom
of the last page of the report.
PAGE
1. In an AT TOP statement, prints the header or summary line at the top
of each page of the report.
2. In an AT BOTTOM statement, prints the summary line at the bottom

of each page of the report.
fld-name
1. In an AT TOP statement, prints the header or summary line at the top
of the control group for which the field-name is the sort-key.
2. In an AT BOTTOM statement, prints the summary line at the bottom

of the control group for which the field-name is the sort-key.
header-element
summary-element
Specify the content, format, and position of the fields printed by the AT
TOP and AT BOTTOM statements. These elements form three
categories:
1. Elements you can use in both Report Writer AT statements, as well as
the Report Writer PRINT statement and the PRINT statement used
at the DATATRIEVE command level. These elements are fully described in Table 5-5:

• fld-name [modifier]
• val-exp [modifier]
• COL n
• SPACE [n]

• SKIP [n]
• NEW-PAGE

7-22

Using the Report Writer

Do not use SPACE [n] as the first header- or summary-element; use
COL n instead.
When you specify NEW-PAGE to start a new report page, and the
Report Writer prints the header line and summary lines specified by
the AT TOP OF PAGE and AT BOTTOM OF PAGE statements (if
either has been included in the report specification). If neither statement is present, the Report Writer prints the report header and column headers specified by other statements in the report specification.

2. Elements you can use only in the Report Writer AT statements:
• NEW-SECTION
Starts a new report page and starts a new sequence of page numbers,
the new page being number one.

• REPORT-HEADER
"O
... ; ..... f-" fohn
n ..... f-; ... n ... n ....""' ... f- hnnrln...
; ..... nl"rI; ..... n.J.. .L.L.L.L\I"
\I.L.l~
y.L.l\l.L.L'-' .LvpV.L \I .l.l,-,uu.'-'.L,
.L.l.l'-'.LUU..l.L"'6

... n-nA ... f-

"''''pv'''''

..... a ......... a

.................... " ' ,

rI
ata
u. ..... " ' " ,

a ..... rI

........... u.

page number.
• COLUl\1N-HEADER
Prints the column headers as defined by the PRINT statement and
the AT statements.
3. Elements you can use in AT and PRINT statements, but have effects
in AT BOTTOM statements that differ from those in the AT TOP and
PRINT statements. You have greater control over these statistical
functions in AT BOTTOM statements than in AT TOP or PRINT
statements:
• COUNT
In AT BOTTOM, prints the number of detail lines in the report,
report page, or control group specified in the statement.
In AT TOP and PRINT, prints the number of data records in the
current collection, regardless of the number of detail lines in the unit
of sorted data specified in the AT TOP statement, or, for the PRINT
statement, regardless of the number of detail lines on a report page
determined by the PRINT statement.
• TOTAL [val-exp]
In AT BOTTOM, prints the total of the value expressions for the
unit of sorted data specified in the statement. (See Chapter 6 for
detailed information on value expressions.)
In AT TOP and PRINT, prints the total of the value expressions for
the current collection, regardless of the totals of the value expressions in the specified units of sorted data.

Using the Report Writer

7-23

• AVERAGE [val-exp]
In AT BOTTOM, prints the average of the value expressions for the
unit of sorted data specified in the statement.
In AT TOP and PRINT, prints the average of the value expressions
for the current collection, regardless of the average of the value expressions in the specified units of sorted data.
• IvIAX lval-exp]
In AT BOTTOM, prints the maximum of the value expressions for
the unit of sorted data specified in the statement.
In AT TOP and PRINT, prints the maximum of the value expressions for the current collection, regardless of the maximum of the
value expressions in the specified units of sorted data.
• MIN [val-exp]
In AT BOTTOM, prints the minimum of the value expressions for
the unit of sorted data specified in the statement.
In AT TOP and PRINT, prints the minimum of the value expressions for the current collection, regardless of the minimum of the
value expressions in the specified units of sorted data.
If you include a statistical element in a PRINT statement, every detail
line in the report will contain the same value in the field specified for
that element.

When you include a statistical element in an AT st~tement, the desired value will be printed in the same column as the values upon
which it acts. The format of the statistical value will be the same as
that specified by the picture clause or edit-string associated with the
value's field. However, the statistical value may not fit the picture or
edit-string of that field, or the picture or edit-string explicitly specified
for the statistical value may be to long to fit under the appropriate
column, and your report may be produced with a jumbled format.
Statistical value for value expressions not included in the PRINT
statement are printed in new columns. No special column header is
printed unless you specify one. When you specify a column header,
make sure there is room for it on the column header line. If the special
header does not fit, it is suppressed.
The value determined by COUNT is centered under the next available
detail field to the right. You can position the value for COUNT where
you want it by assigning its position with a COL n and by giving it an
edit-string. Assigning its position with a COL n alone is not sufficient;
without the accompanying USING edit=string, the COL n is ignored.

7-24

Using the Report Writer

Usage Notes

1. The AT TOP OF REPORT suppresses the report header and the column
headers on the first page of the report. You can use this statement to print
a special header for the first page of the report or to produce a title page.
To create a title page, specify the format and content of the page by a
series of header-elements, and end the statement with a NEW-SECTION
element. This last element shifts the report to a new page and begins
numbering the pages of the report from that point on.
To print the report header and column header line specified by the other
Report Writer statements, include REPORT-HEADER and
COLUMN-HEADER in the list of header-elements in the AT TOP OF
REPORT statement.
A page header printed by an AT TOP OF PAGE statement replaces the
report header and column header on all pages. To print the report header
and column header line in addition to the special header produced with
the AT TOP OF PAGE statement, include REPORT-HEADER and
COLUIV!~~~HEADER in the list of header-elements in the AT TOP OF
PAGE statement.
2. The AT TOP OF rse and AT BOTTOM OF rse statements print summary
lines at the top or bottom of control groups. A control group consists of a
series of sorted data records that all have the same value in in at least one
specified field. For a discussion of control groups in reports, see Section
7.3.4.
The rse you specify in the AT TOP OF rse and AT BOTTOM OF rse
statements is the name of the control group, and should be a sort-key.
When you specify AT TOP OF rse PRINT fld-name, the Report Writer
prints the value in the specified field of the first detail line in the control
group. When you specify AT BOTTOM OF rse PRINT fld-name, the
Report Writer prints the value in the specified field of the last detail line
in the control group. The following is an example of a report specification and report using an AT TOP OF rse PRINT fld-name and an AT
BOTTOM OF rse PRINT fld-name. Note also that the AVERAGE (DISP)
prints the average for the whole collection, not that of the control groups:
DTR>
DTR>
DTR>
RW>
RW>
RW>
RW>
RW>

READY YACHTS
FIND YACHTS WITH BUILDER = "PEARSON"
REPORT FIRST 9 OF CURRENT SORTED BY BEAMt LOA
ATTOP OF BEAM PRINT SKIP t COL 1 t "SHORTEST = "t COL 12 t
LOA USING ZZ9 t SPACE t "FT"
AT BOTTOM OF BEAM PR I NT COL 1 t "LONGEST =" t COL 12 t
LOA USING ZZ9 t SPACE t "FT" t SKIP t

RW> AT BOTTOM OF PAGE PR I NT SK I P t "OUR MOTTO: SERl.J I CE AND l.JALUE"
RW>
SET REPORT-NAME = "BOATS"j"BY"j"PEARSON"
RW>
PRINT COL 25t BEAMt LOAt RIGt
RW>
AVERAGE (DISP) ("Al.JERAGE"j"WEIGHT"j"OF ALL"j"BOATS")
RW>
SET COLUMNS-PAGE = 55
RW>
END-REPORT

Using the Report Writer

7-25

DD-MMM-YY

BOATS
BY
PEARSON
LENGTH
OI.IER
ALL

LONGEST

SHORTEST =

SHORTEST

LONGEST

SHORTEST =

LONGEST

SHORTEST

LONGEST

SHORTEST =

LONGEST

Pase 1

BEAM

LENGTH
OI.IER
ALL

RIG

AI.IERAGE
WEIGHT
OF ALL
BOATS

SLOOP

12 dLll

09
09
09

28
28
30

SLOOP
SLOOP
SLOOP

12 dLll
12 dLll
12 dLll

SLOOP

12 dLll

11
11

33
38

SLOOP
KETCH
SLOOP

12 dLll
12dLll
12 dLll

SLOOP

12 dLll

OUR MOTTO: SERVICE AND VALUE

3. DATATRIEVE checks the sort order of the collection or record stream you
want to report. You can establish a sort order with the REPORT command, a previous SORT command, or a SORTED BY clause in a FIND
command. If you have not established a sort order for the collection or
record stream by any of the methods, the Report Writer prints the following message after encountering the END-REPORT statement:
Proceed ins to report unsorted records

The Report Writer prints this message on your terminal even if you have
sorted the records in the current collection or record stream prior to invoking DATATRIEVE. However, if you have sorted your records prior to
entering DATATRIEVE, the Report Writer still makes the breaks between control groups just as though you had done the sorting during your
DATATRIEVE session.

7-26

Using the Report Writer

If the data is in fact unsorted, the Report Writer divides the detail lines
into control groups anyway A new controlgro-up is form-e-d every time the
value in the specified field changes. If no values in that field are repeated
in consecutive detail lines the Report Writer treats each line as a separate
control group and prints the header and summary lines above and below
each line as indicated in the record specification.
0

7.4.5 END-REPORT Statement
Function

The END-REPORT statement signals an end to the report specification.
Format
END-REPORT

Usage Notes

1. The END-REPORT statement must be the last statement in the report
specification.

2. Following the END-REPORT statement, the Report Writer can take
three courses of action:
• Prompt you for the values you specified with a *.prompt-name in the
record specification.
• Send you a message indicating a syntax error in the report specification.
If the Report Writer detects any syntax errors in the specificationj the
report is not produced, and the report specification is not saved. If you
entered the report specification interactively, you have to reenter it completely. If the report specification is in a procedure, use the
DATATRIEVE Editor to correct the errors.
• Produce the report and send it to the device or file you have specified in
the REPORT command.

Using the Report Writer

7-27

Chapter 8
Using the DATATRIEVE Editor

You can use the DATATRIEVE editor, a subset of the DEC Standard Editor;
to modify dictionary objects already defined in your current data dictionary.
To edit a dictionary object, you must have C (control) access to it.
As you add to or change the dictionary objects, the DATATRIEVE editor does
not check for syntax errors in the definitions. Any such errors become apparent only when you use the modified dictionary object. Hence, you should edit
with caution, especially when changing record definitions.
The changes you make with the DATATRIEVE editor apply only to the
dictionary object in the data dictionary. Any dictionary object residing in your
DATATRIEVE workspace is unchanged by the edits you make to the dictionary entry. For example, the current record definition of a readied domain is
unchanged when you edit the dictionary entry of the record definition. The
new record definition will not take effect until the associated domain is finished and readied again. Similarly, a description table loaded into the
DATATRIEVE workspace is not affected by edits to the dictionary entry for
the table; you must release the table and refer to it again before the changes
take effect.

8.1

Invoking the Editor
You invoke the DATATRIEVE editor at the DATATRIEVE command level
with the following command:
EDIT dictionary-abject-name

(paSSWd)]
[ (*)

[ADVANCED]

Arguments

dictionary-object-name
Is the name of the dictionary object (in the current data dictionary) you
want to edit.

8-1

(passwd)
(*)

Is an asterisk enclosed in parentheses (*) or the password necessary to gain
C (control) access to the dictionary object. If you specify a password, you
must enclose it in parentheses. If you specify (*), DATATRIEVE prompts
you for the password but does not print the response on your terminal. If
you omit this argument, DATATRIEVE uses your log-in UIC/PPN to
verify that you have C (control) access privilege to the dictionary object
you want to edit.

ADVANCED
Must be included in the EDIT command if you want to edit a domain
definition or a record definition.
When you invoke the DATATRIEVE editor, it responds with the following
, prompt:
QED>

8.2 Editor Modes
When you first invoke the editor, you are at the editor's command level and
are in "edit mode." In this mode, the editor interprets all your input as
commands, and you can display and alter the text of the dictionary object.
The QED> prompt indicates that you are in edit mode.
The second editor mode, "insert mode," allows you to enter text directly into
the dictionary object. You enter the insert mode with the INSERT and
REPLACE commands and leave it with CTRL/Z. The editor uses the IN>
prompt to indicate that you are in insert mode. In this mode, the editor
interprets all your input as new text to be entered into the dictionary object,
not as editor commands.

8.3 Line Pointer
The editor uses a line pointer to keep track of the current line. Some commands move you through the text from one line to another, thus changing the
current line. Other commands display or alter lines at various places in the
text but leave the current line unchanged. The line pointer keeps track of your
position in the t-ext.
The line pointer points to the entire current line, not to any part of the line.
You can display the current line by typing a period (.) and a carriage return in
response to the QED> prompt. The line pointer can also point to the end of
the text buffer, where you can add text to the end of the dictionary object.
The symbol [EOB] marks the end of the text buffer.

8-2

Using the DATATRIEVE Editor

8.4 Range Specification
The editor commands for deleting, inserting, replacing, and typing lines, and
for substituting strings all contain an optional argument that specifies the
range of lines on which the command operates. The range may be a single
line, a series of consecutive lines, or a group of nonsequential lines. The range
specifiers you can use with the DATATRIEVE editor are summarized in
Table 8-1.

Table 8-1: Range Specifiers

Range
Specifier

Format

Command Applies To:
All lines containing the specified string. The
search does not distinguish between upperand lowercase letters.

[%]ALL
[%]ALL "string"

'1']",,... 1;~,... ;~r1;nn+nr1 h .. ~n~~,... ~_1

r07"I A l\Tn

([%]AND)

(or , )

I <-11 ,

r-2[,r-3J. ..

.1. .l.l~ .l.lJ..l1(; .L.lIU.l\,,-UvC;U

uy 1 GIIOC; ~

.1.,

+]...,...~

1:_,... :_,J:

1,.11C;11 llllC; 111Ul

cated by rang-e
- r-2 and so forth

where ranges r-l, r-2 are:

BEGIN \

~~~n~"
U

u_ ---0

[%]BEFORE

[%]BEF[ORE]

All lines before the current line and the current line.

[%]BEGIN

[%]BE[GIN]

The first line of the dictionary object.

[%]END

[%]E[ND]

The last line of the dictionary object.

[%]FOR
(or ;)

The number of lines specified by n, starting at
the line specified by range r.

[%]FOR
n

r
;

{

where range r is:

BE [GINlI
"string"

[%]REST

[%]R[EST]

"string"

'string' I
"string"

The current line and all remaining lines in the
dictionary object.
The current line or the next line containing
the specified string. The search does not distinguish between upper- and lowercase leiters, and it starts with the current line and
continues toward the end of the dictionary object until it finds the specified string.
You can use either single or double quotation
marks to enclose strings. However, you must
use them in pairs; you cannot mix them.
(continued on next page)

Using the DATATRIEVE Editor

8-3

Table 8-1: Range Specifiers (Cont.)

Range
Specifier

Format

Command Applies To:

[%]WHOLE

[%]WH[OLE]

All lines of the dictionary object.

r + n

The line that is n lines from the line specified
by range r. When "string" is the range specifier, the command applies to the line that is n
lines from the next occurrence of the specified
string.

where range r is:

\BE1GIN1\
"string"
.(period)

The current line.

Table 8-2 shows several examples of these ranges. The sample command is
TYPE, which serves two purposes: it prints specified lines on your terminal,
and it searches for specified strings. The format of the TYPE command shown
in these examples is only one of several possible formats. See Section 9.5.7 for
a detailed discussion of the TYPE command.
Do not use the THRU or: range specifier when working in the
DATATRIEVE editor. If you do, your edits are cancelled and you are returned
to the DATATRIEVE command level.
Note that if you want to print the rest of a dictionary object using the %R
indicator without a TYPE command, you must specify the percent sign before
the R to distinguish it from the abbreviated form of the REPLACE command.
For example, the following commands all type the rest of the dictionary
object:
TYPE REST
TYPE R
REST
T R
'1.,R

Entering R by itself in response to the QED> does not type the rest of the
dictionary object; it deletes the current line and puts you in the insert mode.

8-4

Using the DATATRIEVE Editor

Table 8-2: Examples of Range Specifiers

Editor Prints:

You Type:
TYPE ALL "BEAM"

All lines containing the string" "BEAM".

TYPE BEGIN AND END

The first line of the dictionary object and the end-of-textbuffer marker ([EOBJ).

TYPE BEGIN, "BEAM"

The first line of the dictionary object and the first line containing the string "BEAM". If the current line is the first line of
the dictionary object and contains the string "BEAM", this
command prints the current line twice.

TYPE BEFORE

All lines before the current line and the current line.

TYPE BEGIN

The first line of the dictionary object.

The end-of-text-buffer marker ([EOE]).
TYPE. FOR 5
TYPE REST

IThe current line and the four lines following it.

The current line and all remaining lines in the dictionary
object.
~

TYPE 'BEAM'

The next line containing the string "BEAM". If the current
line contains "BEAM", the editor prints the current line.

TYPE WH

All lines in the dictionary object.

TYPE BE+5

The sixth line of the dictionary object.

TYPE "BEAM" +6

The sixth line following the next line containing the string
"BEAM". If the current line contains the string "BEAM", the
editor prints the sixth line following the current line.

TYPE.

The current line.

8.5 Editor Commands
Table 8-3 contains a summary of the DATATRIEVE editor commands. The
commands are described in alphabetical order in this section. Section 8.6
contains a sample editing session illustrating some common uses of these
commands.

Using the DATATRIEVE Editor

8-5

Table 8-3: Summary of DATATRIEVE Editor Commands

Command

Format

CTRL/Z

In edit mode, same as EXIT command. In insert
mode, returns control to edit mode.

DELETE

D[ELETE] [range]

Deletes the specified range or the current line if
you omit the range. After deletion, the current
line is the line following the last line deleted.

EXIT

EX[lT]

Returns you to DATATRIEVE command level.
The edited dictionary object replaces previous
version in data dictionary.

INSERT

I[NSERT] [range]

Enters the insert mode. The editor inserts lines
before the line specified by the range or before
the current line if you omit the range. CTRL/Z
ends the insert mode and returns you to the editor command level. If you omit the range, the
current line does not change when you leave insert mode; if you specify a range, the line specified by the range becomes the current line. Do
not use ALL, AND (,), BEFORE, FOR (;),
REST, OR WHOLE when specifying the range in
this command.

QUIT

Returns you to DATATRIEVE command level
and leaves the dictionary object unchanged by
the editing session.

REPLACE

R[EPLACE] [range]

Deletes the specified range or the current line if
you omit the range, and puts you in insert mode.
CTRL/Z ends insert mode and returns you to the i
editor command level, and the current line is the
line following the last line deleted. None of the
restrictions on specifying ranges in the INSERT
command apply to REPLACE.

SUBSTITUTE

S/str-l/[str-2] [/[range]]

Substitutes string-2 for all occurrences of
string-l in the specified range or in current line if
you omit the range. The line in which the last
substitution occurred becomes the current line. If
you omit the range, you can also omit the third
delimiter. If you omit string-2, the editor deletes
the specified string from the range you specify or
from the current line if you omit the range. The
search for the first occurrence of string-l starts
!I with the current line and proceeds toward the
end of the text buffer. Do not use END to snecifv
the range in this command.
.
-

TYPE

8-6

Function

[T[YPE]] [range]

Using the DATATRIEVE Editor

Displays the specified range of lines or the line
following the current line if you omit the range.
The first line displayed becomes the current line,
with one exception: if E[ND] plays any part in
the range of this command, the line pointer
points at the end-of-text-buffer marker ([EOB]).

8.5.1

DELETE Command

Function

Deletes one or more lines from the dictionary object.
Format
D[ELETE] [range]

Argument

range
Specifies the range of lines to be deleted. If you omit the range, only the
current line is deleted.
Position of Line Pointer

Current line is the line following the last line deleted.
Exampies

1. Delete the current line only:
QED> D

2. Delete all lines containing the string 'PHD':
QED> D ALL 'PHD'

3. Delete all lines from the next line containing "PHD" to the end of the
dictionary object:
QED> D "PHD" FOR n

where n is greater than or equal to the number of lines from the current
line to the end of the text buffer.
4. Delete all lines from the beginning of the dictionary object up to, and
including, the current line:
QED> D BEFORE

8.5.2 EXIT Command
Function

Ends an editing session, and returns you to the DATATRIEVE command
level. The edited dictionary object replaces the previous version in the data
dictionary.

Using the DATATRIEVE Editor

8-7

Format
EX[IT]
tTRl/Z )

Argument

None.
Position of the Line Pointer

Not applicable.
Examples

1. End the current editing session with EXIT command:
QED> E)<
DTR>

2. End the current editing session with CTRL/Z:
QED> tTB@
DTR>

8.5.3 INSERT Command
Function

Enters the INSERT mode, which allows you to enter text directly into the
dictionary object. The inserted lines are added before the line specified in the
range or before the current line if you omit the range.
Format
I[NSERT] [range]

Argument

range
Is the line before which the inserted lines are added. If the range is omitted, the' inserted lines are added before the current line.
Position of the Line Pointer

If you omit the range, the current line does not change when you leave insert
mode; if you specify a range, the line specified by the range becomes the
current line.
Notes

1. When you issue the INSERT command, the editor prompts with IN> to
show that you are in insert mode.

8-8

Using the DATATRIEVE Editor

2. Do not use the following range specifiers in the INSERT command:
• [%]ALL
• [%]AND (,)
• [%]BEF[ORE]
• [%]FOR (;)
• [%]R[EST]
• [%]WH[OLE]
3. To leave the insert mode and return to edit mode, enter CTRL/Z.
Examples

1. Insert lines before the current line:
QED> I
I rJ >

[ t ext J

IN>
IN>
QED>

tTRL/Z)

[text]

2. Insert lines before the first line of the dictionary object:
QED> I BEGIN
IN>
[text]

3. Insert lines after the last line of the dictionary object:
QED> I END
[EDB]
IN>
[text]

4. Insert lines before the next line containing the string "BEAM":
QED> I 'BEAM'
IN>
[text]

5. Insert lines between the fourth and fifth lines from the current line:
QED> I .+5
IN>
[text]

Using the DATATRIEVE Editor

8-9

8.5.4 QUIT Command
Function

Returns you to the DATATRIEVE command level, and leaves the dictionary
object unchanged by the editing session.
Format
QUIT

Argument

None.
Position of the Line Pointer

Not applicable.
Notes

1. QUIT aborts an editing session. The dictionary object is left unaffected by
any editing changes made during the editing session.

2. The QUIT command cannot be abbreviated.
Example

Abort the current editing session:
QED> QUIT
DTR>

8.5.5 REPLACE Command
Function

Deletes the specified range of lines in a dictionary object, or deletes the current line if you omit the range, and enters the insert mode, which allows you
to enter text directly into the dictionary object.
Format
R[EPLACE] [range]

Argument

Specifies the range of lines to be deleted. If you omit the range, only the
current line is deleted.
Position of the Line Pointer

After you leave the insert mode, the current line is the line following the last
line deleted; the current line is also the line after the inserted lines.

8-10

Using the DATATRIEVE Editor

Notes

1. When you issue the REPLACE command, the editor deletes the lines
specified by the range and then prompts with IN> to show that you are in
insert mode.

2. To leave the insert mode and return to edit mode, enter CTRL/Z.
3. None of the restrictions on specifying ranges in the INSERT command
apply to REPLACE.
Examples

1. Replace the current line with a single line:
QED>
QED> R
IN>
IN>
QED> •

FIND YACHTS WITH LOA BETWEEN 36 AND 37
FIND YACHTS WITH LOA > 38
~

REPORT CURRENT SORTED BY BEAMt LOAt RIG ON *.WHERE

2. Delete the first line of a dictionary object and enter insert mode:
QED> R BE
IN>
[text]

3. Delete all lines containing the string "PRICE" and enter the insert mode
at the line following the last line deleted:
QED> R ALL "PRICE"
IN>
[text]

4. Delete all lines in the dictionary object and enter the insert mode:
QED> R WHOLE
IN>
[text]

8.5.6 SUBSTITUTE Command
Function

Substitutes a character string for all occurrences of another character string in
the specified range or in the current line if you omit the range.
Format
S[UBSTITUTE] /string-l/[string-2] [/[rangeJ]

Arguments

string-l
Is the string of characters to be replaced.

Using the DATATRIEVE Editor

8-11

/
Is the delimiter that separates the string-l, string-2, and the range. The
delimiter can be any printing character not in string-lor string-2. Only
the first two delimiters are required if you omit the range. If you specify a
range, you must use all three delimiters, and you must use the same
delimi ter all three times.
string-2
Is the string of characters to replace string-I. If you omit string-2, then
string-l is deleted from the current line or from the specified range.
range
Specifies the range of lines within which the substitution is to be made. If
you omit the range, only the current line is affected. If you specify a range,
all occurrences of string-l within that range are replaced by string-2. If
you omit the range, only the first occurrence of string-l is replaced by
string-2, and that first occurrence of string-l need not be in the current
line.
Position of the Line Pointer

If a substitution takes place, the current line is the line in which the last
substitution occurred. If there is no match for string-l within the range, if
specified, or if there is no match for it in the current line or any line from that
point to the end of the dictionary object, and no substitution takes place, the
current line is unchanged.
Notes

1. The editor prints each line in which a substitution occurs.

2. Do not use END to specify the range in this command.
3. The search for the first occurrence of string-l starts with the current line
and proceeds toward the end of the text buffer.
Examples

1. Substitute the string YACHT for the first occurrence of the string YAHCT
in the current line only:
QED> S IYAHCT/YACHTI

2. Substitute the string YACHT for every occurrence ofYAHCT in the entire
dictionary object:
QED>S *YAHCT*YACHT* WH

This WHOLE range is effective regardless of the position of the current
line in the text buffer. If any substitutions are made, the current line is the
line in which the last substitution \vas made. The search for string-l
begins at the first line of the dictionary object and proceeds toward the
end of the text buffer.
8-12

Using the DATATRIEVE Editor

3. Substitute the string YACHT for the next occurrence of YAHCT:
QED> S IYAHCT/YACHT

If there is no occurrence of string-l between the current line and the end of
the text buffer, then the current line is unchanged.
4. Substitute the string YACHT for every occurrence of YAHCT from the

current line to the end of the dictionary object:
QED> S "YAHCT"YACHT" REST

8.5.7 TYPE Command
Function

Displays .the specified range of lines or the line following the current line if you
omi t the range .
.. _--_.&.

rurnun

[T[YPE]] [range]

Argument

range
Specifies the range of lines to be displayed. If you omit the range, only the
line following the current line is displayed.
Position of the Line Pointer

The first line displayed becomes the current line, with one exception: if E[ND]
plays any part in the range of this command, the line pointer points at the
end-of-text-buffer marker ([EOB]).
Notes

1. Both the command name and range are optional. If you enter only a

carriage return, the editor prints the line following the current line, which
then becomes the current line. You can also enter the range specifiers
without the command name.
2. The TYPE command performs the searches in the DATATRIEVE editor.

You can search for text strings in dictionary objects by enclosing the string
you seek in pairs of single or double quotation marks.
Examples

1. Print the current line only:
QED> TYPE

or
QED>

Using the DATATRIEVE Editor

8-13

2. Print the next line (the line following the current line):
QED> TYPE • + 1

QED> • + 1

or
QED> T

QED>

(B@

3. Print the entire dictionary object:
QED> T WH

QED> WH

4. Print the first and last lines of the dictionary object:
QED> T BEGIN,END

or
QED> BEGIN,END

or
QED> BE AND E

5. Print all lines from the current line to the end of the dictionary object:
QED> T REST

QED> REST

QED> 'x'R

8.6 Sample Editing Session
DTR> EDIT CTRL
QED> WH
READY YACHTS
FIND YACHTS WITH LOA BETWEEN 38 AND 37
REPORT CURRENT SORTED BY BEAM, LOA, RIG ON *.WHERE
SET REPORT-NAME = IIYACHTS WITH LENGTH-Ol.IER-ALLllj
1I0F 38 AND 37 FEETII
AT TOP OF BEAM PRINT COL 1, IIBEAM = ", COL 7, BEAM
AT TOP OF LOA PR I NT COL 12, II LENGTH = II, COL 20, LOA, SK I P
PRINT BUILDER, RIG, DISP
AT BOTTOM OF RIG PRINT SK I p, COL a, IINUMBER OF II, COL la,
LOA (" II), COL 17, II FOOT ", COL 22, RIG, COL 28,
"WITH BEAM OF ", COL aOt BEAM, COL a3, II = II, COL aG,
COUNT USING Z9, SKIP
II f MIN (DISP) ~
AT BOTTOM OF REPORT PRINT SKIPf "LIGHTEST
SKIP, "HEAl.IIEST = ", MAH (DISP), SKIP,
"A!.IERAGE WEIGHT OF ALL BOATS = ", A\.JERAGE (OISP)
SET DATE = " DD- MMM- YY
SET COLUMNS-PAGE = 80
END-REPORT
QED> •
READY YACHTS
QED> (B@
FIND YACHTS WITH LOA BETWEEN 38 AND 37
!!

8-14

Using the DATATRIEVE Editor

QE > R
IN
IN
QE > •

FIND YACHTS WITH LOA > 38
tTRLlZ)

REPORT CURRENT SORTED BY BEAM t LOAt RIG ON *.WHERE
QED> S/ON *.WHEREI
REPORT CURRENT SORTED BY BEAMt LOAt RIG
QED> (BIT)
• SET REPORT-NAME = "YACHTS WITH LENGTH - Ol.IER - ALL" I
QED> (BIT)
"OF 36 AND 37 FEET"
QED> R
"GREATER THAN 38 FEET"
IN>
IN>
tTB@
QED> •
AT TOP OF BEAM PRINT COL 1 t "BEAM =" COL 7 t BEAM
QED> ALL "AT BOTTOM"
AT BOTTOM OF RIG PRINT SK I P t COL a t "NUMBER OF "t COL 1a t
AT BOTTOM OF REPORT PRINT SKIPt "LIGHTEST =" MIN (DISP) t
QED>
AT BOTTOM OF RIG PRINT SKIPt COL at "NUMBER OF " COL 1 a t
QED> "BOTTOM"
AT BOTTOM OF RIG PRINT SKIPt COL at "NUMBER OF " t COL 1 a t
QED> (BIT)
LOA(" ") t COL 17 t "FOOT " t COL 221 RIG t COL 28 t
uu
QED> "RnTTnlvl"
MIN (D I SP) t
AT BOTTOM OF REPORT PRINT SK I P t "LIGHTEST
QED> • ;3
MIN (D I SP) t
AT BOTTOM OF REPORT PRINT SK I P t "LIGHTEST
SKIP t "HEAl.lIEST = "t MA}{ (DISP) t SKIP t
"Al.JERAGE WE I GHT OF ALL BOATS = " t Al.JERAGE (D I S P)
QED> •
AT BOTTOM OF REPORT PRINT SKIPt "LIGHTEST = " t MIN (DISP) t

UI~I

QED> D .; 3

QED> •
SET DATE
QED>
IN>
IN>
QED> •

= "DD-MMM-Y'f"

SET MAX-PAGES
tTB@

SET DATE = "DD-MMM-YY"
QED>

(BIT)

QED>

(BIT)

QED>

(BIT)

SET COLUMNS-PAGE = 60
END-REPORT
[EOBJ
QED> BE
READY YACHTS
QED> S/RIG/PRICE/WH
REPORT CURRENT SORTED BY BEAMt LOAt PRICE
PRINT BUILDERt PRICEt DISP
AT BOTTOM OF PRICE PRINT SKIPt COL at IINUMBER OF lit COL
LOA (II II) t COL 17 t "FOOT II t COL 22 t PR I CE t COL 28 t

1at

Using the DATATRIEVE Editor

8-15

QED> WH
READY YACHTS
FIND YACHTS WITH LOA > 38
REPORT CURRENT SORTED BY BEAM, LOA, PRICE
SET REPORT-NAME = "YACHTS WITH LENGTH-o!.IER-ALL"j
"GREATER THAN 38 FEET"
AT TOP OF BEAM PRINT COL 1, "BEAM = ", COL 7, BEAM
AT TOP OF LOA PRINT COL 12, "LENGTH
", COL 20, LOA, SKIP
PRINT BUILDER, PRICE, DISP
AT BOTTOM OF PRICE PRINT SKIP t CDL ll, "NUMBER OF " t COL ill,
LOA (" "), COL 1 7, "FOOT ", COL 22 t PR I CE t COL 28 t
"W I TH BEAM OF ", COL ao, BEAM, COL a3 t !! =
t COL as t
COUNT USING Z8, SKIP
SET MAX-PAGES"= 110
SET DATE = "DD-MMM-YY"
SET COLUMNS-PAGE = GO
END-REPORT
QED> E)<
DTR>

8-16

Using the DATATRIEVE Editor

Chapter 9
Application Design Tool

The Application Design Tool (ADT) is an interactive feature of
DATATRIEVE that aids in the creation of a domain definition, along with the
associated record definition and data file. Using your responses to its questions, ADT creates an indirect command file containing the data dictionary
definitions of the domain and record, and the file specification of the data file.
To enter the definitions in the data dictionary, you merely execute the indirect command file. (See Chapter 12: Procedures and Indirect Command
Files.)

NOTE
Because the installation of the Application Design Tool is optional, ADT may not be available at your installation.
ADT provides an easy-to-learn, easy-to-use method of creating a domain and
specifying a simple record definition. The record definition contains many,
but not all of the features and clauses available in a full record definition.
ADT allows you to define the domain, record, and data file easily by eliminating the need to issue the corresponding DATATRIEVE DEFINE commands.
Thus, you can create dictionary definitions with little or no prior experience
with DATATRIEVE.
To add field definitions or field definition clauses to the record definition
produced by ADT, you can edit the indirect command file with a text editor.
The DA TA TRIEVE Primer contains a brief description of ADT. This chapter
supplements that information and includes a more detailed description of
ADT's features, your dialog with ADT, and the output ADT produces.

9.1

ADT Features
Using ADT you can create a domain definition for an RMS domain and the
associated record definition. You create the record definition by defining every
field in the record. You also specify the name of the file to contain the data for
the domain. The data file can be sequential or indexed sequential. With ADT,
however, you cannot create a domain as a view; to create a domain of that
type, you must use the DEFINE DOMAIN command.

9-1

During an ADT session, you specify the following information:
• The name of the domain.
• The name of the data file for the domain.
• All elementary fields in the record. You cannot include group fields in the
record definition. ADT creates one group field with a level number of 01 and
assigns the record name as the group field name.
• The format of every data field in the record. A data field can be formatted
as a date, a percentage, money, numbers, or characters.
• A query name, if desired, for any field with a name longer than seven
characters. You cannot include a query header for any field or a query name
for any field with a name of seven or fewer characters.
• The format of the data file: either sequential or indexed sequential. For an
indexed sequential file, you indicate the name of the primary key field and
up to two alternate key fields. You can also indicate if a key field can have a
duplicate value and if an alternate key field can be modified.
As you respond to ADT's questions, ADT checks your responses. For example,
ADT verifies that any name you specify (such as a field name) conforms to
DATATRIEVE's rules for names. In addition ADT provides on-line assistance, if you type a question mark (?). You can also direct ADT to print
detailed or abbreviated questions.

9.2 Invoking and Terminating ADT
You invoke ADT at the DATATRIEVE command level with the ADT
command:
DTR> ADT

ADT then begins its dialog, which consists of a series of questions.
To terminate ADT when you have finished defining the domain, record, and
data file, type NO (or N) in response to the question:
Do

YOU

w~nt

to define another dOMain? (YES

NO):

You can also terminate ADT by responding with a CTRL/Z to any ADT
question. When you terminate ADT with a CTRL/Z, you return to the
DATATRIEVE command level.

9-2

Application Design Tool

9.3 ADT Dialog
ADT's first question is:
Do

YOU

want help? (VES or NO):

If you respond YES (or Y), ADT prints a short explanation of its functions
and the on-line assistance available to you.

9.3.1 Responding to ADT Questions
Table 9-1 contains a list of the types of questions ADT asks and the acceptable responses to each type. As shown in the table, in response to any question, you can enter a question mark (?) to receive an additional explanation of
the question, an exclamation point (!) to print the fields defined thus far, or
CTRL/Z to terminate the dialog.
If you enter an inappropriate response to a question, ADT prints an error
'rv'\r\nnnrrn
.lu",,00a.6""

n""""J
a.uu

'M1"\.......,.,nn+n
.1.""1'",,0.1,,0

.f-hn
IJU""

~'I.'nn+~,...."""

\.f U""OIJJ.V.11 •

n"'J1 . . . 1r1r'\.

A
.l"'UJ.J.

a.J.ov

"",,"~"""+rt

1'.1..1.111,,0

on."...."
0..11

r.'M_r... _

_ _ r t r l ..... ,yor..

_ _ ,.l

"".L.LV.L

1.11""000.6""

auu

repeats the question if one of the following errors occurs:
1. Violation of rules for names. Section 4.4 contains a list of rules for specifying DATATRIEVE names.
2. Duplicate names. A field name cannot duplicate either the domain name
or another field name in the domain. Field and domain names must be
unique.
3. Duplicate key fields. A key field must be unique; that is, the primary key
field must be different from the alternate key field(s).

Table 9-1: ADT Question Types and Responses

Question Type
any question

Response

Additional Explanation
ADT prints additional information
about the question.
ADT prints the fields that have already been defined.

... ? (YES or NO):

CTRL/Z (' Z)

ADT terminates, returns you to the
DATATRIEVE command level, and
may not have created an indirect command file.

YES (or Y)
NO (or N)

A single-character response is sufficient for ADT questions of this type.

(continued on next page)

Application Design Tool

9-3

Table 9-1: ADT Question Types and Responses (Cont.)

Question Type
What's in fld-name-

Response

Additional Explanation

DATE (or D)

ADT then asks for the format of the
date.

PERCENT (or P)

ADT automatically defines the field as
3 numeric positions with a decimal
point implied to the right of the right
most digit. The field value is printed
with a percent sign (cC).

MONEY (or M)

ADT then asks for the number of digits to the left of the decimal point.
(ADT assumes 2 digits to the right of
the decimal point.) The field value is
printed with a dollar sign (S) preceding the leftmost digit.

NUMBERS (or N)

ADT then asks for the number of digits to the left and the number of digits to the right of the decimal point.
ADT also asks if you want the leading
zeros to be suppressed when the field
I value
is printed.

Enter one of the above:

CHARACTERS (or C)

... query abbreviation

ADT then asks for the maximum
number of characters the field can
contain .
A carriage return indicates that the
field should not have a query name.

for fld-name?
query-name

ADT uses the character string as the
query name for the field.

9.3.2 Sample ADT Dialog
Figure 9-1 shows an annotated ADT dialog with detailed questions. The sample dialog illustrates several different types of responses to ADT questions
(including a typing error).

Figure 9-1: A Sample ADT Dialog
OTR> AOT
DO YOU 1,.,Iant
DO YOU want
What do YOU
What do YOU
for PAYROLL
What do YOU
What is the

help? (YES or NO) : N
detailed questions? (YES or NO) : Y
want to naMe this dOMain? : PAYROLL
want to naMe the file where the data
will be? : PAY. OAT
want to naMe the first field in PAYROLL? : EMPLOYEE-NAME
query abbreviation for EMPLOYEE-NAME? : NAME

(continued on next page)

9-4

Application Design Tool

What's in EMPLOYEE-NAME-a DATE
a PERCENT
MONEY
NUMBERS used in arithmetic
or ANYTHING ELSE (CHARACTERS)~
Enter one of the above : CC
Your answer must be DATEt PERCENTt MONEYt NUMBERS
or CHARACTERS.
What's in EMPLOYEE-NAME-a DATE
a PERCENT
MONEY
NUMBERS used in arithmetic
or ANYTHING ELSE (CHARACTERS)?
Enter one of the above : C
How many characters Ions is EMPLOYEE-NAME? : 25
Are there any more fields in PAYROLL? (YES or NO) : Y
What do YOU want to name the next field in PAYROLL? : SALARY
What's in SALARY-a DATE
a PERCENT
MONEY
NUMBERS used in arithmetic
or ANYTHING ELSE (CHARACTERS)?
Enter one of the above : M
How many disits to the left of the decimal point? : 6
Are there an}' fTlore fields in PAYROLL? (YES or NO) :' YES
What do you want to name the next field in PAYROLL? : REVIEW-DATE
What is the ~uery abbreviation for REVIEW-DATE? : REVIEW
What's in REVIEW-DATE-a DATE
a PERCENT
MONEY
NUMBERS used in arithmetic
or ANYTHING ELSE (CHARACTERS)?
Enter one of the above : D
Four date formats are available:
1
MMIDDIYY
6/29/79
2
DD-MMM-YY
29-JUN-79
3
DD-MMM-YYYY
29-JUN-1979
4
DD.MM.YY
29.06.79
En t e r for ITI a t n UITI be r 1 t 2 t 3 tor 4 : 1
Are there any more fields in PAYROLL? (YES or NO)
PAYROLL
EMPLOYEE-NAME (NAME) 25 characters
SALARY 6 disits left (and 2 disits riSht) of the decimal t is money
REVIEW-DATE (REVIEW) is a date
Are there any more fields in PAYROLL? (YES or NO) : Y
What do you want to name the next field in PAYROLL? : REVIEWER
What is the ~uery abbreviation for REVIEWER? :
What's in REVIEWER-a DATE
a PERCENT
MONEY
NUMBERS used in arithmetic
or ANYTHING ELSE (CHARACTERS)?
(continued on next page)

Application Design Tool

9-5

Enter one of the above : C
How Many characters Ions is REVIEWER? : 2S
Are there any More fields in PAYROLL? (YES or NO) : N
An indexed file can handle certain queries based on a Key
field very quicKly. A sequential file is not as fast and
does not allow records to be ERASEd. BUTt an indexed file
does not allow you to chanSe the priMarY Key field's data.
Do YOU want your data file to be indexed? (YES or NO) : N
What is the naMe of the file where the DATATRIEVE
dOMaln and field definitions should so? : PAY.CMD
The DATATRIEVE definitions for your dOMain are
located in file SV:[311t3S0JPAY.CMD;1
The record lenSth is 67 bytes.
Do YOU want to define another dOMain? (YES or NO)
NO
DTR>

9.4 Output from ADT
ADT produces a command file containing the definitions you specified in the
dialog.
The indirect command file contains three DATATRIEVE commands:
• DEFINE DOMAIN
• DEFINE RECORD
• DEFINE FILE
If necessary, before you execute the file, you can edit it using a text editor.
You cannot edit the file while in DATATRIEVE.

Figure 9-2 contains the general format of the command file contents.

Figure 9-2: General Format of Command File Contents
DEFINE DOMAIN dOMain-naMe USING dOMain-naMe-REC
ON file-spec;
DEFINE RECORD dOMain-naMe-REC USING
01
dOMain-naMe-REC.
lS fld-naITle-l

[lS fld-naMe-nJ
DEFINE FILE FOR dOITlain-nalTle [KEY=fld-naITle (opt) t ••• J;

Figure 9-3 shows the actual command file produced by the sample dialog in
Figure 9-1.

9-6

Application Design Tool

Figure 9-3: Sample Command File Contents
DEFINE DOMAIN PAYROLL USING PAYROLL-REC
ON PAY.DAT;
DEFINE RECORD PAYROLL-REC USING
01 PAYROLL-REC.
15 EMPLOYEE-NAME
PIC IS X(25)
QUERY-NAME IS NAME.
15 SALARY
PIC IS S9(G)V99
EDIT-STRING IS $$$$t$$$.$$.
15 REVIEW-DATE
USAGE IS DATE
EDIT-STRING IS NN/DD/YY
QUERY-NAME IS REVIEW.
15 REin EWER
PIC IS X(25).

ADT inserts the appropriate field definition clauses in the record definition.
These clauses can be:
• EDIT-STRING for a date, percentage, numeric, or money field.
• USAGE for a date field.
• PIC for a percentage, money, numeric, or character field.
• QUERY-NAME for any field with a name longer than seven characters, if
you specified a query name in the dialog.
ADT also adds a group field with level number 01 and assigns a level number
of 15 to each elementary field definition.

9.5 Clauses and Other Record Attributes Not Available in ACT
Some of the limitations of ADT have already been mentioned: you cannot
define group fields or query headers, you can have no USAGE clauses other
than that for dates, and you can define query names only for fields with names
greater than seven characters.
In addition, you have no control over edit-strings beyond that which ADT
offers you in the dialog, and you cannot insert filler between fields.
The record definitions ADT creates do not contain any of the following
clauses:
• COMPUTED BY
• OCCURS
• REDEFINES
• SIGN
• VALID IF

Application Design Tool

9-7

If you want to insert any of these clauses in the record definition that ADT
creates, you must exit from DATATRIEVE and use a text editor to change the
indirect command file.

9.6 Executing the Indirect Command File
You execute the file produced by ADT as an indirect command file at the
DATATRIEVE command level (see Chapter 12: Procedures and Indirect
Command Files).
DTR> @file-spec

DATATRIEVE then executes each DEFINE command in the file and prints
the command on your terminal as it is executed. Figure 9-4 shows the execution of the command file created earlier in this chapter. The definitions are
stored in the current data dictionary. To enter data in the records, you can
ready the domain for WRITE or EXTEND access (see Section 5.26) and use
the STORE statement (Section 5.36).

Figure 9-4: Execution of Sample Indirect Command File
DTR> @PAY.CMD
DEFINE DOMAIN PAYROLL USING PAYROLL-REC
ON PAY.DAT;
DEFINE RECORD PAYROLL-REC USING
01 PAYROLL-REC.
15 EMPLOYEE-NAME
PIC IS X(25)
QUERY-NAME IS NAME.
15 SALARY
PIC IS S9(6)V99
EDIT-STRING IS $$$$,$$$.$$.
15 REVIEW-DATE
USAGE IS DATE
EDIT-STRING IS NN/DD/YY
QUERY-NAME IS REVIEW.
15 REIn EWER
PIC IS >«25)
I

[Record PAYROLL-REC is 67 bytes IonS]
DEFINE FILE FOR PAYROLL;
DTR>

9-8

Application Design Tool

Chapter 10
Creating and Maintaining Data Dictionaries

Each time you invoke DATATRIEVE, you are automatically connected to a
data dictionary. A data dictionary is an RMS file created by DATATRIEVE
for the storage of definitions and protection information. The file is created on
disk.
This chapter summarizes the steps involved in creating a data dictionary. See
Chapter 5 for a description of the DEFINE DICTIONARY command which
you use in this process. The present chapter also describes how to maintain a
data dictionary and compress it, if necessary, to eliminate unused disk areas.
First, however, it will be helpful for you to understand the contents of a data
dictionary.

10.1 Contents of a Data Dictionary
A data dictionary contains the definitions and protection information for the
following DATATRIEVE data structures:
• Domains
• Records
• Procedures
• Description tables
Each definition describes the contents of the data structure:
• A domain definition contains the name of the domain, the name of the
record definition associated with the domain, and the file specification of
the file containing the data for the domain.
• A record definition contains the name of the record and a definition for each
field in the record. Record and field definitions are described in Chapter II.
• A procedure definition is the procedure itself, including the procedure name
and all commands and statements in the procedure. Chapter 12 describes
procedures and procedure definitions.

10-1

• A description table definition is the description table itself, including its
name and all code-and-description pairs. Description tables and their definitions are described in Chapter 13.
Associated with each of these definitions is a password table. It protects the
one definition with which it is associated and restricts its use. Password tables
supplement the protection features of your operating system. They are described in Chapter 14.

10.2 Creating a Data Dictionary
You create a data dictionary using the DEFINE DICTIONARY command.
The format of this command is shown below; you can find more information
on its use in Section 5.6.
DEFINE DICTIONARY

file-spec

DEFINE DICTIONARY creates an empty indexed sequential RMS file that
is suitable for use as a data dictionary. You supply the file specification, and
the operating system creates an entry for it in your directory. You can choose
any extension for the file when you create it; but, if you use the default
extension (.DIC), the dictionary file will be easier for you to identify when you
list your directory.
As soon as you enter the DEFINE DICTIONARY command, DATATRIEVE
creates a file, if it can, and establishes the new dictionary as your current data
dictionary, just as if you had done a SET DICTIONARY command yourself.
You can then begin entering definitions immediately. If DATATRIEVE cannot create a file because, for example, you do not have write access to the disk,
or the disk is not mounted, it prints a message on your terminal and leaves
you connected to your current dictionary.

10.3 Changing Dictionaries
When you invoke DATATRIEVE, you are automatically connected to a default data dictionary. At the beginning of your DATATRIEVE session, that
dictionary is your current dictionary. You can be connected to only one dictionary at any given time during a session.
To find out the name of your current dictionary, use the following command:
DTR> SHOW DICTIONARY

SHOW DICTIONARY prints the file specification of the current data
dictionary.
If you want to use a different dictionary, use the following format of the SET
command:
DTR> SET DICTIONARY file-spec

10-2

Creating and Maintaining Data Dictionaries

To change from the default dictionary to another dictionary, you must specify
at least one element of the file specification of the other data dictionary. For
example, if you specify only the device name, DATATRIEVE searches that
device for a directory with your UIC/pPN and a file named QUERY.DIC.
(See Section 5.31 for the defaults of the SET DICTIONARY command.)
If DATATRIEVE does not find the 'file you specify, it prints an error message
on your terminal,. and the dictionary current before you issued the
SET DICTIONARY command is still current. At no time are you left in
DATATRIEVE without being connected to a data dictionary.
If you have readied a domain in your current dictionary, and you change
dictionaries, that domain is still available when you are connected to the new
dictionary. This feature allows you to move records from that readied domain
into another domain in the new current dictionary. For a description of this
process of transferring records, see Chapter 16.
If you want to return to the default data dictionary, to which you were
connected at the beginning of your DATATRIEVE session, issue the SET
DICTIONARY command without a file specification:
DTR> SET DICTIONARY

The following dialog illustrates the setting and displaying of data dictionaries.
Note that if you try to SET a dictionary that has not been defined,
DATATRIEVE prints an error message on your terminal. 'The dictionary
must be defined first with a DEFINE DICTIONARY command. Note also
that DATATRIEVE returns the DF:N> prompt when you omit the file specification from the DEFINE DICTIONARY command. In this example ddn1:
represents the name of the device on which the default DATATRIEVE dictionary is stored, and ddn2: is the name of the device on which your file
directory is stored.
DTR> SHOW DICTIONARY
The current dictionary is ddnl:[l ,ZJQUERY.DIC;Z
DTR> SET DICTIONARY NEWDIC
File "NEWDIC" not found
$OPEN failed
DTR> DEFINE DICTIONARY
DFN> NEWDIC
DTR> SHOW DICTIONARY
The current dictionary is ddnZ:[ZOO,ZOOJNEWDIC.DIC;l
DTR> SET DICTIONARY
DTR> SHOW DICTIONARY
The current dictionary is ddnl:[l ,ZJQUERY.DIC;Z
DTR>

Note that an explicit SET DICTIONARY NEWDIC command is not needed
after the DEFINE DICTIONARY NEWDIC, because that DEFINE sets the
dictionary to NEWDIC automatically.
RSTSIE systems suppress the PPN when showing the default dictionary.
VAXNMS systems may use your name as DIC of the dictionary in your
directory in place of the six-digit number shown in the example.

Creating and Maintaining Data Dictionaries

10-3

10.4 Maintaining a Data Dictionary
10.4.1 Displaying Dictionary Contents
You can list the names of all domains, records, procedures, and description
tables defined in the current data dictionary by using the SHOW command:
DTR> SHOW ALL

SHOW ALL also lists the names of all established collections and readied
domains.
To show the definition of a dictionary object, you must have R (read) access to
it. Use the SHOW command in the following format:

DTR> SHOW

dOlrlain-nalrle
rec-nalTle
proc-nalTle
desc-table-nalrle

The SHOW command in this format prints the definition of the specified
dictionary object on your terminal. It does not, however, print the password
table associated with that dictionary object. To print the password table, use
the SHOWP command:

DTR> SHOWP

dOlrlain-nalrle
rec-nalrle
proc-nalTle
desc-table-nalrle

You must have C (control) access to the dictionary item to print its password
table.

10.4.2 Modifying Dictionary Contents
To modify the definition of a dictionary object, you must have C (control)
access to the dictionary object. To modify the dictionary definition of a
domain, record, procedure, or description table, use one of the following
methods:
• Delete the definition from the data dictionary using the DELETE command. Then, issue a DEFINE command to create a new definition.
• Copy the definition to an indirect command file using EXTRACT. Edit the
indirect command file using a text editor. You cannot edit an indirect
command file with the DATATRIEVE editor. After making the needed
changes, return to DATATRIEVE, and execute the indirect command file
as explained in Chapter 12.
The EXTRACT command adds both a DELETE command and a DEFINE
command to the beginning of the indirect command file. The DELETE
removes the old definition of the dictionary object from the current data
dictionary, and the DEFINE creates the new one.

10-4

Creating and Maintaining Data Dictionaries

You can also modify procedures and description tables by using the
DATATHIEVE editor (see Chapter 8).
You should use extreme caution when changing record definitions. You can
change a record definition in such a way that you ·can no longer access the
data. When changing a record definition:
• You should use the same record length.
• You should not add or delete elementary fields.
• You should not change the data type of an elementary field.
• You can add or delete group fields and COMPUTED BY fields.
• You can add VALID IF clauses.
• You can change edit-strings.
• You can change the names of fields, and add or delete query names and
query headers.

10.4.3 Deleting Dictionary Contents
To remove the definition of a dictionary object from the current data dictionary, you must have C (control) access to the dictionary object. To remove a
dictionary definition use the DELETE command:
do ITl a i n - n a!Tl e

DTR> DELETE

reC-na!Tle
prOC-na!Tle
desc-table-na!Tle

Remember to terminate the DELETE command with a semicolon.
DELETE removes from the dictionary both the definition of the dictionary
object and its associated password table. The data or records in the data file
for the domain are not affected by this command.

10.5 Compressing a Dictionary
As definitions are added to and deleted from a dictionary, unused areas of
disk space accumulate. This wasted disk space can be reclaimed by running
the utility program QCPRS. QCPRS compresses any indexed sequential file,
and preserves the file's contents while eliminating unused disk space.
To compress a data dictionary, invoke QCPRS in response to the prompt of
your operating system (not in response to any DATATRIEVE prompt).
QCPRS prints an identification message and requests a command with the
following prompt:
CPR :::-

Creating and Maintaining Data Dictionaries

10-5

Enter the name of the dictionary to be compressed in the following format:
new-file=old-file

The argument new-file is the file specification for the compressed copy of the
dictionary. The argument old-file is the file specification of the dictionary to
be compressed. For both argu~ents, if you omit a field in the file specification, QCPRS uses the following defaults:
Field

Default

dev:

SY: (the system device)

UFD

Your login UIC/pPN

filename

QUERY

.ext

.DIC

Under all operating systems but RSTS/E, the file specifications for new-file
and old-file can be the same. QCPRS merely creates a new copy of the file
with the next higher version number.
Under RSTS/E, the file specifications for new-file and old-file must be different, and you should rename the dictionary file before invoking QCPRS. For
instance, you might change the file extension to .BAK. When you invoke
QCPRS, you can give the new file the original file specification.
After you have entered the file specifications, QCPRS asks you to specify a
number of disk blocks as an allocation for the new version of the dictionary:
ENTER ALLOCATION FOR AREA 0:

Enter an estimate of the number of disk blocks needed for the compressed
version. If your guess is too low, the file is automatically extended to hold the
contents of the original file. If your guess is too high, the extra blocks remain
in the file and give room for contiguous expansion of the dictionary.
QCPRS then prompts again with CPR>, and you can compress another dictionary file or terminate QCPRS with CTRL/Z.
Because QCPRS· does not alter the contents of the original file, you can save
the file as a backup, or you can delete it.
The following dialog illustrates the use of QCPRS after renaming the dictionary to be compressed from QUERY.DIe to QUERY.BAK:
RUN QCPRS
QUERY FILE COPY - COMPRESS UTILITY
CPR> QUERY.DIC=SY:[l ,2JQUERY.BAK
ENTER ALLOCATION FOR AREA 0: 250
CPR> ~

10-6

Creating and Maintaining Data Dictionaries

Chapter 11
Creating Record Definitions

A record is a group of related data. For example, in the YACHTS domain,
each record contains the data relating to one yacht. A record must contain at
least one unit of data, called a "field." Usually, though, a record contains
several fields.
Every domain has an associated record definition that describes the fields in
its records. You can create a record definition using the DEFINE RECORD
command, described in Chapter 5, or the Application Design Tool, described
in Chapter 9. This chapter explains the concepts and techniques for creating
record definitions and explains how to define records that store data in the
form you need it.
If you have defined records using COBOL, then DATATRIEVE's record definition will look familiar to you. But, a knowledge of COBOL is not necessary
to create record definitions in DATATRIEVE.

11.1 The Parts of a Record Definition
A record definition consists of one or more field definitions. A field definition
describes a field in the record and its relationship to other fields. Every field
definition contains at least two parts:
• A level number, which indicates the relationship between the field and
other fields in the record
• A field name, which identifies the field to you and to DATATRIEVE
Some fields need a third part for their definition:
• One or more field definition clauses
Figure 11-1 shows the full YACHT record definition and illustrates the three
parts of a record definition.
11-1

Figure 11-1: Three Parts of YACHT Record
RECORD YACHT
USI~G level number
01 BOAT
___________ field name
.Q2 YPE.
08 MANUFACTURER PIC X(10)
UERY-NAME IS BUILDER.
08 MODEL PIC X(10).
03 SPECIFICATIONS
field definition clause
QUERY-NAME SPECS.
08 RIG PIC )-{(8)
I.lALID IF RIG EQ "SLOOP" t "KETCH" t "MS" t "YAWL".
08 LENGTH-oVER-ALL PIC XXX
VALID IF LOA BETWEEN 15 AND 50
QUERY-NAME IS LOA.
08 DISPLACEMENT PIC 88888
QUERY-HEADER IS "WEIGHT"
EDIT-STRING IS ZZtZZ8
QUERY-NAME IS DISP.
08 BEAM PIC 88.
08 PRICE PIC 88888
VALID IF PRICE>DISP*1.3 OR PRICE EQ 0
EDIT-STRING IS $$$t$$$.

The rest of this chapter describes the two types of fields (elementary and
group), the parts of the record definition, and the types of data that a field
can contain. A record definition clause, which is optional, is explained in
Appendix E.

11.2 Elementary and Group Fields
If you have been working with the YACHTS domain, you have probably seen
that a record can contain two types of fields: elementary fields and group
fields. An elementary field is a basic unit of data. It contains no other field
within it. A group field, on the other hand, contains one or more other fields.

For example, the YACHT record contains seven elementary fields:

MANUFACTURER

MODEL
RIG
LENGTH-OVER-ALL

Elementary fields

DISPLACEMENT
BEAM
PRICE
A record definition must contain at least one elementary field.
The YACHT record also contains group fields. A group field provides a convenient way to refer to more than one field in a record. If a record definition

11 =2

Creating Record Definitions

contains a group field, you can refer to the group field in a statement, instead
of referring to each field it contains. For example, in the YACHT record, the
group field BOAT allows you to refer to every field in the record by the group
field name BOAT.
Group field

BOAT
MANUFACTURER
MODEL
RIG
LENGTH-OVER-ALL

Elementary fields

DISPLACEMENT
BEAM

)

PRICE

Also for convenience, the YACHT record definition groups the first two
elementary fields under a single name: TYPE. TYPE then refers to both
MANUFACTURER and MODEL. The remaining five fields are grouped under the name SPECIFICATIONS:

Group fields
TYPE
MANUFACTURER
Elementary fields
MODEL
SPECIFICATIONS

Group field

RIG
LENGTH-OVER-ALL
DISPLACEMENT

Elementary fields

BEAM
PRICE

Thus, you can use the group field name TYPE in a DATATRIEVE statement
instead of specifying both MANUFACTURER and MODEL. For example,
the following two PRINT statements provide the same results.
PRINT TYPE
PRINT MANUFACTURER, MODEL

Creating Record Definitions

11-3

Every record definition must meet the following requirements for including
elementary and group fields:
1. A record definition must contain at least one elementary field.

2. A record definition must contain a group field that includes all other fields
in the record.
3. A group field must contain at least one field - either elementary or group.
4.

A group field can contain both eiementary and group fields.

11.3 Field Levels and Level Numbers
11.3.1 Field Levels
Every field in a record definition has an associated level, which describes the
relationship of that field to other fields in the record. A group field that
contains all other fields in a record is at the first (or highest) level. In the
YACHT record, BOAT contains all other fields in the record and is at the first
level.
A field that is contained within a first-level field (and no other field) is
subordinate to the first-level field. It is at the second level in the record. For
example, TYPE and SPECIFICATIONS are both at the second level, subordinate to BOAT. Any field subordinate to a second-level field is at the third
level, and so on. Thus, MANUFACTURER and MODEL are at the third
level.

<- First level

BOAT

<- Second level

TYPE
MANUFACTURER

<- Third level
MODEL

<- Second level

SPECIFICATIOt..JS

RIG
LENGTH-OVER-ALL

<- Third level

DISPLACEMENT
BEAM
PRICE

11.3.2 Level Numbers
in a record definition, you must specify every field's level with a level number.
A level nurnber is a one- or two-digit number (from 1 to 65) that precedes the
field name. It describes the field's level. The lower the field's level number,
11-4

Creating Record Definitions

the more inclusive is the field. For example, a level number of 1 indicates a
field that includes all other fields. The first field in a record must have the
lowest level number (usually 1) and it must be a group field that contains all
the other fields.
The fields in the YACHT record definition illustrate levels and level numbers:
01

BOAT
03
03

TYPE
06 MANUFACTURER
06 MODEL
SPECIFICATIONS
06 RIG
06 LENGTH-OVER-ALL
06 DISPLACEMENT
06 BEAM
06 PRICE

BOAT is at the highest level and has the lowest level number (01). The next
higher level number is 03; therefore, TYPE and SPECIFICATIONS are at the
second level, directly subordinate to BOAT. Within TYPE, two fields have a
higher level number: MANUFACTURER and MODEL. These two are directly subordinate to TYPE. Similarly, SPECIFICATIONS contains five subordinate fields: RIG, LENGTH-OVER-ALL, DISPLACEMENT, BEAM,
and PRICE.
The level numbers in YACHT illustrate several rules about assigning level
numbers to a field:

Level numbers need not be consecutive.
Only the relative value of level numbers determines the level and subordination of a field. For example, TYPE and SPECIFICATIONS could be at
level number 02 and the fields they contain at any higher level number.

2. All fields directly subordinate to a group field must have the same level
number. For example, MANUFACTURER and MODEL have the same
level number since they are both directly subordinate to TYPE. And, the
five fields subordinate to SPECIFICATIONS have the same level number.
(That level number can be different from the level number of
MANUFACTURER and MODEL.) Because TYPE and
SPECIFICATIONS are directly subordinate to the same group field
(BOAT), they have the same level number.

3. Only level numbers determine the level of a field.
All the examples of YACHT thus far have shown field names indented to
show the level of fields. Although indentation can make a record definition
easier to read, it has no effect on the level of a field.

Creating Record Definitions

11-5

11.4 Field Names
In addition to a level number, every field in a record must have a field name.
You use the field name to identify the field in DATATRIEVE statements. If
you include the QUERY-NAME clause in the field definition, you can use the
query name instead of the field name. DATATRIEVE also uses the field name
when printing the field's content: if there is no QUERY-HEADER clause in
the field definition, DATATRIEVE uses the field name as a column header for
the field data. If you include the QUERY-HEADER clause in the field definition, DATATRIEVE uses the query header, instead of the field name, to make
the column header. You can override the printing of the field name or query
header by including a column header in the PRINT statement.
A field name must conform to DATATRIEVE's rules for names, described in
Chapter 4. In summary, these rules are:
1. A name can consist of letters, digits, hyphens (-), and underscores (_).
2. The name must begin with a letter.
3. The name must end with a letter or digit.
4. The name cannot duplicate a DAT ATRIEVE keyword. See Appendix A
for a list of keywords.
5. The name must be 30 characters or less.
6. The name can be continued from one line to another only by using a
hyphen.
Although a field name can be 30 characters long, short field names are easier
to use than long ones. If you must use a long field name, such as
LENGTH-aVER-ALL, you may want to include a query name, such as LOA,
in the field definition. The QUERY-NAME clause is described in Section
11.13. You can then use either the field name or the query name in a statement to refer to the field.

11.4.1 Qualifying Field Names
Field names need not be unique; two or more fields can have the same field
name in a record definition. But, duplicate field names must be in different
group fields.
If you use a duplicated field name in a command or statement,
DATATRIEVE uses the first field in the record with that name. For exanlple,
the following record definition defines two fields named BIRTHDAY:
05
05

11-6

OWN.
07 BIRTHDAY USAGE DATE.
07 HEIGHT PIC SVSS.
SPOUSE.
07 BIRTHDAY USAGE DATE.
07 WEDDING-DATE USAGE DATE.

Creating Record Definitions

You can print the value in the first BIRTHDAY field with the following
statement:
PRINT BIRTHDAY

You can refer to the second BIRTHDAY field in the record by qualifying the
field name. You qualify a field name by preceding it with a group name and a
period. For example, the following statement prints the value in the BIRTHDAY
field that is subordinate to the group field SPOUSE:
PRINT SPOUSE.BIRTHDAY

The level of qualification you specify in a statement depends on the level of
group fields in the record definition. For example, a record definition can
contain duplicate group field names as well as duplicate elementary field
names.
03

SON.
05 OWN.
07 BIRTHDAY USAGE DATE.
VI
HEIGHT PIC 9V99.
05 SPOUSE.
07 BIRTHDAY USAGE DATE.
07 WEDDING-DATE USAGE DATE.
DAUGHTER.
05 OWN.
07 BIRTHDAY USAGE DATE.
07 HEIGHT PIC 9V98.
05

SPOUSE.

07
07

BIRTHDAY USAGE DATE.
WEDDING-DATE USAGE DATE.

You can refer to the first BIRTHDAY field in the record in any of the following ways:
BIRTHDAY
OWN.BIRTHDAY
SON.OWN.BIRTHDAY

You can refer to the first BIRTHDAY field in the group field DAUGHTER
using either of the following qualified field names:
DAUGHTER.BIRTHDAY
DAUGHTER.OWN.BIRTHDAY

In summary, if a field name is duplicated and you refer to it without a
qualifying group name, DATATRIEVE uses the first field in the record
with that name. If you qualify a field name with a group field name,
DATATRIEVE searches the first group field in the record with that name for
the specified field.

Creating Record Definitions

11-7

11.4.2 FILLER Field Name
You can specify the keyword FILLER as the name of an elementary or group
field. FILLER specifies a field that you will never refer to in a statement. Like
other fields, a FILLER field must have a level number and can contain field
definition clauses. Unlike other fields, you can use the field name FILLER
more than once within the same group field. DATATRIEVE does not print
the values stored in FILLER fields.
If the FILLER field is an elementary field, you cannot refer to its content in a
DATATRIEVE statement. For example, in the following record definition,
you can never refer to the third field in OWN:
03

SON.
OS OWN.

07
07
07

BIRTHDAY USAGE DATE.
HEIGHT PIC SVSS.
FILLER
PIC X(S).

If the FILLER field is a group field, you can refer to any field in the group, but
not to the FILLER field itself. In the following example, you can refer to the
SON, OWN, BIRTHDAY, and HEIGHT fields, but not the group or elementary FILLER fields.
02

FILLER.
03

SON.
OS OWN.

07
07
07

BIRTHDAY USAGE DATE,
HEIGHT PIC SVSS.
FILLER
PIC X(S),

11.5 Field Classes
DATATRIEVE classifies every field by the type of data it contains or the way
in which it stores data. DATATRIEVE has four classes of fields.
• Alphanumeric fields can store any combination of characters. The
MANUFACTURER and MODEL fields in the YACHT record are examples
of alphanumeric fields. If an alphanunleric field contains only digits, it can
be used in arithmetic computations.
• Numeric fields are made up of digits and an optional sign (+ or -). The
YACHT record, for example, contains the numeric fields DISPLACEMENT,
BEAM, and PRICE. Numeric fields can be used in computations.
• DATE fields contain a date. A DATE field can be used in some computations. For exalnple, you can subtract one date from another to get the
number of days elapsed during a time period.
• COMPUTED BY fields do not store data, but merely describe a computation. A COMPUTED BY field does not occupy space in a record; it exists
solely in the record definition, DATATRIEVE computes the value of the
field when you refer to it in a command or statement.

11-8

Creating Record Definitions

An elementary field can be an alphanumeric, numeric, DATE or
COMPUTED BY field. A group field, however, is always considered alphanumeric. You cannot use a group field in any arithmetic computation.
Table 11-1 summarizes the field classes and their acceptable content.
Table 11-1: Field Classes

Field Type

Class

Elementary field

Alphanumeric

Any combination of characters

Numeric

Any combination of digits and an optional sign (+ or -)

DATE

A date

eOMPUTED

None; the definition specifies a computation, but no

Content

11.6 Field Definition Clauses
You define a field by specifying its level number, its field name, and, ifit is an
elementary field, one or more field definition clauses. A field definition clause
is a keyword (such as PICTURE or QUERY-NAME) followed by a character
string or value expression. A field definition clause can describe any of the
following:

• The class and size of data a field contains and the way in which the data is
stored
• The format of the data when it is printed
• The values to be accepted when data is entered in the field
• The way numeric values are computed when you refer to the field
• An alternate name for the field when you refer to the field or print its
content
• An alternate way to handle the field
An elementary field must have at least one field definition clause. A group
field can, but need not, have a field definition clause.
Table 11-2 contains a list of all field definition clauses. Three clauses
(OCCURS, QUERY-NAME, and REDEFINES) can be used for both elementary and group fields. All other clauses can be used for elementary fields only.

Creating Record Definitions

11-9

Table 11-2: Summary of Field Definition Clauses

Clause

Valid for:

Purpose

COMPUTED BY

Elementary field

Describes a COMPUTED BY field

EDIT-STRING

Elementary field

Specifies the format of a field value when
it is printed

OCCURS

Elementary or group field

Defines multiple occurrences of a field or
group of fields

PICTURE

Elementary field

Specifies the format of a field value as it
is stored in a record

QUERY-HEADER

Elementary field

Specifies the column header for the field
value when it is printed

QUERY-NAME

Elementary or group field

Specifies an alternate name for a field

REDEFINES

Elementary or group field

Creates an alternate definition for a field

SIGN

Numeric elementary field

Specifies the location and representation
of the sign in a numeric field

USAGE

Numeric or date
elementary field

Specifies the internal storage format of a
field or specifies a date field

VALID IF

Elementary field

Tests a value before storing it in a field

An elementary field must contain one of the following clauses:
PICTURE
COMPUTED BY
USAGE DATE
USAGE COMP-l (or REAL)
USAGE COMP-2 (or DOUBLE)
When you define a field, you must end its definition with a period. If the field
is a group field with no field definition clause, place the period immediately
after the field name. For example, the group field BOAT contains no field
definition clauses:
01 BOAT.

If the field definition contains clauses; place the period after the last field

definition clause. For example, the LENGTH-OVER-ALL field contains
three field definition clauses:
08

LENGTH-OVER-ALL PIC XXX
VALID IF LOA BETWEEN 15 AND 50
QUERY-NAME IS LOA.

The first field definition clause can be on the same input line aL the level
number and field name, as shown in the preceding example, or on a separate
11-10

Creating Record Definitions

input line. Delimit all clauses with a space, tab, or carriage return. Entering
the clauses on separate lines and indenting them with spaces or tabs improve
the readability of the record definition.
The rest of this chapter describes each field definition clause. The clauses are
described in alphabetical order, but you can specify the clauses in any order in
the field definition.

11.7 COMPUTED BY Clause
Function

Describes a COMPUTED BY field.
Format
COMPUTED BY val-exp

Arguments

val-exp
Is a value expression consisting of one or Inore field or query names,
numeric literals, and arithmetic operators.
Restrictions

1. This clause is valid for elementary fields only.

2. You cannot use an OCCURS clause or a VALID IF clause In a
COMPUTED BY field.
Description

A COMPUTED BY field is useful if you will be printing an arithmetic computation frequently. It allows you to specify the computation once in the record
definition, then print its value simply by referring to its field name. Generally,
the computation includes the name of one or more fields in the record definition. When you refer to the COMPUTED BY field in a statement,
DATATRIEVE evaluates the value expression using the field values in that
record.
A COMPUTED BY field does not exist or occupy space in a record. It exists
solely in the record definition. The value of a COMPUTED BY field is derived
only when you use it in a statement.
Because it does not exist in the record, you cannot assign a value to a
COMPUTED BY field. STORE and MODIFY statements cannot refer to a
COMPUTED BY field.
You cannot redefine a COMPUTED BY field with the REDEFINES clause.
You cannot use a COMPUTED BY field in a sort list. That is, a COMPUTED
BY field cannot be a sort key in a SORT or SUM statement or a record
selection expression. In addition, you cannot use the field as a control group in
the Report Writer statements AT TOP OF and AT BOTTOM OF.

Creating Record Definitions

11-11

If you include a COMPUTED BY clause in a field definition, you do not have

to include any other field definition clause. However, you may want to specify
the format of the computation when it is printed using an EDIT-STRING
clause.
Examples

1. Compute the price per pound of a yacht as the price divided by the
displacement. In this case, both the PRICE and DISP fields are defined in
the record definition.
08 PRICE-PER-POUND
EDIT-STRING $$$,$$9.99
COMPUTED BY PRICE/DISP.

When the PRICE-PER-POUND field is used in a command or statement,
DATATRIEVE divides the value of the record's PRICE field by the value
of its DISP field. The result of the computation is then the value of the
PRICE-PER-POUND field.
2. Derive the value of the SALESMAN field from a description table named
SALESMEN.
08 SALESMAN
EDIT-STRING IS X(20)
COMPUTED BY MANUFACTURER VIA SALESMEN.

In this example, DATATRIEVE uses the value of the MANUFACTURER
field in the current record to search the description table SALESMEN for
a matching code. If one is found, DATATRIEVE uses its description as
the value of the SALESMAN field.

11.8 Edit-String Clause
Function

Specifies the format of the field value when it is printed.
Format

EDIT-STRING [IS] edit-string
Arguments

edi t-string
Is one or more edit-string characters describing the format of the field
value when it is printed.
Restrictions

This clause is valid for elementary fields only.

11-12

Creating Record Definitions

Description

The EDIT-STRING clause specifies the default format DATATRIEVE uses
when printing a field value. The PICTURE or USAGE clause specifies the
field's internal format. If there is no EDIT-STRING clause, the PICTURE
clause determines the default format. However, DATATRIEVE does not print
a sign or an implied decimal point specified in a PICTURE clause, unless you
specify those characters in an edit string. (To override the default format
specified by a PICTURE or EDIT-STRING clause, specify an edit string in
the PRINT statement.)
You specify the format of the field value with a string of one or more edit
characters. Specify the edit characters as a string without embedded spaces.
In general, each edit character corresponds to one character position in the
printed output. For example, 999999 specifies that the output will be six digits
in six character positions.
To enter more than one of the same edit character, you can shorten the edit
string by placing a repeat count in parentheses following the edit character.
For example, the edit string 9(6) is equal to 999999.
Table 11-3 contains a list of edit-string characters. The edit-string characters
you can specify for a field depends on the class of the field: alphanumeric,
numeric, or date.

Table 11-3: Edit-String Characters

Field Class

Edit-String
Character

Alphanumeric

Each X is replaced by one character from the field's content.

A space is inserted in that character position.

/ (slash)

A slash is inserted in that character position.

- (hyphen)

A hyphen is inserted in that character position.

Indicates text. The number of Ts is the length of a line.
DATATRIEVE prints the entire field using lines of the
length you indicate. Words are not broken; if a word is longer
than the line length it is printed on a line of its own. Edit
strings containing a T cannot contain other characters.

If a Z matches a leading zero in the field's content it is
replaced by a blank. If not, Z is replaced by a digit from the
field's content.

Each 9 is replaced by one digit from the field's content.

* (asterisk)

If an asterisk matches a leading zero in the field's content a *
is placed in that character position. If not, it is replaced by a
digit from the field's content.

o (zero)

A 0 is placed in that character position.

, (comma)

If all the digits to the left of the comma are suppressed zeros,
the comma is replaced by a blank. If not, a comma is inserted in that character position.
(contmued on next page)

Numeric

Description

Creating Record Definitions

11-13

Table 11-3: Edit-String Characters (Cont.)

Field Class

Date

Edit-String
Character

Description

. (period)

A decimal point is inserted in that character position. An
edit string for a numeric field can contain only one period.

- (minus)

If only one minus sign is specified, it is replaced by either a
blank (if the field's content is positive) or a minus sign (if it
is negative). If more than one minus sign is specified (such as
- -), the minus sign is a floating character.

+ (plus)

If only one plus sign is specified, it is replaced by either a
plus sign (if the field's content is positive) or a minus sign (if
it is negative). If more than one plus sign is specified (such as
++), the sign (plus or minus) is a floating character.

If only one dollar sign is specified, it is replaced by a $ in that
character position. If more than one dollar sign is specified
(such as $$), the dollar sign is a floating character.

If the field's content is positive, the letters CR are inserted. If
the field's content is negative, CR is replaced by 2 blanks.
(An edit string can contain only one CR.)

If the field's content is negative, the letters DB are inserted.
If the field's content is positive, DB is replaced by 2 blanks.
(An edit string can contain only one DB.)

A percent sign is inserted in that character position.

Each D is replaced by the corresponding digit of the day of
the month. An edit string should contain no more than 2 Ds;
the use of DD is recommended.

Each M is replaced by the corresponding letter of the name
of the month. An edit string of M(9) prints the entire name
of the month. An edit string should contain no more than 9
Ms.

Each N is replaced by a digit of the number of the month.
An edit string should contain only two Ns; the use of NN is
recommended.

-.07

Each Y is replaced by the corresponding digit of the numeric
year. An edit string should contain no more than 4 Ys; the
use of YY or YYYY is recommended.

Each J is replaced by the corresponding digit of the Julian
date.
An edit strin g should contain no more than 3 Js' the
I
use of JJJ is recommended.

I
W

11-14

Each W is replaced by the corresponding letter from the
name of the day of the week. An edit string of W(9) prints
the entire day. An edit string should contain no more than 9
Ws.

Each B is replaced by a space in that character position.

/ (slash)

A slash is inserted in that character position.

- (hyphen)

I A hyphen is inserted in that character position.

. (period)

A period is inserted in that character position .

Creating Record Definitions

I
I

11.8.1 Alphanumeric Fields
The edit string for an alphanumeric field specifies the number and type of
characters to be printed, except for T edit strings, which print
all the characters. The edit character X is replaced by one character from the
field's content. The characters are transferred from the field to the output in
left-to-right order.
If the edit string contains X and the field's content has more characters than
its edit string, only the leftmost characters are printed. If it has fewer characters than its edit string, DATATRIEVE pads the output with blanks on the
right.
If the field contains only digits, you may use a numeric edit string. The
restrictions on edit strings for numeric fields are explained in Section 11.8.2. If
you use a field in any arithmetic computations, you should define it as a
numeric field. You may perform computations with alphanumeric fields that
contain only digits, but, because alphanumeric fields are padded with spaces
on the right, the results may not be valid.

The edit-string characters B, slash, and hyphen allow you to insert those
characters in the output, in the position you indicate in the edit string. The B
and slash characters are also valid for numeric edit strings, but not T edit
strings. The hyphen is only valid for a field with an edit string containing X.
The following example contains some sample edit strings and the format of
DATATRIEVE's output for two field values: CHALLENGER and 123. The
example also shows the pictuie-stiing chaiacteis used in the field's PICTURE
clause to specify the internal format of the field value.
Picture
String

Edit
String

Output If Field Value Is:
CHALLENGER
123

X(lO)

X(10)

CHALLENGER

123#######

X(lO)

X(3)

CHA

123

X(lO)

XXIX(8)

CHIALLENGER

12/3#######

X(10)

X(5)IX(5)

CHALLIENGER

123##1#####

X(lO)

X(5)-XX

CHALL-EN

123##-##

Note: # represents a space.

Printing Long Field Values
The edit character T allows you to print alphanumeric field values on one or
more lines. The primary use of T is to print fields containing large amounts of
text. The number of Ts in the edit string indicates the maximum number of
characters to be printed on one line. For example, the edit string T(20) indicates that a line of output will contain no more than 20 characters (unless a
single word contains more than 20 characters).
If the field contains more characters than specified in the edit string,
DATATRIEVE prints as many full words on the line as possible. (A word, in

Creating Record Definitions

11-15

this sense, is a string of characters delimited by a space.) DATATRIEVE then
prints the remaining characters on the next line and following lines, if necessary. DATATRIEVE prints only full words; it does not divide or hyphenate
words. DATATRIEVE does not print out trailing· spaces when you use a T edit
string.
For example, the following field definition describes a field containing 150
alphanumeric characters. The edit string specifies that when the field is
printed, an output line will contain no more than 20 characters.
03 YACHT-DESCRIPTION
PIC IS X(150)
EDIT-STRING IS T(20).

The content of the YACHT-DESCRIPTION field could be a definition of
"yacht":
A relatively small sailing or mechanically driven- ship with a sharp prow and
graceful lines, ordinarily used for pleasure cruising or racing.
The following example shows the format of the output when it is printed:
DTR) PRINT YACHT-DESCRIPTION
YACHT
DESCRIPTION
A relatively small
sailinS or
mechanically driven
ship with a sharp
prow and sraceful
linest ordinarily
used for pleasure
cruisins or racinS.

If a word in the field content is longer than the edit string, DATATRIEVE
prints the word, even though it exceeds the length of the edit string. For
example, the following field definition specifies that an output line will contain no more than 10 characters:
03 YACHT-DESCRIPTION
PIC IS }((150)

EDIT-STRING IS T(10).

11-16

Creating Record Definitions

The same field content would be printed as:
DTR) PRINT YACHT-DESCRIPTION
YACHT
DESCRIPTION
A
relative!>'
s ITI all
sailing or
Itlechanically
dril)en
ship I"Jith
a sharp
prol,,1 and
graceful
linest
ordinarily
used for
pleasure

cruisins
or

racing.

When you print a long field value such as this, the field name should be the
last item in the print list. If another print item follows this field in the PRINT
statement, its value will be printed on the same line as the last line of text not the first line of text.

11.8.2 Numeric Fields
An EDIT-STRING clause prints numeric field values in a format that is easy
to read. With edit strings you can suppress leading zeros and print dollar
signs, percent signs, commas, decimal points, and plus or minus signs. For
example, in the YACHT record, the EDIT STRING for the PRICE field
clause causes DATATRIEVE to print the value 09870 as $9,870.
You can use three types of edit characters in edit strings for numeric fields:
replacement characters, insertion characters, and floating characters.
Replacement Characters

The replacement characters for numeric fields are 9, Z, * (asterisk), and 0
(zero). Each 9, Z, or asterisk causes one digit from the field value to be
printed. Each zero causes a zero to be printed, and the corresponding digit in
the field value is discarded.

Creating Record Definitions

11-17

A leading zero is any zero in a field value which has only zeros to the left of it.
If there is an implied decimal place to the left of a zero, then it is not a leading
zero. If a Z corresponds to a leading zero in a field then a space is printed
instead of a zero. If an asterisk corresponds to a leading zero in a field then an
asterisk is printed instead of a zero. The following example shows the differences between the various replacement characters.
Picture
String

Edit
String

Field
Content

Output

99999

9(5)

04092

99999

Z(5)

04092

#4092

99999

*(5)

04092

*4092

99999

ZZZOO

04092

#4000

99V99

99.99

0001

00.01

99V99

ZZ.ZZ

0001

##.01

Note: # represents a space.

Before printing a field, DATATRIEVE computes the number of digits to the
left of the decimal point. (If there is no V in the picture string, all digits are to
the left of the decimal.) If there are more digits to the left of the decimal than
the edit string specifies (either with replacement characters or float~ng characters) DATATRIEVE prints an asterisk in each character position specified
by the edit string. If the field has fewer digits than the edit string specifies
DATATRIEVE pads the output with leading zeros. (These are suppressed if
you use Zs or floating characters.)
For example, a PICTURE clause could specify four digits for a field, and its
edit string only two digits:
03 MODEL-NUMBER
PICTURE IS 8888
EDIT-STRING IS 88.

If the fIeld value is 1234, DATATRIEVE prints two asterisks (**) for the field
value. Therefore, be careful to specify edit strings that are long enough for
numeric fields.
If you define a numeric field with the clauses PIC 9(4) and USAGE IS COMP,
then the field can contain numbers as high as 32,768. To print the field when
it contains a five digit number, you must use an edit string that specifies five
digits,
Insertion Characters

With insertion characters you can print the sign of a field, a decimal point, a
dollar sign, DB for a negative value, CR for a positive value, a percent sign,
commas, and slashes.

11-18

Creating Record Definitions

Printing a Sign

To print a sign (+ or -) in a field value (indicated by an S in its PICTURE
clause), you must specify a + or - in the edit string for that field. The sign
must be the first or last character in the edit string.
If you specify only one sign in the edit string, DATATRIEVE prints the sign in
the position you indicate. If you specify more than one sign, the sign is a
floating character.

You can also use the edit characters DB and CR to indicate the sign of a field
value. You can only use one DB or CR in an edit string, and it must be the
first or last character in the edit string.
The following example shows the use of the edit characters +, -, DB, and CR:

Picture
String

Edit
String

Field
Content

Output

89999

(None)

-1234

1234

89999

-9999

-1234

89999

-9999

+1234

#1234

89999

9999+

-1234

1234-

89999

+9999

+1234

89999

9999DB

-1234

1234DB

89999

9999CR

-1234

1234##

89999

CR9999

+1234

CR1234

Note: # represents a space.

Printing a Decimal Point

To print an implied decimal point in a field value (indicated by a V in its
PICTURE clause), you must specify a period (.) in the edit string for that
field. When DATATRIEVE prints the field content, it aligns all output on the
decimal point.
DATATRIEVE matches the decimal point in the edit string with the implied
decimal place in the field. If the edit string contains fewer digits to the right of
the decimal, the extra digits are not printed. If the edit string contains fewer
digits to the left of the decimal, DATATRIEVE prints asterisks. Thus it is
best to place the period in the edit string in the same position as the V in the
picture string.

Creating Record Definitions

11-19

The following example shows printing decimal points in several different numeric fields.
Picture
String

Edit
String

Field
Content

Output

99V99

(None)

1234

99V99

Z9.99

1234

12.34

99V99

999.9

1234

012.3

99V99

9.999

1234

* ***

99V99

9.999

0123

1.230

99V99

Z(4)

1234

If the last character of the edit string is a period and is not followed by other
input on the same line, DATATRIEVE treats the period as the termination of
the field definition and not as part of the edit string. If the EDIT STRING
clause is the last part of the field definition, specify two periods; the first
period is part of the edit string and the second period ends the field definition.
If the EDIT STRING clause is not the last part of the field definition, place
the next clause on the same line or place a hyphen at the end of the line.

Printing Other Characters

To print a comma, slash, percent sign, or dollar sign, specify that character in
the edit string. If there are only spaces to the left of a comma, DATATRIEVE
prints a space instead of a comma. If you include more than one dollar sign, it
is a floating character. The following example shows how these characters are
used:
Picture
String

Edit
String

Field
Content

Output

99%

45%

9(6)

$999,999

100000

$100,000

9(6)

ZZZ,ZZZ

000040

#####40

9(6)

999/999

12~456

123/456

Note: # represents a space.

Floating Characters

You can specify three edit-string characters ($, -, and +) as floating characters. A floating character replaces all but the last leading zero with spaces.
The last leading zero is replaced by the edit-string character ($, -, or +).
Floating characters that correspond to digits are replaced by those digits.
Since one character is replaced by a t, -, or $, you must specify one more
character than the number of digits in the field.
To use a floating character, you must specify two or more of the same character. You can specify only one floating character in an edit string. For example,

11-20

Creating Record Definitions

you cannot have both a floating minus sign and a floating dollar sign in the
same edit string. The floating characters must be the leftmost characters in
an edit string.
The following example shows the use of floating characters in edit strings:
Picture
String

Edit
String

Field
Content

Output

89(4)

++++9

+0187

#+187

89(4)

++++9

-5764

89(4)

----9

+0187

##187

89(4)

----9

-0001

###-1

9(5)V99

$9(5).99

0015786

$00157.86

9(5)V99

$$$,$$$.99

0015786

##$157.86

9(5)V99

$$$,$$$.00

0015786

##$157.00

(!)mcn cnmml""'1n

+G4362

'l'uq"vO~Lln

C1r./".\

'1''1''1', '1''1''1' LIn

O~\U)

m~ A

or-.nr'1Tl

Note: # represents a space.

11.8.3 Date Fields:
A field defined as USAGE IS DATE is stored internally as a binary value. To
print this field, DATATRIEVE must convert it to another format. If you do
not include an EDIT-STRING clause in the field definition for a date field,
DATATRIEVE prints the field value in the following format:
DD-MMM-YY
To print the date in any other format, you must include an EDIT-STRING
clause in the field's definition. (You can also specify the output format using
the PRINT statement when you print the field.) The edit string for a date
field gives you several formatting choices for printing a date. (You can also use
the PICTURE clause to specify a date field's output format. However, the
PICTURE clause does not provide the many formatting options of the
EDIT-STRING clause.)
For example, you can print the date January 1, 1980, in any of the following
formats:
1 Jan SO
18S0/001
Tuesday IJanuary 01
Jan 01 SO
01/01/S0
01-Jan-18S0 Tue

Creating Record Definitions

11-21

There are many more formats that you can use to print a date. The date can
include:
• The name of the day of the week (Monday, Tuesday, etc.) or just the first
characters of the name (such as Mon, Tue, Wed)
• The day of the month (1, 2, 3, etc.)
• The name of the month (January, February, etc.) or just the first characters
of the name (such as Jan, Feb, Mar) .
• The number of the month (for example, 1 for January and 12 for December)
• The year (such as 1980) or just the last two digits of the year (80)
• The Julian date (for example, 001 for January 1 and 366 for December 31 in
a leap year)
• Delimiters to separate the parts of the date (such as a slash after the month
and day)
You specify the characters to be printed (letters, digits, spaces, slashes, hyphens, or periods) and the order in which the parts of the date are to appear
(such as month, day, year). The edit-string characters that you use to specify
the format of the date are shown in Table 11-3.
DATATRIEVE always outputs the number of characters you specify in the
edit string. If the content of the field is shorter than its edit string specifies,
DATATRIEVE pads the output with spaces or zeros until the length of the
output equals the length of the edit string. For example, an edit string can
specify a nine-letter month: M(9). If the field contains a month with a name
shorter than nine letters (such as June), DATATRIEVE pads the output on
the right with blanks. In this case, June would be printed as:
June#####
For numeric date fields, DATATRIEVE pads the output with zeros on the
left.
The following table contains some edit strings and the format of the output for
two field values: June 4, 1980 and November 27, 1978.
Output if Field Value Is:
Edit String

June 4, 1980

November 27, 1978

DD-MMM-YY

#4-Jun-80

27-Nov-78

MMMBDDBY(4)

Jun##4#1980

Nov#27#1980

1\1(9)BDDBY(4)

June#######4#1980

~overnber##27#1978

NN/DD/YY

6/04/80

11/27/78

W(9)

Wednesday

Monday###

YYYY/JJJ

1980/156

1978/331

DDBMMMBYY/WWW

#4#J un#80/Wed

27#Nov#78/Mon

DD.NN.YY

#4.06.80

27.11.78

Note: # represents a space.

11-22

Creating Record Definitions

11.9 OCCURS Clause
The OCCURS clause defines multiple occurrences (or repetitions) of a field or
group of fields. The multiple occurrences, called a list, create a hierarchy in
the domain. (See Chapter 16 for more information on hierarchies.)
The OCCURS clause has two formats: one format for a fixed number of
occurrences; one for a variable number of occurrences. Each is described in
the following sections.

11.9.1 Fixed Number of Occurrences
Function

Defines a fixed number of occurrences for a field or group of fields.
Format
OCCURS n TIMES

Arguments

n
Is a positive integer specifying the number of occurrences for the field.
Restrictions

A field definition cannot contain both an OCCURS and a COMPUTED BY
clause. (You cannot specify multiple occurrences of a COl\1PUTED BY field.)
Description

This format of the OCCURS clause defines a list with a fixed number of
occurrences. It reserves enough space in each record to contain all the occurrences of the field (or fields), whether or not they contain data. For example,
the following field definition reserves enough space in every record for two
occurrences of the elementary field KIDS-NAMES; each occurrence is 10
characters long.
03 KIDS-NAMES PIC X(10)
DCCURS 2 TIMES.

Thus, yoacan store up to two names (containing up to 10 characters each) in
any record.
The following definition specifies that the group field KIDS-NAMES is
repeated twice. Each group field contains two fields: FIRST-NAME (10 characters long) and MIDDLE-INIT (1 character). A total of 22 characters is
reserved in every record for the group field.
03 KIDS-NAMES OCCURS 2 TIMES.
05 FIRST-NAME PIC X(10).
05 MIDDLE-INIT PIC X.

Creating Record Definitions

11-23

In the record, the fields are stored in the following order:
KIDS-NAMES
FIRST-NAME
MIDDLE-INIT
KIDS-NAMES
FIRST-NAME
MIDDLE-INIT

A field in a group field with an OCCURS clause can contain an OCCURS
clause. The result is a sublist: a list nested within a list. For example, you can
reserve enough space in a record to store up to three nicknames for each
KIDS-NAMES:
03 KIDS-NAMES OCCURS 2 TIMES.
05 FIRST-NAME PIC X(10).
05 MIDDLE-INIT PIC X.
05 NICKNAME PIC X(10)
OCCURS 3 TIMES.

The fields are stored in the following order:
KIDS-NAMES
FIRST-NAME
MIDDLE-INIT
NICKNAME
NICKNAME
NICKNAME
KIDS-NAMES
FIRST-NAME
MIDDLE-INIT
NICKNAME
NICKNAME
NICKNAME

A record definition can contain any number of OCCURS clauses In this
format.

11.9.2 Variable Number of Occurrences
Function

Defines a variable number of occurrences of a group of fields.
Format
OCCURS min TO max TIMES DEPENDING ON fld-name

Arguments

min
Is a non-negative integer specifying the minimum number of occurrences
of the field. This value can be o. DATATRIEVE does not check this value.
max
Is a positive integer specifying the maximum number of occurrences of the
field. This value must be greater than O.

11-24

Creating Record Definitions

fld-name
Is the name of a field in the same record definition. The value of the field
determines the number of occurrences of this field. The field must be a
numeric field containing a non-negative integer; it cannot be defined with
digits to the right of the decimal point.

Restrictions

1. No other field definition can follow the last elementary field in the group
field containing this clause.

2. A record definition can contain only one OCCURS clause in this format.
3. A field definition cannot contain both an OCCURS and a REDEFINES
clause or an OCCURS and a COMPUTED BY clause.

Description

This format of the OCClJRS clause defines a list ~Nith a variable number of
occurrences.
The number of occurrences of the group field in any record is equal to the
value of the field specified in the OCCURS clause. Theref~re, the sizes of
records in the domain can vary. If you use the MAX argument when you
define the data file, all records in the file have the same length. The DEFINE
FILE command is described in Section 5.8.
The FAMILY-REC record definition shows the use of an OCCURS clause in
this format:
01 FAMILY.
03 PARENTS.
06 FATHER PIC X(10).
06 MOTHER PIC X(10).
03 NUMBER-KIDS PIC 88 EDIT-STRING IS 28.
03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER-KIDS.
06 EACH-KID.
08 KID-NAME PIC X(10) QUERY-NAME IS KID.
08 AGE PIC 88 EDIT-STRING IS 28.

The number of occurrences of the KIDS field depends on the value of the
NUMBER-KIDS field. If the value is 0, there are no occurrences of the field;
if it is 1, there is one occurrence, and so on. Each occurrence of KIDS contains
three fields: the group field EACH-KID and the elementary fields
KID-NAME and AGE.
A group field containing this format of the OCCURS clause can contain one or
more fields with an OCCURS clause. The nested OCCURS clause, however,
must specify a fixed number of occurrences of the field.
Creating Record Definitions

11-25

11.10 PICTURE Clause
Function

Specifies the format of the field value as it is stored.
Format

I PICTURE}
PIC

\ ~S]Pictur.-string

Arguments

picture-string
Is one or more picture-string characters describing the format of the field
value as it is stored.
Restrictions

This clause is valid for elementary fields only.
Description

The picture string controls the storage format of the field's content. In general, each character in the string corresponds to one character position in the
field value. "(For numeric fields, you can also include a USAGE clause to
specify the internal format of the digits.) For example, for a numeric field
without a USAGE clause, 999999 specifies six digits in six character positions,
occupying six bytes of storage.
To enter more than one of the same picture character, you can shorten the
string by placing a repeat count in parentheses following the picture character. For example, the picture string 9(6) is equal to 999999.
Specify the picture-string characters as a string. Do not embed a space in the
picture string.
Table 11-4 contains a list of the picture-string characters. The picture-string
characters you specify for a field depend on the class of the field: alphanumeric
or numeric.

11-26

Creating Record Definitions

Table 11-4: Picture-String Characters

Field
Class

Picture
Character

Meaning

Alphanumeric

Each X represents one character in the field.

Numeric

Each 9 represents one digit in the field. You can specify from 1
to 1-8 digits for a numeric field.

An S indicates that a sign (+ or -) is stored in the field. A
picture string can have only one S and it must be the leftmost
character. If there is no SIGN clause for the field, the sign
shares the rightmost character position with the lowest-valued
digit.

A V indicates an implied decimal point. The decimal point
...........
..
...
d. oes not occupy a character pOSItIOn m the neld, although
DATATRIEVE uses its location to align data in the field. A

I
P

_._.l.

_____

_ .i. __ ~ __

_____

___

..l_~

_ _ _ _ _ 1 ______

'1:7

plCLure tSLHng can CUll LaIn UIllY Ulle v.

Each P specifies a decimal scaling position. Each P represents

in digits from an implied decimal point. (A P
I adoes"distance"
not count toward the limit of 18 digits per field.) A P can

appear at the right or left of the picture string. A V is unnecessary for any picture string containing a P.

11.10.1 Alphanu meric Fields
The picture string for an alphanumeric field specifies the number of characters in the field. Only the picture character X is valid in the picture string for
an alphanumeric field. Each X corresponds to a single character position in
the field. For example, the following field definition specifies the MODEL
field contains ten alphanumeric characters:
06 MODEL PIC X(10).

Creating Record Definitions

11-27

11.10.2 Numeric Fields
A numeric field can contain the characters 9, S, V, and P in its picture string
to specify: the number of digits in the field, a sign, an implied decimal point,
and a decimal scaling factor.
Specifying the Number of Digits

The picture character 9 represents one digit in the field value. For example,
the picture string 9(4) indicates four digits; the field value can range from 0 to
9999. There is one exception to this; if you specify PIC 9999 and USAGE IS
COMP, then it possible to store numbers as large as 32,768. You can specify
from 1 to 18 digits for a numeric field.
The following field definition specifies that the BEAM field contains two
digits:
03 BEAM PIC 99.

Specifying a Sign

To specify that a numeric field can contain a sign (+ or -), you must include
an S in its picture string. The S must be the leftmost character in the picture
string; a picture string can contain only one S. For example, the picture string
S9(4) indicates a signed field, four digits in length; the field value can range
from -9999 to +9999.
The sign specified with the PICTURE clause is not printed unless you include
an EDIT-STRING clause with the field definition. For example, the following
field definition specifies a sign in the picture string, which is printed following
the last digit of the field value:
03 CURRENT-BALANCE
PICTURE IS S9999V99
EDIT-STRING IS $$$$9.99-.

Specifying a Decimal Place

The picture character V specifies the position of an "implied" decimal point.
For example, the picture string 9(5)V99 specifies a seven-digit field; the last
two digits of the field value follow the decimal point.

11-28

Creating Record Definitions

The decimal point does not occupy a character position in the record;
DATATRIEVE uses the implied decimal point in computations, Bool-ean expressions, and other arithmetic operations.
The implied decimal point is not printed unless you specify a period (.) in the
EDIT-STRING clause for the field definition. For example, the following
record definition specifies that a decimal point be printed before the last two
digits in the PRICE field:
03 PRICE PIC 888V88
EDIT-STRING IS $888.88.

If there is no V in the picture string, DATATRIEVE treats the field value as
an integer (that is, as if a V were specified to the right of the rightmost digit).
Thus, the picture strings 999 and 999V are equal.
Scaling Factor

The picture character P specifies a decimal scaling factor; that is, the number
of digits from an implied decimal point. Each P in the picture string represents one position from the decimal point.
The P (or multiple Ps) must be the leftmost or rightmost characters in the
picture string. If the P is the leftmost character(s), the decimal point is assumed to be to the left of the leftmost P. For exam pIe, the picture strings
PPP99 and VPPP99 are equal. (If you specify a P in a pictuFe string, the V
character is optional.) If the P is the rightmost character(s), The decimal
point is assumed to be to the right of the rightmost p, Thus, 999PP and
999PPV are equal.
DATATRIEVE treats each P in a picture string as a zero. The string PPP99
specifies that the field can contain values in the range 0 to .00099; the three
leftmost digits are assumed to be zeros. The range of values for a field with a
picture string of 999PP is 0 and 100 to 99,900, but the two rightmost digits are
assumed to be zeros.
Scaling positions are not printed unless you include an EDIT-STRING
clause. The implied decimal point in a picture string containing the P character is not printed unless you specify a period (.) in the EDIT-STRING clause
in the field definition.

Creating Record Definitions

11-29

11.11 QUERY-HEADER Clause
Function

Specifies the column header to be used when the field is printed by the
DATATRIEVE or Report Writer PRINT statement.
Format
QUERY - HEADER~SJ "header-l "~"header-2'J ...

Arguments

'·'header"
Is the column header to be printed above the column of field data. If you
specify only one character string literal, that string is printed on one line
above the column. If you specify more than one character string literal,
they must be separated by a slash (/). The literals are printed on successive lines, centered above the column.
Restrictions

This clause is valid for elementary fields only.
Description

If you omit this clause, DATATRIEVE uses the field name as the default
column header when printing this field.

The column header can include any character except carriage return, line
feed, or control character. To include a quotation mark in a column header,
precede it with a second quotation mark. (See Example 3, below.)
You can perform the same functions of the QUERY-HEADER clause with the
DATATRIEVE or Report Writer PRINT statement. The following PRINT
statement prints a column header above the specified field data.
PRINT fld-naITle( "header-l"[/"header-2"J + + +)

If the size of a record definition is a consideration, you might choose to use
this format of the PRINT statement instead of including a lengthy query
header in the record definition. See Section 5.25 for more information on the
DATATRIEVE PRINT statement and Chapter 7 for the Report Writer
PRINT statement.
Examples

1. When the DISPLACEMENT field is printed, use a column header of
WEIGHT above the column of data.
06 DISPLACEMENT PIC 88888
QUERY-HEADER IS "WEIGHT"
EDIT-STRING IS ZZ,ZZ8
QUERY-NAME IS DISP.

ii-30

Creating Record Definitions

2. When the LENGTH-OVER-ALL field is printed, use a column header of
LENGTH (IN FEET) on two separate lines.
06 LENGTH-OVER-ALL PIC XXX
QUERY-HEADER IS "LENGTH" j"(IN FEET)",

DATATRIEVE prints the column header as:
LENGTH
(IN FEET)

3. When the LENGTH-OVER-ALL field is printed, use a column header of
Length-Over-All ("LOA") on two separate lines.
06 LENGTH-OVER-ALL PIC XXX
QUERY-HEADER IS ILenBth-OI.ler-Allljl(IILOAII)",

DATATRIEVE prints the column header as:
LenBth-Ol.ler-All
("LOA")

Creating Record Definitions

11-31

11.12 QUERY-NAME Clause
Function

Specifies an alternate name for the field.
Format
QUERY-NAME IS query-name
Arguments

query-name
Is the query name. The rules for forming and using a query name are the
same as for those for a field name.
Restrictions

None. This clause is valid for both group and elementary fields.
Description

Use the QUERY-NAME clause when a field name is too long to use easily.
The query name must conform to the rules for names (see Section 11.4). Like
a field name, a query name can duplicate another query name (or a field
name) in the record. A query name can also be qualified by other query names
or field names.
Examples

1. Define DISP as a alternate name for the DISPLACEMENT field.
08 DISPLACEMENT PIC 99999
QUERY-NAME IS DISP.

2. Define SPECS as an alternate name for the group field SPECIFICATIONS.
03 SPECIFICATIONS

3. Define a query name of SPECIAL-HANDLING
DELINQUENT-ACCOUNT-STATUS.
09 DELINQUENT-ACCOUNT-STATUS

PIC }-{
QUERY-NAME IS SPECIAL-HANDLING.

11-32

Creating Record Definitions

for

the

field

11.13 REDEFINES Clause
Function

Provides an alternate way to define a field.
Format
lev-no fld-name-l REDEFINES fld-name-2

Arguments

lev-no
Is the level number of fld-name-1. The level number is not part of the
REDEFINES clause, but is shown in the format only to clarify its relative
position.
fld-name-I
Is the name of the field that provides the redefinition. The field name is
not part of the REDEFINES clause, but is shown in the for:r;nat only to
_1 ___

~f'

~..L

____ 1_..L~ _ _ _ _ _ _ _ ~..L~ _ _ _ _ _ _

..1

f'_____

..L~

__ _

CHirllY lL:S reHiLlve PU:SlLIUIl clIlU lUIlCLlUIl.

fld-name-2
Is the name of the field being redefined.
Restrictions

1. The field to be redefined (fld-name-2) must appear before its redefinition
(fld-name-I) in the record definition. Both fields must have the same
level number.
2. The definition of fld-name-2 cannot contain a REDEFINES clause. However, it can be subordinate to a group field with a REDEFINES clause.
3. Neither fld-name-I nor fld-name-2 can be defined with (or contain a field
defined with) an OCCURS ... DEPENDING clause.
4. Neither field-name-I nor fld-name-2 can contain a COMPUTED BY
clause. (You cannot redefine a COMPUTED BY field.)
5. The REDEFINES clause must immediately follow the name of the field
containing the redefinition (fld-name-I). No other clause can be used
between the field name and the keyword REDEFINES.
6. The field providing the redefinition (fld-name-I) cannot describe an area
larger than the area of fld-name-2. However, the area can be smaller than
that of fld-name-2.

Creating Record Definitions

11-33

Description

The REDEFINES clause redefines an elementary or group field. The redefinition refers to the same area of the record as the original definition, but it uses
the content of the field in a different way. For example, if you need to refer to
parts of a numeric field as well as the field itself, you can redefine the field as
a group field. The subordinate fields of the group fields would contain the
parts of the numeric field value that you will refer to. Thus, the REDEFINES
clause allows you to redefine a numeric field as a group field. (A group field
cannot be numeric; a group field is always alphanumeric.)
The following record definition shows a redefinition of the field PARTNUMBER. PART-NUMBER is a numeric field containing ten digits. Two
group fields redefine PART-NUMBER: PART-NUMBERS-PARTS and
PART-NUMBER-GROUPS. Each redefinition specifies a group field containing a total of ten digits (the total number of digits in all subordinate
fields) .
05 PART-NUMBER PIC 9(10).
05 PART-NUMBER-PARTS REDEFINES PART-NUMBER.
07 PRODUCT-GROUP PIC 99.
07 PRODUCT-YEAR PIC 99.
07 ASSEMBLY-CODE PIC 9.
07 SUB-ASSEMBLY PIC 99.
07 PART-DETAIL PIC 999.
05 PART-NUMBER-GROUPS REDEFINES PART-NUMBER.
07 PRODUCT-GROUP-ID PIC 9(4).
07 PART-DETAIL-ID PIC 9(G).

In this example, the field PRODUCT-GROUP refers to the lowest-valued
digits of PART-NUMBER; PRODUCT-YEAR to the next two lowest-valued'
digits, and so on.

11-34

Creating Record Definitions

11.14 SIGN Clause
Function

Specifies the location and representation of a sign (+ or -) in a numeric
elementary field.
Format

LEADING

SIGN~S]

[SEPARATE]
TRAILING

Arguments

LEADING
TRAILING
Indicates that the sign is at the left (LEADING) or right (TRAILING) of
the field value,
SEPARATE
Indicates that the sign occupies its own character position in the field. If
this argument is omitted, the sign shares a character position with the
field's leftmost (if it is LEADING) or rightmost (TRAILING) digit.
Restrictions

1. This clause can be used only with numeric elementary fields.

2. A field definition cannot contain both a SIGN and a USAGE clause (other
than USAGE IS DISPLAY).
Description

If you do not include a SIGN clause with a numeric field, the sign shares a
character position with the field's rightmost digit. You must include this
clause if a program written in COBOL (or other language) uses the record and
requires that the sign be a separate character or share the leftmost character
position. A sign clause does not affect the printing characteristics of a field.
Examples

1. Define the field CURRENT-BALANCE as a six-digit signed field, with
the sign sharing the leftmost character position.
03 CURRENT-BALANCE
PIC IS S9999 1)99
EDIT-STRING IS $$$$9.99SIGN IS LEADING.

2. Define the field NEW-PRICE as a four-digit signed field. The sign is a
separate character in the rightmost character position.
03 NEW-PRICE PIC S99V99
SIGN TRAILING SEPARATE
EDIT-STRING +++.99.

Creating Record Definitions

11-35

11.15 USAGE Clause
Function

Specifies the internal format of a numeric field or specifies a date field.
Format

DISPLAY

{COMP
}
INTEGER
COMP-l
REAL
COMP-2
DOUBLE
USAGE IS

{

COMP-3
PACKED

{

COMP-5
ZONED

}
}

COMP-6
DATE

Arguments

DISPLAY
Indicates that each digit occupies one byte of storage. DISPLAY is the
default if you do not include a USAGE clause.

t COMP t
(INTEGER,

Indicates that the field value is stored in binary format. INTEGER is a
synonym for COMPo
, COMP-l)
\

{

R~AT
.u ..

I.L.J

Indicates that the field value is stored in single-precision real format.
REAL is a synonym for COMP-I.

COMP-2
{ DOUBLE,
Indicates that the field value is stored in double-precision real format.
DOUBLE is a synonym for COMP-2.

11-36

Creating Record Definitions

C. OMP-3 ~.
{ PACKED,
Indicates that the field value is stored In packed-decimal format.
PACKED is a synonym for COMP-3.
COMP-5 ~
{ ZONED ,
Indicates that the field value is stored in signed decimal format. ZONED
is a synonym for COMP-5.
COMP-6
Indicates that the field value is stored in PDP-11 COBOL V3
COMPUTATIONAL format. (COMP-6 has no synonym.)
DATE
Indicates that the field is a date field.
Restrictions

1. This clause is valid for elementary numeric or date fields only.

2. A field definition cannot contain both a USAGE clause (other than
USAGE IS DISPLAY) and a SIGN clause.
General Description

If a numeric field definition does not have a USAGE clause, each digit in the
field value occupies one character position in the record. Use the appropriate
form of the USAGE clause when a program written in COBOL,
BASIC-PLUS-2, or other language uses the record and requires a different
internal format.
The USAGE IS DATE clause identifies the field as a DATATRIEVE date
field.
The USAGE clause can cause DATATRIEVE to align fields on hardware
storage boundaries. Refer to Appendix E for more information on alignment.

11.15.1 COMP (dr INTEGER) Fields:
A CaMP (or INTEGER) field stores its value in binary format. The size of a
CaMP (or INTEGER) field depends on the number of digit positions specified in its PICTURE clause:
PIC Clause

Size of Field

9(1) to 9(4)

2 bytes

9(5) to 9(9)

4 bytes

9(10) to 9(18)

8 bytes

Creating Record Definitions

11-37

11.15.2 COMP-1 (or REAL) Fields
A COMP-I (or REAL) field stores its value in single-precision real (floating
point) format. COMP-I fields are four bytes long.

11.15.3 COMP-2 (or DOUBLE) Fields
A COMP-2 (or DOUBLE) field stores its value in double-precision real (floating point) format. COMP-2 fields are eight bytes long.

11.15.4 COMP-3 (or PACKED) Fields
A COMP-3 (or PACKED) field stores its value in packed-decimal format.
The value is stored two digits per byte. The value of a COMP-3 field must
contain a sign. The sign occupies the four low-ordered bits in the rightmost
byte. The size of the field depends on the number of digit positions specified
by the f:eld's PICTURE clause:
digit-positions + I
size (in bytes) =
2

For example, a field with three digit positions is two bytes long. If the field
contains an even number of digits, the size is rounded up. Thus, a six-digit
field is stored in four bytes.

11.15.5 COMP-5 (or ZONED) Fields
A COMP-5 (or ZONED) field stores its value in signed decimal format. A
value in a COMP-5 field is stored one digit per byte. Therefore, the size of a
COMP-5 field is the number of digit positions specified in its PICTURE
clause.
The sign of a COMP-5 value shares the rightmost byte with lowest-valued
digit of the value. The lowercase letters p through y represents a negative sign
for the values 0 through 9.

11.15.6 COMP-6 Fields
A COMP-6 field stores its value in PDP-II COBOL V3 COMPUTATIONAL
format. The size of a COMP-6 field depends on the number of digit positions
specified in its PICTURE clause:

II PIC Clause I Size of Field II
9(1) to 9(4)

2 bytes

9(5) to 9(9)

4 bytes

9(10) to 9(14)

6 bytes

19(15) to 9(18) 18 bytes

11-38

Creating Record Definitions

11.15.7 DATE Fields
A DATATRIEVE DATE field stores a date as an eight-byte binary value.
Other languages will not interpret the date field correctly. The date is expressed as the number of clunks (IOO-nanosecond units) since the base date of
00:00:00 AM on November 17, 1858.
When you print a date field, DATATRIEVE translates the number of clunks
to the format you specify in the EDIT-STRING clause (or to the default
format if no EDIT-STRING clause is included in the field definition). The
default format is DD-MMM-YY for dates in the 20th century, and
DD-MMM-YYYY for all other dates.
When you enter a date value, DATATRIEVE translates the input value to
clunks before storing it.
Examples

1. Define the field SALE-DATE as a date field, to be printed in the default
I! __ ..l_L_ 1!!_l..l_
lU1"l11ClL lUI" UClLt:: llt::lU:S.

I! ____ L

08 SALE-DATE USAGE IS DATE.

2. Define the field SALE-PRICE as a REAL (COMP-l) field.
05 SALE-PRICE PIC 8(5)
USAGE REAL
EDIT-STRING IS $(8).

Creating Record Definitions

11-39

11.16 VALID IF Clause
Function

Validates a value for the field before it is stored in the record.
Format
VALID IF bool-exp

Arguments

bool-exp
Is any Boolean expression.
Restrictions

A field definition cannot contain both a VALID IF and a COMPUTED BY
clause.
Description

When a value is entered for the field with a MODIFY or STORE statement,
DATATRIEVE evaluates the Boolean expression. If the Boolean expression
is "True," DATATRIEVE stores the value in the field. If it is "False,"
DATATRIEVE prints an error message and reprompts for the field value.
Examples

1. Compare the value entered for the RIG field to the character strings
SLOOP, KETCH, MS, and YAWL. Store the value in the field if it is one
of those character strings.
08 RIG PIC ~'{(8)
I.JALID IF RIG EQ "SLOOP" t "KETCH" t "MS" t "YAWL".

2. Store a value in the field LENGTH-OVER-ALL if it is between 15 and 50.
08 LENGTH-OVER-ALL PIC XXX
VALID IF LOA BETWEEN 15 AND 50
QUERY-NAME IS LOA.

3. Store a value in the PRICE field if it is greater than 1.3 times the displacement or if it is zero.
08 PRICE PIC 88888
VALID IF PRICE>DISP*l,3 OR PRICE EQ 0
EDIT-STRING IS $$$t$$$.

11-40

Creating Record Definitions

Chapter 12
Procedures and Indirect Command Files

A procedure is a fixed sequence of DATATRIEVE commands, statements,
clauses, or arguments that you create, name, and store in the data dictionary.
A procedure can contain command and statement sequences that you use
frequently or that should be available to other users at an installation.
Once a procedure is defined in the data dictionary, you need only invoke the
procedure to execute all the commands and statements it contains. Thus, a
procedure can save a great deal of time because you need not reenter
commonly used sequences of commands and statements. You avoid the typing
errors that result from issuing DATATRIEVE commands and statements interactively. Furthermore, the complex command sequences in procedures are
available to other users, and need not be reinvented each time they are
needed.
An indirect command file can contain a fixed sequence of DATATRIEVE
commands and statements, but it is stored in your directory, not in the data
dictionary. ADT (Application Design Tool) creates an indirect command file
containing the domain, record, and file definitions, and you can create similar
files of your own. You can also put frequently used sequences of commands
and statements in indirect command files. You can use these files to backup
definitions of dictionary objects, to move dictionary objects from one dictionary to another, and to develop complex procedures. Although somewhat
similar to procedures, indirect command files have some restrictions that
procedures do not. Section 12.2 explains the uses and limitations of indirect
command files.

12.1 Procedures
12.1.1 Creating a Procedure
To create a procedure, 'issue the DEFINE PROCEDURE command. (See
Section 5.9 for more information on the DEFINE PROCEDURE command.)
DEFINE PROCEDURE

Froe-naMe

12-1

DATATRIEVE then prompts with DFN> to indicate that it expects a procedure definition. Enter the commands, statements, clauses, or arguments that
form the procedure definition. DATATRIEVE continues to prompt with
DFN> until you enter the keyword END-PROCEDURE on a line by itself.
DATATRIEVE does not check for syntax errors while you enter the procedure
definition; the syntax is checked only when you invoke the procedure.
DTR) DEFINE PROCEDURE Froc-naMe
DFN>
DFN>
DFN>
DFN) END-PROCEDURE
DTR)

As soon as you enter END-PROCEDURE, DATATRIEVE stores the procedure definition in the current data dictionary and creates a password table for
the procedure.

12.1.2 Contents of a Procedure
A procedure can contain any number of the following DATATRIEVE
elements:
• Full DATATRIEVE commands and statements
• Command and statement clauses and arguments
12.1.2.1 Commands and Statements - A procedure can contain all but five of
the DATATRIEVE commands and statements listed in Chapter 5 or any
statement listed in Chapter 7. If you enter a full command or statement in a
procedure, you must follow the format for that command or statement as
shown in Chapter 5 or 7. And, you must observe any restriction on the command or statement that is listed in its description.

You can include any DATATRIEVE command or statement in the procedure
except the following:
• DEFINE DOMAIN
• DEFINE PROCEDURE
• DEFINE RECORD
*

• DEFINE TABLE
• EDIT
For example, the following command can be entered at the DATATRIEVE
command level to establish a collection named BIGGIES. The collection contains records of all yachts with a length-over-all greater than 40 and is sorted
by the builder name.
DTR) FIND BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER
[8 records found]

DTR)

12-2

Procedures and Indirect Command Files

The same full command can be entered in a procedure:
DTR
DFN
DFN
DTR

DEFINE PROCEDURE BIG-YACHTS
FIND BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER
END-PROCEDURE

When you execute the procedure BIG-YACHTS, the results are the same as
entering the FIND command at the command level:
DTR) :BIG-YACHTS
[8 records found]
DTR)

In addition to containing full commands
and statements, a procedure can contain just a clause or argument from a
command or statement. For example, instead of putting a full FIND command into a procedure, you can include just a record selection expression:

12.1.2.2 Clauses and Arguments -

DTR) DEFINE PROCEDURE BIG-YACHTS-RSE
DFN) BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER
DFN) END-PROCEDURE
DTR)

Then, you can use the procedure name as the argumf3nt of a FIND command:
DTR) FIND :BIG-YACHTS-RSE
[8 records found]
DTR)

In fact, you can use this procedure in any command or statement containing
an rse argument, such as the PRINT statement:

DTR) PRINT ALL :BIG-YACHTS-RSE
MANUFACTURER
CHALLENGER
COLUMBIA
GULFSTAR
ISLANDER
NAUTOR
NEWPORT
OLYMPIC
PEARSON

MODEL
41
41
41

FREEPORT
SWAN 41
41 S
ADI.JENTURE
419

RIG

LENGTH
OI.JER
ALL

WEIGHT

BEAM

PRICE

KETCH
SLOOP
KETCH
KETCH
SLOOP
SLOOP
KETCH
KETCH

41
41
41
41
41
41
42
42

26,700
20,700
22,000
22,000
17,750
18,000
24,250
21,000

13
11
12
13
12
11
13
13

$51 ,228
$48,490
$41,350
$54,970
$80,500

DTR) :BIG-YACHTS-QUERY
Enter MIN LOA: 39

12.1.2.3 Comments You can include comments in a procedure as you
create it, but comments are not stored in the data dictionary:

Procedures and Indirect Command Files

12-3

If you want to print comments on the terminal when you or another user
executes your procedure, you can use the PRINT command, as shown in the
following example:
DTR) DEFINE PROCEDURE YACHTS-REPORT
DFN) PRINT "THIS REPORT REQUIRES AN ESTABLISHED COLLECTION"
DFN) PRINT "SORTED BY BUILDER"
DFN)
DFN)
DFN)

The first two lines of this procedure print a message on your terminal when
the procedure is executed.
DTR) :YACHTS-REPORT
THIS REPORT REQUIRES AN ESTABLISHED COLLECTION
SORTED BY BUILDER

12.1.3 Invoking a Procedure
As you have seen from the previous examples, you invoke a procedure by
preceding its name with a colon (:).
: proc-nalTle

To invoke a procedure, you must have E (execute) access to it based on your
UICIPPN.
The content of a procedure determines where you can invoke it. In general,
you can invoke a procedure anywhere that you can use the commands, statements, clauses, or arguments contained in the procedure. For example, if the
procedure contains only DATATRIEVE commands and statements, you can
invoke it at the DATATRIEVE command level.
DTR)

:proc-naITle

You cannot invoke a procedure in any of the following commands:
• ADT
• DEFINE DOMAIN
• DEFINE RECORD

= DEFINE TABLE
• EDIT
• SET GUIDE

12.1.4 Debugging and Editing a Procedure
When you invoke a procedure, DATATRIEVE executes each command or
statement in the procedure as if it were entered directly at DAT ATRIEVE
12-4

Procedures and Indirect Command Files

command level. Some errors may occur during execution of the procedur~. A
typing error, for instance, can result in a syntax error in an otherwise correctly
formatted command. If an error occurs during execution, DATATRIEVE
prints an error message and terminates the procedure. You can correct the
error by using the DATATRIEVE editor. Invoke the editor with the following
command:
DTR) EDIT proc-name
QED)

When you find the error, use the appropriate editor commands to correct it.
(See Chapter 8 for more information about the DATATRIEVE editor.)

12.1.5 Nesting Procedures
You can nest procedures by invoking a procedure within another procedure.
However, do not allow a procedure to invoke itself, either directly or indirectly; you can create an infinite loop.
lishes a format for printing:
DTR) DEFINE PROCEDURE PRICE-PER-POUND
DFN> PRICE/DISPLACEMENT ("PRICE"/"PER"/"POUND") DFN>
USING ZZ8.88
DFN> END-PROCEDURE
DTR>

The PRICE-PER-POUND procedure can then be invoked in another procedure that prints the builder, model, and price per pound of all yachts in the
CURRENT collection.
DTR> DEFINE PROCEDURE PRICE-REPORT
DFN) PRINT ALL BUILDERt MODELt :PRICE-PER-POUND
DFN) END-PROCEDURE
DTR)

When the procedure PRICE-REPORT is executed, it prints the three fields
on the terminal. The following example uses the BIG-YACHTS procedure to
establish the CURRENT collection and PRICE-REPORT to print a short
report.
DTR) :BIG-YACHTS;:PRICE-REPORT
[8 records found]

MANUFACTURER

MODEL

PRICE
PER
POUND

CHALLENGER
COLUMBIA
GULFS TAR
ISLANDER
NAUTOR
NEWPORT
OLYMPIC
PEARSON

41
41
41
FREEPORT
SWAN 41
41 S
ADVENTURE
418

$1 .81
$2.34
$1.87
$2.48
$.00
$.00
$3.31
$.00

Procedures and Indirect Command Files

12-5

The maximum depth of procedure nesting depends on such factors as the
amount of DATATRIEVE workspace available, the number and size of established collections, the size of all procedures invoked, and the number and type
of readied domains.

12.1.6 Using a Procedure in a Loop
You can invoke a procedure in a REPEAT statement to execute it a number of
times or in a FOR statement to apply it to a collection of records. You must,
however, use care when invoking a procedure in these statements. For example, the following statement is syntactically correct, but will produce results
you may not expect:
DTR> REPEAT 5 :proc-naMe

This statement does not execute the procedure five times; it executes the first
command or statement in the procedure five times, then executes the remainder of the procedure once. When DATATRIEVE encounters the first complete
statement in the procedure, it assumes that the REPEAT statement is also
complete. Therefore, it executes the first command or statement in the procedure five times. DATATRIEVE then executes the remaining commands or
statements in the procedure.
To repeat the entire procedure, enclose the procedure call or the procedure
definition in a BEGIN-END block. For example, the following sequence of
statements puts a procedure call in a BEGIN-END block and repeats the
procedure five times:
DTR) REPEAT 5 BEGIN
DTR) : proc-nalTle
DTR) END

The following example includes a BEGIN-END block in a procedure definition and invokes the procedure in a REPEAT statement.
DTR)
DFN)
DFN)
DFN>
DFN>
DFN>
DFN>
DTR>

DEFINE PROCEDURE proc-naMe
BEGIN

END
END-PROCEDURE
REPEAT 5 :proc-naMe

If you invoke a procedure in a FOR statement, you must use the same tech~
nique: enclose the call or the procedure definition in a BEGIN-END block.
For instance:
DTR> FOR rse BEGIN
DTR> :proc-naITle
DTR> END

12-6

Procedures and Indirect Command Files

Also, remember that if you use a procedure in this way, it cannot include
a FIND or SELECT statement; FIND and SELECT cannot be used In
BEGIN-END blocks.

12.1.7 Aborting Procedures
You can abort the execution of a procedure by including an ABORT statement (Section 5.1) in the procedure definition. If the abort conditions are met
and SET ABORT is in effect, DATATRIEVE aborts the procedure and prints
a message on your terminal. If SET NO ABORT is in effect, DATATRIEVE
aborts the command or statement which contains the ABORT, but continues
to execute the other commands and statements in the procedure.
You can insure that SET ABORT is in effect by including that statement in
the procedure definition. For example:
DTR)
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>

PROCEDURE BIG-YACHTS-QUERY
SET ABORT
DECLARE LENGTH PIC 99
VALID IF LENGTH GT 35.
LENGTH = *."MIN LOA"
IF LENGTH GT 42 THEN ABORT "NO BOATS THAT BIG"
FIND BIGGIES IN YACHTS WITH LOA GE LENGTH SORTED BY
PRINT BUILDERt RIGt LOAt PRICE OF BIGGIES
END-PROCEDURE

OIITI
r-.r-rt
UU!LUC.I'

If you invoke BIG-YACHTS-QUERY and supply a LENGTH of 35 or
smaller, DATATRIEVE reprompts you for a valid LEf-.1GTH. If you supply a

LENGTH greater than 42, the procedure aborts, prints the specified abort
message, and returns you to the DATATRIEVE command level:
DTR> :BIG-YACHTS-QUERY
Enter MIN LOA: 35
Validation error for LENGTH
Re-enter MIN LOA: 43
ABORT: NO BOATS THAT BIG
Execution terrTlinated by "ABORT" staterTlent

If you assign a value between 36 and 42 to LENGTH, the appropriate collec-

tion is printed:
DTR> EDIT proc-name
QED> WH

MANUFACTURER

RIG

LENGTH
Ol.IER
ALL

BLOCK I.
CHALLENGER
COLUMBIA
GULFSTAR
ISLANDER
LINDSEY

SLOOP
KETCH
SLOOP
KETCH
KETCH
MS

39
41
41
41
41
39

PRICE

$48t490
$41 t350
$54t970
$35t900

$51t228

(continued on next page)

Procedures and Indirect Command Files

12-7

NAUTOR
NEWPORT
OLYMPIC
PEARSON
PEARSON

SLOOP
SLOOP
KETCH
SLOOP
KETCH

41
41
42
38
42

$80,500

12.1.8 Maintaining Procedures
12.1.8.1 Displaying Procedure Names Stored in the Data Dictionary - You can
list the names of ali procedures in the current data dictionary with the SHOW
command:

DTR) SHOW PROCEDURES
12.1.8.2 Displaying Procedures - If you want to print a procedure on your
terminal, you can use the SHOW command and specify the name of the
procedure to be displayed. You must have R (read) access privilege to the
procedure:

DTR) SHOW proc-naMe

(paSSIAld)

[ (* )

You can also use the DATATRIEVE editor to print a copy of the procedure on
your terminal. In this case, you must have C (control) access privilege to the
procedure:
DTR) EDIT proc-naMe
QED) WH
12.1.8.3 Deleting Procedures - You can delete a procedure from the current
data dictionary with the DELETE command. You must have C (control)
access privilege to the procedure.

DTR) DELETE proc-naMe

12.1.9 Protecting Procedures
When you create a procedure, DATATRIEVE stores the procedure definition
in the current data dictionary and creates a password table for the procedure.
DATATRIEVE automatically stores one UIC/PPN in the password table with
full access privileges [R (read), W (write), E (execute), M (modify), and C
(control) access]. The actual UIC/PPN that is stored in the password table is
installation-dependent.
If you create a procedure, you have full access privileges to it. If you make no
explicit restrictions, the access privileges of other users are governed by the
defauits established at installation.

12-8

Procedures and Indirect Command Files

You can modify the password table to give various kinds of access privilege to
other users. (See Chapter 14 for information on modifying password tables.)
However, you cannot establish a password for E (execute) access to a procedure; E (execute) access to a procedure is determined solely by the UIC/PPN
with which a user logs in.
To guard against accidental deletion of your procedure (especially if
it is a long one), you should maintain a backup copy of it. You can use the
DATATRIEVE EXTRACT command (described in Section 5.18) to copy your
procedure to an indirect command file for backup.

12.1.10 A Sample Procedure
Figure 12-1 shows the creation of a procedure that uses the Report Writer to
write a summary report of yacht data. The example illustrates not only the
process of creating a procedure but also some statements and elements that
are useful in procedures.
The PRINT statement is used for displaying a message to the user who invokes the procedure.
The prompting value expression *. "YES OR NO" requires the user to
respond to the question: HAVE YOU ESTABLISHED A COLLECTION?
The Boolean expression CONTAINING checks the user's response to the
question. If the response contains a letter N anywhere, the procedure aborts.
The prompting value expression *. "OUTPUT DEVICE OR FILE" allows the
user to select the device or file to contain the report when the procedure is
executed.
Figure 12-1: Sample Procedure
DTR>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DFN>
DTR>

DEFINE PROCEDURE YACHT-SUMMARY
SET ABORT
PRINT "THIS REPORT REQUIRES AN ESTABLISHED COLLECTION,"
PRINT "SORTED BY LOA AND BEAM."
PRINT "HAI.IE YOU ESTABLISHED A COLLECTION?"
IF *."YES OR NO" CONTAINING "N" THEN ABORT "SORRY, NO COLLECTION."
RE PORT ON *." OUT PUT DEI.JI CE OR FILE"
SET REPoRT-NAME="E~<Ai'1PLE: REPORT FROM A PROCEDURE"
SET LINES-PAGE=55, CoLUMNS-PAGE=GO
PRINT BUILDER, MODEL, LOA, BEAM, PRICE
AT BOTTOM OF LOA PR I NT SK I P, AI.IERAGE PR I CE =",
AI.IERAGE (PR I CE), SK I P
AT BOTTOM OF REPORT PRINT COL 13,"NUMBER OF BOATS = ",
COL 33, COUNT, SK I P t "AI.IERAGE PR I CE OF ALL BOATS =" , AVERAGE (PR ICE)
END-REPORT
END-PROCEDURE
II

If you invoke YACHT-SUMMARY and answer NO to the first prompt, the
procedure aborts:
DTR> :YACHT-SUMMARY
THIS REPORT REQUIRES AN ESTABLISHED COLLECTION,
SORTED BY LOA AND BEAM.

Procedures and Indirect Command Files

12-9

HAVE YOU ESTABLISHED A COLLECTION?
Enter YES OR NO: NO
ABORT: SORRYt NO COLLECTION.
Execution terlTlinated b}' "ABORT" statelTlent

If you answer YES to the first prompt, but, in fact, you do not have a current

collection, the Report Writer aborts the procedure and prints an error
message:
DTR> :YACHT-SUMMARY
THIS REPORT REQUIRES AN ESTABLISHED COLLECTIONt
SORTED BY LOA AND BEAM.
HAVE YOU ESTABLISHED A COLLECTION?
Enter YES OR NO: YES
A current collection has not been established

If you make a collection of YACHTS with LOA between 36 and 37 and price

not equal to zero, the following report results:
DTR> READY YACHTS
DTR> FIND YACHTS WITH LOA BETWEEN 36 37 AND PRICE NE 0
[5 records found]
DTR> SORT CURRENT BY LOAt BEAM
DTR> :YACHT-SUMMARY
THIS REPORT REQUIRES AN ESTABLISHED COLLECTIONt
SORTED BY LOA AND BEAM.
HAVE YOU ESTABLISHED A COLLECTION?
Enter YES OR NO: YES
Enter OUTPUT DEVICE OR FILE: TI:
EXAMPLE: REPORT FROM A PROCEDURE

MANUFACTURER
ISLANDER
I • TRADER

MODEL
36
37

DD-MMM-YY
Pase 1

LENGTH
OVER
ALL
BEAM

PRICE

36
36

$31 t 730
$38t500

11
12

AI.IERAGE PRICE
IRWIN
NORTHERN
ALBERG

$35t615

37 MARK I I
37
37 MK I I

AI.IERAGE PRICE
NUMBER OF BOATS
AI.IERAGE PRICE OF ALL BOATS

12-10

Procedures and Indirect Command Files

37
37
37

11
12

$36t950
$50,000
$36t951

$41 t300
5
$38t028

12,,2 Indirect CO-m-mand FUe-s
12.2.1 Creating an Indirect Command File
When you use ADT (Application Design Tool), it creates an indirect command file for you, and that file contains domain, record, and file definitions.
You can also create an indirect command file with a text editor. Invoke a text
editor, give your file a name and file type, and enter the sequence of
DATATRIEVE commands and statements just as you would in DATATRIEVE.
Do not include the prompts (DTR>, DFN>, QED>, or RW». When you
complete the sequence of commands and statements and exit from the editor,
the indirect command file is stored in your directory. .
You can save time by giving your indirect command file a file type of
.CMD; when you invoke an indirect command file and omit the file type,
DATATRIEVE supplies .CMD as the default file type.

12.2.2 Contents of an Indirect Command File
An indirect command file can contain all DAT ATRIEVE commands and
statements, including the five not allowed in procedures (DEFINE DOMAIN,
DEFINE RECORD, DEFINE PROCEDURE, DEFINE TABLE and EDIT).
If you put an ADT, EDIT, or SET
GUIDE command in the file, you cannot specify any responses to the prompts
that follow the entry of those commands in DATATRIEVE. If you put any of
these three commands into an indirect command file, DATATRIEVE puts
you into the requested mode and waits for you to respond to the prompt.
12.2.2.1

ADT, EDiT, and SET GUiDE -

When you then exit from the editor, GUIDE mode, or ADT, DATATRIEVE
executes the next line in the indirect command file. If that line is a valid
response to the prompts of the editor, GUIDE mode, or ADT, but not a valid
DATATRIEVE command or statement, the line is not executed.
DATATRIEVE then prints an error message on your terminal and returns you
to the DATATRIEVE command level.
12.2.2.2 Incomplete Commands and Statements - You can begin or end an
indirect command file with incomplete DATATRIEVE commands and statements, but there are limits you must observe:

• Complete each command element or statement element (for example,
neither TWEEN for BETWEEN nor REL for RELEASE is permitted).
• If your indirect command file ends with an incomplete DATATRIEVE command or statement, end the fragment at a point where DATATRIEVE
accepts a carriage return without terminating the executio~ of the command or statement.

Procedures and Indirect Command Files

12-11

When typed alone on a line, ADT, EXIT, FINISH, HELP, PRINT,
REPORT, and SELECT are complete in themselves. ERASE and MODIFY
must have contexts in which to work, and EXTRACT interprets a carriage
return as an incorrect file specification. When typed alone on a line all the
other commands and statements either prompt you for the missing elements
and return a DTR> prompt, or simply return the DTR> prompt and wait
for you to supply the missing elements.
: If your indirect command file begins with an incomplete DATATRIEVE
command or statement, use a fragment that completes the command or
statement for which DATATRIEVE is expecting an end. For example:
DTR) READY YACHTS
DTR; FIND YACHTS WITH LOA
QZ
[Z records found]
DTR) PRINT BUILDER, RIG,
CLookinS for next eleMent in list]
DTR> @PRT
LOAt PRICE OF CURRENT

MANUFACTURER

RIG

LENGTH
OI.lER
ALL

OLYMPIC
PEARSON

KETCH
KETCH

QZ
QZ

PRICE
$80,500

• Do not put incomplete commands or statements in the middle of an indirect
command file. DATATRIEVE looks at the next entry in the indirect command file for the completion of the incomplete command or statement.
When it fails to find one, DATATRIEVE prints an error message and does
not execute subsequent valid commands or statements in the indirect command file. For example, the indirect command file PRT.CMD contains the
following DATATRIEVE commands and statements:
READY YACHTS
FIND FIRST 5 YACHTS
PRINT BUILDER, RIGt
READY FAMILIES
FIND FIRST 5 FAMILIES
PRINT CURRENT

The PRINT statement is incomplete. When DATATRIEVE does not find a
proper conclusion in the next line, it prints an error message and does not
execute any of the subsequent commands or statements in the indirect command file:
DTR> @PRT
READY YACHTS
FIND FIRST 5 YACHTS
[5 records found]
PRINT BUILDER, RIGt
READY FAMILIES
Expected end of statelTlent, encountered "FAMILIES"
DTR>

12-12

Procedures and Indirect Command Files

12.2.2.3 Comments - If you put comments into an indirect command file,
they are printed on your terminal when you invoke the file. This use of comments is an advantage indirect command files have over procedures.

If your indirect command file defines a procedure and you put comments into
the procedure definition, the comments are not stored in the data dictionary
and are not printed when you invoke the procedure. Those comments are
printed, however, each time you invoke the indirect command file. If you want
comments to be printed when you invoke the procedure, put the comments in
PRINT statements, as suggested in Section 12.2.3.

12.2.3 Invoking an Indirect Command File
To invoke an indirect command file, precede the file specification with an at
sign (@). When you invoke an indirect command file, it must be entered on a
line by itself (except as noted below):
OTR) @ddn:[200t200] PRT.CMO

If the file type is ,CMD; and the file is in your default directmy, you need only
put the file name:
DiR) @PRT.CMO

or
OTR> @PRT

In only one situation can you invoke an indirect command file and have
another command on the same line. This special case only arises when you
first call DATATRIEVE. In response to the system level prompt, you type:
OTR @file-spec

Invoking an indirect command file in this special way differs from invoking
one in response to the DTR> prompt. All the commands and statements in
the indirect command file are executed as though you had entered them
interactively. However, no DATATRIEVE identification message is printed
on your terminal, and after the execution of the last command or statement in
the file, DATATRIEVE adds an EXIT command, and you automatically exit
from DATATRIEVE. You can apply this feature to routines you use regularly,
and to routines deferred for batch processing.
Similarly, you can include a string of DATATRIEVE commands, statements,
and procedures on the same line in which you invoke DATATRIEVE. The
length of the whole line cannot exceed eighty (80) characters, and the commands, statements, and procedures must be separated by semicolons:
OTR READY YACHTS;FINO YACHTS WITH RIG="MS";PRINT BOAT

Mter executing the commands and statements, DATATRIEVE returns you to
the operating system command level.

Procedures and Indirect Command Files

12-13

If the indirect command file is in another user's directory, you invoke it by
specifying all the necessary information in the following format:

dev: [ufd]filename.ext;ver
where:
dev:

device name

[ufd]

user file directory

filename

file name

.ext

file type

;ver

version number

To invoke an indirect command file in another user's directory, you must have
R (read) access to that directory.
You cannot, however, invoke an indirect command file from a procedure.
When you try to enter the at sign and file specification in response to the
DFN> prompt, DATATRIEVE enters the statements of the indirect command file as though you had typed them yourself. The resulting procedure
contains the same sequence of statements as the indirect command file, and
succeeds or fails depending on the logic of that sequence.
You can invoke an indirect command file in response to the RW> prompt of
the Report Writer. The file must begin with valid report statements; if you
complete the report specification in the file with an END-REPORT statement, you can follow the report specification with other valid DATATRIEVE
commands or statements.
You cannot invoke indirect command files while you are in ADT, GUIDE
mode, or the editor,

12.2.4 Debugging and Editing an Indirect Command File
\Vhen you invoke an indirect command file, DATATRIEVE prints each command or statement on your terminal and executes it as if you had entered it
directly from your keyboard. If an error occurs, DATATRIEVE prints an error
message and terminates the execution of the indirect command file. You can
correct the error by exiting from DATATRIEVE and using a text editor to
make the needed changes.

You cannot use the DATATRIEVE editor to change an indirect command file.
When you correct the error, you must return to DATATRIEVE, ready the
necessary domains, establish the appropriate collection, and execute the indirectcommand file again. These extra steps required for editing an indirect
command file are a disadvantage compared to the steps needed to edit a
DATATRIEVE procedure.

12-14

Procedures and Indirect Command Files

12.2.5 Nesting Indirect Command Files
You can invoke both procedures and indirect command files from within an
indirect command file. Do not allow an indirect command file to invoke itself,
either directly or indirectly; you can create an infinite loop.

12.2.6 Using an Indirect Command File in a Loop
Indirect command files act like procedures when used in loops. See Section
12.1.6 for the use of the REPEAT, BEGIN-END, and FOR statements to
form loops containing indirect command files.

12.2.7 Aborting Indirect Command Files
You can abort the execution of an indirect command file by including
an ABORT statement in the file. If the abort conditions are met and
SET ABORT is in effect, DATATRIEVE aborts the indirect command file
and prints a message on your terminal. If SET NO ABORT is in effect,
DATATRIEVE aborts the command or statement which contains the
ABORT, but continues to execute the other commands and statements in the
file.

12.2.8 Maintaining Indirect Command Files
12.2.8.1 Displaying the Names of Indirect Command Files The names of
indirect command files are stored in your directory, not in the data dictionary
as the names of procedures are. If you adopt the convention of using .CMD as
the file type for indirect command files, you can list your indirect command
files by requesting a directory listing of *. CMD at the system level. You can
adopt any convention you wish and use the wild card in the same manner.
12.2.8.2 Displaying Indirect Command Files - You can display the contents
of an indirect command file with the system level command that prints a file
on your terminal.

You can delete an indirect command file from your directory the same way you delete any other file.

12.2.8.3 Deleting Indirect Command Files -

12.2.9 Protecting Indirect Command Files
Indirect command files have less protection from unauthorized use than
DATATRIEVE procedures do. Each procedure has its own password table
that DATATRIEVE checks when the procedure is invoked. Indirect command
files, on the other hand, have only the operating system's protection to prevent other users from reading and then executing your indirect command
files.

Procedures and Indirect Command Files

12-15

DATATRIEVE accepts input from an indirect command file as though it were
entered from a terminal. As a result, DATATRIEVE itself does not provide
any protection against unauthorized use of indirect command files. To prevent other people from using your indirect command files, you must change
the system level protection to deny R (read) access to them.
By using indirect command files you can protect your DATATRIEVE operations from accidental corruption of the data dictionary. In fact, your backup
files of domain, record, file, and procedure definitions can be used as indirect
command files if the data dictionary were corrupted and you needed to restore
the definitions it had previously contained.

12.2.10 Sample Indirect Command File
Figure 12-2 shows an indirect command file similar to the procedure in Section 12.1.10. This example illustrates both similarities and differences between procedures and indirect command files. The indirect command file here
is YSUM.CMD and is invoked with the at sign and without the file type.
Instead of using the PRINT statement for displaying comments, the comments are preceded by exclamation points.
In contrast to the sample procedure, each statement and command in the
indirect command file is printed as DATATRIEVE executes it.
When DATATRIEVE encounters the statement with the *."YES OR NO"
prompting value expression, it pauses in the execution of the indirect command file to wait for the user's response to the question: HAVE YOU
ESTABLISHED A COLLECTION? As in the previous example, the Boolean
expression, CONTAINING, checks the user's response to the question, and if
the response contains a letter N anywhere, the procedure aborts.
When DATATRIEVE encounters the *."OUTPUT DEVICE OR FILE"
prompting value expression, it pauses again to wait for the user to select the
device or file for output of the report.
Note that, except for the report name, the report produced by the indirect
command file is the saTile as the one produced by the procedure
YACHT-SUMMARY.

Figure 12-2: Sample Indirect Command File
contains

of command and

statements:
SET ABORT
!THIS REPORT REQUIRES AN ESTABLISHED COLLECTION;
!SORTED BY LOA AND BEAM.
!HAVE YOU ESTABLISHED A COLLECTION?
IF *."YES OR NOli CONTAINING "N" THEN ABORT "SORRY, NO COLLECTION."
REPORT ON *."OUTPUT DElnCE OR FILE!!
(continued on next page)

12-16

Procedures and Indirect Command Files

SET REPORT-NAME="SAMPLE REPORT"j"FROM AN INDIRECT COMMAND FILE"
SET LINES-PAGE=55, COLUMNS-PAGE=60
PRINT BUILDER, MODEL, LOA, BEAM, PRICE
AT BOTTOM OF LOA PR I NT SK I P t "AVERAGE PR I CE =" t
AI.IERAGE (PR I CE), SK I P
AT BOTTOM OF REPORT PRINT COL 13,"NUMBER OF BOATS - "
COL 33, COUNT, SK I P, "AI.JERAGE PR I CE OF ALL BOATS =", AVERAGE (PR I CE)
END-REPORT

When the domain is readied and the appropriate collection established, the
indirect command file is invoked with an at sign and without the .CMD file
type. DATATRIEVE prints each command and statement as it executes it:
DTR) READY YACHTS
DTR) FIND FIRST 5 YACHTS WITH LOA BETWEEN 36 37 AND PRICE NE 0
[5 records found]
DTR) SORT BY LOA, BEAM
DTR) @YSUM
SET ABORT
!THIS REPORT REQUIRES AN ESTABLISHED COLLECTION,
!SORTED BY LOA AND BEAM.
!HAVE YOU ESTABLISHED A COLLECTION?
IF *."YES OR NO" CONTAINING "N" THEN ABORT "SORRY, NO COLLECTION."
Enter YES OR NO: YES
REPORT ON *. "OUTPUT DEI.JICE OR FILE"
SET REPORT-NAME="SAMPLE REPoRT"j"FRoM AN INDIRECT COMMAND FILE"
SET LINES-PAGE=55, CoLUMNS-PAGE=60
PRINT BUILDER, MODEL, LOA, BEAM, PRICE
AT BOTTOM OF LOA PRINT SKIP, "AI.IERAGE PRICE· =",
AI.IERAGE (PR I CE), SK I P
AT BOTTOM OF REPORT PRINT COL 13,"NUMBER OF BOATS - "
COL 33, COUNT, SK I P, "AI.JERAGE PR I CE OF ALL BOATS =", AI.IERAGE (PR I CE)
END-REPORT
Enter OUTPUT DEVICE OR FILE: TI:
SAMPLE REPORT
FROM AN INDIRECT COMMAND FILE

MODEL

MANUFACTURER
36
37

ISLANDER
I • TRADER

DD-MMM-YY
PaSe 1

LENGTH
OI.IER
ALL

BEAM

PRICE

36
36

11
12

$31 ,730
$39,500
$35,615

AI.JERAGE PRICE
37 MARK I I
37
37 MK I I

IRWIN
NORTHERN
ALBER.G

37
37
37

11
11
12

$36,950
$50,000
$36,951
$41 ,300

AI.JERAGE PRICE
NUMBER OF BOATS
AI.IERAGE PRICE OF ALL BOATS

5
$39,026

Procedures and Indirect Command Files

12-17

Chapter 13
Description Tables

A description table is a set of code-and-description pairs that you create and
store under a description table name in the data dictionary.
By using a description table, you can enter a single value in a command or
statement and cause DATATRIEVE to look for that value in the table. If the
value matches one of the codes in the table, DATATRIEVE can give you two
responses:
1. Tell you that the value equals a code in the table.

2. Use the description associated with the matching code.
If the value does not match one of the codes in the table, DAT ATRIEVE can
give you two other responses:
1. Tell you that the value does not equal any code in the table.

2. Use a default description, which you define when creating the table.
Using a description table, you can save a great deal of record space because
you need store only the codes in a field. For example, you can store a one
character code in a field and print a multiword description as the field's value.
Short codes, for which only you need know the cipher, can be translated into
text meaningful to other people.
You can also associate stable information with other information that changes
frequently. For instance, rather than store prices in several data files, you
might create a description table with part or model numbers as codes and
prices as the associated descriptions. To print a current price, you need only
cite the model number and refer to the description table. Rather than modify
all your data files, you need only update the description table to reflect price
changes.
Description tables can also save the time involved in creating and entering
complex DATATRIEVE command and statement sequences.

13-1

For example, you want to print one of seven character strings, depending on
the value of a value expression. On one hand, you can use a series of
IF-THEN-ELSE and PRINT statements to print the appropriate character
string. On the other hand, you might put each value and its corresponding
character string in a description table ..
The following procedure prints the name of the state corresponding to one of
seven telephone area codes. The procedure prompts for an area code, then
prints the state with that area code. If the user enters an area code that is not
in the New England region, the procedure prints an error message.
PROCEDURE AREA-CODES
DECLARE AREA-CODE PIC 999.
AREA-CODE = *."AREA CODE"
IF AREA-CODE EQ 207 THEN PRINT
IF AREA CODE EQ 603 THEN PRINT
I F AREA CODE EQ 802 THEN PR I NT
IF AREA-CODE EQ 617 THEN PRINT
IF AREA-CODE EQ a13 THEN PRINT
IF AREA-CODE EQ a01 THEN PRINT
IF AREA-CODE EQ 203 THEN PRINT
PR I NT "NOT A I)AL I D AREA CODE"
END-PROCEDURE

"MAINE" ELSE
"NEW HAMPSHIRE" ELSE
"1.JERMONT" ELSE
"EASTERN MASSACHUSETTS" ELSE
"WESTERN MASSACHUSETTS" ELSE
"RHODE ISLAND" ELSE
"CONNECTICUT" ELSE

On the other hand, you can enter the area codes and corresponding state
names in a description table. Then, you can refer to the description table in a
PRINT statement. The description table for these seven area codes contains
the following entries:
TABLE
207
603
802

AREA-CODE-TABLE
MAINEt
"NEW HAMPSHIRE" t
I.JERMONT t
617
"EASTERN MASSACHUSETTS" t
a13
"WESTERN MASSACHUSETTS" t
aOl
"RHODE ISLAND" t
203
CONNECTICUTt
ELSE "NOT A VALID AREA CODE"
END-TABLE

You can now prompt for an area code and print the corresponding state in a
single statement.
DTR> PRINT *. "AREA CODE" I.JIA AREA-CODE-TABLE USING
Enter AREA CODE: 203
CONNECTICUT

}-(21)

Because description tables can be modified using the DATATRIEVE editor,
this description table could be expanded to include other area codes. For large
numbers of code-and-description pairs, you can save time by creating a long
description table rather than a lengthy procedure. Furthermore, because
description table references are contained in Boolean and value expressions,
the tables you create can be used by many DATATRIEVE commands and
statements.

13-2

Description Tables

13.1 Creating a Descri.ption Ta.ble
To create a description table, issue the DEFINE TABLE command. (Section
5.11 contains more information on the DEFINE TABLE command.)
DEFINE TABLE desc-table-name

DATATRIEVE then prompts with DFN> and waits for your description table
definition. Enter the code-and-description pairs, in the following format:
"description" }

"code" }
{

code

{

..
:I escrlPtIon

[t ]

The code and description must be separated by a colon (:); one or more spaces
before and after the colon are optional.
Each code-and-description pair must end with a comma (,), unless it is the
last entry in the description table. If-an ELSE clause is the last line of the
table, then all code-and-description pairs, including the last one, must end
with a comma (,). Do not put a comma after the ELSE clause.
If the code or the description conforms to the rules for DATATRIEVE names
(see Section 4.4), you do not have to enclose it in quotation marks. However,
remember that DATATRIEVE converts any lowercase letters to uppercase.
If the code or the description does not conform to the rules for DATATRIEVE
names, or if you want to preserve lowercase letters in it, you must enclose it in
quotation marks and the rules for character string literals apply; that is,
neither the code nor the description can exceed 250 characters, and neither
can contain a carriage return, line feed, or control character.
After the last code-and-description pair, you can enter an optional ELSE
clause:
ELSE

{"descr~Pt~on"}
descrIPtIon

If an ELSE clause ends your description table, DATATRIEVE substitutes the
description in the ELSE clause for any values not found in the table. If your
description table does not end with an ELSE clause, DATATRIEVE prints an
error message on your terminal when a value is not found in the table.
The ELSE clause has no effect when using a description table to match values
with codes in the table.
The rules for a description in an ELSE clause are the same as for a description
in a code-and-description pair: the description either must conform to the
rules for DATATRIEVE names or must be enclosed in quotation marks and
conform to the rules for character string literals.

Description Tables

13-3

To end a description table definition, enter the keyword END-TABLE on a
line by itself. The END-TABLE statement must follow the ELSE clause, if
specified, or the last code-and-description pair if there is no ELSE clause.
After you enter the END-TABLE statement, DATATRIEVE stores the definition in the current data dictionary and creates a password table for the
description table.
Figure 13-1 summarizes the process for creating a description table.

Figure 13-1: Summary of DEFINE TABLE
DTR) DEFINE TABLE desc-table-naMe
DFN) code-l
description-l t

DFN) [ELSE description-n]
DFN) END-TABLE
DTR)

Figure 13-2 shows the creation of the description table RIG-TABLE, which is
stored in the sample data dictionary for YACHTS.

Figure 13-2: Creating RIG-TABLE
DTR)
DFN)
DFN)
DFN)
DFN)
DFN)
DFN>
DTR)

DEFINE TABLE RIG-TABLE
IISLooplI
lIoNE-MASTII t
IIKETCH II : IITWo MASTS t BIG ONE IN FRoNTII t
IIYAWL II
: IISIMILAR TO KETCH II t
IIM/SII
: IISAILS AND BIG MOTOR II t
ELSE IISoMETHING ELSE II
END-TABLE

As you create a description table, DATATRIEVE checks for syntax errors. For
example, if you forget to end a description with a comma, DATATRIEVE
prints an error message and aborts the DEFINE TABLE command. If a
syntax error occurs, all code-and-description pairs are lost and no description
table is created. To complete the definition of the table, you must begin
with the DEFINE TABLE command and reenter the entire description table
definition.

To avoid this duplication of effort, you can use the DATATRIEVE editor to
create the largest part of a long description table. First, issue the DEFINE
TABLE command, enter one or two code-and-description pairs, and end the
description table with El~D-TABLE. Then call the DATATRIEVE editor and
use the insert mode to continue entering code-and-description pairs.
13-4

Description Tables

Remember that while you are using the editor, DATATRIEVE does not check
for syntax errors in the table, such as missing quotation marks or missing
commas. You should, therefore, use care when entering the rest of the description table. If the table does not work as expected because of an error in its
definition, you can use the DATATRIEVE editor again to correct the mistake.

13.2 Using a Description Table
References to description tables are contained in either value expressions or
Boolean expressions, and you can use those expressions wherever the formats
of DATATRIEVE commands and statements allow them.

13.2.1 Using IN with a Description Table
You can use description tables with the relational operators IN and NOT IN
to make collections, to set conditions in IF-THEN-ELSE statements, and to
validate data. Value expressions that use IN or NOT IN and refer to description tables compare the value of a specified field in a record only with the
codes in the table. The following is the general format for using IN and NOT
IN with a description table:
field-nafTle
*.prOfTIPt
\)ariable-nafTle

[NOTJIN

des c - tab 1 e - n afTI e

1. Making collections.
In a record selection expression that establishes a collection or a record
stream, you can use a Boolean expression containing WITH and a reference to a description table:
OTR> FOR YACHTS WITH RIG IN RIG-TABLE PRINT BOAT

or
DTR> FIND YACHTS WITH RIG NOT IN RIG-TABLE
[5 records foundJ

2. Setting conditions in IF-THEN-ELSE statements.
You can combine IN with a description table reference to set the conditions of an IF-THEN-ELSE statement:
DTR> FOR FIRST 7 YACHTS
DTR> IF RIG NOT IN RIG-TABLE THEN PRINT BOAT

MANUFACTURER
AMERICAN

MODEL
26-MS

RIG

LENGTH
OllER
ALL WEIGHT

BEAM

PRICE

$18t895

5t500

DTR>

Description Tables

13-5

Remember that you must establish a context for the IF-THEN-ELSE
statement by preceding it with a SELECT statement or by nesting it
within a FOR statement.
3. Validating data.
By referring to a description table in a VALID IF clause, you can validate
data in a field before storing the data in a record. The VALID IF clause
must be part of the record definition. The following definition of
PHONE-REC illustrates this method of automatic data validation:
DTR) DEFINE RECORD PHONE-REC USING
DFN) 01 PHONE.
DFN)
02 NAME PIC X(20).
DFN)
02 NUMBER PIC S(7) EDIT-STRING IS XXX-XXXX.
DFN>
02 LOCATION PIC xes).
DFN>
02 DEPARTMENT PIC XX VALID IF
DFN>
DEPARTMENT IN DEPT-TABLE.
DFN)
DTR)

13.2.2 Using VIA with a Description Table
You can refer to description tables in value expressions by combining the
table name with VIA. These references cause DATATRIEVE to compare the
codes in the table with the value you supply, and if the value matches one of
the codes, DATATRIEVE uses the corresponding description in the table as
you have directed in the command or statement. Use the following format to
refer to a description table in a value expression with VIA:
field-name
}
*.prOIT1Pt
{ l}ariable-naITle

VIA

desc-~able-name

You can refer to an entry in RIG-TABLE by using a prompting value expression,as shown in the following PRINT statement:
DTR> PRINT *.TYPE-OF-BOAT VIA RIG-TABLE USING X(30)
Enter TYPE-OF-BOAT: KETCH
TWO MASTS, BIG ONE IN FRONT

If you refer to a description table in a PRINT statement, include a USING
clause to specify the number of characters to be printed. If you omit the

USING clause, DATATRIEVE prints only the first ten characters of the
descri ption.
You can also use a field name as the value expression, as shown in this
example:
DTR> FOR FIRST 7 YACHTS
DTR> PRINT MODEL. RIG. RIG VIA RIG-TABLE USING X(30)
(continued on next page)

13-6

Description Tables

MODEL

RIG

37 MK I I
79
I.'EGA
BALLAD
26
26-MS

KETCH
SLOOP
SLOOP
SLOOP
SLOOP
MS
SLOOP

TWO MASTS, BIG ONE IN FRONT
ONE MAST
ONE MAST
ONE MAST
ONE MAST
SOMETHING ELSE
ONE MAST

30/32

The USING X(30) clause indicates that the third column of data will be 30
characters wide.

13.2.3 Description Tables and DATATRIEVE Workspace
When you first refer to a description table, DATATRIEVE searches the current data dictionary for the table and loads it into the DATATRIEVE workspace. DATATRIEVE then evaluates the value expression, if necessary, and
compares the value withthe codes in the table. The comparison is case sensitive and proceeds character-by-character. Thus, a value expression of 5 will
not match a code of 05, and a value expression of Rig will not match a code of
RIG.
Regardless of whether or not there is a match, the description table remains
in the DATATRIEVE workspace until you either relinquish it with the
RELEASE command or end the DATATRIEVE session. When you switch
data dictionaries, DATATRIEVE does not release the description tables to
which you have referred. In fact, you can still use those tables until you
explicitly release them or end your DATATRIEVE session. (See Appendix B
for a discussion of space saving techniques.)

13.3 Maintaining Description Tables
13.3.1 Displaying Description Table Information
You can list the names of all description tables in the current data dictionary
and all tables in the DATATRIEVE workspace with the SHOW command.
DTR) SHOW TABLES

13.3.2 Displaying Description Tables
To print a description table on your terminal, use the SHOW command and
specify the name of the description table to be displayed. You must have R
(read) access privilege to the description table. Use the following format to
display a description table:
OTR) SHOW desc-table-name

(passl..Jd) ]
[

(*)

Description Tables

13-7

13.3.3 Modifying Description Tables
You can modify a description table in the current data dictionary by using the
DATATRIEVE editor. You must have C (control) access privilege to the
description table. See Chapter 8 for information about the editor.

13.3.4 Deleting Description Tables
You can delete a description table from the current data dictionary with the
DELETE command. You must have C (control) access privilege to the description table. Use the following format:
DTR> DELETE desc-table-nafrle

[ (passIAld)

(* )

13.4 Protecting Description Tables
When you create a description table, DATATRIEVE stores its definition
in the current data dictionary and creates a password table for it.
DATATRIEVE automatically stores one UIC/PPN in the password table with
full access privileges. The actual UIC/PPN that is stored in the password
table is installation-dependent. Any user logged in under that UIC/PPN and
the creator of the table have R (read), W (write), E (execute), M (modify),
and C (control) access to the description table. Depending on the UIC/PPN in
the password table, other users in the installation may be able to delete,
modify, or print the description table.
If you want to grant additional privileges to other users or further restrict the
use of the description table, you must modify its password table. Refer to
Chapter 14 for more information on protecting dictionary definitions, including description tables, and on modifying password tables. Refer to Chapter 5
for the formats of the commands used in the process.

To guard against accidental deletion of your description table, you can maintain a backup copy of it by using the DATATRIEVE EXTRACT command
(described in Section 5.18) to copy your table to a disk or tape file.

13-8

Description Tables

13.5 Example
This example works with a domain of WIDGETS, which consists of various
items that need to be reordered from time to time. The procedure TAB finds
the items no longer in stock, and uses ORDER-TABLE to list the people to
contact when reordering.
DTR> READY WIDGETS
DTR> PRINT ALL WIDGETS
I.JENDOR

PARTS
PART
IN
NUMBER STOCK

ITEM

ACME ASPHALT & SHINGLE
ACME ASPHALT & SHINGLE
ACME ASPHALT & SHINGLE
PURGE SYSTEMS
PURGE SYSTEMS
PURGE SYSTEMS
PURGE SYSTEMS
QUERY ENTERPRISES

ASPHALT
SHINGLES
CUBE WALLS
ERASER-CHALK
ERASER-PENCIL
WHITE-OUT
MAGNETS-20 OZ.
LISTINGS

1001
1002
1003
3001
3002
3003
3004
2001

3
0
8888
3
1
8845
0
4

QUER\{

I'IZI:. rUI'IZ I;:)

..... r- .-.1""\1"'"• .,..,....

2002

C'h.ITC'r:.Or:. T C"'r-l'"'
1-1"1 I 1-1\." Pi J. ClCi:J

DTR> SHOW ORDER-TABLE
TABLE ORDER-TABLE
ilL. LANDFILL-888-555-1234" t
"ACME AS PHAL T &: SH INGLE"
"QUERY ENTERPRISES"
"T. ABMOW-111-555-4321" t
"PURGE SYSTEMS"
"T. SKWAIRDEE-123-555-8878"
END-TABLE
DTR> SHOW TAB
PROCEDURE TAB
FIND WIDGETS WITH STOCK = 0 SORTED BY PART
FOR CURRENT PRINT ITEMt PART,
I.JENDOR InA ORDER-TABLE ("CALL") USING }-{(30)
END-PROCEDURE
DTR> : TAB
ITEM
SHINGLES
REPORTS
MAGNETS-20 OZ.

PART
NUMBER

CALL

1002
2002
3004

L. LANDFILL-888-555-1234
T. ABMOW-111-555-4321
T. SKWAIRDEE-123-555-8878

DTR>

Description Tables

13-9

Chapter 14
Security and Protection

In addition to the protection features offered by your operating system and by
your file services, DATATRIEVE provides protection for your data and dictionary definitions through password tables. Password tables, which are
stored in the data dictionary, regulate the type of access a user has to any
object in the data dictionary.
Every dictionary object (domain, record, procedure, and description table
definition) has an associated password table. This chapter describes the ~on
tents of a password table and the commands you use to maintain a table. The
chapter also offers guidelines for developing a protection strategy to help
ensure the integrity of your data.
Password tables can be effective against "browsing" and accidental corruption of the dictionary or data. They should be used to augment an overall
security system for an installation.

14.1 Contents of a Password Table
A password table consists of one or more entries. Each entry contains the
following information:
• A sequence number
• A lock type
• A key
• One or more access privileges
Figure 14-1 shows a sample password table containing three entries and illustrates the parts of a password table entry.

Figure 14-1: Sample Password Table
Sequence
Number

Lock

Key

Privileges

UIC

[254,203]

SWORDFISH

UIC

[*,*]

14-1

14.1.1 Sequence Numbers
A sequence number is an integer, assigned by DATATRIEVE, that identifies
a password table entry. You use sequence numbers to identify an entry you
are adding to or deleting from the password table. These numbers are sequential, beginning with 1.

14.1.2 Lock Types
Each entry in the password table has a lock type that indicates whether you
access the associated dictionary object by specifying a password or by using a
UIC/PPN. There are two lock types: PW (for password) and UIC (for
UIC/PPN).

14.1.3 Keys
When you attempt to access a dictionary object, you must provide the correct
password for a PW lock, or own the correct UIC/PPN for a UIC lock. These are
called keys.
Password Keys

If the lock type is PW, the key is a one- to ten-character password. Examples of passwords include: FISH-FRY, SWORDFISH, 1234, and
PASSWD-9.

To access a dictionary object using a command or statement that includes
an optional password argument, you can include the password directly in
the command or statement. For example, the domain YACHTS might
contain only one password table entry:
1

SWORDFISH

RWEMC

To delete YACHTS from the dictionary, you must include the password in
the DELETE command:
DTR) DELETE YACHTS (SWORDFISH);

For security reasons, you can suppress the printing of the password at the
terminal. To do this, specify an asterisk enclosed in parentheses instead of
the password. DATATRIEVE will then prompt for the password but not
print it:
DTR) DELETE YACHTS (*);
Enter password for YACHTS:

Use this more secure technique for specifying a password, especially if you
have a hard copy terminal.

14-2

Security and Protection

UJCKeys

If the lock type is UIC (for UIC/PPN), the key is an account number
known to the operating system. Under RSTS/E, an account number is
called a project-programmer number, or PPN. Under all other operating
systems, the account number is called the user identification code, or UIC.
The UIC/pPN consists of a three digit octal group number followed by a
three digit octal user number, separated by a comma and enclosed in
brackets. For example:

[253,201]
A UIC/PPN lock can include either specific UIC/PPN numbers or asterisks; asterisks allow all users or all users in a specified group to access a
dictionary object. For example, the following are all valid password table
lock entries:
[253,201] (only the user with the account number [253,201] has access)
[253, *] (any user with group number 253 has access)
[*, *] (any user has access)

For a lock type of UIC, you do not specify a UIC or PPN in·a command or
statement. Rather, DATATRIEVE checks the UIC/PPN you used logging
in to verify that you have access. For example, if the password table for
the procedure BIG-YACHTS contains just the following entry, then you
must log in under [253,201] in order to access the procedure:
1

UIC

[253,201]

RWEMC

But, if the password table contains the following entry, you can access the
procedure regardless of your UIC/PPN:
1

UIC

[*,*]

RWEMC

NOTE
The UIC/PPN lock type is particularly useful in protecting procedures; you cannot use a password when invoking a procedure.

14.1.4 Access Privileges
An access privilege determines the type of access you have to the associated
dictionary object and the operations you can perform on it. An access privilege
is designated by a single letter, a string of letters, or a blank. Table 14-1
contains a list of access privileges and their meanings.

Security and Protection

14-3

Table 14-1: Access Privileges
Access
Privilege

Meaning

Read. User can SHOW or EXTRACT the associated dictionary object. For a
domain, user can ready the domain for READ access only.

Write. User can ready the domain for RE.A.J), EXTEND, MODIFY, or 'VRITE
access to retrieve, modify, store, or erase records.

Extend or Execute. For a domain, user can ready the domain for EXTEND
access only to store records. For a procedure, user can execute the procedure. For
a description table, user can refer to the description table (using VIA or IN). You
must have E access to a record to ready the associated domain.

Modify. User can ready the domain for READ or MODIFY access to read or
change records in the domain, but not to add or delete.

Control. User can issue the commands DEFINEP, DELETE, DELETEP,
EDIT, and SHOWP.

blank

No access. User cannot access the dictionary object.

Each entry in a password table can include from one to five access privileges,
or designate "no access." (A blank indicates that no access is permitted to a
user with the corresponding key.) For example, the single letter R specifies
that a user with the corresponding key has read access only. The letters RW
specify that the user has both read and write access. Full access, designated
by RWEMC, allows a user complete access to the dictionary object.
Each access privilege allows you to issue certain commands and statements.
For example, with Read privilege, you can issue an EXTRACT command or
ready a domain for READ access. (If you ready a domain for READ, you can
then issue FIND and PRINT statements.) Table 14-2 contains a list of commands that you can issue if you are granted the corresponding access privilege. That table also shows the commands and statements you can issue after
readying a domain. For example, if you are granted only Read privilege to a
domain, you can ready that domain for READ, then issue a FIND statement
to establish a collection. But, you cannot ready the domain for any other type
of access.

Table 14-2: Commands/Statements by Privilege

••
P i'iVilege

for Domain

A .... ·t·

Command(s) Permitted

EXTRACT
READY ... READ

.. ,...
.. ,'
aQl IOnal \Jommana\s)
or Statement(s) Permitted

FIND
PRINT
SELECT
SORT
SUM
(continued on next page)

14-4

Security and Protection

Table 14-2: Commands/Statements by Privilege (Cont.)

I p rlVl
. 01ege
for Domain

Command(s) Permitted

Additional Command(s)
or Statement(s) Permitted

SHOW

READY ... READ

FIND
PRINT
SELECT
SORT
SUM

READY ... MODIFY

FI~D

MODIFY
PRINT
SELECT
SORT
SUM
READY ... WRITE

ERASE
FIND
MODIFY
PRI~T

SELECT
SORT
STORE
SGM
READY ... EXTEKD

STORE

READY ... EXTEND

STORE

READY ... READ
FIND
PRINT
SELECT
SORT
SUM

READY ... MODIFY

FIND
MODIFY
PRINT
SELECT
SORT
SUM

READY ... EXTEKD

STORE

DEFIKEP
DELETE
DELETEP
EDIT
SHOWP

Note: You must have E access to the associated record to ready a domain.

Security and Protection

14-5

Any user with a group (or project) code of 1 (that is, a UIC/PPN in the form
[1,n]) is automatically granted C (control) access in all password tables. Only
users with C (control) access to a dictionary object can access its associated
password table, edit or delete the dictionary object.

14.2 Creating Password Tables
\tVhen you define a dictionary object, DATATRIEVE automatically creates a
password table for that object. The password table initially contains only one
entry, a UIC/PPN that is granted full access privileges to the dictionary
object. The specific UIC/PPN stored in the table is installation-dependent
and is determined when the DATATRIEVE software is installed. The entry
can be in one of the following formats:
[m,*]

Full access privileges are granted to any user with the same group (or
project) code (m) as the creator of the definition. For example, if you log
in under [253,201] and create a procedure definition, then an entry for
[253, *] is stored in the password table for the procedure. Any user with a
group (or project) code of 253 (such as [253,222]) also has full access
privileges to the procedure.
[m,n]
Full access privileges are granted to any user with the same UIC/pPN as
the creator of the dictionary definition. For example, if you log in under
[253,201] and create a procedure definition, then an entry for [253,201] is
stored in the password table for the procedure. Only users with a
UIC/PPN of [253,201] can access the procedure.
[*,*]

All DATATRIEVE users, regardless of their UIC/PPN, are granted full
access to the dictionary object.
Regardless of the actual UIC/PPN stored in the password table, the creator of
the definition is always granted full access privileges (RWEMC) to the dictionary object.
You can grant privileges to additional users or further restrict the use of the
dictionary object by changing its password table. The commands you use
to change the table are summarized in Section 14.4 and described fully in
Chapter 5.

NOTE
These commands are so important to the protection of data
that only users with C (control) privilege can issue them.

14-6

Security and Protection

14.3 DATATRIEVE's Processing of Password Tables
Whenever you use a table, invoke a procedure, or issue one of the following
commands, DATATRIEVE checks the password table to verify that you have
appropriate access privilege:
DEFINEP
DELETE
DELETEP
EDIT
EXTRACT
READY
SHOW
SHOWP
To verify that you have the correct access privilege, DATATRIEVE searches
the password table, checking each entry until a match is found.
DATATRIEVE searches the table in the follo\ving steps:
Step 1:

DATATRIEVE stores your VIC/PPN and determines if you are a
privileged user. A privileged user is one with a group (or project)
code of 1 (that is, a UIC/PPN in the form [1,n]). At a minimum,
DATATRIEVE grants a privileged user C (control) access. It may
grant additional privileges, depending on the results of the following steps.

Step 2:

DATATRIEVE checks the first entry in the password table.
If the lock type is PW, DATATRIEVE checks to see if you specified
a password in the command. If you did and the password matches

the entry's key, DATATRIEVE stops searching the password table
and grants you the privilege (or privileges) listed with the first
entry. If the password does not match or you did not. specify a
password, DATATRIEVE performs Step 3.
If the lock type is UIC, DATATRIEVE checks to see if your
VIC/PPN matches the key. If it does, DATATRIEVE stops search-

ing the table and grants you the privilege(s) listed with the first
entry. If the VICs do not match, DATATRIEVE performs Step 3.
Step 3:

DATATRIEVE checks the next entry in the table, following the
sa~e procedure as in Step 2.
When there are no more entries, DATATRIEVE denies all access to
the dictionary object and rejects your command.

Figure 14-2 contains a flowchart that summarizes DATATRIEVE's processing of a password table.

Security and Protection

14-7

Figure 14-2: Processing of Password Table

Save
UIC/PPN

Yes

Grant
Control
privilege

Read first