Digital PDFs

AA-C742A-TC

December 1977

188 pages

Original

6.2MB

Document:	Users Guide to DATATRIEVE-11 Dec77
Order Number:	AA-C742A-TC
Revision:	0
Pages:	188
Original Filename:	AA-C742A-TC_Users_Guide_to_DATATRIEVE-11_Dec77.pdf

OCR Text

User's Guide

to
DAT ATRIEVE-11
Order No. AA-C742A-TC

First Printing, December 1977

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-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
COMTEX

DECsystem-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP

DDT

LAB-8

DECCOMM
ASSIST-ll

DECSYSTEM-20
RTS-8

FOCAL

INDAC

4/78-14

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-ll
ITPS-10

December 1977
This manual describes the use of DATATRIEVE-ll to
extract and display data from RMS-ll K files on the
RSTS/E, RSX-ll M, and lAS operating systems.

User's Guide
to
DATATRIEVE-11
Order No. AA-C742A-TC

OPERATING SYSTEM AND VERSION:

RSTS/E V68, RSX-l1M V03, and lAS V02

SOFTWARE VERSION:

PDP-ll DATATRIEVE-ll VOl

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

digital equipment corporation · maynard. massachusetts

First Printing, December 1977

DIGITAL
DEC
PDP
DECDS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-ll

DECsystem-1O
DECtape
DIBOL
EDUSYSTEl-l
FLIP CHIP
FOCAL

INDAC
LAB-8

DECSYSTEM-20
RTS-8

4/78-14

MASSBUS
OMNIBUS
OS/8
FHA

RSTS
RSX
TYPESET-8
TYPESET-ll
TMS-ll
ITPS-1O

CONTENTS

Page
PREFACE

vii

SYMBOLOGY

CHAPTER

GENERAL CONCEPTS

1.1

1.5
1.6

INTRODUCTION TO DATATRIEVE-11 INQUIRY
FACILITIES
INTRODUCTION TO DATATRIEVE-11 REPORT
WRITER FACILITIES
SAMPLE DATA FOR EXAMPLES
DEFINITIONS:
FILES, DOMAINS, COLLECTIONS,
RECORDS, AND FIELDS
INTRODUCING THE DATA DICTIONARY
PROCESSING A FILE AS A C-OLLECTION

USING DATATRIEVE-11

2-1

2.1
2.2
2.3
2.4

INVOKING DATATRIEVE-11
STOPPING
ERROR MESSAGES
ENTERING COMMANDS

2-1
2-1
2-1
2-1

SYNTAX RULES FOR DATATRIEVE-11 COMMANDS

3-1

3.1
3.2
3.3
3.4

3-1
3-1
3-1

3.5
3.6
3.7
3.8
3.9
3.10
3.11
3.12
3.13

SEQUENCE OF COMMANDS
SPELLING
SPACING
SPECIAL SYMBOLS -- BRACKETS, BRACES,
ELLIPSIS, UPPERCASE, AND LOWERCASE
CHARACTER SET
COMMENTS
NAMES
LITERALS
CONTINUATION LINES -- CARRIAGE RETURN
COMMAND TERMINATION -- SEMICOLON
KEYWORDS
DELIMITERS
SEQUENCE OF COMMAND ELEMENTS

COMMANDS FOR INQUIRY & UPDATE

4-1

4.1
4.2
4.3
4.4
4.4.1
4.4.2
4.4.3
4.5

STARTING A DATATRIEVE-11 SESSION WITH READY
ENDING A DATATRIEVE-11 SESSION -- EXIT
GETTING AN OVERVIEW OF YOUR DATA -- SHOW
GETTING A COLLECTION TOGETHER -- FIND
Establishing the Collection
Refining the Collection
Naming and Sorting the Collection
RESTRICTING THE SEARCH WITH RECORD
SELECTION EXPRESSIONS

4-1
4-5
4-7
4-13
4-13
4-16
4-19

1.2

CHAPTER

iii

1-1
1-1

1-2
1-2
1-2
1-3
1-3

3-1
3-4
3-4
3-5
3-5
3-6
3-7
3-7
3-8
3-9

4-23

CONTENTS (Cont.)

Page
4-23
4-26
4-28

4.13
4.13.1
4.13.2
4.13.3
4.13.4
4.13.5
4.13.6
4.13.7
4.13.8
4.14

Value Expressions
Boolean Expressions
Full Record Selection Expressions
SELECTING A PARTICULAR RECORD IN A
COLLECTION -- SELECT
PUTTING RECORDS INTO AN ORDER -- SORT
LOOKING AT THE RECORD CONTENTS -- PRINT
Listing Record Contents
Formatting the Printout
CHANGING RECORD CONTENTS IN THE FILES
MODIFY
REMOVING ONE OR MORE RECORDS -- ERASE
ADDING A NEW RECORD TO THE FILE -- STORE
SOME SPACE CONSIDERATIONS
When You're Done With a Collection
RELEASE
When You're Done with a Domain
FINISH
COMBINING DATATRIEVE-ll COMMANDS
BEGIN-END Block
Assignment Statement
REPEAT Statement
THEN Statement
IF-THEN-ELSE Statement
ABORT Statement
DISPLAY Statement
FOR Statement
GETTING ASSISTANCE WITH THE HELP COMMAND

COMMANDS FOR REPORT WRITING

5-1

5.1
5.2
5.3
5.4
5.5
5.6

PARTS OF A REPORT
INVOKING RW -- REPORT
TERMINATING THE REPORT -- REPORT END
SPECIFYING REPORT PARAMETERS -- SET
FORMATTING DETAIL LINES -- PRINT
FORMATTING SUMMARY LINES -- AT

5-1
5-4
5-6
5-7
5-10
5-11

PROCEDURES

6-1

6.1
6.2

INTRODUCTION TO PROCEDURES
INVOKING A PROCEDURE

6-1
6-1

FOR THE DATA ADMINISTRATOR

7-1

7.1
7.1.1
7.1.2
7.1.3
7.1.4
7.2
7.2.1
7.2.2
7.2.3
7.2.4

DATA DICTIONARY TOPICS
Defining the Records -- DEFINE RECORD
Defining the Domains -= DEFINE DO~AIN
Defining a Procedure -- DEFINE PROCEDURE
Deleting a Previous Definition - DELETE
DATA PROTECTION FEATURES
Two Types of Lock
Five Types of privileges
Password Table Structure
Creating and Maintaining Password Tables

7-1
7-2
7-6
7-9
7-12
7-15
1-15
7-15
7-15
7-16

4.5.1
4.5.2
4.5.3
4.6
4.7

4.8
4.8.1
4.8.2
4.9
4.1.0
4.11
4.12
4.12.1
4.12.2

CHAPTER

7.2.5

P~CI!CI!t.r,...,...rl
- - - - .... - - -

7.2.6

Coding the Table Entries

l'J'I~h'o
----~

P,...,...roCCI!CI!;'nrT
- - - - - - - - ..... :::J

4-32
4-36
4-39
4-40
4-45
4-48
4-51
4-54
4-58
4-59
4-61
4-62
4-63
4-64
4-66
4-67
4-69
4-71
4-72
4-74
4-76

7-17
7-19

CONTENTS (Cont.)

Page

7.2.7
7.2.8
7.2.9
7.2.10
7.3

Design Guidelines for P-assword Tables
Adding Entries to the Password Table
DEFINEP
Deleting a Password Table Entry -DELETEP
Printing a Password Table -- SHOWP
RESTRUCTURING DATA

7-20
7-22
7-25
7-28
7-30

APPENDIX A

SAMPLE DATATRIEVE-ll SESSION

A-I

APPENDIX B

SUMMARY OF DATATRIEVE-ll COMMANDS AND
STATEMENTS

B-1

APPENDIX C

DATATRIEVE-ll KEYWORDS

C-l

APPENDIX D

DATATRIEVE-ll MESSAGES (ALPHABETICALLY)

D-1

APPENDIX E

COBOL RULES

E-l
Index-l

INDEX

FIGURES
FIGURE

1-1
1-2
3-1
3-2
4-1
4-2
5-1
5-2
7-1
7-2
7-3

Sample Data
Collection Cursor
Illustrating Syntactical Symbols
Example of carriage Return Interpretation
Sample Displays Resulting from the SHOW
Command
Sample PRINT Command Output
Parts of a Report
Sample Report Writer Sequences
Example of Password Table Structure
Flowchart of Password Processing Logic
Illustrating a Simple Case of Restructuring

4-11
4-45
5-3
5-14
7-16
7-18
7-31

TABLES
TABLE

P-l
3-1
3-2
4-1
4-2
4-3
4-4
4-5
5-1
5-2
7-1
7-2
E-l
E-2
E-3
E-4

Symbols Used in this Manual
DATATRIEVE-ll Character Set
Keywords
Types of File Access Modes and Modifiers
Value Expressions
Boolean Expressions
Effects of the SELECT Command
Print-list Elements
Default Report Parameters
Summary Items
Privilege Codes
Privilege Requirements by Command
PICTURE Character-String Symbols
USAGE Specifications
Sign Qualifiers
Edit-String Symbols
v

viii
3-4
3-8
4-2
4-24
4-27
4-35
4-43
5-9
5-13
7-16
7-20
E-2
E-2
E-3
E-4

PREFACE

This manual is directed toward the programmer who combines familiarity
and access to RMS-II files with a need to rapidly extract and display
data from those files. This manual serves as both a user's guide and
reference manual to DATATRIEVE-II. As a minimum, the reader should
have a basic knowledge of the operating system, and should have read
the Introduction to RMS-II.
Ideally, the reader is a programmer or Data Administrator experienced
with at least one programm1ng language such as COBOL, FORTRAN, or
BASIC. Regardless of the amount of actual programming experience, the
user would have studied the language reference manual and user's guide
for at least one of these languages. Thus, it is also assumed the
reader has acquired basic input/output and file concepts from these
manuals.
This user would be experienced with various keyboards found on
terminal devices and would be able to adapt if a given keyboard used
the DELETE or RUBOUT key to perform an erasing function.
Any reader lacking the above qualifications should not proceed
further, but should consider whether it would be more appropriate to
read instead the Beginner's Guide to DATATRIEVE-II.
This latter
manual describes a subset of the mater1al 1ncluded here, and in more
elementary terms. Not every user requires -- or wants to learn -- all
the capabilities of DATATRIEVE-II. This is something that each user's
management must determine on an individual basis.
The organization of this manual leads you into the full language
capabilities first.
The topics are presented in a logical learning
sequence in Chapters I through 4, rather than by any alphabetical or
implied functional order.
In Chapter 5, you will find all the
information necessary to learn to use the Report Writer facility to
customize and print a variety of types of reports using data from
RMS-II files. You will find that all the syntax rules you learned in
Chapter 3 carryover directly into the Report Writer statements.
Chapter 6 introduces procedure definitions
used to invoke a procedure.

and

presents

the

method

Chapter 7 presents topics of special interest to Data Administrators
only. The general reader will probably want to skip Chapter 7.
Appendix A is worth your study once you have read the entire manual,
since it provides a sample of an interactive DATATRIEVE-II Session.
It contains a number of additional examples of the commands, and
should help reinforce what you have already learned.
Appendixes B, C, and D provide summary information for convenient
reference. Here you will find a summary of all the command formats, a
list of DATATRIEVE-II keywords, and an alphabetized list of all the
error messages.
Appendix E summarizes some COBOL rules that apply to data
used by DATATRIEVE-II.

vii

definitions

SYMBOLOGY
Throughout this manual you will encounter certain consistent usages of
symbols,
colors,
and
underlining
for
clarifications.
These
conventions are summarized in Table P-l.
Table P-l
Symbols Used in This Manual
Symbol

Name

Meaning

Return

Symbolizes the
carriage
return key or function on
terminal keyboards.

[ ]

Syntax Brackets

Po.

[ ]

Square Brackets

{}

These
smaller
square
brackets
are
keyboard
symbols that you enter in
the places shown.

Braces

A syntax symbol in command
formats
that
indicates
select one of the enclosed
items as a required entry.

Ellipsis

A syntax symbol denoting
possible repetition of the
preceding elements.

red print

syntax symbol in command
formats
that
indicates
select one of the enclosed
entries if you wish.

Anything you would type on
your terminal. All system
printout appears in black
print.

I
Control Character

Represents the CTRL key on
many terminals. Normally
struck in unison with the
alphabetic character that
immediately follows.

xxxxx

Uppercase Letters

Used for command names or
other
elements
in the
statements that must be
spelled as shown.

xxxxx

I Lowercase letters

I Used in the command syntax

blank or
I Graphic
space

I Symbolizes

to represent items to be
replaced by the appropriate
I names or values.
the blank or
space
character.
Only
used
here
to
denote
required spaces.
integer

Lowercase n
(an integer
number)

Represents
an
decimal number.

Underlining

Used in the command syntax
with uppercase words to
represent a keyword that
must be specified in every
use of the command, unless
the keyword is enclosed in
outer syntax brackets.

viii

CHAPTER 1
GENERAL CONCEPTS

This chapter presents the definitions and fundamentals necessary to
learn
DATATRIEVE-ll quickly.
DATATRIEVE-ll accepts English-like
commands from the user and reacts by extracting data from RMS-ll
files.
It can even be directed to modify or update the file. This
entire process occurs in interactive mode -- which means that you
issue a command, the software responds, and you may either correct an
error, continue by issuing more commands, or stop. Most users become
so comfortable with the language they are able to construct the
commands while at the terminal and adapt to the ongoing changes; they
do not find it necessary to preplan on paper every command that will
be entered. In this way it works much like a conversation with a
friend, and is sometimes called a dialogue.
Everything that can be done in DATATRIEVE-ll can be done
in
application programs. However, there are some distinct advantages to
the interactive approach:
•

DATATRIEVE-ll "programs" are specific to a given need.

•

DATATRIEVE-ll sessions are shorter with less coding

•

Time consuming compilations are not needed.

•

Users can respond to errors
results at executiorr time.

•

Any particular session can be lengthened or shortened at will.

unexpected

overhead~

variations

The Report Writer facility of DATATRIEVE-ll will take data operated on
by DATATRIEVE-ll
(or straight from an RMS-ll file) and print it to
conform to user-specified formats.

1.1

INTRODUCTION TO DATATRIEVE-ll INQUIRY FACILITIES

You direct DATATRIEVE-ll with English-like commands. DATATRIEVE-ll is
a command interpreter that both interprets and acts on each statement
as received. Section 2.4 and Chapter 3 provide you with all the common
rules that apply to using the commands. Your major task will be to
formulate the commands that express your desires accurately to
DATATRIEVE.
A number of requirements can be fulfilled by alternate
combinations of commands. This means that the "right" solution to a
DATATRIEVE-II problem is any solution that works.
When you make mistakes, you will be pleased to find that the
consequences are seldom very severe. You can always go back to where
you started and issue a corrected version of the command(s). This may
be a bit of a nuisance, but at least you will not have lost or
destroyed your data in the meantime.
1-1

GENERAL CONCEPTS
There will be certain sequences of commands that must be issued on a
recurring basis at every installation. As a result, DATATRIEVE-ll has
a feature that permits the definition and use of procedures.
These
are nothing but DATATRIEVE-ll commands that are generalized and saved
with a special name, a procedure name.
Later at any time in a
DATATRIEVE-ll sequence of commands you can invoke the procedure by
calling out its name. This saves you some redundant typing. It also
provides a means to establish and distribute more complicated sequences
of commands so that everyone within the installation can benefit from
them without necessarily having to reinvent them. Chapters 6 and 7
provide more discussion of procedures.

1.2

INTRODUCTION TO DATATRIEVE-ll REPORT WRITER FACILITIES

Once you have successfully invoked DATATRIEVE, you can specify that
you wish a certain format of report printed on one of the available
devices. The data to be used in the report may come directly from the
RMS-ll files or may have been preselected and manipulated through a
series of DATATRIEVE-ll commands.
Each report specification is enclosed between a pair of commands:
REPORT and REPORT END.
We will call this entire grouping an RW
sequence, where RW refers to the Report Writing
facility
of
DATATRIEVE-ll.
More than one Report Writer exercise can be incorporated at a time in
a given seSSlon.
In fact, it is possible to bounce back and forth
between inquiry processing and RW processing. The only restriction on
intermixing inquiry processing and RW statements in a session is that
inquiry processing statements must not occur inside an RW sequence.

1.3

SAMPLE DATA FOR EXAMPLES

Throughout the manual the examples use one set of sample
data is depicted in Figure 1-1.

data.

This

The sample data is based on an inventory of yachts, as kept by
Star-Key Marina, Inc. Seven pieces of information are kept for each
type of yacht: the manufacturer, the model number, the rig type, the
length-over-all, the displacement (or weight), the beam size, and the
price.

1.4

DEFINITIONS:

FILES, DOMAINS, COLLECTIONS, RECORDS, AND FIELDS

This section defines the terms domain, collection, record,
field.

file,

and

Records are groups of related items of data that are treated as a
unit. For example, all the pieces of data describing a model of yacht
in the marina could be grouped to comprise that yacht1s record.
Each of the individual pieces of data in a record is referred to as a
field.
For example, the yacht's model number, length, and price are
all potential fields in the yacht record.

1-2

GENERAL CONCEPTS
The term files is used to refer to the logically related groups of
data that are kept by RMS-ll. For example, we might put all of the
yacht records for the current inventory at Star-Key Marina, Inc., into
one file.
Domains are named groups of data containing records of a single type.
An RMS-ll domain consists of all the records in a given RMS-ll file.
In this case, we could say that all the yacht records for the current
inventory are kept in the YACHTS domain. The number of records in any
domain may change as new records are stored or old records are erased.
A record collection is a subset of a domain. It may consist of no
records, one record, or up to all the records in the domain. Using
our previous example, we could say that all the yachts manufactured by
Grampian could be made to form the Grampian-collection, while those
yachts manufactured by Islander could be
used
to
form
the
Islander-collection.
To carry this example one step further, if the
inventory is currently out of stock of yachts manufactured by
Seaworthy, the Seaworthy-collection will be empty, or null.

1.S

INTRODUCING THE DATA DICTIONARY

The Data Dictionary is a location where the
definitions
for
procedures, recoras, anu domains are kept 1n a standard fashion by
DATATRIEVE-lle The Data Administrator will be concerned with the
creation and maintenance of Data Dictionary information. Certain
users will be able to display certain information from within this
dictionary, but only management will be concerned with defining it.

1.6

PROCESSING A FILE AS A COLLECTION

The most important concept to master is collection processing.
DATATRIEVE-ll operates on collections of records taken from the files.
To get down to the level of record processing you must first use the
FIND and SELECT commands to gather the collection and extract desired
records. DATATRIEVE provides a collection cursor to keep track of
your place in the collection. Figure 1-2 illustrates the cursor as a
place marker. You will learn how to manipulate the cursor, moving it
through the collection, from the first, to possibly the next or the
nth record, all the way to the last.
Your moves need not always
follow a forward direction:
yo~
can move about the collection at
will.
In most DATATRIEVE-ll operations, the files are never changed, but a
great deal of manipulation occurs on the collections. Thus, the
collections can be thought of as just a sort of temporary storage,
kept for immediate purposes, and then released.

1-3

GENERAL CONCEPTS

MANUFACTURER

MOItEL

RIG

ALBERG
ALBIN
ALBIN
AMERICAN
AMERICAN

37 MK II
79
VEGA
26
26-MS
30/32
28
TYPHOON
25
35
32
35
CARIBBEAN
CM 30
CM 32
HO
26
28
34
27
37
37 MARK II
25
28
BAHAMA
39
S. CROSS
28
19
26
28
21
222
CENTAUR
IMF'ULSE

KETCH
SLOOP
SLOOP
SLOOP

BAYFIELD
CAPE DORY
CAPE DORY
CAPE DORY
CARIBBEAN
CHALLENGER
CHALLENGER
CHRIS-CRAF
CLIPPER
CLIPPER
EASTWARD
GRAMPIAN
GRAMPIAN
GRAMPIAN
HUNTER
I. TRADER
IRWIN
IRWIN
ISLANDER
ISLANDER
LINDSEY
RYDER
SABRE
SALT
TANZER
TANZER
VENTURE
VENTURE
WESTERLY
WINDPOWER

LENGTH
OVER
ALL
WEIGHT BEAM
37
26
27
26
26
32
28
19
25
35
32
35
35
30
32
24
26
28
33
27
36
37
25
28
24
39
31
28
25
26
28
21
22
26
14

MIS
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP

MIS
SLOOP
SLOOP
KETCH
SLOOP
KETCH
KETCH
SLOOP
SLOOP
SLOOP

MIS
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP
SLOOP

Figure 1-1

20,000
4,200
5,070
4,000
5,500
9,500
9,000
1,900
4,000
18,000
12,800
14,800
18,000
3,800
4,500
7,000
5,600
6,900
12,000
6,500
18,600
20,000
5,400
5,994
4,200
14,500
13,600
7,400
2,600
4,350
6,800
1,500
2,000
6,700
650

Sample Data

1-4

12
10
08
08
08
10
09
06
07
11
11
12
11
08
08
09
08
10
10
09
12
11
12
10
08
12
00
09
07
09
10
07
07
08
07

PRICE
$36,951
$17,900
$18,600
$9,89~

$18,895
$32,875
$21,990
$4,295
$8,995
$37,850
$31,835
$39,215
$37,850
$9,500
$12,950
$15,900
$11,495
$14,475
$29,675
$14,999
$39,500
$36,950
$10,950
$15,908
$6,500
$35,900
$32,500
$22,000
$6,590
$11,750
$17,500
$2,823
$3,564
$15,245
$3,500

GENERAL CONCEPTS

CAPE DORY
BOMBAY

CLIPPER

LAST

26-MS

®
®
ALBERG

37 MK U

Figure 1-2

Collection Cursor

Just as you would expect, the FIRST record of the collection is the
first one encountered when it was being established or collected. The
record numbered with
in Figure 1-2 identifies the first record in
this example.

The NEXT record is always the one immediately after the CURRENT one.
In the figure; the CUB~ENT record is the sixth one; so the NEXT record
must be the seventh.
We have been referring to records according to their numeric position
in the collection, that is, sixth, seventh, and so forth. This is a
proper form of reference, and in the DATATRIEVE-ll language you will
use digits for the position number whenever a format specifies the nth
record.
The LAST record is the one located at the very end of the collection.
If there happen to be no records at all in a collection, we say the
collection is null, and the collection cursor will have to be null,
too.
Generally, you will work on just one collection at a time, the CURRENT
one.
However, there is the facility to name a collection and refer
back to it later in the same session, if you feel that it has enough
importance or probability of reuse.
(See Section 4.4.)
Thus, you may find yourself working with a number of collections, one
of which is the CURRENT one, the one most recently the object of a
FIND command. Each of the collections has its own collection cursor
and may have a designated CURRENT record, as well. However, only one
collection may be CURRENT at a time.

1-5

GENERAL CONCEPTS
The lifetime of any collection is limited to a given session.
Collections cannot be saved, nor can they be shared by several users.
However, you can always reproduce a
collection
of
identical
characteristics (although not necessarily identical records since the
files can change in the interim). You simply repeat the sequence of
FIND
command(s) used initially to establish and/or refine the
collection.
If you find this to be
a
frequently
recurring
requirement, perhaps your installation should define the steps as a
procedure. (See Chapter 6 and Section 7.2.)
Collections may be ordered on command. When you sort a collection,
you may well change the position a particular record holds.

1-6

CHAPTER 2
USING DATATRIEVE-ll

In this chapter you will learn how to know when DATATRIEVE-ll is ready
to accept a command, how to terminate a session, what to expect in the
error messages, and the general mechanics of entering commands.
However, the commands are described in later chapters.

2.1

INVOKING DATATRIEVE-ll

Once you have logged onto your system and instructed the operating
system ~u invoke DATATRIEVE-~~ according to the standard operating
system procedures: you will see the prompt DTR) on your terminal.
This means you are ready to enter a DATATRIEVE-ll command.

2.2

STOPPING

You may leave a DATATRIEVE-ll session at any time by means of the EXIT
command (Section 4.2) or the CTRL Z (~Z) character combination.

2.3

ERROR MESSAGES

Because you
notification
options:

operate in interactive
mode,
you
get
immediate
when an error is detected. This gives you the following

•

revise your work (if this was a major error),

•

correct the problem in the last command, or

•

terminate the session.

All error messages are listed in alphabetical order in Appendix D.
You will observe that the messages are sentence-like and quite
descriptive. There will be no need to "decode" an error code, as you
may have done in some other languages.

2.4

ENTERING COMMANDS

As you learn the commands in the following chapters, you will find
certain common rules apply to entering them. For example, you can
only enter a command after the prompt DTR>.
Furthermore, you must
terminate a command with a final carriage return. Once a command is
entered, DATATRIEVE-ll begins execution immediately. If you have made

2-1

USING DATATRIEVE-ll
an error, but no significant changes were made to the collection, you
may generally simply reissue the command in corrected form to obtain
the desired results.

2-2

CHAPTER 3
SYNTAX RULES FOR DATATRIEVE-II COMMANDS

This chapter presents all the basic rules that apply to
the
construction of DATATRIEVE-ll commands.
You must understand the
significance of spelling, spacing, syntax symbols, and sequence when
using the commands. You will learn what characters are permitted in
the commands, how to form names and literals, how to insert comments,
and how to continue and terminate command lines. You will also see
how to interpret syntax symbols, how to delimit (separate)
the parts
of a command, and what the keywords in the commands are.

3.1

SEQUENCE OF COMMANDS

There are just a· few restrictions regarding the sequence of the
commands.
EXIT is always the last command. READY is often the first
command, but it could be preceded by others.
Beyond that, you can
intermix commands with each other, and likewise, you can intermix RW
commands with each other, with a great deal of freedom.
However, as
mentioned in Chapter 1, once you begin the specification of a report,
you cannot introduce other commands until the REPORT END command is
processed.

3.2

SPELLING

Spelling is critical: you must enter commands as they are shown in
their "Format" description.
As a general rule, command names or
elements may not be abbreviated unless the particular
command
description tells you to do so.

3.3

SPACING

DATATRIEVE-ll is a free-form language, which means that you may have
any number of intervening spaces or tab characters between language
elements. Since DATATRIEVE-ll is English-like, the examples generally
show single spaces between elements.

3.4

SPECIAL SYMBOLS -- BRACKETS,
LOWERCASE

BRACES,

ELLIPSIS,

UPPERCASE, AND

The preface introduced these special symbols, but it may be helpful to
supplement the definitions with examples. Special symbols are used in
the syntax descriptions to clarify proper usage of the command
elements.
While they are discussed individually here, you will note

3-1

SYNTAX RULES FOR DATATRIEVE-ll COMMANDS
in Figure 3-1 that they can be combined
expression in numerous ways, even nesting.

given

syntactical

Syntax Brackets ([ ]) denote items that are optional.
If more than
one item is enclosed in brackets, you may chose one (or none) of the
items.
Square Brackets ([ ]) denote the bracket symbols on the
are required where shown.

keyboard

and

Braces ({}) enclose one or more items that are required.
If more
than one possible entry is shown, you must include one of the choices,
but you can specify no more than one.
Ellipsis ( •.• ) imply that you can choose to repeat a version of the
immediately preceding command element. In DATATRIEVE-ll there are no
restrictions on the number of repetitions, unless you are explicitly
told so.
Watch for punctuation characters needed to serve as
separators for the repetitions. Note that repetitions only occur at
your option.
Uppercase letters denote required words
underlined, these words are optional.

~hen

underlined.

When

not

Lowercase letters are used with generic terms that must be replaced by
tbe appropriate names or values.
Underlining ( ) denotes that the uppercase word is required in every
use of the command or statement, unless enclosed in outer brackets.
Figure 3-1 illustrates a fairly complex syntactical
structure,
employing all these symbols in an English sentence rather than a
command. Observe how the symbols can be nested.
Wherever nesting
occurs, the meaning of the outermost pair of symbols prevails. Thus,
when a seemingly required item inside braces occurs inside a pair of
outer brackets, the entire group is considered to be optional.
As you study Figure 3-1, notice the large number
that can be constructed to conform to the
possibilities are shown here.

of legal sentences
only a few
syntax;

Later, when you see these same symbols used in actual DATATRIEVE-ll
command definitions, keep in mind the large number of combinations of
command elements they imply. Do not be concerned that you will need
to enter these special symbols as part of the command. They only
exist as part of the description of the command, as a sort of code to
indicate a number of ways you can choose to construct each command
from its parts.

3-2

SYNTAX RULES FOR DATATRIEVE-ll COMMANDS

Assume the following syntactical structure:

The following sentences
could construct:

are

among

the many possibilities the user

JOHN PLAYS, AND LOSES ALL.
None of the optional bracketed items is included;
required underlined words in uppercase are kept.

only

the

JOHN PLAYS THE HORSES, AND LOSES ALL.
An object word for PLAYS is supplied, but the
clause is omitted.

bracketed

FORGETS

JOHN PLAYS, FORGETS HE HAS A DATE WITH MARY, AND LOSES ALL.
The optional bracketed items after PLAYS
FORGETS clause is added.

are

omitted,

but

the

JOHN PLAYS THE FIELD, FORGETS HE HAS A DATE WITH SUSIE, AND LOSES ALL.
All options included except the repetition.
JOHN PLAYS BASEBALL, FORGETS HE HAS A DATE WITH
GAIL, AND LOSES ALL.

DATE

WITH

Observe the substitution of BASEBALL for
the lowercase
sport-name and the repetition at the site of the ellipsis.

word

Figure 3-1

BETTY,

Illustrating Syntactical Symbols

3-3

SYNTAX RULES FOR DATATRIEVE-ll COMMANDS
3.5

CHARACTER SET

The character set consists of the letters A through Z,
through 9, and certain special symbols. See Table 3-1.

numbers

Table 3-1
DATATRIEVE-ll Character Set
A
B

C
D
E
F

H
I
J

K
L
M
N
0
p

Q
R
S

3.6

T
U
V
W
X
Y
Z
0
1
2
3
4
5
6
7
8

(
)
[
]

/
"

COMMENTS

You may introduce a comment anywhere in your session if you like, by
keying an exclamation point character (1), following it with text, and
terminating with a carriage return (~). The text may consist of
any characters in the character set including the exclamation point.
Comments may begin anywhere on an input line and are not
start at the beginning of the line.

required

The value of comments diminishes in an interactive environment.
You
may find you wish to include them in indirect command files (Section
7.1). However, you will find that if you put them in your procedure
definitions (Section 7.1.3), they are not retained in the Data
Dictionary.

3-4

SYNTAX RULES FOR DATATRIEVE-ll COMMANDS
3.7

NAMES

Names are constructed from the letters A through Z, numbers 0 through
9.-1. aJl~ttlte._.$p-~cj,aJ, . . _chaLctct~J~,. hyph.~n .. t~:J...'rhe .. c_.onstxuctiQn Qf .name_s ...
is subject to five rules:

3.8

Every name must begin with a letter.

Names must never end with a hyphen.

Names can only be continued from the end of one input line to
the beginning of the next by means of a hyphen, as will be
explained in Section 3.9.

You must be careful when creating names to avoid the
DATATRIEVE-ll
keywords.
(See Section 3.11. ) For your
convenience,
these
special
names
are
also
listed
alphabetically in Appendix C.

Names of records, domains, procedures, and collections are
kept in the Data Dictionary and are subject to a size
limitation of 30 characters.

LITERALS

There are two categories of literals:
alphanumeric
Thus, different rules apply for specifying each.

and

numeric.

Alphanumeric literals may consist of alphabetic, numeric, and special
characters.
All alphanumeric literals must be enclosed in quotation
m~rks (").
For example, if you use the phrase BUILDER EQUAL "O'DAY",
"O'DAY" is an alphanumeric literal. Similarly, in MODEL EQUAL "37 MK
II", "37 MK II" is an alphanumeric literal. To include a quotation
mark as a legal character within an alphanumeric literal, use two
consecutive quotation marks.
For example, you might want to display
an alphanumeric message, "CAPT. JACK SAYS, ""TIME TO REORDER""", such
that TIME TO REORDER would appear in quotes.
Combinations using the CTRL (A) character are not permitted as special
characters in an alphanumeric literal.
Nume.ric literals consist of digits and an optional decimal point
(.),
and they are written without quotation marks. For example, you may
use the phrase, BEAM EQUAL 12. Here, 12 is a numeric literal.
If the
decimal point is included, it must not be the first character in the
number. Thus, 0.5 is permitted as a numeric literal, but .5 is not.

3-5

SYNTAX RULES FOR DATATRIEVE-Il COMMANDS
3.9

CONTINUATION LINES -- CARRIAGE RETURN (~)

Some of the DATATRIEVE-II statements can become longer than a single
You simply
line length.
DATATRIEVE-II permits continuation lines.
enter a carriage return (~) as you approach the end of each line
and continue the statement on the next line or lines.
DATATRIEVE is able to recognize all the possible elements in a command
and to interpret whether there should be more input to follow any
given carriage return. As proof of this, you may see DATATRIEVE-II
responses that say:
[LOOKING FOR element-name] where element-name is
the syntactical element that DATATRIEVE-II has determined should
follow the preceding portion of a command.
CAUTION
If you enter a carriage return at a
point where a logical termination could
occur, DATATRIEVE assumes it has found
the termination and looks no further.
You may use the hyphen (-) to remove all
ambiguity:
a
hyphen
preceding
a
carriage return always implies a command
continuation to DATATRIEVE.
However,
you should not continue more than two
successive lines with hyphens.
Also note that the hyphen provides the only proper way to continue a
literal or name from one line to the next. To continue a hyphenated
name, such as SMALL-YACHTS, you could specify any of the following
forms, or variations of them.
SMALL- C~;l')
-YACHTS
or
SMALL-- C~ET)
YACHTS
or
SM- 0fT:1

ALL-YACHTS

Figure 3-2
sentence.

illustrates

these

concepts

3-6

with

ordinary

English

SYNTAX RULES FOR DATATRIEVE-ll COMMANDS

Assume the sample sentence:
JOHN WENT TO THE OFFICE AND RAN INTO MARY

JOHN~
WENT~

TO THE OFFICE ~
AND RAN INTO MARY ~

Subject, but no verb, so continue.
Missing the object, continue.
Sentence appears complete, stop.
Attempt to process as a new sentence.

To remedy the premature termination, try this instead:

JOHNGQ
WENTGQ
TO THE OFFICE AND ~
RANGD

Now it is obvious there is more.

MARYGQ

Structure appears complete, stop.

INTO~

You could have used a hyphen (-) after "OFFICE"
to indicate continuation:

JOHN~
WENT~

TO THE OFFICE- ~
AND RAN INTO MARY ~

Figure 3-2

3.10

Subject, but no verb, so continue.
Missing the object, continue.
Hyphen before return, continue.
Structure appears complete, stop.

Example of Carriage Return Interpretation

COMMAND TERMINATION--SEMICOLON

Since DATATRIEVE recognizes the command elements, it is not necessary
to terminate each command with some form of punctuation such as a
semicolon.
However, the option exists for you to specify the
semicolon, if you desire, as the formal designation of command end.
Two commands, DELETE and DEFINE, require the semicolon.
If you want to issue more than one command per input line, you must
use the semicolon to separate the commands. Furthermore, DATATRIEVE
will not begin to process any commands on the same input line until a
carriage return is detected.
Spaces or tab characters at the end of a line are ignored.

3.11

KEYWORDS

Keywords are language elements that have a specific meaning to
DATATRIEVE-ll.
If you use them in any other context, you may confuse
DATATRIEVE about your intentions. Thus, it is a good policy to avoid
the use of these words as names of domains, procedures, records,
fields, and collections.
The full list of keywords is reproduced in Table 3-2 and Appendix C.
3-7

SYNTAX RULES FOR DATATRIEVE-ll COMMANDS
Table 3-2
Keywords
ABORT
ADVANCED
ALL
AND
ASC
ASCENDING
AT
AVERAGE
BEGIN
BETWEEN
BOTTOM
BT
BY
CHARACTER
COL
COLLECTIONS
COLUMN
COLUMN-HEADER
COLUMNS-PAGE
COMP
COMP-l
COMP-2
COMP-3
COMP-5
COMP-6
COUNT
CURRENT
DATE
DECREASING
DEFINE
DEFINEP
DELETE
DELETEP

3.12

DESC
DESCENDING
DISPLAY
DOMAIN
DOMAINS
EDIT-STRING
ELSE
END
END-PROCEDURE
EQ
EQUAL
ERASE
EXCLUSIVE
EXIT
EXTEND
FILL
FIND
FINISH
FIRST
FOR
GE
GREATER-EQUAL
GREATER-THAN
GT
HELP
IF
IN
INCREASING
IS
JUSTIFY
LAST
LE
LEADING

LESS-EQUAL
LESS-THAN
LINES-PAGE
LT
MAX
MAX-LINES
MAX-PAGES
MIN
MODIFY
NE
NEW-PAGE
NEW-SECTION
NEXT
NO
NO-DATE
NO-NUMBER
NOT
NOT-EQUAL
NUMBER
OF
ON
OR
PAGE
PIC
PICTURE
PRINT
PROCEDURE
PROCEDURES
PROTECTED
PW
QUERY-HEADER
QUERY-NAME
READ

READY
RECORD
RECORDS
RELEASE
REPEAT
REPORT
REPORT-HEADER
REPORT-NAME
SELECT
SELECTIVE
SEPARATE
SET
SHARED
SHOW
SHOWP
SIGN
SKIP
SORT
SORTED
SPACE
STORE
TAB
THE
THEN
TOP
TOTAL
TRAILING
UIC
USAGE
USING
VERIFY
WITH
WRITE

DELIMITERS

Delimiters are required around keywords, names, and
delimiters are separators, and you may select
choices:
•

the space;

•

the tab character, and

•

the carriage return.

Any given DATATRIEVE-ll session may
times in many different places.

3-8

use

all

three

literals.
These
any of the three

delimiters

many

SYNTAX RULES FOR DATATRIEVE-ll COMMANDS
3.13

SEQUENCE OF COMMAND ELEMENTS

Each possible command element has a position in the command format.
-This _ Lelativ_e_ lCLc_ation_ia_al_w~¥--s __ ill ustratecL-when---thacommand- .£OXlna-tsare given. It is extremely important that you obey this sequence when
you formulate your commands.
When you decide to omit one of the
optional elements, just leave its relative position in the command
empty, but proceed to the remaining elements in the left-to-right
sequence.

3-9

CHAPTER 4
COMMANDS FOR INQUIRY & UPDATE

This chapter presents the commands that are part of the
facility for inquiry and update.

4.1

DATATRIEVE-ll

STARTING A DATATRIEVE-ll SESSION WITH READY

As soon as you have successfully invoked DATATRIEVE-ll and have
obtained the DTR) prompt, you are able to enter your first command.
If you have been away from the system for a while, you may wish to
refresh your memory by means of the HELP command that is described as
the very last item in this chapter. (See Section 4.14.)
The operations you are about to attempt will probably require the use
of one or more domains. Before you can use any domain you must ready
it, so you will probably want to issue a READY command as one of your
commands, if not the first. The purpose of readying a domain is to
claim it for your use. This means that if other users want to use it,
too, they may be subject to certain restrictions. It is important
that any shared resource be handled according to certain rules.
The data processing management at your facility will have given
considerable thought to whether certain resources may be shared. One
issue is whether to restrict the ability to change any of the record
fields in a file to only certain users. Another concern is whether to
permit sharing at all. By the time you are ready to run your first
DATATRIEVE-ll request, these issues should be resolved.
The types of access modes and modifiers are described in Table 4~1.

4-1

COMMANDS FOR INQUIRY & UPDATE
Table 4-1
Types of File Access Modes and Modifiers
Modifier

Meaning

SHARED

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

PROTECTED

Any other user may access, but not concurrently
write, modify, or extend (add) records in this
domain.

EXCLUSIVE

No other user may concurrently execute a READY
for this domain -- for any type of access.

Mode Name

Meaning

READ

Retrieve only.

MODIFY

Retrieve and change only.

WRITE

Retrieve, change, add, or delete.

EXTEND

Add only.

NOTE: The Data Administrator will have some control over
which modes of access (READ, MODIFY, WRITE, or EXTEND)
are permitted for each domain.
(See Chapter 7.)
However, you are the only one controlling the acceptance
of the access
modifiers
(SHARED,
PROTECTED,
or
EXCLUSIVE) •

4-2

COMMANDS FOR INQUIRY & UPDATE

READY
Purpose
This command informs the system that you expect to
reference a certain domain. At the same time, you can
declare how you intend to use the domain. For example,
you can indicate that you want to just read from it, or
that you expect to modify it, or that you will want
exclusive use of it.
Format

SHARED
domain-name-l [(password-str-l)] PROTECTED
[ EXCLUSIVE

READ ]
MODIFY
WRITE

[ EXTEND

You must supply a domain-name, and it must name a
domain that exists in the Data Dictionary and on
the RMS-ll files.

You may optionally wish to specify the access
modifiers and/or access modes that you expect to
use. See Table 4-1 for a description of each.

In some cases it may be necessary to know a
password to gain access to a particular domain. If
you are given a password to specify, be sure to
enclose
it in parentheses.
If you enter an
asterisk (*) for your password, you will
be
prompted to supply a password. In this mode your
password specification will not be echoed on your
terminal
device
to
ensure
greater password
security.

If none of the access modifiers or modes is
specified, it is assumed you wish to ready the
domain for PROTECTED READ.

Requirements
None.
Restriction
You cannot issue a READY command in a procedure
definition (Section 7.1.3), a BEGIN-END Block (Section
4.13.1), or THEN statement (Section 4.13.4).
Prompts &
Responses
None, unless you specify an asterisk (*) for the
optional password. This will cause the following prompt
to appear:
PLEASE SUPPLY PASSWORD:
Effects
1.

The domains are
availability.

4-3

checked

for

existence

and

COMMANDS FOR INQUIRY & UPDATE
2.

DATATRIEVE checks an internal password table for
the named domain to ensure that you are allowed the
type of access mode requested for that domain.

The record definition
checked for existence.

You can only ready one domain at a time with this
command. However, you can use the command multiple
times in a session to ready a number of domains at
once.

If you READY the same domain again but give
different access qualifiers, the last READY to be
executed prevails.

for

this

domain

also

Examples
The following example readies the domain YACHTS (yacht
records) for exclusive use by this user and allows the
domain to be read, modified, erased, and/or extended.
Since this is the full range of access capabilities and
the most restrictive access modifier, it is logical to
assume a password is necessary.
Your password is
FAIRWINDS.
DTR>READY YACHTS (FAIRWINDS) EXCLUSIVE WRITE; ~
The following example illustrates how to ready the same
domain for shared read-only access when no password is
required:
DTR>READY YACHTS SHARED READ ;,~
Hints
You should adopt the practice of only readying those
domains you really intend to use. However, since very
little can be done in a DATATRIEVE session unless you
have performed a READY, you will probably also want to
adopt the habit of issuing the READY command(s) at the
very beginning of the session.
It is also good practice to be as unrestrictive in the
access mode specification as you can afford to be. For
example, if you insist on demanding that the domains
you
use be kept EXCLUSIVE, you can hurt system
performance for other users that could otherwise be
sharing the domain.
Finally, if you only intend to retrieve records from
the domain, keep in mind that READ mode is more
efficient for this purpose than either WRITE or MODIFY
mode.
Selecting either of the latter two just to
retrieve is overkill.
You can confirm that a domain has been readied by means
of the SHOW READY command described in Section 4.3.

4-4

COMMANDS FOR INQUIRY & UPDATE
4.2

ENDING A DATATRIEVE-ll SESSION -- EXIT

If at any time you wish to leave your terminal or

stop

DATATRIEVE

.s_es.s_i2Ih .. Y.OJ,L.shQJ,tlQ. . k:n~tw:.. _bQwt.Q J,Ls.~.tlte.EJtlT~..~1ll1lJ.anQ_~. .~lt!~.~.Q.mJJLClIl(l

lets you terminate any session gracefully. It 1S the proper way to
finish all sessions, and assures you that no unauthorized user can
gain access to domains you have readied from your terminal.
It is
also the most considerate action to take so that domains are freed up
for other users to gain access. It is good practice not to leave the
terminal unless you have performed an EXIT command.

4-5

COMMANDS FOR INQUIRY & UPDATE

EXIT
Purpose
execute
When you
this
DATATRIEVE-II session.

command,

you

Format
EXIT
Requirements
You may issue this command
DATATRIEVE-II session.

any

time

Prompts &
Responses
No prompting messages appear, but you will be informed
that the session is terminated. The response assumes
the form:
BYE
Effects
1.

DATATRIEVE-II processing is terminated.

Any domains that had been readied are automatically
closed, and all collections established in this
session are released. This is true for both the
named and unnamed collections.

You cannot issue another DATATRIEVE-II
until you reinvoke DATATRIEVE-II.

command

Example
DTR>EXIT;~

BYE
Hint
You can accomplish the functions of
with a CTRL Z (~Z).

4-6

the

EXIT

command

COMMANDS FOR INQUIRY & UPDATE
4.3

GETTING AN OVERVIEW OF YOUR DATA -- SHOW

If at any time you begin to wonder about the contents of a particular
-de-ma-i-n-· ·-0--r -r-e-cor-d,---- -··y-G-u---may- w-a-n-t· -to---is-sue·· --the- -SHQW··-comma-nd-.-···· -Each
installation can provide its users with current printouts depicting
the domain and record definitions that will be used. However, it is
the SHOW command that is used to generate them, and it is always
helpful to know how to use this command yourself.
In some installations domain and record information will be quite
static, while in others, there may be frequent changes. When in
doubt, it is easy enough to request a copy with the SHOW command.
Furthermore, since a collection is a temporary formation, you may want
to monitor your collections yourself. All these capabilities, and
more, are possible with the SHOW command.

4-7

COMMANDS FOR INQUIRY & UPDATE

SHOW
Purpose
This command requests a copy of the summary details
maintained in the Data Dictionary for your data. You
may request to see all the information maintained, or
you may just request to see specific portions of it.
For example, you might limit your review to the domain
details, or you might restrict it even further to only
one particular domain, collection, or record.
Format
SHOW show-item-l [,show-item-2 ••• ]
1.

You must supply at least one show-item, and it must
be one of the following possible choices:
PROCEDURES
DOMAINS
COLLECTIONS
RECORDS
ALL
CURRENT
READY
procedure-name-l [(password-str-l>]
domain-name-l [(password-str-2)]
record-name-l [(password-str-3)]
collection-name-l
Observe that three of the possible
take an optional password string~

show-items

may

You may optionally wish to request additional
information by appending one or more show-items.

If you specify PROCEDURES, DOMAINS, COLLECTIONS, or
RECORDS, your display will show the names of the
defined procedures, defined domains, established
collections, or defined records, respectively, as
they exist at this point in time.

If you specify ALL, your display will contain the
names of
all the defined procedures, defined
domains, established collections,
and
defined
records.

If you specify CURRENT, your display will provide
only the information describing the CURRENT record
collection.

If you specify READY, your display will identify
the names of all domains that are presently ready,
their file type, access mode, and access modifier.

If you name
a
specific
procedure,
domain,
collection,
or
record,
you
will
be given
information regarding just that particular item,
provided it is not protected from your view.
Procedures, domains, and records can be protected
so that only users with password knowledge can view
or change them.
-

4-8

COMMANDS FOR INQUIRY & UPDATE
8.

If you want, you may separate each
of
the
show-i terns
by
a
carr iage
return
( ~ ).
DATATRIEVE will execute each part of the command up
to- -e-ach- .-carxiage. r-e-turn-; .. and w-ill _th_encDme _ha_ck to
look for more show-items.

Requirements
The format of the SHOW command that specifies a
resource-name
(where domains, records, and procedures
are the resources) requires that the issuer have access
privileges.
These
checks are part of the data
protection features described in Chapter 7.
The only other prerequisite concerns the specification
CURRENT. You should only specify SHOW CURRENT when you
have established a CURRENT collection with the FIND
command.
Section 4.4 describes the various FIND
commands.
Restriction
You must not use this command within a procedure.
Section 7.1.3.)

(See

Prompts &
Responses
for the optional
If yeu s~ecify an asterisk
(*)
password, you will be prompted to specify the full
password by the message:
PLEASE SUPPLY PASSWORD:
Otherwise, no prompting messages appear, but you
find
the display occurring automatically on
terminal device.

will
your

Effects
1.

If you are deemed to have access privileges for a
named
resource
(such as a particular record,
domain, or procedure definition),
the results of
the request appear, in the order of the show-items,
bn your terminal device. The format of the output
is explained by Figure 4-1.

For the other types of show items, no checking is
necessary;
the results appear, in the order of the
show-items, on your terminal device.
See Figure
4-1 for a sample of the printout format.

There is no effect on the collection cursor.

Examples
The following example displays the names of
procedures, domains, collections and records.
DTR>SHOW ALL; ~

4-9

all

the

COMMANDS FOR INQUIRY & UPDATE
The following example illustrates how to display just
the
record
definition
for
the
record
named
COBOL-YACHTS. Assume that your password is SUNNY-DAY.
DTR>SHOW COBOL-YACHTS (SUNNY-DAY); ~
Hints
If you are going to use a password with the SHOW
resource-name form of the command, consider specifying
just an asterisk in parentheses (*).
DATATRIEVE will
respond by requesting the full password, but will not
echo the characters you enter.
This affords greater
password security.

4-10

COMMANDS FOR INQUIRY & UPDATE

DTR)SHOW DOMAINS
DOMAINS:
THINGS-TO-DO
I1ICT-DOMAIN
-f'ORTRAN=-YACHTS
COBOL-YACHTS
BOATS
FEATURES
DATA-TYPES
MESSAGES
RMS-MSGS
COMP-SCALE
MESSAGES-SHIP
YACHTS
IITR),SHOW YACHTS
DOMAIN YACHTS
USING YACHT ON
YACHT.DAT;
'DTR>SHOW YACHT
RECORD YACHT
USING
01 BOAT.
03 TYPE.
06 MANUFACTURER PIC X(10)
QUERY-NAME IS BUILDER.
06 MODEL PIC X(10).
03 SPECIFICATIONS
QUERY-NAME SPECS.
06 RIG PIC X(6).
06 LENGTH-OVER-ALL PIC XXX
QUERY-NAME IS LOA.
06 DISPLACEMENT PIC 99999
QUERY-HEADER IS -WEIGHTEDIT-STRING IS ZZ,ZZ9
QUERY-NAME IS DISP.
06 BEAM PIC 99.
06 PRICE PIC 99999
EDIT-STRING IS $$$,$$$ .;
DTR>READY YACHTS; FIND THE YACHTS WITH PRICE >0;
[35 RECORDS FOUND]
DTR>SHOW CURRENT
COLLECTION CURRENT
DOMAIN: YACHTS
NUMBER OF RECORDS: 35
NO SELECTED RECORD
DTR>SHOW COLLECTIONS
COLLECTIONS:
CURRENT
'DTR> SHOW READY
READY DOMAINS:
YACHTS: RMS INDEXED, PROTECTED READ
DTR>SHOW POUNDS-PER-FOOT
PROCEDURE POUNDS-PER-FOOT
DISP/LOA (-POUNDsa/apERa/-FOOT a ) USING Z(5)
Figure 4-1

Sample Displays Resulting from the SHOW Command

4-11

COMMANDS FOR INQUIRY & UPDATE

ItTR>SHOW ALL;
DOMAINS:
THINGS-TO-DO
DICT-DOMAIN
FORTRAN-YACHTS
COBOL-YACHTS
BOATS
FEATURES
DATA-TYPES
MESSAGES
RMS-MSGS
MESSAGES-SHIP
YACHTS
RECORDS:
THING-TO-DO
DICT-REC
FORTRAN-YACHT
COBOL-YACHT
FEATURE-RECORD
DATA-TYPE-RECORD
RMS-MSGS-RECORD
MSG-RECORD
MSG-SHIP-REC
YACHT
PROCEDURES:
REPORT
POUNDS-PER-FOOT
LOA-REPORT
MESSAGE-REPORT
FEATURE-REPORT
MESSAGE-LISTINGS
LIST-MESSAGES
PR ICE-PER-POUNII
PRICE-INCR
COLLECTIONS:
SLOOPS (ALSO CURRENT)
I~EADY lIOMA I NS :
YACHTS: RMS INDEXED, PROTECTED READ
Figure 4-1 (Cont.)

Sample Displays Resulting from the SHOW Command

4-12

COMMANDS FOR INQUIRY & UPDATE
4.4

GETTING A COLLECTION TOGETHER -- FIND

The first step toward manipulating a collection is to "establish" it.
~his
proc:esspulls the c:ollectiontog~ther and gives it an initial
-shape -or --de-£rnit16n-~ -----wTth-the- three- -v-erslon-g---6i--th-e- FIND c-ommaii"Ci
described in this section, you can choose to:

4.4.1

•

establish a new collection,

•

refine an existing CURRENT collection, or

•

name and/or sort a collection while establishing it.

Establishing the Collection

Before you can perform a number of DATATRIEVE operations, you must
establish a collection of records for processing. If you wish, this
collection may consist of all the available records in a domain.
Or,
you may restrict the collection to just a subset of the domain's
records. You use the FIND command to establish collections. You may
establish a number of collections in a given DATATRIEVE session
through multiple usages of the FIND command. The last collection to
be established is referred to as the CURRENT collection.

4-13

COMMANDS FOR INQUIRY & UPDATE

FIND
Purpose
This command pulls together or establishes a collection
of records. This collection may consist of zero, one,
or more records. In fact, it may contain all the
available records.
As a result of the FIND command,
the collection becomes the CURRENT collection. Nothing
else is done to the resultant collection; it is simply
formed so that you can perform other operations on it
such as SELECT, SORT, MODIFY, or PRINT.
Format
FIND domain-name-l [WITH condition]
1.

You must supply a domain-name, and it must
domain that you have already readied.

name

You may optionally wish to restrict the records
that are collected by specifying the word WITH
followed by a condition. Section 4.5 provides all
the rules necessary to formulate this Boolean
expression.
(Observe that a variety of compound
Boolean
expressions
are
permitted
for
the
condition, so that you can effectively specify
multiple conditions.)

Requirements
You must have already performed a successful READY on
this domain with any of the access modes of READ,
WRITE, or MODIFY, but not EXTEND.
Section
4.1
describes the READY command.
Prompts &
Responses
No prompting messages appear, but you will be informed
how many records met your selection criterion. The
response assumes the following form:
[n RECORD(s) FOUND]
where n is a number representing the number of
found.

records

Effects
1.

The records are collected in the order in which
they are found. You should not infer that there
will be any order to the collection.

The collection just established by this command
now the CURRENT collection.

The collection cursor is left null.

Examples
The following example collects all 113 records
domain YACHTS.

4-14

the

COMMANDS FOR INQUIRY & UPDATE

DTR>FIND YACHTS; ~
[113 RECORDS FOUND]
The following example illustrates how to collect only
t-h-o-s-e-----r--e-co-r-ds-i-n---the--d-o-m-a-i-n --Y-Aewrs-----th-at-have---an- -overalllength that exceeds 32 feet and cost less than $50,000.
DTR>FIND YACHTS WITH LENGTH-OVER-ALL >32 AND ~
DTR>PRICE < 50000 ~
[36 RECORDS FOUND]
Note the use of a compound Boolean expression to
for two concurrent conditions.

check

Also note in this example that the first ~
follows
the logical operator AND so that there can be no
confusion that the command has ended.
Only when the
second
~
is detected will DATATRIEVE decide that
the end of the command has been reached.

4-15

COMMANDS FOR INQUIRY & UPDATE
4.4.2

Refining the Collection

If you have established a collection, but after reviewing it or
considering the number of records in it, realize you wish to restrict
it to fewer records, you may want to "refine" it.
Although you could probably accomplish the same objective by revising
your last FIND domain WITH condition command, you may want to start
processing with the collection at hand, instead. This is, of course,
the CURRENT collection, and it usually represents far fewer records
than would the whole domain. Thus, time savings are possible when you
rework an existing collection versus searching the entire domain
again. The FIND CURRENT WITH condition command does just that.

4-16

COMMANDS FOR INQUIRY & UPDATE

FIND CURRENT
Purpose

ThIs comrn-~iricr <iene-rarly - applie-s

a res-trictiv-e set or
conditions to the CURRENT collection to produce a new
CURRENT collection that is more explicitly selected.
Although the specification of a condition is not
mandatory, this form of the FIND cooo~and has no meaning
unless a condition is given.
Format
FIND CURRENT [WITH condi tion]
1.

You must have established
CURRENT collection.

collection

the

You may optionally wish to restrict the records
that are collected by specifying the word WITH
followed by a condition. Section 4.5 provides all
the rules necessary to formulate this Boolean
expression.
(Observe that a variety of compound
Boolean expressions are permitted for the condition
so that you can effectively specify
multiple
conditions.)

If no condition is specified, you have accomplished
nothing except to make the cursor null since the
resultant CURRENT collection will be identical to
the initial one.

Requirements
You must have already successfully
collection as the CURRENT collection.

established

Prompts &
Responses
No prompting messages appear, but you will be informed
how many records met your selection cri~erion. The
response assumes the following form:
[n RECORD(s) FOUND]
where n is a number representing the number of
found.

records

Effects
1.

The records are collected in the order in which
they are found. You should not infer that there
will be any order to the collection.

The collection just established by this command
now the CURRENT collection.

The collection cursor is left null.

The previous collection, unless named, is released.

4-17

COMMANDS FOR INQUIRY & UPDATE
Examples
The following example assumes you have collected all
113 records in the domain YACHTS into the CURRENT
collection and now wish to refine the collection to
include only those records of yachts manufactured by
Caribbean.
DTR>FIND CURRENT WITH BUILDER EQ "CARIBBEAN"; GD
[1 RECORD FOUND]
The following example assumes you have just established
as the CURRENT collection only those 59 records in the
domain YACHTS that have an overall length less than 32
feet and a price less than $50,000. Now you must
refine that collection to include only those with a
displacement (weight) less than 7000 pounds.
DTR>FIND CURRENT WITH DISPLACEMENT < 7000; ~
[38 RECORDS FOUND]

4-18

COMMANDS FOR INQUIRY & UPDATE
4.4.3

Naming and Sorting the Collection

While you frequently use collections as temporary storage and may only

--need- - ---t-o--- ---u-s-e---cn-e---eol1-e-e-t-i-o-n- --(-t-he----C-URRENT--o-n-e)-----at -a- --t-i-me-, -sumeti-mes---it--

is helpful to be ab~e to give a collection a name. Once a collection
carries a name, you can set it aside, establish other collections as
the CURRENT one, at their separate times, and yet always return to
process the named collection, when necessary.
You may also want to sort the collection. Although the SORT command
described in Section 4.7 does this as its sole function, you may if
you wish, sort the collection while establishing it.
In this most
powerful version of the FIND command you can establish, name, and sort
a collection all at once.
Several points are extremely important regarding named collections:
•

they only exist for your purposes during this session,

•

they cannot be saved, and

•

every type of normal or abnormal exit releases them.

You need never be concerned that the name you select for your
collection might duplicate some other user's. Two concurrent users
can use the same collection name without conflict because collections
can never be shared.
Your only concern should be that if you name
more than one collection in a session, you might not keep your
collection names unique.
If in doubt, issue a SHOW COLLECTIONS
command to determine the names you have used.
Refer to Section 3.7 for the rules for names.

4-19

COMMANDS FOR INQUIRY & UPDATE

FIND rse
Purpose
This command gives you the power to establish a
collection, refine a collection, extract a subset of
the collection, sort the collection, and/or name a
collection.
If
you
examine the command syntax
carefully, you will see that this version of the FIND
command is actually a superset of the previous two
versions discussed. All this capability is possible
through the record-selection-expression, or rse. While
the rse is fully described in a separate section (see
Section
4.5),
this
command
offers a practical
introduction to the key features of the rse.
Format
FIND record-selection-expression
where the record-selection-expression (rse) assumes the
following form:

[~iisT nJ [collectn-name-2 !Wr~~~~~~~n-name-f
[WITH conditn]
ldomal.n-name-l ')
[SORTED BY key-l[,key-2 ... ]]
The record selection expression follows all
presented in Section 4.5.3.

the

rules

You must supply either a domain-name, a collection
name, or CURRENT, and that identifier must pertain
to a domain that you have already readied.

If you specify FIRST n, n can be any value
expression
that
resolves
an
integer
into
representing the upper bound of the number of
records found in the domain, CURRENT collection, or
collectn-name-3.

If you specify the optional ALL, you obtain
records in the named collection or domain.

If you specify collectn-name-2, you will give the
new collection a name. Be sure the name you assign
does not conflict with a keyword (Table 3-2) or one
of the existing names for a defined record, domain,
or procedure (use SHOW ALL, if necessary to check).

4-20

all

COMMANDS FOR INQUIRY & UPDATE
5.

You may optionally wish to restrict the records
that are collected by specifying the word WITH
followed by a condition. Section 4.5 provides all
the ____rul_elL nac_essary - -to---formulate-- -th-i-s- --B-o-o-l-ean
expression.
(Observe that a variety of compound
Boolean
expressions
are
permitted
for
the
condition, so that you can effectively specify
multiple conditions.)

The sort-keys assume the following form:

~~~![~~~~;!]~
INCREASING

[

field-name-l

DECREASING

Requirements
You must have already performed a successful READY on
the source domain.
Section 4.1 describes the READY
command.
If you specify CURRENT, there must be an established
CURRENT collection, formed by a previous FIND command.
Prompts &
Responses
No prompting messages appear, but you will be informed
how many records met your selection criterion. The
response assumes the following form:
[n RECORD{s) FOUND]
where n is a number representing the number of
found.

records

Effects
1.

The records are collected in the order in which
they are found. You should not infer that there
will be any order to the collection unless you
include the optional SORTED BY clause.

If you specify the FIRST n clause, you obtain a
subset of the collection as the final act after any
restricting and sorting have occurred.

If the number specified for n in the FIRST n clause
exceeds the number of records that can be found,
the maximum will be found.

4-21

COMMANDS FOR INQUIRY & UPDATE
4.

The collection just established by this command
now the CURRENT collection.

If you specify collectn-name-2, it becomes
name of the collection you have created.

the

The collection cursor is left null.

Example
The following example creates a new collection of ten
records named the TEN~BEST-BUYS from· the domain of
YACHTS by restricting them to the sloops longer than 28
feet that weigh at least 7000 pounds and cost up to
$35,000. It then sorts them into increasing sequence by
price and skims off the first ten records.
DTR>FIND FIRST 10 TEN-BEST-BUYS IN YACHTS WITH ~
DTR>RIG=IISLOOP II AND LOA > 28 AND ~
DTR>DISPLACEMENT> 7000 AND PRICE BETWEEN 1 AND~
DTR>35000 SORTED BY INCREASING PRICE;~
[10 RECORDS FOUND]
Hint
If you use an existing collection name, the existing
collection is supplanted by the one being established.

4-22

COMMANDS FOR INQUIRY & UPDATE
4.5

RESTRICTING THE SEARCH WITH RECORD SELECTION EXPRESSIONS

In learning the FIND command in the previous three sections, you
learned about a synt~ctical element called a condition. Conditions
--w-e-re---(fsed-a-s---t-he--s-e-lec-e-ion--c-r-ite-ria- - --to------flrrth-er---de-flnEf a-group -ofrecords.
Conditions may be expressed in terms of value expressions
and Boolean expressions. These are important elements in the larger
structure, the record selection expression. -To acquire the background
to study the full record selection expression, first look at the value
and ~oolean expressions.

4.5.1

Value Expressions

The
value
expression
(value-exp)
provides
an
unambiguous
representation of some combination of items and operators that is
generally evaluated as a numeric value. Later in this chapter you are
going to see how value expressions are used in Boolean expressions, in
the print-list of the PRINT command, in the record number specifier of
the SELECT command, and in the FIRST n clause of the full record
selection expression.
As shown by Table 4-2, the range of items that can be used as value
expressions is quite large. Table 4-2 summarizes these possibilities
and explains them. You should be aware that it is possible to create
compound value expressions that become quite complex. For example,
(A + B)I C * 0_+ 500 is a vaLueexpres$ion~

4-23

Table 4-2
Value Expressions
I

Item Format

Description

Remarks

field-name-l

Contents of this field in the CURRENT
record! are evaluated and used.

Uses CURRENT record l of CURRENT collection, so both must exist and contain a
field with this name.

collectn-name-·l. field-narne-·2

Contents of this field in the CURRENT
record l of the narned collection are
evaluated and used.

Be sure to supply a per iod (.) as a
connector. The field narned must exist
in the records of the named collection.
The collection must be established and
have a CURRENT record l •

"character-string"

The character string is used as given,
unless the context forces it to be
treated as a nurnber2.

Any characters may be used except the
carriage return, line feed, or CTRL Z
(A Z). To include a quotation mark, use
two successive quotation marks.

integer-l

A string of digits interpreted as a
decimal number.

:z:
c::

The resultant value is the negation of
the value of value-exp-l.

- value-exp-l

( value-exp-2 )

value-exp-3

Take care when using character-strings
for value-exp-l: they are changed into
numbers.

Causes the evaluation of the enclosed
value expression to occur prior to
that of any other value expression
with which it appears.
.

{~ } value-exp-4

Interpreted as the arithmetic result
of the operation on the two values expressed by the value expressions.

The rules of precedence for arithmetic
operations hold (unless you use parentheses to force certain operations to
occur first): multiplications (*) and
divisions (I) precede additions (+)
and subtract~~ns (-), working left-toright.

---------------~--------------------------------------------~----------------------------------------------~

(continued on next page)

::0

Table 4-2
(Cant.)
Value Expressions
Item Format
value-exp-5

MIN
MAX
AVERAGE
{ TOTAL

! value-exp-6

value-exp-7 [OF rse]

Remarks

Description
Creates a new character string by combining the two character strings gi.ven
for value-exp-5 and value-exp-6.

Special caution should be used wi~h
numbers. The result maintains a
left-to-right pattern.
For examp~e,
"ABC"!"DEF" produces "ABCDEF",
"12"!"034" produces "12034", but
12!034 produces 1234.

computes 2 your choice of the maximum,
minimum, average, or total, respectively of this value expression for all
records (in the CURRENT collection, by
default).
If the OF clause is used,
then the computation can occur 'on your
choice of the named collection, the
named domain, or the CURRENT c6llection,
and they can be further restricted by
the rest of the expression.

N
(J1

*.prompt-name-l}
{ **.prompt-name-l

Permits the specification of the value
at execution time.
Has special importance in procedures. Prompt-name-l
should be the namE! you want
DATATRIEVE-ll to use to prompt you
to supply a value.

DATATRIEVE-ll prints the message ,
PLEASE SUPPLY VALUE FOR prompt-n~me-l:
and waits for your response befote it
processes the command in which t~is
value expression occurs.
(Exampl;es
occur in Sections 4.11 and 4.13.~.)

COUNT [OF r se]

Computes the nUmbE!r of records in t:he
object of the record selection expression.

The default is the number of rec~rds
in the CURRENT collection.

IThe CURRENT record is the record the collection cursor identifies.
a record by the SELECT command, which is disCUSSE!d in Section 4.6.

The collection cursor can only be mo~ed to

2Value expressions are treated as numbers in the SELECT command, in the' FIRST n clause of the record selec:tion
expression, and when subject to arithmetic operat:ors (+, -, *, and /) or computations for maximum, minimdrn,
total, and average. Thus, these are not appropriate places for the alphanumeric character string.

Z
10

COMMANDS FOR INQUIRY & UPDATE
4.5.2

Boolean Expressions

Boolean expressions describe conditions used to restrict a collection
to records that satisfy these criteria. The Boolean expressions may
be simple (used alone)
or compound
(combined with other Boolean
expressions) .
When they are incorporated in commands, DATATRIEVE
always tests to see whether they are true for a given record. If the
expressions are true, DATATRIEVE performs the command function on the
record. If the expressions are not true, the record is rejected by
the command.
Simple Boolean expressions compare the value of a particular field in
a record aqainst specified values. The comparison is based on certain
"operators" that are shown in the formats summarized in Table 4-3.
Note that some operators are synonymous; choose the one you like the
best.
Compound Boolean expressions combine two or more Boolean expressions
to create a more precise definition of the conditions to apply. The
compound Boolean expressions are given in the second half of Table
4-3.

4-26

Table 4-3
Boolean Expressions
Operator
Sylnbol

Meaning

Format/Example

>
GT
GREATER-THAN

A > B

GE
GREATER-EQUAL

A GE B

<
LT
LESS-THAN

A < B
A LT B

LE
LESS-EQUAL

A LE B

EQ
EQUAL

A EQ B

True if A is greater than B

A GT B
A GREATER-THAN B
True if A is greater than or equal to B

A GREATER-EQUAL B
True if A is

les~

than B

A LESS-THAN B
True if A is less than or equal in value to B

A LESS-EQUAL B
True if A equals B

A EQUAL B
A

EQ B,C, [OR] D
A EQUAL B,C, [OR] D
A = B,C, [OR] D

True if A equals any of the three values, B, C, or D

NOT-EQUAL
NE

A NOT-EQUAL B
A NE B

True if A does not equal B

BT
BETWEEN

A BT B [AND] C
A BETWEEN B [AND] C

True if the value of A falls in between the range of values of B through
C, inclusive

AND

BOOL-A AND BOOL-B"
PRICE>IOOOO AND G!D
BUILDER EQ "SEAWORTHY" G!D

True if the values of the Boolean expressions BOOL-A and BOOL-B are both
true

NOT

NOT BOOL-A
NOT PRICE>IOOOOG!D

True if the value of the Boolean expression BOOL-A is false

BOOL-A OR BOOL-B
MODEL="43K" OR MODEL="49K" G!D

T:r'ue if either of the Boolean expressions BOOL-A or BOOL-B is true

(BOOL-A)
(BEAM<12 AND LOA BT 20 AND 35) G!D

True if BOOL-A is true. The parentheses force the evaluation of thi~
Boolean first. Note that BOOL-A can be a compound Boolean, and this :is a
means of groupi.ng Booleans in case the normal precedence rules* wou14 not
px'oduce the desired effect.

01::00

I
t-.J
-....J

(

)

Z
10
C
H

Note
The character A above represents a field name, while B, C, and Dare va.lue expressions (as described in Section 4.5.1~.
*Normal precedence rules require evaluation of expressions with NOT first, followed by expressions with AND, followed by
expressions with OR.

COMMANDS FOR INQUIRY & UPDATE
4.5.3

Full Record Selection Expressions

The full record selection expression (rse) combines a number of
elements already learned, including value expressions and Boolean
expressions, as well as a sorting clause.
It 1S a very powerful
subexpression in a number of commands and as such will be described in
much the same way the commands are.

4-28

COMMANDS FOR INQUIRY & UPDATE

rse
Purpose
This subexpression specifies a collection of records.
Format

[~~isT nJ [collectn-name-2 IN]r~~~~;~~n-narne-}
(WITH conditn]
ldOmal.n-name-l J
[SORTED BY key-l [, key-2 ••• ]]
1.

You must supply either a domain-name, a collection
name, or CURRENT and your choice must refer to a
source domain that you have already readied.

If you specify FIRST n, n can be any value
expression that yields an integer representing the
upper bound of the number of records desired for
processing.

If you specify ALL, all records in the named domain
or collection will be processed. This is also the
default.

If you specify collectn-name-2, you will create a
The only case where this
new collection name.
collection name is retained, however, is when the
rse occurs in a FIND rse command. When the rse
occurs in a MODIFY or PRINT command, the new
collection name is lost when the command completes.
Be sure the name you assign does not conflict with
a keyword (Table 3-2) or one of the existing names
for a defined record, domain, or procedure
(use
SHOW ALL, if necessary, to check existing names).

You may optionally wish to restrict the records
that are collected by specifying the word WITH
followed by a condition
(Boolean
expression) •
Section 4.5.2 provides all the rules necessary to
formulate this Boolean expression.

If you specify the SORTED clause, the sort occurs
on either the CURRENT collection, the domain, or
collectn-name-3.

The sort-keys assume the following format:

[

~~~!I~~~~~!J]

field-name-l

INCREASING
DECREASING

The number of sort-keys you may
specify
is
unlimited.
If you exceed the system capacity, you
will be notified that the dynamic memory
is
exhausted.

The specification of the word BY is optional, and
is
only
offered to maintain an English-like
structure.

4-29

COMMANDS FOR INQUIRY & UPDATE
10.

Every field-name specified as a sort-key must be
legal for the CURRENT collection. This means the
field must occur in the record definition.

11.

If the specifications of ASCENDING, INCREASING,
DESCENDING, or DECREASING are omitted for the first
sort-key, DATATRIEVE assumes you wish this field
sorted in ASCENDING sequence.

12.

If the sort direction specification is omitted on
subsequent sort-keys, DATATRIEVE assumes you want
the last-specified sorting-direction to prevail.

13.

When more than one field-name is specified, the
collection is sorted so that the first field-name
is treated as the major sort key, and
each
successive key becomes more and more minor.

Requirements
If you specify CURRENT, there must be an established
CURRENT collection.
If you name a collection for
collectn-name-3,
that
named
collection
must be
established.
Prompts &
Responses
No prompting messages appear, unless you
value expression of the form

introduced

*.prompt-name-l
Effects
1.

The collection of records is formed in the order in
which the records are found.
You should not infer
that there will be any order to the collection
unless you include the optional SORTED BY clause.

If you specified the FIRST n clause, you obtain a
subset of the collection as the final act after any
restricting and sorting have occurred.

If the number specified for n in the FIRST n clause
exceeds the number of records that can be processed
to meet the selection criteria, the maximum number

will be chosen:
4.

The collection cursor is left null.

4-30

COMMANDS FOR INQUIRY & UPDATE
5.

If all the elements in
the
expression
are
specified, the sequence of events is as follows:
a.

Restrict the collection according to
clause.

Sort the collection
specifications.

Extract the FIRST n of the results.

Name this
name-2.

collection

per

the

according

the

WITH

SORTED

to collectn-

If a given rse omits any of the clauses, that
particular step disappears, but the progressive
sequence still follows as above.

4-31

COMMANDS FOR INQUIRY & UPDATE
4.6

SELECTING A PARTICULAR RECORD IN A COLLECTION -- SELECT

Once you have established a collection, the ability to manipulate the
collection cursor through the established collection becomes a prime
consideration. The SELECT command provides this capability.

4-32

COMMANDS FOR INQUIRY & UPDATE

SELECT
Purpose

TnIscommarid

specifTe-g

that

yOu

want· a

patticuTar

record made available for your purposes from either the
CURRENT collection or a named collection. You succeed
in moving the collection cursor to a particular point
in the collection. The record you move to becomes the
CURRENT record, and the one immediately after it
becomes the NEXT record. Remember, a record may be the
CURRENT
record
without necessarily being in the
collection that is the CURRENT collection.
Format

FIRST

SELECT

NEXT
LAST
[collectn-name-l]
value-exp-l

You should supply a record number specifier such as
FIRST or LAST. If you omit this specifier, it is
assumed that you wish the NEXT record in the
collection.

The specification for value-exp-l must be a value
expression that produces a positive integer, and it
must not exceed the total number of records in the
collection.
This restriction prohibits the use of
alphabetic character strings
and
necessitates
caution with alphanumeric character strings.

You may optionally wish to use collectn-name-l to
name
a specific collection for the selection
process; otherwise, it is assumed you wish to
reference the CURRENT collection.

Requirements
You must have already established
collection or a CURRENT collection.

either

the

named

Restriction
You should not use the SELECT command in any compound
statements.
Compound statements are created with the
statements in Section 4.13.
Prompts &
Responses
None.
Effects
The effects of the command are highly dependent on the
record number specifier given and the state of the
collection and the position of its cursor at the
outset. Table 4-4 summarizes the different effects.
Notice particularly that any time you attempt a SELECT
on an empty collection, you will get an error message.

4-33

COMMANDS FOR INQUIRY & UPDATE
Because there can be multiple collection cursors,
SELECTing a record from a collection does not make that
collection CURRENT if it was not already so.
Examples
The following example shows two ways to select the very
next record from the CURRENT collection.
DTR) SELECT NEXT; ~

(1)

DTR) SELECT; ~

(2)

In Method (2), the record number specifier was
and NEXT is used by default.

omitted

The following example illustrates how to select just
the first record from the collection of small boats
(less than 26 feet long).
DTR)SELECT FIRST SMALL-BOATS; ~
This example illustrates how to select the twentieth
yacht record in the collection of medium-sized yachts.
DTR)SELECT 20 MEDIUM-YACHTS; ~
This example selects
CURRENT collection.

the

last

yacht

record

the

DTR)SELECT LAST; ~
Hints
It is important to keep track of which collection is
the CURRENT collection in case you want to omit the
collection name in the SELECT command or others.
If
you have any doubts about which collection is current,
you can always issue the SHOW CURRENT command.
(See
Section 4.3.)
When the collection cursor is null, the use of a SELECT
NEXT command is equivalent in effect to a SELECT FIRST.

4-34

COMMANDS FOR INQUIRY & UPDATE
Table 4-4
Effects of the SELECT Command
Specification

Normal Effect

Empty Collection

Cursor at LAST

FIRST

Cursor points
to first member

Cursor is null
(Error)

Gets first member
with no error

Cursor advances
forward one
record

Cursor is
unchanged, error
message is given

LAST

Cursor points
to last member

Cursor is
unchanged

value-exp-l

Cursor moves
to member
numbered
value-exp-l

Gets the
value-exp-l
member, if it
exists, no error

4-35

COMMANDS FOR INQUIRY & UPDATE
4.7

PUTTING RECORDS INTO AN ORDER -- SORT

You will find frequent need to order or reorder collections of
records.
The sorting facility supplied by the SORT command alone or
the SORTED BY clause in other commands gives you this power.
Collections can be sorted into ascending (increasing) or descending
(decreasing) sequence based on the standard ASCII collating sequence.

4-36

COMMANDS FOR INQUIRY & UPDATE

SORT
Purpose
-Thi-s---comm-cfno----gef'fe-r-aTly- - --cnanges

tJi-e

6rd-ei~-

or--- a

collection of records.
You may decide you wish the
collection ordered according to certain key data fields
and each of these fields can be in either ascending or
descending order.
Format
SORT [collection-name-l] BY sort-key-l [, sort-key-2 •.. ]
where each sort-key assumes the following form:

~~~J[:~~~~!~
INCREASING

field-name-l

DECREASING

If you omit a collection-name, it is assumed that
you
want
the sort to occur on the CURRENT
collection.

If you provide a collection-name, it
name of an established collection,

The number of sort-keys you may
specify
is
unlimited.
If you exceed the system capacity, you
will be notified that the dynamic memory
is
exhausted.

The specification of the word BY is optional, and
is
only
offered to maintain an English-like
structure.

Every field-name specified must be legal for the
collection being processed.
This means it must
occur in the record definition.

If the specifications of ASCENDING, INCREASING,
DESCENDING, or DECREASING are omitted for the first
sort-key, DATATRIEVE assumes you want this field
sorted in ASCENDING sequence.

If the sort direction specification is omitted on
subsequent sort-keys, DATATRIEVE assumes you want
the last-specified sorting-direction to prevail.

When more than one field-name is specified, the
collection is sorted so that the first field-name
is treated as the major sort key, and
each
successive key becomes more and more minor.

must

the

Requirements
You must have already performed a
this
collection.
Section 4.4
command.

4-37

successful FIND on
describes the FIND

COMMANDS FOR INQUIRY & UPDATE
Prompts &
Responses
None.
Effects
1.

The records in the collection are sorted
order specified or implied.

into

the

The collection cursor is null at the conclusion
this command.

Any remaining pointers to
records
previously
removed by an ERASE command
(Section 4.10) are
permanently erased.

Examples
The following example sorts all the yacht records in
the 26-foot yacht collection into alphabetical order
based on the manufacturer name first and then on the
model number.
DTR>SORT YACHTS-26 BY ASC MANUFACTURER, MODEL; ~
The following example illustrates how to sort the
records in the CURRENT collection into order according
to the yachts having the highest price.
DTR>SORT BY DESCENDING

PRICEi~

Hints
If you encounter a problem in sorting, most likely it
will be in exceeding the memory space. If this should
happen, you may want to consider any or all of the
following approaches:
1.

FINISH any domains you can (Section 4.12.2).

RELEASE any collections
4.12.1) •

READY domains that were readied for WRITE or MODIFY
access to permit read-only access since this mode
uses less buffer space (Section 4.1).

4-38

you

won't

need

(Section

COMMANDS FOR INQUIRY & UPDATE
4.8

LOOKING AT THE RECORD CONTENTS -- PRINT

By this time, the beginning user who used a terminal to practice the
preceejingc0Inmands is probably _frustrated by being unai:>le _to "l()()k at
l

;

-tl'fEf- -r-e-sUTt-s- --6f--th-e-- tornIrf~fiias--e-nfer-ed- ~ -- -The-----PlflNT---cornm~ilid

display certain parts of the collections.

4-39

---pe-r-mIFs --you--- -i <>

COMMANDS FOR INQUIRY & UPDATE

PRINT
4.8.1

Listing Record Contents

Purpose
This command provides a printout of
the
record
contents. You may request to see one or more fields in
either a single record or a complete collection of
records.
Since these printouts can be formatted to a
certain extent, they are quite sufficient for informal
purposes.
However, you may want to consider the
capabilities of the Report writer for more elaborately
formatted printouts. See Chapter 5 for a discussion of
the Report Writer.
Format
PRINT [ALL] [print-list-l]

[OF rse]

[ON

(file-spec-l
l*·prompt-name-l

where the record-selection-expression (rse) assumes the
following form:

[~ST nJ [collectn-name-2 W~~~~;~~n-name-~[WITB
conditn]
~omaln-name-l )
[SORTED BY key-l [, key-2 .•. ]]
If necessary, review the descriptions
selection expressions in Section 4.5.3.

record

If you specify ALL before the print-list, you will
obtain a printout of all the records in the group
you designate.

If you omit ALL, the printout will include only the
items desisnated for the CURRENT record of the
designated group.

The optional print-list can specify names, value
expressions, literals, and horizontal and vertical
spacing characters. The
print-list
assumes the
form of any combination of the optional elements
shown in Table 4-5.
Print-list
elements are
separated by commas.
Note that "n" (as shown in
the table) represents a decimal integer of your
selection. For more details see Section 4.8.2.

The optional OF rse clause refers to the same
record selection expression seen in Section 4.5.3.
This powerful expression lets you print records
from named collections rather than restricting you
to the CURRENT collection and permits sorting them,
refining them, and/or even subsetting them -- all
in one command. If the OF rse clause is used, it
completely overrides the specification of ALL.

If you specify the optional ON file-spec-l clause,
file-spec-l must be the name of a file or device
specification. If you omit the file specification,

4-40

COMMANDS FOR INQUIRY & UPDATE
the printout appears on your terminal device. Note
your
other
alternative
is
to
use
the
value expression
*.prompt-name
(described
in
~ection4.5.+) . to prompt a later entry of a file or
dev-ice--specIffca-Ei6ri .~. 6.

Note that all the command elements after the
command name PRINT are apparently optional. It is
fine to specify only the word PRINT if the CURRENT
collection has a CURRENT record; you will get the
printout for that one record. However, if there is
no CURRENT record in the CURRENT collection and if
you omit all the optional command elements, you
will obtain an error message and a printout of
every field in every record in the CURRENT record
collection.
Again, be warned that
elements, if specified,
sequence shown.

all
must

optional
be given

command
in the

Requirements
The collection cursor must not be null or else you must
request ALL.
Prompts &
Responses
No prompting messages appear.
Effects
1.

The printout will conform to the examples provided
in Figure 4-1.
Note that the default calumn
headers consist of the field-names as specified in
the record definition.

The output of the command is directed to the
terminal device, unless you provide an alternate
file specification with the ON file-spec-l clause.

The values of the
appropriate columns.

The collection cursor is left unchanged.

fields

are

printed

the

Examples
More examples occur in Figure 4-2.
Hints
You may wish to use the CTRL 0 (nO)
character
combination to halt a lengthy printout that you realize
is in error or should not have started at this time.
If a printout is moving over your video terminal screen
faster than you can read it, you may want to use the
CTRL S (nS) to cause a temporary interruption and the
CTRL Q (nQ) to resume. However, a better choice may be
to direct the printout to another file for hard copy
review.

4-41

COMMANDS FOR INQUIRY & UPDATE
You may abbreviate the PRINT command in just two
possible ways. You can eliminate the words ALL and OF
when you have no print-list, want ALL records, and want
to specify either a domain name or FIRST n. Thus, the
following exceptions to the syntax above will be
accepted:
DTR>PRINT FIRST 5 MEDIUM-YACHTS WITH PRICE> 5000; ~
DTR>PRINT YACHTS WITH PRICE<lOOOOO SORTED BY DESC PRICE; ~

4-42

Table 4-·5
Print-list Elements
Element

Default

Function

field-name-l [modifiers]

Specifies a class of data
items to be printed
from the record.
Modifiers are
explained below.

All the fields
in the record

value-exp-l [modifiers]

A value to be inserted. (See Section
4.,5.1.)
Modifiers
are explained below.

None

Causes n horizontal
spaces between entries
on each line.

1 space

SPACE

TAB

en]

COL n

SKIP

en]

t-t

Introduces as many
tab characters into the
print line as specified by n.

If n is omitted, a
single tab is assum~d

Advances across the
horizontal line to column n. Note: n must
not be less than 1 or
more than the page
width. If n is less
than present column, a
line is skipped.

None

Maves n blank lines
ahead to start a new
line. Printing starts in
column 1, unless another
element modifies the
posItion further.

Single spacing

(continued on next page)

Z
10
C
t-t

Table 4-5
(Cont.)
Print-list Elements
~--------------------.------------------------------------------------------------------------------------,

Function

Element

Default

~.-----------------------------------,------------------------------------.-------.--------------------~

NEW--PAGE

Begins a new print
page. Printing starts in
column 1, unless another
element modifies the
posltion further.

None

~-----------------------------------~------------------------------------~------.--------------------~

("header-l" [Ilheader-2" ...

USING edit-string

Specifies a characterstring (Section 3.8)
to be printed on
successive lines over
the immediately preceding
field-name or value-expression.
Specification of a
hyphen for the header
indicates no header is
desired.

Headers are composed
of the field-name
definitions from the
record definitions

Imposes the characteristics of this editstring on the preceding
field or value expression.
Edit-strings must observe
COBOL rules (Appendix E).

Uses the edit-string in
the record definition, if
any. Otherwise considers the field's PICTURE
string.

NOTE
DATATRIEVE-ll restricts the column
width
to
132
characters.
It
automatically sets tabs at every eighth column.
Thus,
if the print
position is column 10 and DATATRIEVE encounters a TAB 2 specification, the
new position will be column 24.
~.-------,---------------------------------------------------------------------------.----------------------~

COMMANDS FOR INQUIRY & UPDATE
4.8.2

Formatting the Printout

In the description of the PRINT command you

learned

that

you

could

_speci£¥__ __ a_print~-lis-t-"-----Tab-l-e----4,.,,. 5 -suromar-i-z-e-s----t-he-pos-s-i-b-le--e-l-eme-n-ts---you-

may choose for your print list. These elements may be mixed in many
combinations.
All are optional.
Sometimes DATATRIEVE assumes a
default value when you omit an element in the print list. Print-lists
are processed in left-to-right order.
Figure 4-2 provides some examples of the PRINT command and the
printouts that were produced from them.

actual

DTR>!SET UP FOR A DEMONSTRATION OF VARIOUS FORMS OF THE PRINT COMMAND
DTR>READY YACHTS SHARED READ;
DTR>FIND YACHTS WITH RIG=-SLOOP- AND PRICE>20000 SORTED BY LOA;
[8 RECORDS FOUNDJ
DTR>SELECT 4;
DTR>!

DTR>!****************************************
DTR>!PRINT ALL THE FIELDS OF JUST THE 4TH RECORD OF THE CURRENT COLLECTION
DTR> ! OF SLOOPS F'RICED OVER $20,000
DTR>!(IT/S THE SELECTED RECORD)
DTR> !
DTR>PRINT
LENGTH
OVER
MANUFACTURER
MODEL
RIG
ALL
WEIGHT BEAM
BAYFIELD

30/32

SLOOP

PRICE

DTR>!****************************************

DTR>!THE NEXT 3 EXAMPLES JUST PRINT THE VALUE EXPRESSIONS IN THEIR PRINT-LISTS
DTR>!
DTR>PRINT -DATATRIEVE-l1 MAKES-,- REPORT WRITING -,-EASYDATATRIEVE-ll MAKES REPORT WRITING EASY
DTR>PRINT -2 + 2 = 52 +2 =5

IITR>PRINT 2+2
4

DTR>!****************************************
DTR>!PRINT THE MANUFACTURER AND MODEL FIELDS OF ALL THE RECORDS IN THE CURRENT
DTR>!COLLECTION
DTR>!
DTR)PRINT ALL COL 10,MANUFACTURER,COL 30,MODEL;
MANUFACTURER

MODEL

CAPE DORY
SABRE
RYDER
BAYFIELD
CHALLENGER
CARIBBEAN
CHALLENGER
CHRIS-CRAF

28
28
S. CROSS

Figure 4-2

30/32

32
35
35
CARIBBEAN

Sample PRINT Command Output

4-45

COMMANDS FOR INQUIRY & UPDATE
DTR> !****************************************
DTR> !PRINT ALL FIELDS OF ALL KETCHES PRICED OVER $30,000,
DTR> !SORTED BY LENGTH
DTR) !
DTR>PRINT YACHTS WITH RIG = -KETCH- AND PRICE> 30000 SORTED BY LOA

MANUFACTURER
I. TRADER
ALBERG
IRWIN

MODEL

RIG

37
KETCH
37 MK II
KETCH
37 MARK II KETCH

LENGTH
OVER
ALL
WEIGHT BEAM

PRICE

12
12
11

$39,500
.36,951
.36,950

36
37
37

18,600
20,000
20,000

!****************************************

DTR>
DTR> !PRINT ALL FIELDS OF ALL RECORDS IN THE DOMAIN OF YACHTS
DTR> I
DTR> F'RINT YACHTS

MANUFACTURER

MODEL

ALBERG
ALBIN
ALBIN
AMERICAN
AMERICAN
BAYFIELD
CAPE DORY
CAPE DORY
CAPE DORY
CARIBBEAN
CHALLENGER
CHALLENGER
CHRIS-CRAF
CLIPPER
CLIPPER
EASTWARD
GRAMPIAN
GRAMPIAN
GRAMPIAN
HUNTER
I. TRADER
IRWIN
IRWIN
ISLANDER
ISLANDER
LINDSEY
RYDER
SABRE
SALT
TANZER
TANZER
VENTURE
VENTURE
WESTERLY

37 MK II
79

RIG

KETCH
SLOOP
VEGA
SLOOP
SLOOP
26
26-MS
MIS
SLOOP
30/32
SLOOP
28
SLOOP
TYPHOON
SLOOP
25
35
SLOOP
SLOOP
32
SLOOP
35
CARIBBEAN SLOOP
CM 30
SLOOP
SLOOP
CM 32
HO
MIS
SLOOP
26
SLOOP
28
34
KETCH
27
SLOOP
37
KETCH
37 MARK II KETCH
SLOOP
25
SLOOP
28
SLOOP
BAHAMA
39
MIS
S. CROSS
SLOOP
SLOOP
28
19
SLOOP
SLOOP
26
28
21
222

CENTAUR

1"'\1

LENGTH
OVER
ALL
WEIGHT BEAM
37
26
27
26
26
32
28
19
25
35
32
35
35
30
32
24

26
28
33
27
36
37
25
28
24
39
31
28
25

rt.,." ....

;:)L..uur

SLOOP
SLOOP
SLOOP

22
26

Figure 4-2 (Cont.)

12
10
08
08
08
10
09
06
07
11
11
12
11
08
08
09
08
10
10
09
12
11
12
10
08
12
00
09
07
09

PRICE
.36,951
.17,900
$18,600
.9,895
.18,895
$32,875
.21,990
'4,295
'8,995
$37,850
.31,835
.39,215
,37,850
'9,500
.12,950
.15,900
'11,495
.14,475
.29,675
.14,999
.39,500
.36,950
.10,950
.15,908
.6,500
.35,900
.32,500
.22,000
.6,590
.11,750

.LV

07
07
08

.2,823
.3,564
.15,245

Sample PRINT Command Output

4-46

COMMANDS FOR INQUIRY & UPDATE
DTR>!*************************************************
DTR>!PRINT ALL THE FIELDS OF THE FIRST 3 RECORDS IN THE GROUP OF YACHTS THAT ARE
DTR>!SHORTER THAN 26 FT.
DTR>,

DTR;:'fi>RlitTFTRST 3 SMALL""l'A-cKTS -n·r YA-CHTS WITH LOA -::: 26

MANUFACTURER

MODEL

RIG

LENGTH
OVER
ALL
WEIGHT BEAM

CAPE DORY
CAPE DORY
EASTWARD

TYPHOON
25
HO

SLOOP
SLOOP
MIS

19
25
24

1,900
4,000
7,000

PRICE
$4,295
$8,995
$15,900

06
07
09

DTR> !*************************************************
DTR>!PRINT JUST THE PRICE FOR THE SAME GROUP BUT EDIT IT DIFFERENTLY
DTR> !
DTR>PRINT PRICE USING $ZZ,ZZZ.OO OF FIRST 3 SMALL-YACHTS IN YACHTS WITH LOA -::: 26~
PRICE
$ 4,295.00
$ 8,995.00
$15,900.00
DTR> !*************************************************
DTR) !PRINT THE CURRENTLY SELECTED RECORD IN THE CURRENT COLLECTION
DTR) I
DTR) PRINT

MANUFACTURER
BAYFIELD

MODEL
30/32

RIG

LENGTH
OVER
ALL
WEIGHT BEAM

SLOOP

PRICE

DTR) !WERE YOU SURPRISED? NONE OF THE PRINT COMMANDS HAVE REALLY ESTABLISHED
DTR> !COLLECTIONS OR SELECTED ANY RECORDS, SO THE CURRENT RECORD IS STILL THE 4TH
DTR) !RECORD IN THE COLLECTION OF SLOOPS FORMED BY THE VERY FIRST 3 COMMANDS
DrR> !*************************************************
DTR) !PRINT THE PRICE, MANUFACTURER AND MODEL OF YACHTS COSTING OVER
DTR) !$35,000. DOUBLE SPACE THE PRINTOUT. ~START IN COLUMN 16, GIVING
DTR) !THE PRICE FIELD THE HEADING "IT'S ONLY MONEY". PRICE WILL BE
DTR) !ZERO SUPPRESSED, BUT NO DOLLAR SIGN IS DESIRED.
DTR> !
DTR> PRINT SKIP 2,TAB 2,PRICEC"IT'S ONLY"I-MONEY") USING DTR>ZZ,ZZZ, COL 34,MANUFACTURER,MODEL OF YACHTS WITH DTR) PR J: CE>35000;
IT'S ONLY
MONEY

MANUFACTURER

36,951

ALBERG

37 MK II

37,850

CARIBBEAN

39,215

CHALLENGER

Figure 4-2 (Cont. )

MODEL

Sample PRINT Command Output

4-47

COMMANDS FOR INQUIRY & UPDATE
4.9

CHANGING RECORD CONTENTS IN THE FILES -- MODIFY

One of the most powerful capabilities of DATATRIEVE is the ability to
change the data as it exists in the RMS-ll files. with all the
commands previously described, all actions occurred on copies of
portions of the files. At no time were you able to affect the file
itself. However, with the MODIFY command, you will be able to change
data values in specific records. Certain safeguards are, however,
inherent in the system. For example, you will only be able to use the
MODIFY command on domains you successfully readied in WRITE or MODIFY
mode.
(See Section 4.l.)

4-48

COMMANDS FOR INQUIRY & UPDATE

MODIFY
Purpose
This command can change from one to all the data fields
in:
•

any given record or

•

all the records in a collection.

Format
MODIFY [ALL]

[fld-name-l [, fld-name-2 • •• ]]

[OF rse]

where the record selection expression (rse) assumes the
form:

~T nJ [collectn-name-2 rnI;;~~~;~~n-name-~
[WITH conditn]
ldoma1n-name-l :;
[SORTED BY key-l [, key-2

If necessary,
review
selection expressions
(Section 4.7).

oJ]

of
record
the descriptions
and sort-keys
(Section 4.5.3)

If you specify ALL before fld-name-l,
then the
changes you request will be made to every record in
the group you designate.
If you omit ALL before
fld-name-l,
then your changes will be made only to
the CURRENT record in either the named or CURRENT
collection.

If you supply a field name, it must name a field
that belongs to the record type associated with
either the CURRENT or named collection.

If you omit the field names, DATATRIEVE will prompt
you to specify a change value for every field in
the record.

Requirements
You must have already performed a successful READY on
the source domain for the records, and it must be
readied for WRITE or MODIFY access.
Section 4.1
describes the READY command.
Unless you are specifying ALL, the collection cursor
must not be null;
it must point to a record as the
result of a successful SELECT command.
Section 4.6
describes the SELECT command.
Restriction
You cannot modify the primary key field in any
sequential record.

4-49

indexed

COMMANDS FOR INQUIRY & UPDATE
Prompts &
Responses
Once your command has been accepted, DATATRIEVE prompts
you with a request to specify the new value for each of
the field names.
If all field names are being changed,
then they will be requested in the order of the record
definition.
DATATRIEVE prompts with the message
PLEASE SUPPLY VALUE FOR field-name:
It then waits for you to enter a value after the colon.
Note that DATATRIEVE prompts for each elementary data
item in the field names you supplied, or issues all the
field names one-by-one.
If at any time in the prompting cycle, you want to
escape, you can enter a CTRL Z (~Z). This aborts the
MODIFY command, and prints the message
EXECUTION TERMINATED BY OPERATOR
Effects
1.

In both the collection and the RMS-ll file each
field name specified is changed to the new value
supplied.

The collection cursor is left unchanged.

Additional effects may occur as prescribed by the
record selection expression.
(See Section 4.5).

Example
The following example changes two fields in the four
records in the collection of yachts built by Seaworthy.
DTR>MODIFY ALL DISP, PRICE OF SEAWORTHY-YACHTS; ~
PLEASE SUPPLY VALUE FOR DISP:

5500 LR~

PLEASE SUPPLY VALUE FOR PRICE:

22500 ~

Hints
The values supplied should correspond to the data
characteristics established for the field in the record
definition. For example, the field length of' the new
value should not exceed the defined length. Explicit
checking is not performed, but certain violations will
be recognized if DATATRIEVE uncovers an incompatibility
while moving the new data into the area reserved for
the old data.
You will not be permitted to skip over a data item by
responding with just a carriage return (~). If you
do, you will be prompted again to supply the same
field.
However, you can leave a data item empty or
zero-valued by entering a single space before the
carriage return.

4-50

COMMANDS FOR INQUIRY & UPDATE
4.10

REMOVING ONE OR MORE RECORDS -- ERASE

During routine operations, it is not uncommon to determine that one or
~gr~ __ Z;~~Q_Z;_Q_~ ___~_ Z;~!:qy~J.iq.9_~h_~Y_§_ 9JJtliy~_cl tJLeJI!.lS_~_fJ.lln_EtS_S ands_hould
be removed from a file. This sort of file maintenance function is
generally performed by a program at the installation. However,
DATATRIEVE-ll offers the ability to perform "simple" removals of
certain records. However, the word "simple" is critical here. When a
record is removed by DATATRIEVE, there is no audit trail left.
Because no historical details from the record are retained, serious
accounting problems can result if ERASE is used indiscriminately.
This is one reason why the use of passwords and access modes is so
important. However, abuses can still occur at the hands of qualified
users. Hopefully, when you use the ERASE command, you will do so with
the proper amount of caution and respect for the data integrity.

4-51

COMMANDS FOR INQUIRY & UPDATE

ERASE
Purpose
This command removes
files.

one

records

from

the

Format
ERASE

[ALL

[Qr rse]]

where the record-select ion-express ion (rse) assumes the
following form:

[~i~ST nJ [collectn-name-2 IN]{;~~~~~~n-name-;t
[WITH condi tn]
domaln-name-l )
[SORTED BY key-l [, key-2 ... ]]
If necessary, review
selection expressions
(Sec t ion 4. 7) •
1.

of
record
the descriptions
(Section 4.5.3) and sort-keys

If you supply a record selection expression, it
must refer to a collection in a source domain that
you have already readied in WRITE access mode.

Requirements
You must have already peformed a successful READY on
the source domain for WRITE access.
Section 4.1
describes the READY command.
Restriction
You cannot erase sequential RMS-ll records.
Prompts &
Responses
None.
Effects
1.

If you omit the optional elements, you will erase
only the CURRENT record of the CURRENT collection,
if any.

If you specify only ALL, you will
member of the CURRENT collection.

erase

every

If you specify the optional rse, you will
every record of the collection you identify.

erase

The collection cursor becomes null.

Examples
The following example illustrates how you
all records in the CURRENT collection.
DTR> ERASE ALL; ( Rr:T )

4-52

could

erase

COMMANDS FOR INQUIRY & UPDATE
The next example illustrates how you could erase
the CURRENT record in the CURRENT collection.

just

DTR)ERASE; ~
The last example illustrates how to erase
records in the named collection SMALL-BOATS.

all

the

DTR)ERASE ALL OF SMALL-BOATS; (~T)
Hints
You must know which is the CURRENT collection and which
is the CURRENT record before you attempt any ERASE
command. If in doubt, use the SHOW CURRENT command
(Section 4.3) and/or the PRINT command (Section 4.8) to
ensure that you know what you will be erasing.
If you request a printout that includes erased records,
DATATRIEVE omits the deleted records. However; if you
SELECT a record that has been erased, DATATRIEVE
notifies you that the record has been removed. This
notification is possible since a record pointer remains
after the deletion occurs.
It is only through the SORT command or SORTED BY clause
(Sections 4.7 and 4.4, respectively) that pointers to
records previously erased are removed.

4-53

COMMANDS FOR INQUIRY & UPDATE
4.11

ADDING A NEW RECORD TO THE FILE -- STORE

Certain qualified users ~ay be permitted to add new records to
existing files.
This 1S a common file maintenance function in any
installation, but there are
some
advantages
(with
attendant
disadvantages) to using DATATRIEVE for this function. The DATATRIEVE
user can rapidly add a record and supply data for the fields, avoiding
the need to use a special file maintenance program. However, opening
records with DATATRIEVE includes the risk that correct procedures may
not be followed. Furthermore, data will not be subjected to extensive
edits and logical crosschecks such as a specialized program could
impose.
For example, if it is known that sailboats can only have
lengths between 8 and 70 feet, you would logically assume an error has
been
made
if
someone
specifies 2 or 99- feet for the LOA
(length-over-all field). This is the sort of checking a specialized
program could do that the more casual DATATRIEVE user could omit.
Likewise, suppose management has recently dictated that no more boats
manufactured by SMITT-JONES should be accepted. Now, even if the
maintenance program has been updated to include a test for this
prohibition, the unwitting DATATRIEVE user could insert new records
and undermine the policy decision.
Using DATATRIEVE to add records to files is the quick and dirty
method, in every sense of the expression. Please be aware of the
potential problems that this feature can cause.

4-54

COMMANDS FOR INQUIRY & UPDATE

STORE
Purpose
Tln:s -c-oIlimarra- -c-t-efcftes---a:---fl"ew----t-ec-o-ra- 1. nthe aomatn y-ou
specify.
DATATRIEVE accepts your specification of the
fields you want to enter or prompts you to specify data
for each field defined for the record.
Format
STORE domain-name-l [USING statement-I] [VERIFY USING statement-2]
1.

You must supply a domain-name, and it must name a
domain you have already readied for WRITE or EXTEND
access (Section 4.1).

If you want to provide a statement for statement-I,
in general it will assume the following form:
BEGIN fld-name-l = value-l
[ifld-name-2 = value-2 ••• ]
iEND
where its keyword USING, if specified, must be on
the same line as the keyword STORE; the remaining
elements, separated by semicolons, may be on one or
more
successive
lines.
Follow
the
usual
conventions regarding hyphens and carriage returns
for line continuations. You may want to read about
the BEGIN-END Block and assignment statements that
are described in Section 4.13.

If you specify a VERIFY clause, no data is stored
until the conditions of statement-2 are comoleted.
Thus, this provides an opportunity to ensure that
data is correct before it becomes part of the file.

The optional
word
USING
is
permitted
for
English-like usage, but serves no other purpose.

Requirements
You must have already performed a successful READY on
this domain for either WRITE or EXTEND access. Section
4.1 describes the READY command.
Restriction
You cannot
files.

STORE

new

records

into

RMS-ll

relative

Prompts &
Responses
Unless you specify a statement g1.v1.ng field-names and
desired values, you will be prompted to supply data for
each of the defined fields in the record.
The
prompting message assumes the following form:
PLEASE SUPPLY VALUE FOR field-name:
where DATATRIEVE replaces "field-name" in

4-55

the

message

COMMANDS FOR INQUIRY & UPDATE
with the name of the field being sought. DATATRIEVE
waits for your response, and if accepted, proceeds to
the next sequential field in the record definition,
until all fields have been filled.
Effects
1.

The fields are added to the record "in the order in
which they are provided. If any piece of data is
inappropriate for its definiton, assumptions are
made or error messages issued, and the command
continues on to the next defined field.
If a
numeric field was oversize and contained numeric
data, the high-order digits were truncated and an
error message issued.
If an alphanumeric field
contained
excessive
string
data,
truncation
occurred without an error message.

The collection cursor remains unchanged. The newly
added record is not in any collection. If you want
to print this record, you must first establish a
collection that contains it, and then select it.

Examples
The following example stores a new yacht record in the
domain YACHTS.
Observe that this choice of format
causes DATATRIEVE to prompt you for the data items.
DTR>STORE YACHTS i ~
PLEASE SUPPLY VALUE FOR MANUFACTURER: DONOVAN ~
PLEASE SUPPLY VALUE FOR MODEL: 34LK~
PLEASE SUPPLY VALUE FOR RIG: SLOOP ~
PLEASE SUPPLY VALUE FOR LENGTH-OVER-ALL: 34~
PLEASE SUPPLY VALUE FOR DISPLACEMENT: 4000 (RET)
PLEASE SUPPLY VALUE FOR BEAM: 12 ~
PLEASE SUPPLY VALUE FOR PRICE: 32000 ~
If you had merely wanted to open a new record with only
the manufacturer, model, and type of rig for the data
items, you could have done the following:
DTR>STORE YACHTS BEGIN~
DTR>MANUFACTURER="DONOVAN"i
DTR>RIG="SLOOP" i END; ~

MODEL=1l34LK"i ~

The next example first obtains data for a ll~W yacht
record, and then performs a series of IF statements
(Section 4.13.5) to test for undesirable data values.
If any are found, the STORE function does not occur.
If the record passes these tests, the record is printed
and the user is given the opportunity to review and
approve it in its entirety prior to storing it.

4-56

COMMANDS FOR INQUIRY & UPDATE
DTR)STORE YACHTS VERIFY USING ~
DTR) BEGIN~
DTR)
IF BEAM EQ 0 THEN ABORT "BAD BEAM" ~
DTR)
IF DISP EQ 0 THEN ABORT "BAD DISPLACEMENT" ~
UTR)
rp- --N-oT--LOl1--SETWREN -2-0 ----AND---G--Q-TttEN-AOORT-( -RET J
DTR)
IIBAD LENGTH" ~
DTR)
PRINT~
DTR)
DISPLAY "CONFIRM WITH Y IF OK" ~
DTR)
IF *. CONFIRMATION NE "y" THEN ~ ABORT "STORE ABORTED" ~
DTR)
DTR)END~

In this case, because the PRINT command occurs within
the VERIFY operation, the record of interest (which is
not the CURRENT one), is the one displayed.
Hints
If you do not use the VERIFY option, make a practice of
printing out each new record upon completion of a
successful STORE command. This way, you may detect
incorrect or omitted data items. Corrections can be
made by using the MODIFY command
(Section 4.9), once
you have selected (Section 4.6) the new record.
As in the MODIFY command, explicit checking is not
performed, but certain violations will be recognized if
DATATRIEVE uncovers an incompatibility while moving new
data into its reserved area.
When in full prompt mode, you will not be permitted to
skip over a data item by responding with just a
carriage return
(~).
If you do, you will be
prompted again to supply the same field.
However, you
can leave a data item emotv or zero-valued by entering
a single space before the carriage return.
A final hint is to consider the use of the REPEAT
statement
(Section 4.13.3)
in conjunction with the
STORE command whenever you must create a series of
records in a given session. For example, observe how
the following combination of the two commands saves
operator input time:
DTR)-REPEAT 3 STORE YACHTS BEGIN ~
DTR).MANUFACTURER=" DONOVAN"; ~
DTR)-MODEL=* .MODELNAME; ~
DTR)-RIG="SLOOP"; ~
DTR)'END; ~
35LK~
PLEASE SUPPLY VALUE FOR MODELNAME:
36LK~
PLEASE SUPPLY VALUE FOR MODELNAME:
PLEASE SUPPLY VALUE FOR MODELNAME:
37LK~
DTR)
In the example above, you created three new records,
having three fields with nonzero or nonblank values.
Two of the fields were common to all three records;
therefore, with the use of the REPEAT statement and the
value expression of the form *.prompt-name, you created
a situation where the only data input was for the field
that varied from record to record.
Had ten or more
records been involved, the savings would seem even more
significant.

4-57

COMMANDS FOR INQUIRY & UPDATE
4.12

SOME SPACE CONSIDERATIONS

Since DATATRIEVE keeps control information and record buffers for
active collections in memory,
it is important to keep the memory
overhead as low as possible. Two commands facilitate this:
RELEASE
and FINISH.
Invoke RELEASE whenever you are sure you have finished
using a named collection.
FINISH serves a similar function for
domains.

4-58

COMMANDS FOR INQUIRY & UPDATE

RELEASE
4.12.1

When You're Done with a Collection -- RELEASE

Purpose
This command effectively removes a named collection
from the system to free space for other uses. Note
that it is the collection kept in temporary storage
that is lost, but the records and domains from which it
originated are unaffected. If necessary, the released
collection can always be reestablished later.
Format
RELEASE collectn-name-l [,collectn-name-2 •.• ]
1.

You must supply at least one legitimate collection
name.
CURRENT is a legitimate collection name for
an unnamed collection, if it is the CURRENT one.

You may optionally wish
to
name
additional
collections for release. The collections need not
be formed from the same source domain.

Requirements
There should be one or more named collections
domains.

your

which

Prompts &
Responses
None.
Effects
1.

The collections are removed in the order
they are named in the command.

If the command fails while looking for subsequent
collections, you will find that the collections up
to the problem collection have been lost. However,
the
problem
collection
and
any
following
collections have not been touched.

Examples
The following
collection.

example

releases

the

SMALL-BOATS

DTR)RELEASE SMALL-BOATS; ~ The following example illustrates how to release
collections:

three

DTR)RELEASE SMALL-BOATS,MEDIUM-YACHTS,LARGE-YACHTS; ~

4-59

COMMANDS FOR INQUIRY & UPDATE
Hints
Cultivate the habit of releasing collections as soon as
you know you have finished with them.
Note that an
automatically
command.

unnamed CURRENT collection is always
released by the next successful FIND

The FINISH command
(Section 4.12.2) RELEASEs
all
collections belonging to the domains it operates on.
Thus, it is redundant to specify a RELEASE command
followed by a FINISH command involving the same domain.
Likewise, if you intend to EXIT immediately after this
RELEASE command, it is unnecessary to use the RELEASE
command. EXIT performs the RELEASE function for you.

4-60

COMMANDS FOR INQUIRY & UPDATE

FINISH
4.12.2

When You1re Done with a Domain -- FINISH

Purpose
This command deactivates one or more domains to free
space and/or to permit other users to gain access. You
do not remove the domain or its records, you merely
relinquish any previous claims to it made through an
earlier READY command in this session.
Format
FINISH [domain-name-l [,domain-name-2 ... ll

If you do not specify any domain
READY domains are deactivated.

names,

all

your

Requirements
None.
Prompts &
'CoC!T"\l"\nC!oC!

~'\.,-,...,.t'''''01.''''''''-''''''

None.
Effects

The named domains that were READY are deactivated
so that they are no longer READY and cannot be the
subject of any FIND commands.

If you name a domain that never
receive an error notification.

was

READY,

you

Any collections that existed
RELEASEd.

the

domain

are

for

Examples
The following example finishes the domain YACHTS.
DTR) FINISH YACHTS i ~
The following example illustrates
ready domains.

how

finish

all

DTR)FINISHi ~
Hints
If you accidentally FINISH a domain you want READY, you
can simply READY it again.
If you intend to EXIT immediately after this FINISH
command, it is unnecessary to use the FINISH command.
EXIT performs a FINISH for you.

4-61

COMMANDS FOR INQUIRY & UPDATE
4.13

COMBINING DATATRIEVE-ll COMMANDS

There are a few additional statements you can learn that will permit
you to combine DATATRIEVE-ll commands in powerful ways.
These
capabilities may have more significance to the designers of procedures
(Chapter 6), but are available to all DATATRIEVE-ll users. They are
therefore brought to your attention.
These statements employ some elements you have already learned:
the
record selection expression and the simple forms of the FIND, SORT,
MODIFY and PRINT commands. The statements will be explained first and
then some examples of how to combine them effectively will be given.
You have actually already seen three of these, the BEGIN-END Block,
the
assignment
statement,
and
the REPEAT statement, all in
explanations of the STORE command; but they will be introduced more
formally now.

4-62

COMMANDS FOR INQUIRY & UPDATE

BEGIN-END Block
4.13.1

BEGIN-END Block

Purpose
This statement groups the enclosed statements into a
single compound statement. This facility is employed
in the STORE command (Section 4.11).
Format
BEGIN statement-1
1.

statement-2 •.• ]

You must supply at least one
(Section 4.13.2).

END

assignment

statement

Requirements
Conform to the requirements of the STORE and assignment
statements.
Section 4.11 describes the STORE command.
Section 4.13.2 describes the assignment statement.
Prompts &
Responses
None.

Effect
1.

The statements
entered.

are

executed

the

sequence

Examples
The following example shows the use of a BEGIN-END
Block with the STORE command. The effect will be to
store a new record in the domain YACHTS for a 24-foot
yacht built by Dufour with a model number of 24.
DTR> STORE YACHTS US ING ~
DTR> BEGIN ~
DTR>
BUILDER=IIDUFOUR" GJ
DTR>
MODEL=1I24" ~
DTR>
LOA=24i ~
DTR>ENDi ~

4-63

COMMANDS FOR INQUIRY & UPDATE

Assignment Statement
4.13.2

Assignment Statement

Purpose
The assignment statement provides an alternative method
of establishing field values in the STORE command. The
value is supplied by the statement itself, either
explicitly or by reference to another field name. This
differs from the technique of the MODIFY command
(Section 4.9) since in that case you merely identified
the changing field(s)
by name, and then DATATRIEVE
requested the new data item-by-item.
Formats
field-name-l

= value-exp-l
the

record

Field-name-l must be defined
in
definitions for the source domain.

Value-exp-l must be a legal value expression.

field-name-2

= field-name-3

Field-name-2 and field-name-3 must
data items.

These groups must have at least one ia~ntically
named elementary data item. This name may be the
defined name or the substitutable QUERY-NAME.

each

group

Requirements
The record must exist in a source domain that you
readied for WRITE or EXTEND access.

have

Prompts &
Responses
None, unless
value-exp-l
assumes
*.promptname or **.promptname.

the

form

Effects
1.

The fields are added to the record in the order in
which they are provided. If any piece of data is
inappropriate for its definition, assumptions are
made or error messages issued, and the command
continues on to the next defined field.
If a
numer ic field was oversize and contained numer ic
data, the high-order digits were truncated, and an'
error message issued.
If an alphanumeric field
contained
excessive
string
data,
truncation
occurred without an error message.

The collection cursor is left unchanged.

4-64

COMMANDS FOR INQUIRY & UPDATE
Example
The following example uses three assignment statements
in a :aE_G.IR~BND .81Q.G_k withina. S.TQBE GQmmaJHt tQPla.c..e a
value of $9000 in the price field in the new record.
DTR>STORE YACHTS BEGIN ~
DTR>
BUILDER=IISEAWORTHY" ~
DTR>
MODEL= SW I II ~
DTR>
PRICE = 9000; END; ~
II

The second format of the assignment statement is used
primarily to restructure data. This topic is described
separately for the Data Administrator in section 7.3.
Hints
Note that you must use the equals sign symbol
the Boolean operator EQ.

(=)

not

No editing is performed on the data you supply.
T·he final example in the Hints section for the STORE
command
(Section
4.11)
illustrated
the use of
*.prompt-name as the value expression in the assignment
statement.
Consider now, the effect of **.prompt-name
.:: .......

.I..U

CI.

_ .:~.:, ............
;;:).I..lll.l....LCI..L

_';~'''I_~,:""""",

;;:).I..~UCl.I...I..vu.

m~"",
.LUC

~"'''''''''''I''''''
VCI...LUC

""''U''W''''II.''''''' __ ';''_

CAt'.LC;;:);;:).I..VU

doubl~

'''I_';_~
U;;:).I..U,=,

.... "'''''''

~uc

asterisks has special meaning in a situation
where repetition is planned.
The value expression
**.prompt-name effectively asks for this value just one
time when inside a REPEAT or FOR loop. Once the value
is supplied, it is used for its purpose repetjtively
and no further requests are made of the user for this
item.
For example, although the model number is
requested three times 10 the example below, the beam is
only requested once.
DTR>REPEAT 3 STORE YACHTS BEGIN ~
DTR>MANUFACTURER=IIDONOVAN i, ; ~
DTR>MODEL=* . MODELNAME; ~
DTR>RIG="SLOOP"; ~
DTR>BEAM=**.BEAMSIZE; ~
DTR>END; ~
PLEASE SUPPLY VALUE FOR MODELNAME: 35LK~
PLEASE SUPPLY VALUE FOR BEAMSIZE: 12~
PLEASE SUPPLY VALUE FOR MODELNAME: 36LK~
PLEASE SUPPLY VALUE FOR MODELNAME: 37LK~
DTR>

4-65

COMMANDS FOR INQUIRY & UPDATE

REPEAT
4.13.3

REPEAT Statement

Purpose
This statement causes
the
immediately
following
statement to be executed a given number of times before
execution progresses on to the next command.
This
clause
can
save
you a great deal of tiresome
repetition.
Format
REPEAT
1.

value-exp-l

statement-l

You must supply a value expression for the
number of times to repeat the action (Section
4.5.1) •

Requirements
None.
prompts &
Responses
None, unless
value-exp-l
assumes
*.promptname or **.promptname.

the

form

Effect
1.

The subsequent statement is executed as many
as dictated by the value supplied.

times

The following example adds 20 new yacht records to
domain.

the

Example

DTR> REPEAT 20 STORE YACHTS GQ
Hints
Remember that with the combination of REPEAT and STORE
you can propagate a simple error through a great deal
of data.

4-66

COMMANDS FOR INQUIRY & UPDATE

THEN
4.13.4

THEN Statement

Purpose
This connecting word joins commands or statements so
that execution of the second statement immediately
follows the first.
Format
statement-l THEN statement-2
1.

You must supply two statements. You may choose any
of the commands, used singly or in combinations for
these statements, with two exceptions. Do not use
the FIND command with SELECT, and do not use ABORT
(Section 4.13.6) for statement-I.

Requirements

Conform to the requirements of the statements.
Restrictions
Do not use the combination FIND THEN SELECT.
specify an ABORT statement for statement-2.

not

the

Prompts &
Responses
As provided by the statements being executed.
Effects
1.

The first statement
second one.

executes,

followed

Other effects depend on the choice of statements.

Example
The following example directs DATATRIEVE-ll to print
the type and price of the CURRENT yacht and then modify
the price.
DTR)PRINT TYPE, PRICE THEN MODIFY PRICE; ~
MANUFACTURER

MODEL

PRICE

AMERICAN
26
$9,898
PLEASE SUPPLY VALUE FOR PRICE: lO,898~

4-67

COMMANDS FOR INQUIRY & UPDATE
Hint
You may issue a number of successive THEN statements if
meaningful.
For example, you could enter the following
commands:
DTR) READY YACHTS EXTEND ~
DTR) STORE YACHTS US ING ~
DTR)
BUILDER = "DONOVAN" THEN ~
DTR)
MODEL = "DV24"; ~

4-68

COMMANDS FOR INQUIRY & UPDATE

IF -THEN-ELSE
4.13.5

IF-THEN-ELSE Statement

Purpose
This statement provides a limited choice of actions
that may be followed based on existing conditions.
Format
IF condition THEN statement-l (ELSE statement-2]
1.

You must supply a condition in the
Boolean expression (Section 4.5.2).

form

You must supply an action to be taken, in the form
of statement-I.
Statement-l may be a simple or
compound command.

You may optionally want to specify a
second
possible
action
in the form of statement-2.
Statement-2 may be a simple or compound command.

Requirements
Conform to
specified.

the

requirements

the

statement(s)

Prompts &
Responses
As dictated by the statement(s) specified.
Effects
1.

The condition is tested and if and only if it is
true, statement-l is executed. If the condition
proves false, any optional statements following the
word THEN will be executed.

The execution proceeds to
command.

the

DATATRIEVE-ll

Example
The following example tests if LOA is greater than 99.
If it is, the user wishes to MODIFY the field.
Otherwise, the execution can proceed to the next
command.
DTR>IF LOA>99 THEN MODIFY LOA; ~

4-69

COMMANDS FOR INQUIRY & UPDATE
Hint
You may nest your IF statements.
For example, the
following sequence would classify a yacht by size and
recognize ahy yacht that was oversize. It employs the
DISPLAY statement described in Section 4.13.7.
DTR)IF LOA BETWEEN 0 AND 26 THEN DISPLAY "SMALL-YACHT" ELSE ~
DTR)IF LOA BETWEEN 27 AND 32 THEN DISPLAY "MEDIUM-YACHT iI ELSE ~
DTR)IF LOA BETWEEN 33 AND 99 THEN DISPLAY "LARGE-YACHT" ELSE ~
DTR)DISPLAY "THIS YACHT IS WRONG LENGTH"~

4-70

COMMANDS FOR INQUIRY & UPDATE

ABORT
4.13.6

ABORT Statement

Purpose
The ABORT statement provides a means of terminating
command execution in a compound statement. Note that
it only affects the one command or statement under
consideration;
it does not affect the DATATRIEVE-ll
session as a whole.
Format
ABORT value-exp-l
1.

Value-exp-l must
Section 4.5.1.)

value

expression.

(See

Requirements
None.
Prompts &
Responses
None.
Effects
1.

If the ABORT action takes place, whatever value you
specified for value-exp-l will be displayed on your
terminal device, followed by the notification
EXECUTION TERMINATED BY

ABORT II COiviIviAND

The collection cursor is left unchanged.

You are prompted
command.

enter

the

DATATRIEVE

Example
The following example shows the use of the ABORT
statement
in
combination
with
an
IF-THEN-ELSE
statement, for a record whose model number is not 345T.
DTR>IF MODEL EQ 11345T II THEN MODIFY PRICE ELSE ~
DTR>ABORT IINOT MODEL 345T"; GD
ABORT: NOT MODEL 345T
EXECUTION TERMINATED BY "ABORT" COMMAND
DTR>
Hint
In the example below the concatenation character <:> is
used to construct a value-expression that provides a
more informative message.
DTR>IF MODEL EQ 11345T II THEN MODIFY PRICE ELSE GD
DTR>ABORT IIMODEL NO. IS: ":MODEL~

4-71

COMMANDS FOR INQUIRY & UPDATE

DISPLAY
4.13.7

DISPLAY Statement

Purpose
This statement causes DATATRIEVE to immediately print
the value specified.
This facility lets you conduct
brief checks on certain results while some operation is
in progress.
It is clearly not intended for writing
large amounts of data; the PRINT command or Report
writer
facilities
are
better choices for that.
However, the DISPLAY statement can be a handy tool for
displaying limited quantities of data, especially when
you recall the range of items qualifying as value
expressions (Table 4-2).
Format
DISPLAY value-exp-l
1.

You must supply
Section 4.5.1.

value

Refer

form

displayed

expression.

Requirements
None.
Prompts &
Responses
None, unless
value-exp-l
assumes
*.promptname or **.promptname.

the

Effect
1.

The value of the value expression is
your terminal.

Example
The following example shows the DISPLAY statement
with an IF-THEN-ELSE statement.

used

DTR>IF PRICE>35000 THEN DISPLAY~
DTR>"OVER-BUDGET" ELSE PRINT BUILDER; ~
MANUFACTURER
AMERICAN
Hints
You could use the DISPLAY statement in a REPEAT-STORE
compound statement to send an intermediate message to
the user. For example, in the illustrated sequence

4-72

COMMANDS FOR INQUIRY & UPDATE
below, the reminder to ENTER NEXT RECORD precedes each
request for data and sort of documents the beginning of
each new record.
DTR>REPEA~U-3· -nrSPLAY

. tJ-ENTERNEXT .RECORnHTHEN (- -REt--)

DTR> STORE YACHTS US ING ~
DTR>BUILDER = "DUFOUR" C§)
You may want to consider the use of the concatenation
character
(:> to create a more informative message.
See the Hint section of the ABORT command
(Section
4.13.6) •

4-73

COMMANDS FOR INQUIRY & UPDATE

FOR
4.13.8

FOR Statement

Purpose
This statement specifies that the substatement that
follows must be performed on the group of records
identified by the record selection expression.
Format
FOR rse-l statement-l
1.

You must supply a record selection expression.
Section 4.5.

The substatement statement-l may be
two or more commands linked by
(Section 4.13.4).

See

a command or
the word THEN

Requirements
The domain identified by the rse must be READY.
You must obey the requirements
invoke as statement-I.

any

command

you

Prompts &
Responses
The prompts and responses will be dictated
choice of command(s) for statement-I.

your

Effects
1.

On READY domains, there is no prerequisite that
FIND
(unless CURRENT is specified in the rse)
and/or SELECT be executed. The collection will be
temporarily "found"
(but not established) for you
and processed. This part of the processing will
not affect the cursor either.

The final effects will depend
command(s) for statement-I.

your

choice

Example
The following example identifies the records of yachts
manufactured by Pearson for modification of the price.

4-74

COMMANDS FOR INQUIRY & UPDATE
DTR>FOR YACHTS WITH ~
DTR>BUILDER EQ II PEARSON " PRINT MODEL, PRICE THEN ~
DTR>MODIFY PRICE; ~
MODEL

PRICE

26
$11,000
PLEASE SUPPLY VALUE FOR PRICE: 11500~
26W
$10,000
PLEASE SUPPLY VALUE FOR PRICE: 10500 ~
DTR>

4-75

COMMANDS FOR INQUIRY & UPDATE

HELP
4.14

GETTING ASSISTANCE WITH THE HELP COMMAND

Purpose
This command requests assistance with one or more
commands.
Two forms of help are available, since the
commands can be thought of in two categories:
simple
and advanced. You only enter the realm of the advanced
form of any command when you employ the optional
elements such as the record selection expression.
Format
HELP [ADVANCED]

[commnd-name-l [, commnd-name-2 •.. ]]

If you specify one or more command-names, they must
each be legitimate DATATRIEVE commands.

You may optionally specify that you wish the more
advanced type of assistance by specifying the word
ADVANCED.

Requirements
None.
prompts &
Responses
No prompting messages appear, but you will be informed
how to use the command or commands you specified.
Effects
None.
Examples
The following example requests help with
forms of the FIND and SELECT commands.

the

simple

obtain
FIND and

DTR>HELP FIND, SELECT; ~
The following example illustrates how
assistance with the more complex forms
MODIFY commands.
DTR>HELP ADVANCED FIND,

4-76

MODIFYi~

CHAPTER 5
COMMANDS FOR REPORT WRITING

This chapter presents the commands that are part of the DATATRIEVE-ll
facility for report writing. These commands are entered in a group or
block, that we will call the RW sequence.
Before learning how to
construct an RW sequence, you should review the parts of a report.

5.1

PARTS OF A REPORT

The Report writer allows you extensive flexibility in designing a
report. The flexibility, however, means that a generalized report may
have a large number of components. For example, the list of possible
components includes report headers, column headers, report sections,
detail lines, summary lines, report groups, and report events.
Because we will refer to each of these parts by name, it is important
for you to understand what they are. Figure 5-1 illustrates a typical
report and its parts.
The REPORT HEADER is the line or lines that may be printed at the top
of your report, usually as a title. The report header may include tne
report name, date, and page number or any combination of these three
items.
Nearly all reports will contain a report header on the first
page; at your option, you may request that the header be printed on
subsequent pages or subsequent sections.
The COLUMN HEADER consists of one· or more lines pr inted as the headers
for the columns in the report. The column header may include field
names, DATATRIEVE keywords, or other headers that you have specified.
A REPORT SECTION is just what it sounds like: a section of a report.
A report section begins on a new page, numbered one. You might want
to divide the report into sections' when you plan to separate it and
send the various sections to different people.
One or more lines in the report that are produced from a data record
in the file are collectively called the DETAIL LINE. The detail line
need not be straight from the file; the RW allows you to add literal
strings and arithmetic expressions.
For example, you could add an
arithmetic expression such as PRICE/DISP to calculate the cost per
pound for each yacht. The resulting value would become part of the
detail line in the generated report but not part of the data record.
A number of successive input records with a single value for a
particular field constitutes a REPORT GROUP (sometimes just called a
group). The end of a report group is reached when the next record has
a different value for the field in question. Report groups are often
a useful key for formatting indentation and spacing. You can create
subgroups by specifying more than one sort-key.

5-1

COMMANDS FOR REPORT WRITING
The beginning or end of a report group or the top or bottom of a page
or report is called a REPORT EVENT. You can request that various
procedures take place when a report event occurs. For example, at the
bottom of a report group, you might want to print totals or subtotals
for one or more fields.
In addition to invoking special procedures, a report event can trigger
a SUMMARY LINE.
Summary lines can include summary information (for
example, any of the statistical functions TOTAL, COUNT, AVERAGE, MAX,
or MIN) for a report, page, or report group, but they are not limited
to such information.
A summary line can also contain
header
information for groups, pages, or reports, or perhaps start a new page
or section.
In the sections that follow you will learn Report writer statements
that specify these parts of a report. After all the statements have
been discussed individually, Figure 5-2 illustrates some RW sequences
that combine the statements.

5-2

COMMANDS FOR REPORT WRITING

LISTING OF SAILBOATS BY LENGTH AND TYPE~---LENGTH

RIG

MANUFACTURER

MODEL

WEIGHT

BEAM

CHALLENGER
GULFSTAR
ISLANDER

41
41
FREEPORT

26,700
22,000
22,000

13
12
13

$51,228
$41,350
$54,970

20,700

$48,490

24,250

$80,500

41
KETCH

SLOOP

'::C;'<?~~,MB~/\ ". ," .,,,41
"4------if:~1~~'1
OLYMPIC

ADVENTURE

AVERAGE PRICE: $55,30
REPORT GROUP A consists of four records all having a length of 41 feet.
REPORT GROUP B consists of one record having a length of 42 feet.
EVENTS occur here when the rig type changes from K~TCH
and when the sailboat length changes from 41 to 42 feet.

R~~UHT

Figure 5-1

Parts of a Report

5-3

SLOOP

COMMANDS FOR REPORT WRITING

REPORT
5.2

INVOKING RW -- REPORT

Purpose
This statement invokes the Report writer facility of
DATATRIEVE-ll. You may obtain a report on any collection
or domain that is already established.
Format
REPORT

[rse]

[ON

file-spec-l]

where the record selection expression (rse)
form:
[ALL

LrIRST ~ [collectn-name-2 ~

CURRENT
}
collectn-name-3
{ domain-name-l

assumes

the

[WITH condi tn]

[SORTED BY key-l [, key-2 . .. ]]
Note t~at n represents any decimal integer.
If necessary, review the descriptions
selection expressions in section 4.5.3.

record

If you specify a record selection expression,
will
obtain a report on the records in
collection or domain you designate.

you
the

If you omit the record selection expression, the
report will include the CURRENT collection d-ata
only.

If you specify the optional [ON
file-spec-l]
clause, file-spec-l must be the name of a file or
device specification. If you do not designate a
special file specification, the report appears on
your terminal.
Note that you
can
use
the
value expression
*.prompt-name
(described
in
section 4.5.1) to obtain a
file
or
device
specification.

Requirements
You must have already established a collection
specify CURRENT or a collection name.

you

Prompts &
Responses
None.
Effects
1.

The report reflects only the CURRENT collection
data unless you supply a collection name in the
record selection expression.

5-4

COMMANDS FOR REPORT WRITING
2.

The output of the report is directed to the
terminal unless you provide an alternate file
specification in the ON file-spec-l clause.

The Report writer treats all the subsequent input
as RW statements until you issue the REPORT END
statement.

The collection cursor is left unchanged.

Examples
The following example initiates a report for
CURRENT collection to be printed on the terminal.

the

DTR> REPORT i ~
The following example initiates a
MEDIUM-YACHTS
collection
with
characteristics to be printed on line

report for the
the
specified
printer unit 2.

DTR>REPORT FIRST 7 MEDIUM-YACHTS WITH PRICE<~
DTR>40000 SORTED BY LOA ON LP2:; ~
Hints
The ability to print the report on your terminal may be
especially useful for preparing a "trial run" of a
report. This way you can check the spacing and format
before you print the report on the line printer or
other device.
While there is no provision in the REPORT command
syntax for specifying that you wish multiple copies of
your report, you could always use the
following
technique to obtain them. First generate a copy of the
report into a named area (for example, REPORT ON
REPI.SAV), and then use an operating system command to
queue multiple listings of that file from the area.

5-5

COMMANDS FOR REPORT WRITING

REPORT END
5.3

TERMINATING THE REPORT -- REPORT END

Purpose
The REPORT END statement is the last statement in an RW
sequence.
It
signals DATATRIEVE that subsequent
commands are not to be treated as part of the RW
sequence.
Upon
recognition
of
the REPORT END
statement, DATATRIEVE begins to check the complete RW
sequence
for
syntax errors.
If none is found,
execution of the report request begins.
Otherwise,
error messages appear on your terminal and you must
correct the errors before your
request
can
be
processed.
Format
REPORT END
Requirements
You must have previously issued a REPORT statement, a
SET REPORT-NAME statement, and at least one PRINT or AT
statement.
prompts &
Responses
None.
Effects
1.

DATATRIEVE scans all the RW statements for syntax
errors. If none is found, the report you requested
will be printed on the specified device.
If any
errors are present, you must correct them before a
report can be printed.

Example
The following example ends a sequence of RW commands.
DTR>REPORT END;~

5-6

COMMANDS FOR REPORT WRITING

SET
5.4

SPECIFYING REPORT PARAMETERS -- SET

This statement defines values for
parameters throughout the report.
following items:

one
or
more
You can set the

• Report name
• Maximum number of lines per report

• Maximum number of pages per report
• Page numbering or no page numbering
• Date or no date
• Number of lines per output
• Number of columns per output page
p~ge

Format
SET parameter-l [jparameter-2 ... ]
where the parameters
list:

are

chosen

from

the

following

REPORT-NAME = report-name
MAX-LINES = integer-l
MAX-PAGES = integer-2
NUMBER
NO-NUMBER
DATE = [" str ing-l"]
NO-DATE
LINES-PAGE = integer-3
COLUMNS-PAGE = integer-4
1.

REPORT-NAME must consist of one or more name
segments, separated by slashes. The name segments
must be literals (see Section 3.8).
DATATRIEVE-ll
centers
the
segments
on
successive
lines.
REPORT-NAME must be set once in every RW sequence.

Integer-l denotes the maximum number of lines that
the report may include.
If the number of lines
(including blank lines and lines automatically
skipped)
exceeds
this
number,
DATATRIEVE-ll
automatically terminates the report. If you omit
this parameter, no checking is done, and the report
may run until terminated by outside intervention.

Integer-2 indicates the maximum number of output
pages that the report may span. DATATRIEVE-ll
automatically ends the report after printing this
number of pages.
If you omit this parameter, no
checking is done and the report may run until
terminated by outside intervention.

5-7

COMMANDS FOR REPORT WRITING
4.

NUMBER and NO-NUMBER, respectively, allow you
include or exclude page numbers in the report.

DATE and NO-DATE,
respectively, allow you
to
include or exclude the date of your report. The
DATE parameter has an optional
string-l
clause.
If you omit this clause, DATATRIEVE-ll uses the
current system date in the format dd-mmm-yy, as in
l8-AUG-77.
By including the string-l clause, you
can specify a particular date in any format you
want.
For example, DATE="OCTOBER 31, 1977" or
DATE="HALLOWEEN" are two acceptable forms.

Integer-3 represents the number of lines to be
printed on each output page.
If you omit this
specification, DATATRIEVE-ll automatically uses a
value of 60.

Integer-4 denotes the number of columns to be
printed across the output page.
If you omit this
value, DATATRIEVE-ll automatically uses a value of
132. The maximum value of integer-4 is 132.

Requirements
None.
Prompts &
Responses
None.
Effects

DATATRIEVE-ll sets values for all the parameters
included
in the SET statement.
These values
pertain to the entire report.

If certain parameters are not set, DATATRIEVE-ll
adopts the default values shown in Table 5-1.

Examples
The following example sets a report name.
DTR)SET REPORT-NAME = "YACHT SALES" / G!2J
DTR) "IN CALENDAR YEAR 1977" / ~
DTR> ~~ STAR-KEY MARINA, INC.!!~
The second example sets a value of 58
and 72 columns per page.
DTR)SET LINES-PAGE = 58, COLUMNS-PAGE

lines

per

page

7?~
I

'----"

Hint
lr you need to
set several parameters in the same
report, you can use more than one SET statement. The
additional SET statements may not, however, be used to
change parameters that have already been set.

5-8

COMMANDS FOR REPORT WRITING

Table 5-1
Default Report Parameters
Patame-tel"

De faUlt V al lie

REPORT-NAME

None. Required

MAX-LINES

None. Not required.

MAX-PAGES

None. Not required

NUMBER

Pages will be numbered.

DATE

Current date in computer is used.

LINES-PAGE

COLUMNS-PAGE

132

5-9

COMMANDS FOR REPORT WRITING

PRINT
5.5

FORMATTING DETAIL LINES -- PRINT

Purpose
This statement specifies the content and
detail line in the report.

format

Format
PRINT detail-item-l [,detail-item-l •.• ]
1.

Detail-item-l and detail-item-2 are the same print
list elements that were defined in Table 4-5. See
Section 4.8 for a complete description of the PRINT
command.

You may specify only one PRINT statement to specify
the
detail
line
format
in
each
report
specification.

Requirements
None.
Prompts &
Responses
None.
Effect
1.

The RW produces a detail line for each record in
the collection or domain on which the report is
based.

Example
The following example produces a detail line that
starts with nlne spaces, and then lists the yacht
displacement and price as recorded in the data record.
Finally, the price of the boat is divided by its
weight, and the result is printed in the last column
under the heading "PRICE PER POUND."
DTR>PRINT SPACE 9, DISP, PRICE,(Kcl)
DTR>PRICE/DISP ("PRICE"/"PER"/"POUND") USING ~
DTR>$ZZ,ZZZ.99; ~

5-10

COMMANDS FOR REPORT WRITING

AT
5.6

FORMATTING SUMMARY LINES -- AT

Purpose
This statement specifies the content and format of a
summary line in the report. A summary line may appear
at the top or bottom of a page, report, or field.
It
may include a value, the result of an arithmetic
calculation, or a report header. The summary line may
also specify special spacing instructions, a new page,
or a new section of the report.
Format

TOP
lBOTTOMJ

f ield-name-l)
PAGE
PRINT
(
REPORT

summry-item-l [,summry-item-2 ••• ]

Field-name-l must name a field that belongs to the
record type associated with the collection on which
you are reporting.

Table 5-2 lists all the legal values for summary
items.
Note that since a modified PRINT statement
is part of the AT s~a~ement, many of ~ne legal
options of the PRINT statement may be used in the
summary items as well.

The value expression is evaluated using the first
or last record of the group, the page, or the
collection,
depending
on
the
summary
line
specification.

If you specify TOTAL, COUNT, AVERAGE, MAX, or MIN,
RW computes the quantity for the field, page, or
report. These specifications may only be part of
an AT BOTTOM statement;
you cannot summarize a
column, page, or report in this manner at the top.

NEW-PAGE signals two report events:
BOTTOM OF PAGE
TOP OF PAGE
Any procedures specified for the top or bottom of
the page will be executed whenever a NEW-PAGE is
specified.

NEW-SECTION signals three report events:
BOTTOM OF PAGE
TOP OF REPORT
TOP OF PAGE
After each new section is started,
page numbers to 1.

5-11

resets

the

COMMANDS FOR REPORT WRITING

Unless you explicitly
specify
otherwise,
RW
automatically perfo~s the following statement each
time it starts a new page:
AT TOP OF PAGE PRINT REPORT-HEADER., COLUMN-HEADER;

If you sorted the collection before invoking RW, RW
maintains the order imposed by the sort.
If you specify more than one AT TOP or AT BOTTOM
statement, and the values of one or more fields
change between successive input records, RW does
not execute the AT TOP and AT BOTTOM statements in
the order in which you typed them.
Instead, it
executes them in the order in which you specified
the sert-keys before invoking the Report writer.

Requirements
None.
Prompts &
Responses
None.
Effect
1.

If you specify more than one summary item, the
procedures the summary items imply are executed in
the order in which they are implied. For example,
items specifying AT TOP result in printing at the
top of the named item, while those carrying AT
~OTTOM
notations are saved and printed at the end
of the report group.

Examples
The £ollowing example identifies the report event of a
change in the length-ever-all field, and causes the new
LOA value to be printed under the column header LENGTH
at the beginning of each report event.
DTR)AT TOP OF LOA PRINT LOA("LENGTH");~
The next example prints both the report name and column
headers at the beginning of each new page.
DTR)AT TOP OF PAGE PRINT REPORT-HEADER,

5-12

COLUMN-HEADER~

COMMANDS FOR REPORT WRITING
Table 5-2
Summary Items
-- --+-

Item

------------------------

FUnction

COL n

Advances across the horizontal line to column
n. Note: n must not be less than one or more
than the page width.
If n is less than the
present column, a line is skipped.

SKIP [n]

Moves n blank lines ahead to start a new line.
Printing starts in column one, unless another
element modifies the position further.

TOTAL

Causes a total to be printed for the field
the bottom of the page or report.

field-l

Causes the number of items in the page, field,

COUNT

nr
--

r~nnrr
rn
h~
--1:"---- --

nrinr~~

1:"- ........ _ - - .

AVERAGE field-l

Causes the average of
field-l to be printed.

all

the

values

for

MAX

field-l

Causes the maximum value in the
printed.

field

MIN

field-l

Causes the minimum value in the
printed.

field

NEW-PAGE

Forces a new page at this point in the report.
Note that this phrase activates any TOP OF
PAGE statements that you have specified.

NEW-SECTION

Causes the beginning of a new section

report.

of the
Page numbers are restarted at one.

REPORT-HEADER

Causes the printing of the report header,
specified via the SET REPORT-NAME command.

COLUMN-HEADER

Causes the printing of the column headers.

value-expression
[mod i fie r s]

Causes a value to be
See Table 4-5.

inserted in the report.

NOTE
The
TAB
specification,
although
permitted in the PRINT command, is not
permitted here.

5-13

1----

COMMANDS FOR REPORT WRITING
DTR>READY YACHTS WRITE
DTR>FIND YACHTS WITH LOA > 33
[7 RECORDS FOUNDJ
DTR>REPORT;
DTR>SET REPORT-NAME=-TESTING-;
DTR>SET COLUMNS-PAGE = 50
DTr-;:)f'RINT PRICE, BUILDER, RIG;
DTR::REF'ORT END;

TESTING

28-0CT-77
PAGE 1

PRICE

MANUFACTURER

RIG

$36,951
$37,850
$39,215
$37,850
$39,500
$36,950
$35,900

ALBERG
CARIBBEAN
CHALLENGER
CHRIS-CRAF
I. TRADER
IRWIN
LINDSEY

KETCH
SLOOP
SLOOP
SLOOP
KETCH
KETCJ{
MIS

IITR>READY YACHTS
DTR>REPORT YACHTS WITH LOA >36 SORTED BY BUILDER, LOA
DTR>SET REPORT-NAME = -YACHT SALES-I
DTR>-IN CALENDAR YEAR 1977-1
DTR)-STAR-KEY MARINA, INC.DTR)SET LINES-PAGE = 58, COLUMNS-PAGE = 72;
DTR)PRINT SPACE 9, [lISP, PRICE,
DTR>PRICE/DISP (-f'RICE-I-PER-/-POUND-) USING
DTR>SZZ,ZZZ.99;
DTR>AT TOP OF LOA PRINT LOA (-LENGTH-)
DTR)AT TOP OF PAGE PRINT REPORT-HEADER,DTR)COLUMN-HEADER;
DTR:::REPORT END;

LENGTH
37
39

YACHT SALES
IN CALENDAR YEAR 1977
STAR-KEY MARINA, INC.

28-0CT-77
PAGE 1

WEIGHT

PRICE

PRICE
PER
POUND

20,000
20,000

$36,951
$36,950

$
$

1.00
1.00

14,500 .

$35,900

2.00

Figure 5-2

Sample Report writer Sequences

5-14

COMMANDS FOR REPORT WRITING
DTR> READY YACHTS
DTR)FIND YACHT-TYPES IN YACHTS SORTED BY ASC RIG,
DTR) BUILDER, LOA;
.~.45.__ REGOKQ$ . fQ.LJHD.J

DTR)SELECT FIRST;
DTR>REPORT YACHT-TYPES;
DTR)SET REPORT-NAME=-YACHTS GROUPED BY TYPE-;
DTR)SET COLUMNS-PAGE = 72
DTR)AT TOP OF RIG PRINT RIG
DTR) P,RINT BUILDER, LOA, DISP, BEAM, PRICE;
DTR)AT BOTTOM OF RIG PRINT COUNT
DTR) REPORT END;

28-0CT-77
PAGE 1

YACHTS GROUPED BY TYPE

RIG

MANUFACTURER

LENGTH
OVER
ALL

KETCH
ALBERG

GRAMPIAN

I. TRADER
IRWIN

36
37

WEIGHT

BEAM

PRICE

20,000
12!'000
18,600
20,000

12
10
12
11

$36,951
$29!'675
$39,500
$36,950
4

MIS

AMERICAN
EASTWARD
LINDSEY

26
24
39

ALBIN
ALBIN
AMERICAN
BAYFIELD
CAPE DORY
CAPE DORY
CAPE ·DORY
CARIBBEAN
CHALLENGER
CHALLENGER
CHRIS-CRAF
CLIPPER
CLIPPER
GRAMPIAN
GRAMPIAN
HUNTER
IRWIN
ISLANDER
ISLANDER
RYDER
SABRE
SALT
TANZER
TANZER
VENTURE
VENTURE
WESTERLY
WINDPOWER

26
27
26
32
19
25
28
35
32
35
35
30
32
26
28
27
25
24
28
31
28
25
26
28
21
22
26
16

5,500
7,000
14,500

$18,895
$15,900
$35,900
3

SLOOP

Figure 5-2 (Cant.)

08
09
12

4,200
5,070
4,000
9,500
1,900
4,000
9,000
18,000
12,800
14,800
18,000
3,800
4,500
5,600
6,900
6,500
5,400
4,200
5,994
13,600
7,400
2,600
4,350
6,800
1,500
2,000
6,700
650

10
08
08
10
06
07
09
11
11
12
11
08
08
08
10
09
12
08
10
00
09
07
09
10
07
07
08
07

$17,900
$18,600
$9,895
$32,875
$4,295
$8,995
$21,990
$37,850
$31,835
$39,215
$37,850
$9,500
$12,950
$11,495
$14,475
$14,999
~10,950

$6,500
$15,908
$32,500
$22,000
$6,590
$11,750
$17,500
$2,823
$3,564
$15,245
$3,500

Sample Report writer Sequences
5-15

COMMANDS FOR REPORT WRITING
DTR)!THE RW SEGUENCE THAT CREATED FIGURE 5-1.
DTR)!
DTR)READY YACHTS
DTR)REPORT YACHTS SORTED BY ASC LOA, RIG
DTR)SET REf'ORT-NAME=·LISTING OF SAILBOATS BY LENGTH AND TYPEDTR)SET LINES-PAGE=15
DTR)SET COLUMNS-PAGE=70
DTR)AT TOP OF LOA PRINT LOA(·LENGTH·);
DTR)At TOP OF RIG PRINT RIG(·RIG·);
DTR)AT BOTTOM OF REPORT PRINT COL 30,DTR)-AVERAGE PRICE: -,AVERAGE PRICE USING $ZZ,Z99
DTR)PRINT TYPE, DISP, BEAM USING Z9, PRICE;
DTR)REPORT END;
Figure 5-2 (Cant.)

Sample Report Writer Sequences

5-16

CHAPTER 6
PROCEDURES

6.1

INTRODUCTION TO PROCEDURES

Procedures are groups of DATATRIEVE statements and commands that you
want to name so that you can cause them to execute without having to
reenter them each time they are needed. Whether or not you become
involved in defining procedures, you will probably want to invoke some
of them as your use of DATATRIEVE expands. The use of procedures can
save you a great deal of time at the keyboard. Since the sequence of
commands has been "debugged" prior to its entry in the
Data
Dictionary, you can avoid some of the common errors of writing
T"\7\m7\mnT'C'lT'C'

.u.l"'1.J..rl..LL"~J,,;J

6.2

v J.:J

,..I"'\.'I"'I'\'I"'I'\""" ...... ~~

\WOVJIlJ.lla.&"uo

"!'Ito ...... ~
Q'J.U

t'-I .... "!'Ito .....

,...."I"I'\,...,. ...... ~~

.;:) \...(;1. \""'Ii;;;'.lllC'"

\.....,

~'V' ... ,O;'"''t"''\.''''' ... ~'P'''\O'''1'~'..:7
~A '-~'1ll:"V'.L w.a."~V"""~"""J

•

INVOKING A PROCEDURE

Once a procedure has been defined and placed in the Data Dictionary,
you may invoke it by name any time you need it. The technique is to
issue a colon (:) immediately prior to the procedure name. If you are
not sure of the procedure name; you can issue a SHOW PROCEDURES
command (Section 4.3).
To illustrate this technique, suppose you know there is a procedure
called PRICE-INCR in your Data Dictionary. Once you ready the qomain
YACHTS for writing, you can invoke PRICE-INCR to display both the
current value of the price field and the value of the price if
increased by 10 percent. The procedure asks you to supply the value
of the price, so that you can modify the old value to the newly
calculated figure.
It repeats this process for every yacht with a
price greater than zero. This procedure will produce the same results
that you would have achieved by issuing the following sequence of
DATATRIEVE commands.
(As you would suspect, these commands comprise
the procedure definition.)
DTR> FOR YACHTS WITH PRICE > 0 ~
DTR>PRINT "PRICE: ",PRICE," 10% INCREASE: ",PRICE*l.l USING(§)
DTR>$$$,$$$ THEN MODIFY PRICE; ~
DTR>FINISH; ~
Invoking this sequence of DATATRIEVE-ll commands is as simple as
calling its name.
You simply precede the name by a colon. You may
follow it with an optional semicolon if you wish.
For example, using the defined procedure PRICE-INCR we could cause
10 percent price increase in all the yacht records as follows:

6-1

PROCEDURES
DTR>READY YACHTS WRITE; ~
DTR>:PRICE-INCR~

PRICE
PRICE:

$36,951 10% INCREASE:

PLEASE SUPPLY VALUE FOR PRICE:

$40646.10
40646~

and so forth.
You would
requested
domain.

be
to

informed of the current and calculated price and
supply a value for PRICE for each of the records in the

6-2

CHAPTER 7

FOR THE DATA ADMINISTRATOR

This chapter covers some topics of special interest to the Data
Administrator.
The average user will not need to study this
information. From this chapter the Data Administrator can learn how
to define records, domains, and procedures, how tG maintain-these
definitions, how to use the data protection features for greater
installation security, and finally, how to restructure data in
existing files into other formats.

7.1

DATA DICTIONARY TOPICS

Before any user can use DATATRIEVE-ll on the records and domains, an
individual at the installation must first define the records and
domains. These definitions are retained in the Data Dictionary along
with the procedure definitions.
In the following sections you wLll learn how to use the DEFINE command
to create the record, domain, and procedure definitions. You will
also learn how to remove the definitions from the Data Dictionary.

A general suggestion is offered here since you may find yourself
wanting to edit your definitions and there is no editing facility that
operates on the Data Dictionary:
(DATATRIEVE-ll requires that you
delete a definition and then redefine it). You might consider instead
setting all your definitions up in indirect command files.
These
files may be edited at will with your operating system's editor. When
you are satisfied with the definition, you enter DATATRIEVE-ll and
simply respond to the DTR) prompt with
@file-name-l ~
This technique was employed during DATATRIEVE-ll installation.

7-1

FOR THE DATA ADMINISTRATOR
7.1.1

Defining the Records--DEFINE RECORD

You must define each field in each record,
its size and general
characteristics.
While COBOL programmers will find the format of the
definitions to be familiar, you should not assume that the RMS-ll
files need to be generated by COBOL programs or that any other
knowledge of the COBOL language is required.
This is simply a
convenient
format
for
describing
the
data items and their
relationships to one another in each record. Even if you have never
studied COBOL, you should be able to use the elements comfortably once
you see a few examples. The pertinent COBOL rules have been extracted
and summarized. They are presented in Appendix E.

7-2

FOR THE DATA ADMINISTRATOR

DEFINE RECORD
Purpose
.TbIs . c aromanc . t-teaTe-s· --a-compleTe _. - r-ercord-ae f-ini-tI-on in
the Data Dictionary.
This definition will permit
references to the record and its fields.
It is
necessary, however, that the record also be defined as
part of a defined domain. This action can take place
either before or after the record definition, provided
it occurs before a user attempts the first reference to
the record.
Section 7.1.2 describes how to define a
domain.

Format
DEFINE RECORD record-name-l USING data-def-l [data-def-2 ••. ]

;

1._

You must specify a record name.

(See Section 3. 7 • )

Each record must consist of at least one data item
(field) requ1r1ng a data definition. Additional
fields will require additional data definitions.
The
definitions
must
be given in the same
sequential order as the fields exist in the record.

Data definitions will assume the format of COBOL
data definitions, employing the technique of a
PICTURE clause to describe the type of data (for
example, numeric and alphanumeric) its length, and
permitted contents. This approach also supports
the use of level-numbers to describe subfields
within major fields. Each data definition assumes
the following format:
level-no fld-nme-l [PIC IS char-string
[USAGE IS usage] [SIGN IS qualifiers]]
You will find descriptions of the optional
USAGE, and SIGN clauses in Appendix E.

PIC,

You may also intersperse optional clauses such as
[OUERY-NAME IS name].
or
[OUERY-HEADER IS IIheader-l ll [lllheader-2 11 • • • ]l .
or
[EDIT-STRING IS edi t-str ing] •
These clauses designate abbreviations for
the
field name or abbreviations for the header to be
used when printing the field on reports, or they
specify an editing pattern to control the format of
the data when it is output. The EDIT-STRING clause
is described in Appendix E.
4.

Observe that each data definition elementary
item terminates with a mandatory period.

The semicolon is required for command termination.
You may also separate the optional clauses by
semicolons, if you wish.
To avoid any possible
misinterpretation about the period that ends a data

7-3

data

FOR THE DATA ADMINISTRATOR
definition line and the period that represents a
decimal point in a character string, particularly
when followed by a semicolon, you should adopt the
following practice:
Place the final semicolon that terminates
record definition on a line by itself.

the

Requirements
You must not use any of the keywords
in
your
definitions as either field names or record names.
These keywords are described in Section 3.11. You also
must not duplicate previously defined record, domain,
or procedure names.
Restriction
The DEFINE RECORD command
procedure definition.

not

permitted

Prompts &
Responses
None.
Effects
1.

Provided you have chosen a unique name for the
record, your new definition will be placed in the
Data Dictionary.

A password table (Section 7.2) will be created for
this resource and your UIC will be entered with
full access privileges (RWEMC).

If the record name you choose is not unique, your
command will be rejected.
(TO modify an existing
record definition, you must first delete the old
version with the DELETE command (Section 7.l.4),
then issue a new DEFINE RECORD command--unless you
have followed the suggested editing technique of
Section 7.1 and used indirect command files.)

Example
The following example defines the yacht record as
in a number of examples throughout this manual.

7-4

used

FOR THE DATA ADMINISTRATOR
DTR>DEFINE RECORD YACHT USING ~
DTR>Ol BOAT. ~
DTR>
03 TYPE. ~
DTR>
06 MANUFACTURER PIC X(lO) ~

-DTR)--

- (.5UERy=NAi4E----:fs-BuIL-DE-If~ (

RET -)

DTR>
06 MODEL PIC X(lO). ~
DTR>
03 SPECIFICATIONS ~
DTR>
QUERY-NAME SPECS. ~
DTR>
06 RIG PIC X(6). ~
DTR>
06 LENGTH-aVER-ALL PIC xxx ~
DTR>
QUERY-NAME IS LOA. ~
DTR>
06 DISPLACEMENT PIC 99999~
DTR>
QUERY-HEADER IS "WEIGHT" ~
DTR>
EDIT-STRING IS ZZ ,ZZ9 ~
DTR>
QUERY-NAME IS DISP. ~
DTR>
06 BEAM PIC 99. ~
DTR>
06 PRICE PIC 99999 ~
DTR>
EDIT-STRING IS $$,$$$. ~
DTR> ;~
Hints
The SHOW record-name command (Section 4.3)
will allow
you to confirm that a record definition has been
created as you planned.
This is a good practice
because ~~ is important to keep up-to-date coples of

the record definitions; in case they should be lost
damaged during operation.

7-5

FOR THE DATA ADMINISTRATOR
7.1.2

Defining the Domains--DEFINE DOMAIN

For each domain, there can be only one record type as defined by the
DEFINE RECORD command described in Section 7.1.1. However, different
domains may reference the same record type,
if desired.
In this
section you will learn how to define a domain.

7-6

FOR THE DATA ADMINISTRATOR

DEFINE DOMAIN
Purpose

-ThIs- command -defInes -ci domaIn of o-ii-e--kIiicf ofreCo-rcL
without this definition, which is kept in the Data
Dictionary, no references can be made to the records.
Format
DEFINE DOMAIN domain-nme-l USING rec-nme-l ON rms-file-spec-l
1.

You must supply
unique.

domain-name,

and

must

You must also provide a record name for a record
that has been or will be defined to exist in this
domain.

You must provide an RMS-ll file specification that
identifies the device and file name and extension
where the domain will reside, or at least exist,
during operations.

You must not use any of the keywords (Section 3.11)
for your domain or record names. Furthermore, you
must not duplicate previously defined
domain,
record, or procedure names when establishing the
new domain name. The record name must uniquely
identify its record definition.

You must terminate the command with a semicolon.

Requirements
Use only unique names for domains and records.
Restriction
You must not use the
procedure definition.

DEFINE

DOMAIN

command

Prompts &
Responses
None.
Effects
1.

Provided you have chosen a unique domain name for
the domain, your new definition will be placed in
the Data Dictionary.

A password table (Section 7.2) will be created for
this resource and your UIC will be entered with
full access privileges (RWEMC).

If the domain name you choose is not unique, your
command will be rejected.
(TO modify an existing
domain definition, you must first delete the old
version with the DELETE command (Section 7.1.4),
and then issue a new DEFINE DOMAIN command.
See
also the alternate method suggested in Section
7 .1 • )

7-7

Example
The following example defines the domain YACHTS, using
the record called YACHT, from the file YACHT.DAT.
Observe that the domain name is the plural form,
YACHTS, while the record name is singular. This makes
the two names unique, although the difference is
somewhat subtle.
DTR>DEFINE DOMAIN YACHTS USING YACHT ON~
DTR>YACHT.DAT;~

Hint
The SHOW domain-name command (Section 4.3) W~LL confirm
that a domain definition has been created as you
planned.

7-8

FOR THE DATA ADMINISTRATOR
7.1.3

Defining a Procedure

DEFINE PROCEDURE

Before any user can invoke a procedure, it must be defined
c_atalo_9-u.ed__ Onec.oJnma_n.d. is u._s.ed to do this.:OEE'I.NEEROC_EOURE.

7-9

and

FOR THE DATA ADMINISTRATOR

DEFINE PROCEDURE
Furpose
This command creates a procedure definition that is
automatically catalogued in the Data Dictionary. This
procedure definition becomes available immediately to
you and any other user. It remains available until it
is deleted by means of the DELETE command.
Format
DEFINE PROCEDURE procedure-name-l

:} DATATRIEVE-ll commands and statements
END-PROCEDURE
1.

You must supply a procedure name, which
must
conform to the rules for names in Section 3.7.

You may specify one or more DATATRIEVE commands
statements, optionally separated by semicolons.

The end of the procedure definition is signalled by
an END-PROCEDURE statement.

Requirements
None.
Restrictions
You must not include any of the following commands that
require access to the Data Dictionary: READY, SHOW,
DEFINE RECORD, DEFINE DOMAIN, DEFINEP, DELETE, DELETEP,
or SHOWP.
You cannot nest DEFINE PROCEDURE commands.
In other
words, do not attempt to create a procedure within a
procedure.
Prompts &
Responses
None.
Effects
1.

The procedure, consisting of all the commands and
statements you specify, is automatically catalogued
by name in the Data Dictionary.

Any comments you specify in the definition are
catalogued.

A password table (Section 7.2) will be created for
this resource and your UIC will be entered with
full access privileges (RWEMC).

7-10

not

FOR THE DATA ADMINISTRATOR
Examples
The

following

example

shows

how

create
a
a_ _rep()rt .of
every time the

P~9<:: ~cj p J:'_~____ deJ_J n ~J:J QIJth_CiJ___ wjJJ. __ Pr;9d_y~e

yacht types for the YACHTS domain
procedure is invoked.

DTR)DEFINE PROCEDURE YACHT-TYPE-REPORT~
DTR)REPORT YACHTS SORTED BY ASC RIG, BUILDER, LOA~
DTR)SET REPORT-NAME="YACHTS GROUPED BY TYPE"; ~
DTR)PRINT RIG, BUILDER, LOA, DISP, BEAM, PRICE; ~
DTR)AT BOTTOM OF RIG PRINT COUNT ~
DTR)REPORT END; ~
DTR)FINISH; ~
DTR)END-PROCEDURE;~

Hints
Test your procedures as DATATRIEVE-ll commands
before
you
create
and catalogue the formal
definitions. This permits you to debug them first.
Otherwise, you may create a definition, try it,
find it doesn't work, and be faced with deleting it
so that you may reenter the entire piece of code
again. You cannot simply change a line of code in
the definition.
If a definition is in error, it
must be first removed, then reentered.
See also the editing technique suggested in Section
7.1 as an alternative.

7-11

FOR THE DATA ADMINISTRATOR
7.1.4

Deleting a Previous Definition -- DELETE

Before you can redefine any domain, record, or procedure, you are
required to delete the existing definition. This requirement helps
ensure that definitions are not mistakenly corrupted, and lends
support to the requirement that only unique names may be used.

7-12

FOR THE DATA ADMINISTRATOR

DELETE
Purpose
This command deletes a previous definition of either a
domain, procedure, or record from the Data Dictionary.
Once the item is removed,
no user can successfully
reference it.
Format
DELETE

dOmain-name-l
}
record-name-l
[(password-str-l)]i
{ procedure-name-l

You must supply
your
choice
of
either
domain name, a record name, or a procedure name.

You must terminate the command with a semicolon.

You must possess C(ontrol)
access privileges for
the named resource. This will be determined from
your UIC or the optional password you may supply.
See Section 7.2 for more information on passwords.

Requirements

roe name specified for the domain, record, or procedure
must match a name defined in the Data Dictionary.
You must possess C(ontrol) access privileges.
Restriction
You must not include the DELETE command in a
definition.

procedure

Prompts &
Responses
None.
Effects
1.

The definition of the record, domain, or procedure
is removed from the Data Dictionary. When dealing
with records and domains, note that only the
definition is removed. There is no effect on the
physical file:
neither the file nor
its records
are deleted.
Only the ability to reference the
data through DATATRIEVE-ll is lost, at least until
such time as new definitions are provided.

The password table for the named resource
removed from the Data Dictionary.

also

Examples
The following example deletes the definition of the
domain called YACHTS, assuming that your UIC possesses
C privileges.
DTR)DELETE YACHTS; ~

7-13

FOR THE DATA ADMINISTRATOR
The following example illustrates how to remove the
definition of the yacht record from the Data Dictionary
using a password that has been accorded C privileges.
DTR)DELETE YACHT (SUNNY-DAY); ~
The last example illustrates how you might delete the
definition of the procedure called PRICE-PER-POUND.
DTR)DELETE PRICE-PER-POUND; ~
Hints
If critical definitions are accidentally deleted with
this command, you can replace them with the DEFINE
command.
However, this brings up another advantage of using
indirect command files for all your definitions, as
suggested in Section 7.1. Restoring a lost definition
can be as easy as
DTR)@PRODFI ~
if the definition is stored in a command file
PRODFl.CMD, in this case.

7-14

such

FOR THE DATA ADMINISTRATOR
7.2

DATA PROTECTION FEATURES

The protection of data within DATATRIEVE-ll is
two independent mechanisms:
the protection

accomplished through
systems of RMS-ll and
th-ose wtt-hinDA~A~RIEVE.;.;11 i tse-lf.
The DATltTRIEVE;...ll USEH'c-ifh
regulate access to domains, records, and procedures through access
requirements recorded with the definitions in the Data Dictionary.

Before you can learn the commands that direct and control the security
features of DATATRIEVE-ll, you must learn some basic concepts of the
design.

7.2.1

Two Types of Lock

This security system employs two different types of lock:
PW (Passwords) -- character strings of up to ten characters that
the user must employ with certain commands (for
example, SUNNY-DAY and FAIRWINDS).
UICt (or PPNt) account numbers -- numbers known to the operating
system that DATATRIEVE-ll can check, that the user
need not specify.
Thus, this is the
default
1 I""\.,...J,._ .... ..::7T"\'O'

.... v ..... ".

... .1.1:'''''

.... h~

..... '" t!'"'t
... u .......... ""

.... ,,~ ..... ,,~

... """" ... """'"

'I'.'I''J,..""..,...
WU"""

... ",..., • ..: ........... ~
,"C':1'-'.1.,"CI..l

I-C,,_

\.Lv ....

- - _ ...... _ , -

CAQtUP..LC,

[ 305 , 305] and [*, *] ) •
These locks and keys are maintained on a domain, record, and procedure
basis.
That is, each resource has its own password table identifying
the password strings or user account numbers that may have access to
the resource. Furthermore, this table tracks the type of access that
may be granted the user whose key satisfies the key and lock-type
requirements.

7.2.2

Five Types of Privileges

The types of access are called the user's privileges.
Thus, even
though you may be allowed to modify the YACHTS domain, your co-worker
Steve may only be permitted to read the records in the same domain.
The types of privileges are defined in Table 7-1.

7.2.3

Password Table Structure

Figure 7-1 illustrates the password table structure using a possible
example for the YACHTS domain. Each sequential line is a password
table entry.
There will never be a vacancy in the sequential table entries.
DATATRIEVE-ll processing of the DEFINEP and DELETEP commands ensures
this.

t UIC is the User Identification Code specification referred to by
many operating systems, while PPN is the "Project Programmer Number"
as referred to by RSTS/E. Both refer to the user's disk directory and
are expressed syntactically as [m,n] where m and n may be integers or
an asterisk (*). In this manual the term UIC will be adopted.
7-15

FOR THE DATA ADMINISTRATOR
Table 7-1
Privilege Codes
Privilege
Code

Meaning

R(ead)--

User can only retrieve this resource.

E(xtend)--User
resource.

M(odify)--User can retrieve
this resource.

W(rite)-- User can do all of the above (retrieve,
change, and add), and can also erase records.

C{ontrol)--User can
commands:
DELETEP,
DELETE.

can

only

add

records

this

change

records

issue the
data
protection
DEFINEP, and SHOWP, as well as

There can be from zero to five privileges granted per lock-type and
key entry. However, since a W privilege grants R, E, and M privileges
anyway, there will seldom be more than four privileges per entry.
The number of entries in each table is unrestricted
are dynamically allocated.
Sequence
Number

Lock
Type

Key

Privileges

PW
PW
UIC
PW
UIC
UIC
UIC

FAIRWINDS
SUNNY-DAY
[304,303]
STAR-KEY
[305,305]
[301,314]
[*,305]

CW
W

3
4
5
6
7

Figure 7-1.

7.2.4

and

all

entries

"-6"
R
CREM
C
REM

Example of Password Table Structure

Creating and Maintaining Password Tables

The password tables are automatically started and given a single entry
at resource definition time. This entry identifies the creating user
(by UIC) and permits the creator the full set of privileges (REMWC),
for this resource.
One of the Data Administrator's major responsibilities lS to define
the additional password table entries for each resource. These
additional entries are created by means of the DEFINEP command.
They
are maintained by the DELETEP and DEFINEP commands.
Since the
authorized Data Administrator also needs to obtain printouts of the
tables for review, the SHOWP command is designed for this purpose.
Entries are created or deleted one at a time, except when the entire
table is erased.
The password table for any resource is erased
whenever that resource is deleted by means of the DELETE command.
(See Section 7.1.4.)
7-16

FOR THE DATA ADMINISTRATOR
These table creation and maintenance commands are so important to the
protection of the data that only users with the C(ontrol) privilege
will be allowed to invoke them.

7.2.5

Password Table Processing

Whenever there is a question of access to a domain,
record, or
procedure, the password table for that resource is examined. Access
privileges are checked for any of the following commands:

• READY
• SHOW domain-name
• SHOW record-name

• SHOW procedure-name
• DEFINEP

• DELETEP
• SHOWP

• DELETE
Password tables are processed in a standard fashion that has important
implications for the table entry designer. The rules are summarized
below and illustrated by the flowchart in Figure 7-2.
1.

Users who are considered "privileged" by their operating
system because they have received project codes lower than 8,
are automatically given the C(ontrol) access privilege. They
may receive additional privileges as a result of the next two
steps that otherwise apply to less privileged users.

Table entries are searched sequentially looking for the first
hit. Thus, if a particular user qualifies for access under a
number of possible lock-type and key combinations, the access
privileges granted will be the first one(s) encountered.

The comparison of keys is directed by
the
lock-type
specification in the table
(not by the user's password
specification or default UIC). If the table entry calls for
a PW (password) lock-type, the user's command is checked for
inclusion of a password that matches.
If the table entry
calls for a UIC, the user's UIC is automatically checked.

The combined effect of these three rules is that even if the user has
a password and specifies it with the command, it will serve no purpose
if the user qualifies for access under a UIC type of table entry that
DATATRIEVE-ll encounters first.

7-17

FOR THE DATA ADMINISTRATOR
User requested
READY, DELETE,
DEFINEP, DELETEP,
SHOWP, or
SHOW resource-nme-1

Determine UIC
and save it

Yes

Give user the
C privilege as
a minimum