Digital PDFs

AA-H282A-TK

May 1978

196 pages

Original

5.9MB

Document:	Interactive Query Language Users Guide Dec78
Order Number:	AA-H282A-TK
Revision:	0
Pages:	196
Original Filename:	AA-H282A-TK_Interactive_Query_Language_Users_Guide_Dec78.pdf

OCR Text

Interactive Query
Language
User's Guide
Order Number AA-H282A-TK

December 1978
ABSTRACT
The TOPS-l0/TOPS-20 Interactive Ouery Language (lOL)
User's Guide describes the Interactive Query language
Release 3.0
SUPERSESSION/UPDATE INFORMATION:

This guide supersedes:
IOL User~s Guide (DEC-l0-UQTA-A-D)
IOL Reference Manual
(DEC-l0-UQRA-A-D)

OPERATING SYSTEM AND VERSION:

TOPS-l0, Version 6.02 or later
TOPS-20, Version 3.0 or later

SOFTWARE AND VERSION:

Ial, Version 3.0
DBMS, Version 5 or later
COBOL, Version 12 or later
SORT, Version 3.0 or later (TOPS-l0)
SORT, Version 4.0 or later (TOPS-20)

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

digital equipment corporation · maynardJ massachusetts

First Printing, December 1975
Revised:
December 1978
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.

1975, 1978 by Digital Equipment Corporation

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
DDT
DECCOMM
ASSIST-II

DECsystem-IO
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-a
DECSYSTEM-20
RTS-8

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-II
TMS-II
ITPS-IO

CONTENTS

Page
PREFACE
OBJECTIVES AND READER ASSUMPTIONS
STRUCTURE OF THE DOCUMENT
ASSOCIATED DOCUMENTS
STANDARD SYMBOLS
GLOSSARY
CHAPTER

CHAPTER

vii
vii
viii
ix
xi

FUNCTIONS OF IQL

1-1

1.1
1.2
1.3
1.4

LEVELS AND MODES OF IQL
ACCESSING DIFFERENT FILE STRUCTURES
USING RESERVED WORDS
DELETING IQL FILES

1-2
1-4
1-4
1-5

RUNNING IQL

2-1

2.1
2.2
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5
2.3.6
2.4

EXPLAINING IQL PROMPTS
EXPLAINING MESSAGE FORMATS
USING ASSISTANCE COMMANDS
Controlling and Displaying the IQL Job
Creating, Editing, and Saving a Query
Using a Query File to Generate a Report
Maintaining Query Files
Creating and Changing a Data File
Creating and Changing a Dictionary
ASSISTANCE COMMAND FORMATS
BROWSE
DEFINE
DELETE
DICTIONARIES
EDIT
EXECUTE
EXIT
GET
INPUT
ITEMS
JOB
LIST
QUERIES
REPLACE
RUN
SAVE
STORE
UPDATE
WRITE

2-1
2-2
2-3
2-3
2-3
2-3
2-3
2-4
2-4
2-4
2-6
2-8
2-9
2-10
2-12
2-14
2-15
2-16
2-17
2-19
2-20
2-21
2-22
2-23
2-24
2-25
2-27
2-28
2-29

iii

CONTENTS

(CONT.)

Page
CHAPTER

CREATING AND EDITING A QUERY

3-1

3.1
3.2
3.3
3.4
3.5
3.6
3.7

FORMATTING DEFAULTS
ORDERING QUERY STATEMENTS
STAGING A QUERY
QUALIFYING ITEM NAMES
COMMENTING IN A QUERY
READING A DBMS DATA BASE
QUERY STATEMENT FORMATS
ACCEPT
ACROSS
AUTHORITY
AVERAGE
COMPUTE
COpy
CREATE
DATE
DISPLAY
FIND ITEM
FIND KEY
FIND
FORM-LINES
GO TO
HEADING
HOLD
HSPACE
IF
LMARGIN
MAXIMUM
MINIMUM
NEWPAGE
OPEN
PAGE
PAGE-LINES
PAGING
PICTURE
PRINT
REPORT
RESET
REWRITE
RMARGIN
SET
SORT
SUMPRINT
TALLY
TITLES
TOTAL
VSPACE

3-1
3-2
3-2
3-2
3-3
3-3
3-3
3-6
3-8
3-10
3-12
3-14
3-16
3-18
3-20
3-21
3-22
3-24
3-26
3-28
3-29
3-31
3-33
3-34
3-35
3-37
3-38
3-40
3-42
3-43
3-45
3-46
3-47
3-48
3-50
3-52
3-53
3-54
3-55
3-56
3-57
3-58
3-59
3-61
3-62
3-64

CONTENTS (CONT.)

Page
CHAPTER

CREATING AND EDITING A DATA FILE

4-1

4.1
4.2
4.3

BEGINNING THE IMMEDIATE MODE
RECOVERING SEQUENTIAL DATA FILES
IMMEDIATE MODE COMMAND FORMATS
APPEND
BOTTOM
CHANGE
COLUMNS
DELETE
DOWN
EXIT
EXTRACT
FIND
FINDLIST
INSERT
LIST
SAVE
TOP
UP
VERIFY

4-1
4-2
4-2
4-6
4-7
4-8
4-10
4-11
4-12
4-13
4-14
4-15
4-16
4-18
4-21
4-23
4-24
4-25
4-26

CREATING AND EDITING A DICTIONARY

5-1

5.1
5.2
5.3
5.4
5.5

DEFINING A DICTIONARY FOR DBMS
DISPLAYING A DICTIONARY
DEFINING DICTIONARY PROTECTION
ORDERING DICTIONARY ENTRIES
DICTIONARY COMMAND FORMATS
AD
CD
DD
FD
PD
RD
SD

5-1
5-2
5-3
5-4
5-4
5-6
5-7
5-8
5-11
5-15
5-17
5-19

RUNNING IQL IN BATCH

6-1

APPENDIX A

EXAMPLE ASSISTANCE SESSION

A-I

APPENDIX B

EXAMPLE IMMEDIATE MODE SESSION

B-1

APPENDIX C

EXAMPLE DICTIONARIES

C-l

CHAPTER

CONTENTS

(CONT.)

Page
APPENDIX D

MAXIMUMS

D-l

APPENDIX E

SUMMARY OF EDITOR COMMANDS

E-l

IQL EDITOR
TOPS-20 EDITOR

E-l
E-2

IQL ERROR MESSAGES

F-l

ERROR MESSAGES FROM IMMEDIATE MODE
ERROR MESSAGES FROM DEFERRED MODE

F-l
F-4

ASSOCIATED DOCUMENTS DESCRIPTIONS

G-l

E.l
E.2
APPENDIX F
F.l
F.2
APPENDIX G
INDEX

Index-l

FIGURES
FIGURE

1-1

Levels and Modes of IQL

1-3

TABLES
TABLE

1-1

Files Created by IQL

1-5

PREFACE

OBJECTIVES AND READER ASSUMPTIONS
The TOPS-lO/TOPS-20 Interactive Query Language User's Guide describes
the features of IQL Release 3.0, which is a full data management
system with comprehensive input,
update,
browse,
and
report
capabilities.
This guide describes each function in detail.
However, the guide is
not intended to be a teaching manual.
As a prerequisite of reading
this guide, it is recommended that you read the companion manual, An
Introduction to IQL,
which presents a series of example sessions
showing most of the features used in this guide.
The guide assumes that you are familiar with DBMS schemas and that you
know how to read a DBMS data base through FIND and GET operations of
IQL.

STRUCTURE OF THE DOCUMENT
The guide contains six chapters:
Chapter 1 explains file handling by IQL.
everyone.

Chapter 1 should be read

Chapter 2 explains how to access IQL and how to enter the various
levels of IQL.
Chapter 2 should be read by everyone.
Chapter 3 explains how to prepare a query file,
which you use to
generate a report.
Chapter 3 should be read by everyone.
Chapter 4 explains how to create, update,
and
Chapter 4 should be read by everyone.

read

data

file.

Chapter 5 explains how to prepare a dictionary, which defines to IQL
the data file or data base. The chapter should be read by
the data base administrator and programmer.
Chapter 6 explains how to use IQL in a batch job. Chapter 6 should be
read by the data base administrator and programmer.

vii

ASSOCIATED DOCUMENTS
TOPS-IO Introduction to IOL
DEC-IO-LIQLA-A-D
Started With TOPS-IO Commands
DEC-IO-OTSCA-A-D

G~tting

TOPS-IO Operating System Commands Manual
AA-0916C-TB
Getting Started With TOPS-20
AA-4187C-TM
TOPS-20 User's Guide
AA-4179B-TM
TOPS-20 EDIT User's Guide
DEC-20-UEUGA-A-D
TOPS-20 EDIT Reference Manual
AA-5415A-TM
TOPS-IO Data Baae Management System Programmer's Procedures Manual
AA-090IC-TB
TOPS-20 Data Base Management System Programmer's Procedures Manual
AA-4149B-TM
TOPS-IO Beginner's Guide to Multiprogram Batch
DEC-IO-OMPBA-C-D
TOPS-IO Multiprogram Batch Reference Manual
DEC-IO-OMBRA-A-D
TOPS-20 Getting Started With Batch
DEC-20-0BGSA-A-D
TOPS-20 BATCH Reference Manual
DEC-20-0BRMA-A-D

viii

STANDARD SYMBOLS
The following table explains the symbols used in this guide:

Symbol

Terminal
Key

(crw )

CTRL key

The control sequences control several of
the computer operations.
CTRL/C means
you should hold down the CTRL key and at
the same time type the letter C.

DELETE key
RUBOUT key

The rubout sequence deletes one character
each time you press the key.

ESC key
ALT key
ALTMODE key
PREFIX key

One
purpose
of the escape sequence
notifies the TOPS-20 Operating System to
complete the command that you began.
(When you are communicating with the
Operating System,
use of this key does
not produce a printed character.)
The
second purpose of the escape sequence
indicates to some system programs that
you
finished
the
work.
(When you
communicate with system programs using
the
escape key sequence,
the system
prints a dollar
sign
($)
on
the
terminal.)

RETURN key
CR key

The carriage return sequence notifies the
system that you have finished typing a
line.
After
you press this key, the
terminal printing head or cursor goes to
the beginning of the next line.
Unless
otherwise stated, all user input must be
terminated by pressing the RETURN key.

SPACE bar

The space bar creates a blank space
moving the terminal printing head
cursor one space to the right.

LINE FEED key
LF key

The linefeed symbol
indicates a place
where you press the key labeled LINE FEED
or LF.

Description

by
or

GLOSSARY

Alphavariable

An alphanumeric working item created by IOL while
generating a report. Names of alphavariables must
start with A, can be up to thirty characters long,
and can contain a - z, 0 - 9, and - . IOL creates
an alphavariable when it sees an item name starting
with A, does not find that name in the dictionary,
and determines that the information is read and
written
to
the
same
item.
IOL makes the
alphavariable as long as necessary to contain the
longest amount of information placed into it.

ASCII

The
American
Standard
Code
for
Information
Interchange is a binary code established by the
American National Standards Institute. The code as
applied to DIGITAL equipment can be either six bits
or seven bits and represents alphanumeric characters
and special symbols such as a semicolon (:), period
(.), and percent (%).

Assistance Level

The initial command level in IOL. In the assistance
level, you can display helping text, define and
inspect dictionaries, write or store or change
queries, request a report, create or update a data
file, or go to another command level.

Browse

A function of the immediate mode that permits you to
look at information in a file but not change it:
also referred to as read-only
access.
While
browsing, you can interactively position a file,
look at specific records or sets of records, and
list specific items for single records or sets of
records.

Constant

A pure number used anywhere in an IOL command.
Constants can contain decimals or can omit them •.
Constants can start with + or -:
if there is no
sign, IOL assumes the constant to be positive. It
is not necessary to supply leading or trailing zeros
in constants.
Examples of constants are: 1, 1.2,
.4567, -8.76, 00074, and 74.

Current Record

If a file is positioned at a particular record, that
record is called the current record. If the file is
positioned at the beginning (or top),
it
is
positioned before the first record and no current
record exits.
If the file is at the end (or
bottom), it is positioned after the last record and
no current record exits.

Data Item

An item (or field) in a record read by IOL from a
data file or data base. Data items can be numeric
or alphanumeric. Numeric data items can be binary
or ASCII characters. Descriptions of data-items are
stored by IOL in dictionaries. Data item names can
be up to thirty alphanumeric characters and dashes
and must start with a letter other than X.
IOL lists data-item names under the ITEM NAME column
title of a dictionary display.

DBMS

The full network CODASYL-standard data base
of Digital Equipment Corporation.

manager

Deferred Mode

The deferred mode and the immediate mode are the two
modes of IOL. In the deferred mode, IOL processes
query statements to generate reports and write
specific records from the data file to a new file.

Dictionary

A dictionary is a table stored by IOL that describes
a
data
file
or
data base.
IOL refers to
dictionaries when IOL generates reports and updates
or browses a data file. A dictionary stores the
location of a data file or data base, as well as
information about the individual data-items in the
file. Data-item entries in dictionaries contain
information describing how the items are stored and
cosmetic information anticipating printing (such as
column
titles
and editing pictures).
Example
dictionaries are shown in Appendix C.
Dictionary names must begin with an alphabetic
character and can contain up to thirty alphanumeric
characters and dashes.

DISK6

DISK6 is a 6-bit ASCII code.

DISK7

DISK7 is a 7-bit ASCII code.

Edit Level

IOL enters the edit level when you issue either the
WRITE or EDIT assistance command to write or edit a
query file.

FINDLIST

A FINDLIST is a qualifying argument of an immediate
mode command that instructs IOL to apply the command
to selective records in the data file.

Help Word

A help word is a key word that you submit to IOL for
a display of explanatory help text. To display a
list of the help words at your site, use HELP as an
IOL assistance command.

Item

An item is a symbolic term used in this guide to
indicate a data item, alphavariable, or numeric
variable.

Literal

A literal is any -string of characters enclosed in
quotes and used by IOL exactly as you specified.
You can set off a literal with either single (') or
double (") quotes as long as you start and end the
literal with the same quote mark. If you set off
the literal with one quote mark, you can include the
other quote mark in the literal.

xii

In the special literals used to designate page
headings or column titles, double slashes
(II)
instruct IQL to start a new line.
The following
lines are examples of literals.
"FEB 28"
'BOB "RED" JONES'
'LINE l//LINE 2'
Immediate Mode

The immediate mode and the deferred mode are the two
modes of IQL.
In the immediate mode, IQt processes
a command when you enter the command.
You can
display on the terminal selected items from a data
file, update a data file, and change, delete,
and
display a dictionary.

Integer

A special constant, always written without a decimal
point.

Operating System

The IQL User's Guide refers to the TOPS-IO and
TOPS-20 Operating Systems as the operating system.

Password

A password is a string of up to six alphanumeric
characters that are stored in encrypted form in a
dictionary.
As defined in a dictionary,
IQL can
require you to specify a password to read or change
sensitive data items in a data file.
You supply a
password to IQL when IQL prompts you for
the
password or when· IQL encounters
an
AUTHORITY
statement in a query.
Examples of passwords are:
CAROLE, BOB, 14WX6Z, MORDOR.

Query

A query is a collection of source statements written
like English language sentences that IQL uses to
generate one or more reports.
The statements in a
query are not carried out until you use the RUN or
EXECUTE assistance command.
Queries can be named
and stored.
Query names can be up to thirty
characters long, must start with an alphabetic
character,
and can contain alphanumeric characters
and dashes.

Report Leyel

The report level is the level that IQL enters when
you issue the RUN or EXECUTE assistance command to
generate a report.

Search Path

The Operating System uses a search path when looking
for
a file through two or more directories.
Refer
to Chapter I to establish a search path.

String

A string
spaces.

Summary

A summary is a line on a report that is calculated
by the TALLY, TOTAL, AVERAGE, MAXIMUM, or MININUM
query statements.

Update Level

The update level is the level that IQL enters when
you issue the UPDATE assistance command to IQL to
read or change a data file.

any

xiii

series

characters

including

Variable

A variable is a numeric working item generated by
IOL for reading and writing a value. Names of
variables must start with X or zz, can be up to
thirty characters long, and contain alphanumeric
characters and dashes. Variables for IOL contain
thirtee~ integer and five decimal places.

xiv

CHAPTER 1
FUNCTIONS OF IQL

Interactive Query Language - IQL - is a proprietary data management
system.
It provides both laymen and computer professionals with a
comprehensive ability to define data files, input or update the data
files,
obtain derivative files, retrieve information from data bases
or data files, and generate sophisticated reports.
For example, to produce a printed report entitled PERSONNEL LIST on
TOPS-20 Operating System, enter the following lines on a terminal:

f~IC~L..~

<CJA>WRITE ~
%FILE NOT FOUND~ CREATING NEW FILE
INPUT: QC017S.TMP.l
00100
OPEN PE:J~S()NNEL ~
00200
HEADING' PEF~S()NNEL LIST 'G£)
o 0 ~~ () ()
P F~ I NT NA ME ~ S () C- SEC ~ DATE ..-Hr~ , SAL A R Y G£)
~ $

O()4()O

*EGB
I:: C~C():L 78 + TMP + :l :J

(~PRINT C~C017S .I... PT + :l/DELETE G£)

The first line in the example enters IQL.
The second line in the
example allows you to enter the TOPS-20 text editor where you begin to
write a query.
OPEN

PEr~S()NNEL

The first query statement informs IQL which dictionary and which data
files
to read when IQL generates the report.
A dictionary, which the
data base manager creates with IQL, describes the data file to IQL.
A
dictionary also contains formatting information for the report.
HEADING 'PERSONNEL LIST'

The second query statement informs IQL of the heading to enter at
top of the report.
PRINT

NAME,SOC-SEC,DATE-HR~SALARY

1-1

the

FUNCTIONS OF IQL
The final statement directs IQL to create a print-formatted
each employee.

line

for

You terminate the text editor with the E command and generate the
print-formatted report file with the RUN assistance command.
Using
the TOPS-20 PRINT command, you print the report on the line printer.

1.1

LEVELS AND MODES OF IQL

IQL contains several command levels, each level containing a unique
set of commands.
IQL displays a message when you enter a level and
displays a message when you exit a level.
Figure 1-1 illustrates the IQL levels and the IQL commands you use to
move from one level to another level.
Upon entering IQL, as explained
in Chapter 2 in this guide,
you enter the assistance level.
For
instance to append data to a data file, you use the UPDATE assistance
command to enter the update level.
IQL enters the update level and
displays a prompt indicating that IQL is ready to accept an update
level command.
You then use the APPEND update level command to enter
the input level.
IQL displays a prompt for each field in the data
file.
To terminate the input level, use the EXIT input level command
and to terminate the update level, use the EXIT update level command.
IQL then returns to the assistance level.
In addition to the levels of IQL, Figure 1-1 shows the two modes of
IQL.
In the immediate mode, IQL performs the DEFINE, BROWSE, UPDATE,
and INPUT level commands as soon as you terminate a command with the
~arriage
return.
In the deferred mode, you write a query at the edit
level.
At the other levels, IQL analyz~s the query and generates a
print-formatted file.

1-2

MONITOR LEVEL
RIOL
RUNIOL
END
IOL
EXIT
IOL ASSISTANCE LEVEL
(Creates and displays dictionaries and queries, gives help, and controls the remainder of IOU

I
DEFINE

UPDATE

BROWSE
END
EXIT
SCRUB

I-'

END
EXIT

INPUT
END
EXIT

EDIT

WRITE

EXECUTE

RUN

EUN

Only if
error in
query

UPDATE LEVEL

EDIT LEVEL

ANALYSIS LEVEL

(Retrieves from a data
file, carrying out each
command as you enter
it. File changes are
not permitted.)

(Retrieves from or
creates or changes a
data file, carrying
out each command
as you enter it.)

(Uses TOPS text editor
to change a nonanalyzed
query.)

(Analyzes the state·
ments in a nonanalayzed
query.)

automatic

I"%J

(")

8
H

o
Z

tI.l

I"%J

INSERT
APPEND
DICTIONARY
DEFINITION
LEVEL
(Prompts field by
field to create or
change dictionary
entries.)

INPUT LEVEL
(Prompts field by field
to make new data
records in a data file.)

escape
key
EDIT INPUT
LEVEL
(Inputs new statements to a query.)

- - - - - - - - - - - - - - - - immediate mode

(automatic)

10
t"I
EXECUTION
LEVEL
(Follows statement
analysis; Passes one or
more data fi les or a
data base to prepare
reports and/or output
files.)

deferred m o d e - - - - - - - - - - - -

Figure 1-1

Levels and Modes of IQL

FUNCTIONS OF IQL
1.2

ACCESSING DIFFERENT FILE STRUCTURES

IQL handles sequential, Indexed Sequential Access Method
(ISAM),
and
Data Base Management Systems (DBMS) file structures. A file structure
determines the method that IQL uses to access information in a
file.
To write to a file, IQL collects a set of data and writes it into the
file as a record.
A record is the smallest unit of information that
the system reads and writes when it accesses a file.
For instance, to
read an address of a customer or
the year-to-date purchases of a
customer,
the system must read every record from the beginning of the
sequential file in order to arrive at the desired information.
For
the system to read the same information in an ISAM file, the system
proceeds directly to the records associated with the customer that you
request.
For a DBMS file structure, the system reads only the record
containing the data you request.
IQL locates data files or data bases on device DSK:
and follows
the
search path that exists for DSK:.
If you wish to access a file in a
directory other than the directory in which you logged into the
system,
you must set up a search path.
For instance, by using one of
the following Operating System command sequences, you can set up a
search path which the system uses to locate a file.
(~'DEFINE

(LOGICAL NAME) [lSK: <DIRECT1>, ·:::DIRECT2>

.f.: SETSF~C ~

(TOPS-20)
(TOPS-IO)

DIRECTI is the directory that you logged into the system and DIRECT2
is the directory where you want the system to continue the file
search.
If the system cannot find the file
in DIRECTl,
the system
searches DIRECT2 for the file.
Refer
to the TOPS-IO Operating
description of the SETSRC program.

System

Commands

Manual

for

If you specify more than two directories in the search path, IQL looks
in each directory, from left to right, until IQL finds the file.
If
you frequently use a
search path, you or
the on-site software
specialist can set up a search path in the LOGIN.CMD file.
The system
automatically reads the LOGIN.CMD file immediately after you log into
the system.
Refer
to the Operating System user's guide (such as as
the TOPS-20 User's Guide) for more information.

1.3

USING RESERVED KEYWORDS

The words,
abbreviations,
and symbols listed below have special
meanings in IQL.
You should avoid using reserved keywords as
data-item names in dictionaries or as item values.
However,
you can
use a reserved keyword if you enclose it in quotes.
ALL
AND
APPEND
BOTTOM
CHANGE
COLUMN
DELETE
DOWN
END
EQ
EQUAL
EQUALS

EXIT
FIND
FIRST
FOR
GE
GEQ
GQ
GR
GREATER
GT
IF
IN

INPUT
INSERT
IS
LE
LEQ
LESS
LIST
LQ
LS
NE
NEQ
NEXT

1-4

NOT
NQ
OR
PRINT
QUERY5
RECORD
RECORDS
RECOVER
SAVE
TO
TODAY
TOP

UP
UPDATE
VERIFY
WHEN
WHERE
XRANDOM

<
>

FUNCTIONS OF IOL
1.4

DELETING IOL FILES

Although you need not understand this section to use IOL, DIGITAL
recommends that you read this section before you delete any files from
the directory.
IQL creates permanent and temporary files in the login directory to
store· dictionaries, queries, data files, and print-formatted reports.
Table 1-1 lists the filenames created by IQL that you can display by
using the TOPS-lO or TOPS-20 DIRECTORY command. The table uses the
symbolic term, job, in filenames such as QCjobS.LPT.
The symbolic
term,
jobs, refers to the actual job number that the Operating System
assigns when you lpg into the system. For instance, if the job number
is 17, IQL creates a filename such as QC017E.LPT in the directory.
Table 1-1
Files Created by IQL
File
Name

Assistance
Command

File
Structure

QPDICT.SEQ
QLjobD.LPT

DEFINE
DEFINE

sequential
sequential

One or more dictionaries
of
Line printer file
dictionary
changes or
full
dictionary
contents.

QCjobS.TMP
QCjobS.QMP

EDIT
EDIT

sequential
sequential

QC jobS. TMP.

WRITE

sequential

Current query area.
Previous current query
area.
Current query area.

QCjobE.LPT
QCjobE.LPT

RUN or
EXECUTE

sequential
sequential

Print-formatted report.
Print-formatted report.

name.QRY
name.QRY

RUN or
SAVE

sequential
sequential

One analyzed query.
One analyzed query.

name.OUT
name.OUT

RUN or
EXECUTE

sequential
sequential

Copied data file
(same format) •

name. type
name. type

RUN or
EXECUTE

sequential
sequential

Copied data file
(same format) .

name. type
name.type
name.type
name.type

UPDATE
UPDATE
INPUT
INPUT

sequential
ISAM
sequential
ISAM

One data
One data
One data
One data

QLjobU.LPT
QLjobU.LPT
QLjobU.LPT

INPUT
BROWSE
UPDATE

sequential
sequential
sequential

One line diary file.
One line diary file~
One line diary file.

QPQRYS.SEQ
QPQRYS.SEQ

REPLACE
STORE

sequent·ial
sequential

One or more
nonanalyzed queries.

1-5

File
Contents

file.
file.
file.
file.

FUNCTIONS OF IOL
In addition to the EXECUTE and RUN assistance commands, the COpy query
statement also creates a sequential data file with the filename of
either name.OUT or name. type. The .OUT file type is supplied by IOL
when you omit a file type specification to IOL.
Some of the temporary files, such as the OCjobS.TMP file, are deleted
by IOL when, for instance, you use a second WRITE assistance command
in the same IOL session or when you use the EXIT assistance command to
terminate an IOL session. Generally when you conclude an IOL session,
you should either:
1.

Use the TOPS-IO or TOPS-20 DELETE command to remove
files that IOL does not delete.

unwanted

Use the TOPS-IO or TOPS-20 PRINT command
switch to print print-formatted files.

/DELETE

with

the

Except for print-formatted files, IOL deletes an existing file before
creating another file using the same filename. For print-formatted
files, IOL creates another file with a unique filename by incrementing
the first digit of the job number in the filename. For instance, if
you issue a second RUN assistance command in the same session and IOL
encounters the file OL017E.LPT in the directory, IOL writes the new
report(s) to the new file OLl17E.LPT.

1-6

CHAPTER 2
RUNNING IQL

Depending upon how IQL is implemented at the site, you begin IQL from
t~e Operating System with one of the following command sequences:
I(~I...~

or
f~

IC~L~

or
HUN IC~J... ~

or
F~UN DEVICE: <DIRECTDRY>IQL.. ~

You terminate the command with a carriage return which permits the
Operating System to execute IQL.
IQL displays a <QA> prompt and
expects you to input an assistance command.
NOTE
For
IQL to run,
the ISAMF6.IDX and
ISAMF7.IDX
files must exist in the
search path.
The files are supplied to
the site on the IQL Distribution Tape.

2.1

EXPLAINING IQL PROMPTS

The following list explains the prompts that IQL displays and
the
responses that IQL expects.
You terminate the response with a
carriage return, which permits IQL to accept the response.
1.

<QA>
The <QA> prompt indicates that IQL is waiting for you to type
an assistance command.
For instance, IQL displays:

<QA>
You respond with an assistance ,command such as:
«~A> ITEMS

INVENTDf~Y ~

2-1

RUNNING IQL
2.

<QU>
The <QU> prompt indicates that IQL is waiting for you to type
an immediate mode command. For instance, IQL displays:

<ou>
You respond with an immediate mode command such as:
<C~U>L..IST

ALL DEPT

42:L~

*prompt:
A prompt that begins with an asterisk (*)
and ends with a
colon (:)
indicates that IQL wants you to type an item of
data. For instance, IQL displays:

*DESCRIPTION (IF ANY>:
You respond by typing a line such as:

*DESCfnPTION (IF ANY>:

2.2

VALUE FOF~ ITEM ~

EXPLAINING MESSAGE FORMATS

IQL displays messages as follows:
1.

(message)
IQL displays progress reports or information messages and
encloses them in parentheses. You are not required to take
any action.
For instance, IQL displays:

(END OF UPDATE SESSION)
The message informs you that IQL
mode.
2.

exiting

the

immediate

warning

messages.

% message

Messages starting with a percent sign are
For instance, IQL might display:
% CANNOT FIND THIS DICTIONARY

The message informs you that IQL cannot locate the dictionary
that you specified in an assistance command. Repeat the
command with a valid dictionary or use the DICTIONARY
assistance command to display the names of the dictionaries
in the directory.

2-2

RUNNING IQL
2.3

USING ASSISTANCE COMMANDS

To enter an assistance command, you need only supply enough of the
command to uniquely identify it.
(For instance, DIC is enough to
identify the DICTIONARIES command.)
If IQL expects more words in the
command,
IQL displays a prompt and ends it with a colon (:).
You
terminate the command with a carriage return,
which permits IQL to
perform the function.

2.3.1

Controlling and Displaying the IQL Job

Use the JOB assistance command to display the job number.
The system
uses the job number to name temporary and print files that you may
wish to access outside of IQL.
Use the EXIT or END assistance command
to terminate IQL and to return to the Operating System.

2.3.2

Creating, Editing, and Saving a Query

When you first write a query with either the EDIT or WRITE command,
IQL enters the information into the current query area.
IQL uses the
current query area as a work space.
The current query area contains
the source query statements that you enter following the EDIT or WRITE
assistance command.
The source query statements are described in
Chapter 3.
You can store the current query area into a file with
either the STORE or SAVE command. With the STORE command, IQL writes
the nonanalyzed current query area into a permanent disk file.
with
the SAVE command, IQL analyzes the source query statements from either
the current query area or a nonanalyzed query file and writes the
analyzed query into a permanent disk file.
If you attempt to store or
save a query without naming it, IQL prompts you for a query name.
To work with a nonanalyzed query file,
you must return it to the
current query area by using the query name with either the GET, EDIT,
LIST, RUN, or SAVE command.
You can edit a nonanalyzed query file
after you return it to the current query area.
You cannot return an
analyzed query to the current query area and edit the analyzed query.

2.3.3

Using a Query File to Generate a Report

IQL first analyzes the query instructions and then performs them.. Use
the RUN command to analyze the query and to generate the report(s)
from a nonanalyzed query.
The nonanalyzed query can be located in
either the current query area or in a nonanalyzed query file.
Use the EXECUTE command to generate a report from an analyzed query.
Before using the EXECUTE command, you must analyze and save the
nonanalyzed query with the SAVE command.
Generating a report from an
analyzed query is faster than generating a report from a nonanalyzed
query.

2.3.4

Maintaining Query Files

IQL retains nonanalyzed queries in a single file and analyzed queries
in separate files.
Use the QUERIES command to list the nonanalyzed
queries.
Use the DELETE command to remove a nonanalyzed query and the
REPLACE command to replace a stored nonanalyzed query with the
contents of the current query area.
2-3

RUNNING IOL
2.3.5

Creating and Changing a Data File

Use either an INPUT, UPDATE, or BROWSE command to create, update, or
read a data file.
You can only create and modify sequential and
indexed sequential data files. Refer to Chapter 4 in this guide for
more information.

2.3.6

Creating and Changing a Dictionary

A dictionary defines the data base or data file to IQL.
Use the
DEFINE, DICTION~RY, and ITEMS commands to manipulate a dictionary.
The DEFINE command permits you to create a new dictionary or to change
an existing dictionary. Although IQL checks the dictionary changes or
additions as you enter them, IQL does not physically create or change
the dictionary until you enter an END dictionary command. Refer to
Chapter 5 in this guide for a full description.

2.4

ASSISTANCE COMMAND FORMATS

The assistance commands use the following command conventions:
1.

First character location
The command begins in the first character location
<QA) prompt.

afer

the

One or more spaces separate a command from a parameter.
one or more spaces separate parameters.

Also

Space

Lowercase and uppercase characters
A parameter identified by lowercase characters indicates that
you are to supply a variable as indicated by the variable
name.
A parameter identified by uppercase characters indicates that
you are to supply the exact characters as they are shown in
the text. Usually, an uppercase parameter is an option to
the command and provides you with additional functions to the
command.

Square brackets [ ]
A parameter enclosed in square brackets indicates an optionai
parameter.
Do not use the square brackets in the assistance
commands you write; the square brackets indicate an optional
parameter.
When you do not supply the parameter, the system
applies a default value as explained in the parameter
description.
A parameter not enclosed in square
the system requires the parameter.

2-4

brackets

indicates

that

RUNNING IQL
5.

Examples
In the examples, data you enter is shown in red print whereas
data the system displays is shown in black print.

The remainder of the
alphabetical order.

chapter

presents

2-5

the

assistance

commands

RUNNING IOL
BROWSE
FUNCTION:
The BROWSE assistance command places IOL in the immediate mode
but restricts to read-only access the sequential or indexed
sequential data file
(subject to any password requirement).
Refer to Chapter 4 in this guide for a description of the
immediate mode.
The BROWSE assistance command is similar to the UPDATE assistance
command, except that you can only read the data file.
FORMAT:
BROWSE

dictionary-name

[filename]

DISCUSSION:
Specify a dictionary name that' IOL can find in the login
directory.
You can request IOL to display a list of the
dictionaries with the DICTIONARIES assistance command.
If you supply a filename, IOL uses that filename rather than the
filename in the dictionary.
The filename must follow the
ffffff.ext naming convention, where ffffff is one to
six
alphanumeric characters and ext is one to three alphanumeric
characters.
If the file is protected at the READ level, IOL asks you for the
password and checks it before unlocking the file for browsing.
EXAMPLES:
1.

<QA>BROWSE CUSTOMERS G!D
(YOUR DIARY FILE IS: QL039ULPT
(CnDLIST IF CUSTNO ::: 23G!G
00023DEEPSEA DIVERS, INC
DENISE DU BOIS
DEEPSEA LAN
MIAMI
FL29375000067777000067777000100000
<QU:::£ND0iG
(END OF UPDATE SESSION)
(QA>

IOL lists the first record that qualifies.

2-6

RUNNING IQL

<C:~A>BI~OWSE

CUSTOMERS G!I)
(YOUR DIARY FILE IS: QL039ULPT )
«~U>LIST ALL. IF CUSTNO =:: 23 GID
00023DEEPSEA

DIVERS~

INC

MIAMI
0002:'~JOHN JONES
BOSTON
AL WHARF
0023PACEF~ DEVICES
CHICAGO
AVE.

DENISE DU BOIS
DEEPSEA L.AN
FL29375000067777000067777000100000
BILL WIL.LIAMS
14 COMMERCI
MA01832000232479000046700000250000
WILLARD J. HOLMES
47 BAYPORT
IL60477000233175000100000000250000

(AT END OF FILE)
<C~U>END ~

(END OF UPDATE SESSION)

<C~A>

IQL lists all the records that qualify.
Since the example
did not request any particular items after the word list, IQL
displays the entire record.
3•

<C~A>BROWSE PEF~SONNEL

GID

(YOUR DIARY FILE IS: QL039ULPT )
<QU>LIST FNAME INIT LNAME PHONE ALL IF STATE = COLORADO
( 449 ) 989· ·190 1
(045)211-0912
( 379 ) 491 M-~)73'7

S NELMS
KEVIN
G ZAI:~ZEl,JSKA
IRENE
p KOUF~ANEY
OSCAR
(AT END OF FILE)

<OU>END~

(END OF UPDATE SESSION)
<OA>
The EMPLOY.NEW filename overrides the filename contained in
the dictionary.
Also the example requests that IQL display
specific items from the records that qualify.

2-7

RUNNING IQL
DEFINE
FUNCTION:
The DEFINE assistance command defines the dictionary transactions
to create or update an IQL dictionary.
FORMAT:
DEFINE
DISCUSSION:
When you terminate a DEFINE session with the END dictionary
command, IQL creates or updates the dictionary based on the
transactions you enter. If you terminate a DEFINE session with
the SCRUB dictionary command, IQL aborts the DEFINE session and
does not change or create a dictionary. Refer to Chapter 5 in
this manual for more information. Three example dictionaries are
shown in Appendix C.
EXAMPLE:
I.

<OA> fiEF I NEG!D
*FD,DD,PD,CD,RD,ADySD,END,SCRUB:
*ACTION CODE (A,C,D OR P):
*DICT NAME - UP TO 30 CHARS:
*DICT UNLOCKING PASSWORD, IF ANY:
*FILE IN NAME AS XXXXXX.EEE:

FD~
C~
PERSONNEL~
SESAME~

NEXTQID

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
DDQID
*ACTION CODE (A,C,D):
C~
*ITEM NAME (UP TO 30 CHARS):
NAMEGiD
*TOP COLUMN TITLE (UP TO 10 CHARS): FULL NAME~
*BOTTOM TITLE (UP TO 10 CHARS):
NEXT~
END~

(END DICTIONARY TRANSACTION INPUT)
(END DICTIONARY UPDATE)
<QA>
The example illustates changing a dictionary named PERSONNEL.
The first transaction - FD - supplies a password to IQL and
explains to IQL that you wish to change information located
in the dictionary. IQL unlocks the dictionary. The second
transaction - DD - changes the top column title of the item,
NAME, to FULL NAME. All the other dictionary fields remain
unchanged.

2-8

RUNNING IQL
DELETE
FUNCTION:
The DELETE assistance command removes the stored
query(s) from the QPQRYS.SEQ file of stored queries.

nonanalyzed

FORMAT:
DELETE

query-name [ ... query-name]

EXAMPLES:
1.

<C1A> DELETE IF··.. BOI~T····CUTOF~- JACKTEBT ~
(IF-BORT-CUTOFF DELETED)
(JACKTEBT DELETED)
«~A>

<UA> DELETE CHARLIE BETH CLAIRE ~
(CHARLIE DELETED)
X BETH NOT FOUND TO BE DELETED (CLA I 1:<[ DEL.ETED)
<[~A>

In the second example, IQL could not find a query with the
name BETH.
IQL displays a warning message and then deletes
the query CLAIRE.

2-9

RUNNING IOL
DICTIONARIES
FUNCTION:
The DICTIONARIES assistance command provides a terminal display
of the file information for each dictionary in the directory.
FORMAT:
DICTIONARIES [master-password]
DEFAULTS:
IQL proceeds to display a list of the
encounters
a
protected
dictionary,
information and displays the dictionary
directory entries.

dictionaries.
If IQL
IQL omits protection
name,
file
type,
and

DISCUSSION:
The column headings in the diiplay are explained as follows:
DICT NAME

The DICT
names.

NAME

FILE TYPE

The FILE TYPE column lists, for the data file,
the file structure and the data format.
The
file structure can be SQ for sequential files,
IS for
ISAM files, or DTABASE for DBMS files.
The data format can be DISK6 for
6-bit ASCII
format or DISK7 for 7-bit ASCII format.

FILE-IN NAME

The FILE-IN NAME column lists the name of
data file that the dictionary describes.

DIRECT

The DIRECT column lists the directory where IQL
can find the data file.

REC LEN

The REC LEN column defines as the number of
ASCII characters the logical length of the data
file record.

BLK FAC

The BLK FAC column describes the number of
records per block;
0 means that the system
takes care of the blocking factor.

KEY LOC

The KEY LOC column lists, for ISAM files,
the
character
location
in the record of the
leftmost character of the key.
(The leftmost
character location in a
record is character
position 1.)

KY LN

The KY LN column lists,
for
ISAM files,
length in ASCII characters of the key.

KY TP

The KY TP column lists, for ISAM files, the key
type.
A key type of AU is an alphanumeric key.
A key type of NS is a signed numeric key.
A
key type of NU is an unsigned numeric key.

2-10

column

lists

the

dictionary

the

RUNNING. IQL

RO PW

The RO PW column lists the read password
reference, which occurs later in the dictionary
and protects against unauthorized reading of
records from the data file.

CP PW

The CP PW column lists the copy or write
password reference, which occurs later in the
dictionary and protects against unauthorized
creating, copying, and updating of records from
the data file.

RW PW

The RW PW column lists the rewrite password
reference, which occurs later in the dictionary
and protects against unauthorized changing of
records in an ISAM data file.

EXAMPLE:

(aA) DICTIONARIES

SESAME~

DICTIONARIES IN YOUR DI~ECTORY:
DICT
NAME

FILE
TYPE

FILE-IN
NAME

DIRECT

INVENTORY sa DSK7 INVENT. SEQ
PERSONNEL IS DSK7 PERSON.IDX

.JANE

REC BLK KEY KY KY RD CP RW
LEN FAC LOC LN TP PW PW PW
:LEW
600

o
5

5 AU 10 20 30

(END LIST OF DICTIONARIES)
(QA)
contains
the
As shown in the example, the directory
The INVENTORY
dictionaries
INVENTORY
and
PERSONNEL.
dictionary describes a sequential data file by the name of
INVENT.SEQ located in the directory, <JANE>. The PERSONNEL
dictionary describes an ISAM data file by the name of
PERSON. lOX located in the login directory.

2-11

RUNNING IQL
EDIT
FUNCTION:
The EDIT assistance command transfers control to a text editor to
edit or change either the current query area or a stored
nonanalyzed query in the QPQRYS.SEQ file of stored queries.
FORMAT:
EDIT [query-name]

[LIST]

DEFAULTS:
If you omit a query name, IQL edits the current query.
If you
omit the LIST option, IQL does not list the query before entering
the editor.
DISCUSSION:
If you furnish a query name,
IQL moves the contents of the
related query to the current query area before entering the
editor.
IQL enters an editor within IQL when you execute IQL under
the
TOPS-IO Operating System.
IQL enters the EDIT editor when you
execute IQL under the TOPS-20 Operating System.
Appendix E In
this guide explains the IQL editor and provides a summary of some
of the TOPS-20 EDITOR commands.
EXAMPLES:

<QA> EDIT NEWHIRES LIST~
**NEWHIF~ES

OPEN F'EF~SONNEL.
HEADING 'LIST OF NEW HIRES'.
IF DATE-HR LEQ 77 PRINT NAME, DEPT, DATE-HR.
EDIT: QC014S.QRY
*GD
00100 OPEN PERSONNEL.
*I.~

00150

DISPLAY ON.G!D

*FHEADING~$

00200

HEADING 'LIST OF NEW HIRES'.
JANUARY 1~$. ~
HEADING 'LIST OF NEW HIRESIISINCE JANUARY 1'.

*SHIf~ESGD$HIRESIISINCE

00200

*GU
00300

IF DATE-HR LEQ 77 PRINT NAME, DEPT, DATE-HR.

*SLE(~~$GEQ~.~

00300 IF DATE-HR GEQ 77 PRINT NAME, DEPT, DATE-HR.
*PI00 ~
00100 OPEN PERSONNEL.

2-12

RUNNING IQL
*P~

00100 OPEN ~ERSONNEL+00150 DISPLAY ON.
00200 HEADING 'LIST OF NEW HIRESIISINCE JANUARY 1'.
00300 IF DATE-HR GEQ 77 PRINT NAME, DEPT, DATE-HR.
*EUNQID
I:: aco 14S. (~RY::J

<QA>
In example 1, line 150 is added, the report heading
changed, and the IF clause is changed from LEQ to GEQ.

IQL lists the NEWHIRES query and enters the text editor. The
first editor command, the linefeed key, displays the first
query statement, which is the first line in the query.
The
second editor command, the I character and a period, enters
the editor into the insert mode. You then add a line between
the
first
and
second
query statements.
The editor
automatically terminates the insert mode when you press the
carriage return key.
With the third editor comm~hd, the
FHEADING$ sequence, you request the editor to find the first
line that contains the character string HEADING. The editQr
displays the line when the editor finds the character string.
With the fourth editor command, another line feed, you
display the line following the report heading line.
The
sixth editor command, the SLEQ$GEQ$.
character string,
requests the editor to change the LEQ sequence to GEQ.
The
PIOO editor command· lists the query with all the changes.
The E editor command exits the editor and returns control to
IQL.
2.

<C~A>EDIT
NEWHIRES
LIST ~
**NEWHIHE!:>
OPEN PERSONNEL.
HEADING 'LIST OF NEW HIRES'
IF HIRE-YR LEQ 77 PRINT NAME, DEPT, HIRE.

*LGD
OPEN PERSONNEL.
*I.GE)
DISPLAY ON.~
*FHEADING:C!EO
HEADING 'LIST OF NEW HIRES'.
*SHIF~ES nHI=\:ESIISINCE JANUARY :L:.CE2)
HEADING 'LIST OF NEW HIRESIISINCE JANUARY I'.
*t..G!!)

IF HIRE-YR LEQ 77 PRINT NAME, DEPT, HIRE-YR.
*Slo.[CH GE(~: .G!D
l~ HIRE-YR GEQ 77 PRINT NAME, DEPT, HIRE-YR.
*TOP~

OPEN PERSONNEL.

*P;AL..I...~

OPEN PEr~SONNEL.
DISPLAY ON.
HEADING 'LIST OF NEW HIRESIISINCE JANUARY 1'.
IF HIRE-YR GEQ 77 PRINT NAME, DEPT, HIRE-YR.

*END~
«~A>

In example 2, the same edits are performed as explained in
example 1.
However, example 2 shows the IQL editor on the
TOPS-IO Operating System.

2-13

RUNNING IQL
EXECUTE
FUNCTION:
The EXECUTE assistance command generates a report from an
analyzed query file.
FORMAT:
EXECUTE query-name
DISCUSSION:
You must specify an analyzed query.
Each analyzed query file
uses the extension of .QRY. Refer to the SAVE command for more
information on analyzed query files.
If you expect to use a query frequently without changing it, you
can save computer time by analyzing the query once, saving it,
and using the EXECUTE assistance command each time you want a
report.
with the EXECUT& assistance command, IQL bypasses the
analyze stage and produces the report.
This procedure is
particularly useful if you are using IQL as a report writer in a
production stream with other programs.
EXAMPLE:
1.

<QA> EXECUTE

NEWHIRES ~

... (the report goes here if routed to terminal) ...
<QA>

Immediately after you issue the EXECUTIVE assistance command,
IQL looks for the HIRE.QRY analyzed query file, reads the
data file, and generates the report(s).

2-14

RUNNING IQL
EXIT
FUNCTION:
The EXIT assistance command returns control from
Operating System and displays an exit message.

IQL

the

FORMAT:
EXIT
DISCUSSION:
When you terminate the IQL session, IQL deletes all the working
files it creates, including the current query area. To preserve
the current query area before you terminate IQL, use the STORE
assistance command.
EXAMPLES:
1.

«~A>

EXIT ~

EXIT
(~

You terminate IQL and return to the TOPS-20 Operating System.
2.

«~A> EXIT @)

EXIT

You terminate IQL and return to the TOPS-IO Operating System.

2-15

RUNNING IQL
GET
FUNCTION:
The GET assistance command moves a nonanalyzed query
file of stored queries into the current query area.

from

the

FORMAT:
GET [query-name]

[LIST]

DEFAULTS:
If you omit a query name, GET uses the current query area,
remains unchanged.

which

If you use the LIST option, IQL displays the name of the query
and the contents.
If you omit the LIST option, IQL displays the
name of the query.
DISCUSSION:
If you use a query name, IQL writes the query from the file of
nonanalyzed stored queries into the current query area.
The GET
command destroys the previous contents of the current query area.
EXAMPLES:
1.

<OA>GET~

**BLUE-EYES
<QA>
IQL lists the current query name, which is BLUE-EYES.
2.

<QA> GET
L..IST~
**BLUE--EYES
OPEN APPLICANTS.
IF COLOR-EYES = 'BLUE' SORT BY STATE, CITY.
PRINT NAME, STATE, CITY, AGE.
<QA>
IQL lists the contents of the current
already contains the query BLUE-EYES.

query

area,

which

GET
NEWH I r~ES G!D
**NEWHIRES
<QA>
«~A>

IQL retrieves the query NEWHIRES from the file of nonanalyzed
queries to the current query area and lists the query name.
4.

«~A>

GET
NEWHIRES
LIST G!D
**NEWHIRES
OPEN PERSONNEL
HEADING 'NEW HIRES SINCEIIJANUARY 1, 1977'
IF HIRE-DATE GEQ 770101 PRINT NAME, DEPT, HIRE-DATE
<QA>
IQL retrieves the query NEWHIRES from the file of nonanalyzed
queries to the current query area and lists the query.
2-16

RUNNING IQL
INPUT
FUNCTION:
The INPUT assistance command places IQL into the input level.
In
the input level,
you enter data on the terminal keyboard to
create sequential data files.
Refer to Chapter 4 in this guide
for more information on the input level.
FORMAT:
INPUT

dictionary-name

[filename]

DEFAULTS:
Before IQL prompts you for field values, IQL initially sets
record in the data file to all spaces.

each

DISCUSSION:
If you omit a dictionary name, IQL prompts you for a name.
If you also enter a filename, IQL uses the filename you enter
instead of the filename
in the dictionary.
The filename must
follow the ffffff~ext naming convention, where ffffff is one to
six alphanumeric characters and ext is one to three alphanumeric
characters.
If IQL finds that the file already exists in the directory,
IQL
displays a message and enters the update level (that is, the
INPUT assistance command does not permit you to write over an
existing file).
In the update level, you can change the data
file.
Refer to Chapter 4 for more information on the update
level.
If IQL finds that the dictionary contains a password protection
at the READ or WRITE level, IQL prompts you for the password and
checks it before permitting you access.
IQL begins the input level by issuing a prompt for
the first
field in the first record and waits for the response.
IQL
prompts you for item values in the order in which IQL finds
the
items in the dictionary.
IQL issues a prompt for the next field
in the record and continues the prompts until IQL encounters the
'end of the dictionary, you direct IQL to perform something else,
or you enter the END or EXIT input command.
When you terminate
the input level with the END or EXIT input command, IQL returns
to the assistance level.
Refer
to
the
INSERT
command
description,
located in Chapter 4, for a list of the commands to
control the input level and for an explanation of the error
handling.

2-17

RUNNING IQL
EXAMPLE:
l.

<CJA> I NPUT
CUSTOMERS ~
(THE DIARY FILE IS QL023U.LPT)
(NEXT F~ECOFUI)
*NUMB (CUSTOMER NUMBER) 5 N:
*NAME (CUSTOMER NAME) 30 A:
*SLSMAN (SALESMAN NAME) 25 A:
*CITY (CUSTOMER CITY) 15A:
*NAME (CUSTOMER NAME) 30 A:
*SLSMAN (SALESMAN NAME) 25 A:
*CITY (CUSTOMER CITY) 15 A:
*CYSLS (CURR YR SALES) 8.2 N:
*LYSLS (LAST YR SALES) 8.2 N:
*CLIMIT (CREDIT LIMIT) 8.2 N:

~54G!0

PORTABLE DEVICES GIQ
CAf~LETON SCOTT ~
UP 2~
PORTABLE DEVICES CED
DOWNG!0

ST.

LOUIS~

$1,500.~

3012.46G!:)

NEXTQ:D

(NEXT F~ECOF~D)
*NUMB (CUSTOMER NUMBER) 5 N: 37
... (continues until you terminate it with END or EXIT) ...
... (you terminate the input level with END or EXIT) ...
<QA>
The example shows IQL prompting for the creation of a
complete record. IQL found the data item descriptions in the
CUSTOMERS dictionary in the order of NUMB, NAME, ... , LYSLS,
and CLIMIT.
Also, notice that the UP 2 input command was used to go back
two prompts and correct an error for the data item, NAME.

2-18

RUNNING IQL
ITEMS
FUNCTION:
The ITEMS assistance command formats and displays the contents of
a dictionary.
FORMAT:
ITEMS

dictionary

[master-password]

DEFAULTS:
If you omit the password and IQL finds that the dictionary or an
item is protected, IQL obscures any information that would allow
you to locate the protected item.
DISCUSSION:
IQL formats the dictionary contents for a
display line.

72-character

terminal

You can also print the dictionary contents on the line printer.
As explained in Chapter 5, the FD dictionary command formats the
dictionary contents for a l32-character line and displays the
formatted contents on the line printer.
IQL displays the information in two sections.
The first section
is a description of the dictionary and the data file.
Refer to
the DICTIONARY assistance command for
an explaination of the
first
section.
The second section of ihe display is a
description of the dictionary contents labeled with column
headings.
Refer
to Chapter 5 for a description of the second
section.
EXAMPLE:

«~A>

DICT
NAME

ITEMS

PERSONNEL

SESAMEG£)

FIL.E
TYPE

FII...E""IN
NAME

DIRECT
.. H

PERSONNEL IS DSK7 PERSON.IDX
ITEM
1D NAME
p£r

TOP
TITLE

.....................

<JANE>

BOTTOM
TITLE

TIGEF~

PD BEAR
F'D FOX
[In EMPNO
EMPLOY
[II) L.NAME-CH LNAME
•••••

REC BL.K '-(EY KY KY FUr CP RW
LEN FAC LOC LN TP PW PW PW
600

5 AU 10 30 50

1ST NO. T S PRINTING SCAN
CHAR CHAR Y C PICTURE GNNS PT
.... _- - - -_._-_ .....-

~:;O

NUMBER

30
10
:I.

CHAF~

5 N 0 ZZZZ9

1 A0

<t~A>

The example shows a display of the PERSONNEL dictionary.
The
password,
SESAME, was specified to IQL so that IQL could
di~play the passwords in the PD entries.
2-19

RUNNING IQL
JOB
FUNCTION:
The JOB assistance command displays the job
Operating System assigns to the IQL session.

number

that

the

FORMAT:
JOB
DISCUSSION:
IQL uses the job number as an ingredient for naming its temporary
and print files.
The job number can be useful if you wish to
work with these files outside of IQL. Chapter 1 in this guide
describes the specific files that IQL uses.
EXAMPLE:
1.

<t~A>

JOB @)
JOB NUMBER:

~52

<C~A>

2-20

RUNNING IQL
LIST
FUNCTION:
The LIST assistance
nonanalyzed query.

command

displays

the

contents

FORMAT:
LIST

[query-name]

DEFAULTS:
If you omit a query name, IQL lists'the current query area.
If you supply a query name, IQL moves the nonanalyzed query from
the file of stored queries into the current query area and
displays it.
EXAMPLES:
1.

<QA> LISTG!)

**MARKET-PROJECT
OPEN PROSPECTS
COMPUTE EXPECTED = EXPECTED * 1.1
TOTAL EXPECTED BY REGION, DISTRICT
MAXIMUM EXPECTED BY REGION, DISTRICT
«~A>

The example lists the current
MARKET-PROJECT.
2.

<QA> LIST

query

area,

which

named

PROSPECT-DETAIL~

**PROSPECT-DETAIL
OPEN PI:~OSPECTS
HEADING 'PROSPECTIIDETAIL'
PRINT PROSPECT, DATE-IN, EXPECTED, PROBABILITY
<QA>

In the example, IQL retrieves and
lists
nonanalyzed query named PROSPECT-DETAIL.

2-21

the

stored

RUNNING IQL
QUERIES
FUNCTION:
The QUERIES assistance command displays a list of all nonanalyzed
queries stored by IQL in the file of stored queries.
FORMAT:
QUERIES
EXAMPLE:

<QA> QUERIES G!D
QUERIES STORED IN THE DIRECTORY:
NEWHIRES
SALES-·ANAL YSIS
LOANS

SALARY-··ANAL YSIS
CUSTOMERS-OVER-CREDIT
RISK ···ANAL. YS I S

(END LIST OF STORED QUERIES)
<QA>

2-22

PROJECTS
LEADS

RUNNING IQL
REPLACE
FUNCTION:
The REPLACE assistance command deletes the named query from the
file of stored queries and writes the contents of the current
query area into the file of stored queries.
FORMAT:
REPLACE

[query-name]

DEFAULTS:
If you omit the query name from the command line but you name the
current query area, IQL replaces the stored nonanalyzed query
with the contents of the current query area. If you do not name
the current query area and do not supply a query name with the
command, IQL prompts you for a query name.
DISCUSSION:
The contents of the current query area are not
REPLACE command.
EXAMPLES:

REPLACE G!D
(PO-AUDIT REPLACED)
<OA>

«~A>

<C~A>

REPL.ACE OPEN-PO~
(OPEN-PO REPLACED)
<OA>

2-23

affected

the

RUNNING IQL
RUN
FUNCTION:
The RUN assistance command
generates a report.

processes

nonanalyzed

query

and

FORMAT:
RUN

[query-name]

[NOLIST]

[SAVE]

DEFAULTS:
If you omit the query name, IQL runs the query located in the
current query area. If you furnish a query name, IQL moves that
query from the stored nonanalyzed query into the current query
area, analyzes the query, and generates a report.
If you use the
contents.
If
contents.

NOLIST option, IQL does not list the query
you omit the NOLIST option, IQL lists the query

If you use the SAVE option, IQL creates an analyzed query file
with a file type of .QRY. Refer to the SAVE command description
for more information.
DISCUSSION:
The query in the current query area is not affected by IQL when
you use the RUN assistance command to generate a report from the
current query area.
If IQL finds an error in the query during an analysis, IQL issues
the appropriate error messages and returns to the assistance
level so that you can correct the errors (by using the EDIT
assistance command).
EXAMPLES:
1.

<QA> RUN ~
.•. {listing of current query goes here) ...
•.. (report produced by current query goes here) ...
<QA>

<QA> RUN
DEPT-MGRS
NOLISTG!!)
**DEPT·-MGRS
... (report produced by query DEPT-MGRS goes here) ..
(END QUERY PHASE; PRINT FILE IS QL215E.LPT)
{GA>

2-24

RUNNING IQL
SAVE
FUNCTION:
The SAVE assistance command analyzes and saves in an analyzed
query file the current query area or a stored nonanalyzed query.
You can subsequently generate a report from an analyzed query
file with the EXECUTE assistance command.
FORMAT:
SAVE

[query-name]

[NOLIST]

[RUN]

DEFAULTS:
If you supply a query name, IQL analyzes the nonanalyzed query in
the file of stored queries and writes the analyzed query into a
file named name.QRY. The filename is the first six characters of
the query name.
If you omit the query name, IQL uses the name of the current
query area.
If you do not name the current query area, IQL
requests a query name.
If you 'use the
contents.
If
contents.

NOLIST option, IQL does not list the query
you omit the NOLIST option, IQL lists the query

If you use the RUN option, IQL analyzes the query, generates
report, and saves the analyzed query into a disk file.

the

DISCUSSION:
IQL writes the analyzed query in a disk file with a filename
consisting of the first six characters of the query name combined
with the extension .QRY.
Since some versions of the system
utilities do not fully process filenames with dashes (-) in them,
you should avoid using dashes in the first six characters of the
query name.
If a .QRY file already exists with the target name, IQL notifies
you of the conflict and refusea to save the new query; neither
the'existing .QRY file nor the current query area is affected.
EXAMPLES:
1.

<QA> SAVE GE)
**NEWHIRES
OPEN PERSONNEL.
HEADING 'LIST OF NEW HIRES'.
IF DATE-HR LEQ 77 PRINT NAME, DEPT, DATE-HR.
% IQA014 INVALID/MISSING PASSWORD FOR PERSONNEL
<QA>EDIT @)
EDIT: QC039S.TMP.3
*G!::)

00100

OPEN PERSONNEL.

2-25

RUNNING IQt

*00150
I·GiD
AUTHORITY

TIGER.~

*EUN GiD

[QC039S.TMP.4]
<t~A> SAVE GD
**NEWHIRES

OPEN PERSONNEL.
AUTHORITY TiGER.
HEADING 'LIST OF NEW HIRES'.
IF DATE-HR LEQ 77 PRINT NAME, DEPT, DATE-HR.
<QA>
2.

<QA> SAVE
**QUAF\TEF~L

QUARTERLY
Y

NOL I ST

RUN G!D

..• (report produced by QUARTERLY goes here) ...

(QUARTERLY SAVED AS QUARTE.QRY)
«~A>

2-26

RUNNING IQL
STORE
FUNCTION:
The STORE assistance command stores the current query
the file of nonanalyzed queries.

area

into

FORMAT:
STORE [query-name]
DEFAULT:
If you omit a query name, IQL uses the name of the current query
area.
If you did not name the current query area, IQL prompts
you for a query name.
DISCUSSION:
IQL writes the nonanalyzed query in the QPQRYS.SEQ file of stored
queries. You can retrieve a stored nonanalyzed query at any time
with the LIST, EDIT, RUN, or SAVE assistance command.
If you attempt to store a query and a query already exists by
that name, IQL notifies you of the conflict and refuses to store
the query. Neither the current query area nor the existing
stored query is affected.
To generate a report from a stored query, use the RUN command
with the query-name option. Refer to the RUN assistance command
for more information.
EXAMPLES:
1.

<QA> STOREG!)(the current query, R2D2, is stored)
(F~2D2

STORED)

«~A>

<[~A>

BTORE

C3PO G!D

(C:3F'D STORED)

<QA>

2-27

RUNNING IQL
UPDATE
FUNCTION:
The UPDATE assistance command places IQL into the update level of
the immediate mode so that you can update or inspect either
sequential or indexed sequential data files (subject to any
password requirement}. Refer to Chapter 4 in this guide for more
information on the immediate mode.
FORMAT:
UPDATE

dictionary-name

[filename]

DISCUSSION:
IF IQL does not find the file referenced in the dictionary, IQL
notifies you and enters the immediate mode to create the file.
If you supply a filename, IQL uses the filename you supply rather
than the filename in the dictionary. The filename must follow
the ffffff.ext naming convention, where ffffff is one to six
alphanumeric characters and ext is one to three alphanumeric
characters.
If IQL finds that the dictionary is protected from either READ or
WRITE access, IQL asks you for the password and checks it. If
you respond with the READ password, IQL notifies you that IQL is'
opening the file for only read access.
EXAMPLE:
1.

<QA> UPDATE
CUSTOMERS ~
*F'ASSWORD: MICKEY~
(THE DIARY FILE IS QL032U.LPT)
(AT TOP OF FILE)
<QU> LIST CUSTOMER SAl.ESMAN SAl.ES ALl.~
PORTABLE DEVICES INC CARLETON SCOTT
1,472.00
ELECTROSCAN LABS BILL GLASS 21,500.00
<QU> TOPG!D
<WJ> CHANGE SALESMAN TO ' .JIM REILLY' FOR CUSTNO 23G!D
SEAFOOD BROKERS INC
JIM REILLY023456780023302
0301111020
... (UPDATE session continues) ...
... (you end UPDATE session via END or EXIT) ...
<QA>

2-28

RUNNIN~

IQL

WRITE
FUNCTION:
The WRITE assistance command allows you to begin writing a new
query in the current query area. IQL places you into the insert
level of the appropriate text editor. Appendix E explains the
IQL editor and provides a summary of some of the TOPS-20 EDITOR
commands.
FORMAT:
WRITE

[query-name]

DEFAULT:
If you omit a query name, IQL does not name the current query
area. If you later attempt to save or to store the current query
area and omit the query name from the assistance command, IQL
prompts you for a query name.
DISCUSSION:
The WRITE assistance command destroys the
the current query area.

contents

EXAMPLES:
1.

<QA> WRITE ~
INPUT: QC022S.QRY
00:1.00 OPEN PERSONNEL...~
0020() HEADING /NEW HIRE L.IST/. ~
0()3()O IF DATE·-HIRE GEQ 770101 PRINT NAME, DEPT. ~
00400 ~$
*EUN~
[C~C()22SC

• QF~Y:1

«~A>

<QA> WRITE
NEW-HIREH··L.IST~
INPUT: QC022S.QRY
OO:L 00 OPER PERSONNEL.. (NOTE ERROR ~
00200 HEADING /NEW HIRE L..IST/+~
00300 IF DATE-HIRE GEQ 770101 PRINT NAME, DEPT.
00400 ~ $
*Pl00 G!!)
00100 OPER PERSONNEL..
*SOF'ER~$OPEN ~$.~ (FIX AN ERROR)
00100 OPEN PERSONNEL..
*EUNG!D
[: QC022S. Qt~Y::I
«~A>

2-29

CHAPTER 3
CREATING AND EDITING A QUERY

A query is a collection of query statements that IOL reads to generate
one or more reports.
The query statements direct IOL to do the
following:
1.

Read sequential and ISAM data files and read DBMS
files

Select records or data

Calculate derivative information

Summarize the data

Format reports

Resequence the order of records

Write output files

data

base

with the RUN assistance command, you instruct IOL to read a querYJ
analyze it, and generate the report(s).
You can store the query into
a file with the REPLACE, RUN, SAVE, and STORE assistance commands.
If
you use the RUN or SAVE assistance command to create an analyzed query
file, you must use the EXECUTE assistance command to generate the
report(s).
If you use the REPLACE or STORE assistance command to
create a nonanalyzed query file,
you must use the RUN assistance
command to generate the report(s).
Refer to Chapter 2 for more
information on these assistance commands.

3.1

FORMATTING DEFAULTS

IOL uses the following defaults in formatting reports if
override these defaults in a query:

you

Single spacing vertically

Three spaces between elements horizontally

Fifty-nine printed lines (including heading) per page

Date of run as mm/dd/yy at top left of each page

Page number at top right of each page

Left margin at 1

Right margin at 132
3-1

not

CREATING AND EDITING A QUERY
3.2

ORDERING QUERY STATEMENTS

IQL determines which file or schema you wish to process from the
dictionaries you named in the OPEN statement. However, you do not
need to use an OPEN statement if you are using IQL only as a data
generator or calculator and are not reading any files. Any statements
that IQL finds before the OPEN statement are executed once at the
start of the query.
NOTE
The query runs much faster if
overall
format
statements
beginning of the query.

3.3

you
at

put
the

STAGING A QUERY

The execution of a query proceeds in stages. The first stage starts
with the first OPEN statement and ends with the first SORT statement
or the end of the query, whichever occurs first.
The first stage
takes as its primary input the original file or data base. Successive
stages, if any, start with one SORT statement and end with the next
SORT statement or the end of the query. Each stage takes as input the
sorted output of the previous stage. This can be the entire original
file sorted or an extracted and sorted subse~.
In this way, you can
read in a file, extract some records, sort and produce one report, do
a further extract, sort again, and produce another report; all
without passing the entire original file more than once.
The following statements illustrate a 3-stage query:
OPEN GRANTS.
(start stase 1)
HEADING 'OVERALL GRANT TOTAL'.
TOTAL AMOUNT.
IF ZIP GED 5000 SORT BY STATE, GRANTOR.
HEADING 'WESTERN GRANT SUMMARY',
(start stage 2)
TALL.Y GRANTOR BY STATE.
TOTAL AMOUNT BY STATE.
AVERAGE AMOUNT BY STATE.
IF STATE EQ 'CA' SORT BY DESCENDING AMOUNT.
HEADING 'CALIFORNIA GRANT DETAIL'.
(start stage 3)
PRINT GRANTOR, GRANTEE, AMOUNT, DATE, DESCRIPTION.

3.4

QUALIFYING ITEM NAMES

If you process more than one input file in the same query and the same
item name occurs in different dictionaries, you can qualify the item
name by prefixing it with the name of the dictionary and a dash.
For
instance if you are working with dictionaries named PAYROLL and
PERSONNEL in the same query, and each contains the item named SSNO,
you can identify which SSNO you mean by writing PERSONNEL-SSNO or
PAYROLL-SSNO. If you do not qualify a duplicated item name, IQL uses
the item value from the first dictionary named in the OPEN statement.

3-2

CREATING AND EDITING A QUERY
3.5

COMMENTING IN A QUERY

Any statement that starts with an asterisk (*)
is
comment continues until lOL encounters a period.

3.6

comment.

The

the

query

where

READING A DBMS DATA BASE

To read· a DBMS data base, use the FIND statement in
you wish to read the data base.

IOL reads different logical. records from a DBMS data base and
assembles the logical records into one physical record of a sequential
file created by IOL. IOL assembles the physical records in the order
in which you specify the logical records in the FIND statement.
If you sort the subsequent sequential file, lOL reads each of the
physical records and sorts them as composite records. You cannot read
~rom a data base after you sort it.
For lQL to read from a data base, you must make available to IOL a
dictionary describing that data base. A dictionary is required (in
addition to the schema) since it contains formatting information that:
1.

Anticipates printing reports

Defines column titles

Edits pictures

This information is not available in a DBMS schema.

3.7

QUERY STATEMENT FORMATS

The query statements use the following statement conventions:
1.

First character location
The statement begins in the first character location
line.

the

One or more spaces separate a statement verb from
argument. Also one or more spaces separate arguments.

Space

Lowercase and uppercase characters
An argument identified by lowercase characters implies that
you are to supply a variable as indicated by the variable
name.
An argument identified by uppercase characters indicates that
you are to supply the· exact characters as they are shown in
the text.

Square brackets [ ]
An argument enclosed in square brackets indicates an optional
argument.
Do not use the square brackets in the query
statements you write; the square brackets indicate only an
3-3

CREATING AND EDITING A QUERY

optional argument. When you do not supply the argument, the
system applies a default value as explained in the argument
description.
An argument not enclosed in square
the system requires the argument.
5.

brackets

indicates

that

Special characters
An argument containing special characters, such as the equal
sign, quotation marks, parentheses, and arithmetic symbols,
requires the special characters as shown in the statement
format.

Alphanumeric values
Enter an alphanumeric value as a string of characters
including quoted spaces.
If you do not furnish all the
characters needed to fill the field,
the system
left
justifies the value and inserts spaces to the right of the
value. For instance if you specify SMITH to a 10-character
field, the system stores the value as SMITH66666, where each
delta symbol indicates a space.
If the string contains spaces, enclose the string in either
single
quotes
(') or double quotes (II).
The system
understands either quote mark, but be sure you end the quoted
space with the same quote mark with which you started. If
you use quotes in the value, set off the quoted value with
the other quote mark. For instance:
'SMITHSONIAN INSTITUTION'
'BOB IICHIP" JONES'
IIROBERT C. SMITH"
To enter all spaces as the value for an
enter the value as ' ,

alphanumeric

field,

Numeric values
Enter a numeric value as a string of special symbols
digits. You can use the following special symbols:

and

comma
dollar symbol
decimal point
signs

+ and -

Valid formats include:
$1,234.56
$1,234.56+

+100

+1,234.56
1,234.56+
-100.0

1,234.56
-1(10
-100.00

1234.56
100100.00-

The system ignores dollar signs and commas in the numeric
value and accepts signs in the leading or trailing position
of the value. If you do not enter a sign, the system assumes
a positive value.
The system uses the decimal point that you supply to
vertically align the value, but the system does not actually
store the decimal point. The system knows from the scale in
the dictionary where the decimal point is located in the
numeric field.
3-4

CREATING AND EDITING A QUERY
For integer constants, you should omit the decimal point or
embed it (such as, 475 or 475.0)
to avoid any possible
confusion between a decimal point and a period ending a
statement.
If you do not furnish enough digits to fill the field,
the
system provides leading and trailing zeros (after the decimal
point) to fill the field.
To furnish an all zero value for a numeric item, simply enter
the single digit O.
8.

Continuation
You can continue a query statement on the next line.
However, do not split words. If you must split a literal,
divide the literal into two literals with the first part on
one line and the second part on the second line.

Reserved keywords
There are a number of reserved keywords with special meaning
to the system. These words are listed in Chapter 1. If you
must use a reserved keyword as a value, enclose the keyword
in quotes.
The TODAY reserved keyword interrogates the Operating
for the current date. The format is YY/MM/DD where:
YY
MM
DD

System

is the last two digits of the year
is the month of the year
is the day of the month

For instance, you can use TODAY in an IF statement as part of
the condition test.
The XRANDOM reserved keyword provides you with a random
10-digit number. For instance to report a sampling, you can
use XRANDOM in a FIND statement.
The remainder of the
alphabetical order.

chapter

presents

3-5

the

query

statements

CREATING AND EDITING A QUERY
ACCEPT
FUNCTION:
The ACCEPT statement requests item values from the terminal to
allow you to change information or directives during the query
run. DUring the generation of the report(s}, IQL issues a prompt
for the value and then waits for you to enter the value.
FORMATS:
ACCEPT item [ ... item]
ACCEPT variable [ ... variable]
DISCUSSION:
IQL' accepts any alphanumeric or numeric data. The accepted value
replaces the previous value in either the current record (in
core) or the variable.
You can use
necessary.

the

statement

anywhere

and

often

IQL creates a prompt from the information that IQL finds in the
dictionary entry for the item to be accepted. IQL uses the item
name, top and bottom column titles, item type, item length, and
the scale (if any).
As soon as you enter a value,
following syntax errors:

IQL

checks

the

value

for

the

Alphanumeric values must be equal to or less than the
of the field.

length

Numeric values must be limited to $ , +
and numbers and
must be equal to or less than the length of the field.
In
addition, IQL fills in leading and trailing zeros, ignores
the dollar sign and comma, and uses the decimal point only to
vertically align the value.

A frequent use of ACCEPT is to provide search values for a
specific run of a query.
To provide search values, use the
ACCEPT statement before the OPEN statement so you need only use
one statement or use the FIRSTIME statement.
EXAMPLES:
1.

Using an accepted alphavariable to control an extraction.

ACCEPT ASTATE.
HEADING 'PROSPECTS IN ' ASTATE.
OPEN PROSPECTS.
IF STATE = ASTATE
PRINT DIRECTOR, SITE, HARDWARE.
Might result in the prompt and response:

*ASTATE 2A: AZ G!D

3-6

CREATING AND EDITING A QUERY
2.

Using repeated ACCEPT statements to find keyed ISAM records.

DISPLAY 'TO END SEARCH, ENTER -QUIT-'.
OPEN PROSPECTS.
ACCEPT ANAME.
IF ANAME = -QUIT- GO TO XT.
FIND KEY = ANAME.
DISPLAY ANAME, EQUIPMENT, SALES, PERCENT.
3.

Using IQL like a desk calculator (no OPEN statement).

DISPLAY 'TO QUIT, ENTER 0',
TITLES X = 'ANNUALIISALARY'.
10ACCEPT X.
IF X = 0 GO TO XT.
COMPUTE Xl = X I 2080.
DISPLAV 'ANNUAL SALARV:',X,'HOURLV SALARV:',Xl.
GO TO 10.

3-7

CREATING AND EDITING A QUERY
ACROSS
FUNCTION:
The ACROSS statement sets IOL to assemble more than one logical
print line across a physical print line. Thus, IOL permits
printing several identically formatted lines from different
records across the page.
FORMAT:
ACROSS

integer

DEFAULT:
If you omit the ACROSS statement from a query, IOL prints one
physical line per print statement; that is, IOL uses ACROSS 1.
DISCUSSION:
Each time IOL executes a print statement, it sets up a logical
line.
If you do not use the ACROSS statement, IOL prints the
logical line immediately. If you use the ACROSS statement, IOL
places the logical lines end to end until IOL assembles the
number you specify. IOL then prints the composite line. At the
end of each stage in the query, IOL prints any in-progress print
lines.
If you use a horizontal spacing constant at the end of a print
line, IOL reserves the required number of spaces at the end of
the line before IOL appends the next line. This feature is handy
for vertical alignment.
If an assembled line is too long to fit in the space between the
left and right margins, IOL truncates the assembled line on the
right before printing it.
IOL does not display a warning
message.
The ACROSS statement is frequently used for setting up mailing
labels when several labels across are printed on special forms.
However, the ACROSS statement is useful in many other cases for
tightening up reports.
The current setting for ACROSS is carried from one stage to the
next and from one report to the next in a multiple-report query.
If you need a new across setting, even if it is 1, you must
specifically reset it with another ACROSS statement.

3-8

CREATING AND EDITING A QUERY
EXAMPLE:
1.

Mailing labels; (note paging turned off).
PAGING OFF.
TITLES OFF.
ACROSS 2.
OF'EN ALUMNI.
VSPACE 3.
PRINT NAME, 5.
VSF'ACE 1.
PRINT STREET,5.
PRINT CITY,3,STATE,5.
PRINT ZIP,25.

because special form
two across
three spaces between label
name is 25 characters long
single space within label
street is 25 characters long
city-is 19 characters long, state is 2
characters long
zip is 5 characters long

might give:
ALVIN J COWENS
JEROME C DAVIDSON
45 MEADOWBROOK BLVD.
4762 FAIRMOUNT
CLEVELAND HEIGHTS
OH SHAKER HEIGHTS
44118
44120
ERIE C HOPWOOD
•••

WILLIAM F FRANKLIN

•••

3-9

CREATING AND EDITING A QUERY
AUTHORITY
FUNCTION:
The AUTHORITY statement provides authorized passwords
access to protected files or data items.

permit

FORMAT:
AUTHORITY password [ ... password]
DEFAULT:
If you omit the AUTHORITY statement in a query, IOL processes
unprotected files or items, but does not permit you to run a
query that refers to protected files or items.
DISCUSSION:
Passwords that protect files or individual items are stored (in
encrypted form) as PD (Password Definition) entries in an IOL
dictionary. For a discussion of these passwords, see Chapter 5.
When you us~ IOL with DBMS data bases, one of the passwords
specified 1n the AUTHORITY statement must correspond to the
privacy key for compile in the DBMS schema.
You can specify up to 10 passwords in an AUTHORITY
You can specify the passwords in any order.

statement.

If you use an exclusivity option in a dictionary you own to
protect a specific data item, you must specify the exact password
in the AUTHORITY statement in order to use that item.
If you do not use an exclusivity option in protecting an item, or
for file l~vel protection, the use of a particular password
unlocks all file accesses or nonexclusive items protected at the
same or a lower level (password number).
EXAMPLES:
1.

Assume dictionary PERSONNEL is read protected by password
BEAR at level 10, item PHONE is protected b~ exclusive
password FOX at level 30, and item SALARY 18 further
protected by the exclusive password TIGER at level 50.

OPEN PERSONNEL.
AUTHORITY BEAR.
PRINT NAME, DEPT.
In example 1, the password BEAR unlocks the file to read it.
If however, the example attempted to print the item SALARY,
IOL would refuse to read the item SALARY.

OPEN PERSONNEL.
AUTHORITY TIGER.
PRINT NAME, SALARY, DEPT.
In example 2, the password TIGER permits
3-10

access

SALARY.

CREATING AND EDITING A QUERY
Since TIGER is a higher ranked password than BEAR, the file
is also unlocked for reading.'
3.

OPEN PERSONNEL
AUTHORITY TIGER, FOX
PRINT NAME, PHONE, SALARY
In example 3, both passwords are required since the
PHONE and SALARY are protected by exclusive passwords.

items

Assume the dictionary ACCOUNTS is read protected by the
password ALICE, copy ,(writing to a new outp~t file) is
protected by the password CARL, and rewrite (writing back
into an ISAM file) is protected by password DENISE.
OPEN ACCOUNTS
AUTHORITY ALICE
IF ACeT-CLASS = 6 COPY RECORD
IQL does not permit this query to run.
However, if either
the password CARL or DENISE is included in the AUTHORITY
statement, IQL would run the query.

3-11

CREATING AND EDITING A QUERY
AVERAGE
FUNCTION:
The AVERAGE statement calculates the average of a numeric item in
one of two ways:
1.

Over an entire report.

Within a specific value of
(breaks) .

one

FORMAT:
AVERAGE item [BY item [ •.. item] ]

.
(

controlling

items

variable )]

DEFAULT:
If you do not specify a
average is calculated
AVERAGE statement.

break item (that is, BY item), the
over all records that pass through the

Unless you specify otherwise, each AVERAGE statement calculates
the specified average and prints it at the proper time.
DISCUSSION:
The format and use of the AVERAGE STATEMENT are exactly the same
as the other summary statements MAXIMUM, MINIMUM, TALLY, and
TOTAL.
The AVERAGE statement is a stand-alone statement;
it is not
necessary for you to use TOTAL or TALLY in order to use AVERAGE.
If you do not specify a break
calculates the average over
AVERAGE statement.

item (that is, BY item), IOL
all records that pass through the

If you specify a break item, 'IOL calculates the
prints it when IOL detects a change in the item.

average

and

You can specify more than one break item as long as they are
minor to the one preceding it. An average is calculated for each
break item. When a change in any break item occurs, lOL assumes
all the break items to the right of it in the AVERAGE statement
also change. The purpose of this is to prevent inadvertent
overlap of minor break items over major break items. For
instance if you were averaging a grade point average for each sex'
in each school and IOL encounters an all-girls school, AVERAGE
GPA BY SEX gives a misleading answer whereas AVERAGE GPA BY
SCHOOL, SEX gives the correct answer.
Since averaging is an arithmetic operation, the item you average
must be numeric. However the item(s) controlling the break can
be any type.
Unless the SUMPRINT OFF statement is in effect, lOL prints the
average line on the report as an average title on the left and
the average value on the right. lOL constructs the average title
for an item from the top and bottom dictionary titles and from
3-12

CREATING A~D EDITING A QUERY
the word AVG:. IOL constructs the title for a break item from
the top and bottom dictionary titles of the break item and
constructs the overall title for all the break items with the
word OVERALL.
You can give a name to the average by using
argument at the end of the statement.
variable name with either X or ZZ.

the (
variable)
You must begin the

After defining the variable, you can use it like any other item.
For instance, you can include the variable in computations. One
such usage is to calculate percentages at the end of a query.
Another usage is to print the average in a print line with other
data, such as printing summaries directly under details.
EXAMPLES:

HEADING 'ORGANIZATIONAL BUDGETS'.
OPEN BUDGET-FILE.
AVERAGE BUDGET BY DIV, DEPT.
AVERAGE BUDGET.
might give:

HOME DEPT 421 ANNUAL BUDGET AVERAGE:
HOME DEPT 427 ANNUAL BUDGET AVERAGE:
HOME DEPT 433 ANNUAL BUDGET AVERAGE:
HOME DIV 110 ANNUAL BUDGET AVERAGE:

23,921.46
37,446.00
12,777.50
24,714.82

HEADING 'PRINTING AVERAGES UNDER DETAIL'.
SUMPRINT OFF.
OPEN LABOR-DETAIL.
IF NEWGROUP OF DIV PRINT XACTUAL XLASTYR XCURR.
AVERAGE ACTUAL-HRS BY DIV ( = XACTUAL ).
AVERAGE LASTYR-HRS BY DIV ( = XLASTYR ).
AVERAGE CURR-HRS BY DIV ( = XCURR ).
PRINT ACTUAL-HRS LASTYR-HRS CURR-HRS.

3-13

CREATING AND EDITING A QUERY
COMPUTE
FUNCTION:
The COMPUTE statement calculates a new value for a numeric item.
FORMAT:
COMPUTE item-l

item-2
constant
arithmetic expression

DISCUSSION:
Item-l and item-2 can be a numeric data-item or a numeric
variable.
A numeric data-item name must begin with a letter,
other than the letter X, and can be up to 30 alphanumeric
characters and dashes. 10L lists data-item names under the ITEM
NAME column title of a dictionary display.
A numeric variable must begin with the letter X or letters ZZ and
can be up to 30 alphanumeric characters and dashes. The initial
You can initialize a
value of a numeric variable is zero.
numeric
variable with the ACCEPT, CHANGE, RESET, and SET
statements.
Constants can have a leading sign (+ or -). and can contain
embedded decimal points. 10L assumes a positive constant if you
omit a leading sign. For integer constants, you should omit the
decimal point or embed it (that is, write 475 or 475.0 rather
than 475.) to avoid any possible confusion between a decimal
point and a period ending a statement.
An arithmetic expression can be any logical combination of item
names, variable names, summary names, constants, arithmetic
operators, and left and right parentheses.
Nested parentheses
are calculated from the inside to the outside.
The arithmetic operators are:

* multiply

divide
add
subtract

The arithmetic operators must be preceded and followed by one or
more spaces.
Otherwise, 10L might confuse the operator with an
item name or variable name.
IOL mUltiplies and divides from left to right, and then adds and
subtracts from left to right. Intermediate computation results
are carried to thirteen integer and five decimal places.
10L
rounds off to the fifth place decimal at each step of a
computation. If a computation overflows, the integer becomes too
large~
10L prints and displays an error message, truncates the
integer, and continues.

3-14

CREATING AND EDITING A QUERY
EXAMPLES:
1.

HEADING -HIGH VOLUMEIISTORES-.
OPEN STORES.
COM F' UTE XRAT I 0 :::: SAL ESIS Q- FT.
IF XRATIO GR 4.99 SORT BY DESCENDING XRATIO.
PRINT STORE-NAME, MANAGER, SAL~S, SQ-FT.
The query in example l'shows computation of a ratio
sorting on a computed ratio.

and

the

HEADING 'SALES BONUSES'.
OPEN SALESMEN.
COMPUTE BONUS ==
( WKLY-SAL
52 )
SALES - QUOTA ) I QUOTA.
IF BONUS LS 0 COMPUTE BONUS
O.
AVERAGE BONUS. TOTAL BONUS.
PRINT SALESMAN, QUOTA, SALES, BONUS.

The query in example 2 shows a COMPUTE statement using
parentheses.
BONUS is a data item in the record for the
salesman file.
Therefore, the query is calculating new
values for BONUS to show in the report.

3-15

CREATING AND EDITING A QUERY
COpy
FUNCTION:
The COpy statement writes the current
file to a new sequential file.

record

from

the

primary

FORMAT:
COpy

[RECORD]

[TO

"filename"]

DEFAULT:
If you do not use the filename option, IOL gives the file the
same name as the primary input file and adds the extension .OUT.
The file is written on device DSK:.
DISCUSSION:
The copied file always contains the same data format (6-bit ASCII
or 7-bit ASCII) as the primary input file.
If the primary input
file is a DBMS data base, the copy output is 7-bit ASCII.
You can use the COpy statement after you use one or more SORT
statements.
In this case, the order of the copied file is not
the same as the original input fil~ but is the order after the
most recent sort.
There can be multiple COPY statements in a
query. However, only one COpy file can be used in each stage of
a query.
If you change the value of item(s) in the current record with the
SET, RESET, or COMPUTE statements, the copied record contains the
changed item(s). This feature is useful for making systematic
changes in files.
If you use the COpy statement under control of the IF statement,
IOL copIes only those records where the conditions meet the
relationship in the IF statement.
Unless you specify the correct password(s), lOt does not permit
you to copy records when a dictionary protects the primary input
file at either the read or copy level.
The copied file can be queried using the same dictionary that you
used to query the original file. Be sure to furnish the new
filename in the OPEN statement so that you query the copied and
not the original file.
If you use the filename option and you specify a device, lOt
writes out the file under the specified name and on the specified
device.
IOL always writes output files in the same directory in which the
job is being run.
If a file already exists with the same name as lOt is
IOL writes over the old file.

3-16

write,

CREATING AND EDITING A QUERY
EXAMPLES:
1.

OPEN ACCOUNTS.
IF VENDOR-NO = 100 SET SALESMAN TO 'JONES'.
COpy TO IACCTS.SEQR.
In example 1, IQL copies each record to the file ACCTS.SEQ.
for each record where item VENDOR-NO is 100, IQL changed the
salesman name to JONES in the copied record.

OPEN ACCOUNTS.
SORT ACCOUNTS BY BALANCE.
COpy RECORD.
In example 2, IQL sorts' and copies th~ records to the file
ACCTS.OUT if the file described by the dictionary ACCOUNTS is
named ACCTS.SEQ.

OPEN COURSES
FIND KEY = '01000' THRU '02000'
COpy RECORD TO COURSE-SEQ
IF NO-STUDENTS GR 20
SORT BY NO-STUDENTS
SECOND STAGE OF THE QUERY STARTS HERE
COpy RECORD TO 'ENROLL-SEQ'

Here the original file described by the dictionary COURSES is
an ISAM file.
The selected records (with keys between 999
and 2000) are copied to one sequential file, COURSE.SEQ.
From the COURSE. SEQ file, IQL selects the records where the
course enrollment exceeds 20, sorts the selected records, and
copies them to a second sequential file, ENROLL. SEQ.

3-17

CREATING AND EDITING A QUERY
CREATE
FUNCTION:
The CREATE statement writes a file whose records contain only
specific items and formats the records as you specify in the
CREATE statement. The records that the CREATE statement writes
can contain record or data items from any input file as well as
working items or filler positions.
FORMAT:
CREATE ["filename"]

[=]

value [ ... value]

DEFAULT:
If you do not use the filename option, CREATE writes the
file on device DSK: under the name CREATE.OUT.

created

DISCUSSION:
Value can be an item or literal. The record created is formatted
from left to right by putting the item value side by side in the
order named in the CREATE statement. Numeric variable values are
written as numeric (not binary) with 13 integer and 5 decimal
places. Binary items are converted to numeric before being put
in the created record.
Created files are always written in ASCII on device DSK:.
IOL always writes output files in the same directory in which the
job is run.
If a file already exists with the same filename as the one IOL is
to write, IOL writes over the old file.
You can use a special value of:
FILLER

integer

This special value reserves an integer number of blank spaces
that point in the created reco~d.
EXAMPLE:
1.

HEADING 'HIGH VALUEIIINVENTORY ITEMIIANALYSIS'.
TITLES X = 'ITEMIIVALUE'.
PICTURE X = ' ••• ,.$$.99'
OPEN INVENTORY PRICES.
FIND PRICE-PART = PARTNO.
IF PRICE GR 100 COMPUTE X = PRICE * QTY
CREATE ·COST.SEQ' = PA~TNO,PRICE,QTY,FILLER=5"VALUE"X
PRINT PARTNO, PRICE, QTY, X.

3-18

CREATING AND EDITING A QUERY
The query reads the primary file, INVENTORY, and then looks
up a corresponding record in a secondary file, PRICES. For
instance, assume that PARTNO is a length of 6 and a value of
123456 and that QTY is a length of 5 and a value of 00740 in
the INVENTORY file. Also assume that PRICE-PART is a length
of 6 and a value of 123456 and that PRICE is a length of 5
and a value of 00198 ~n the PRICES file. IQL then creates a
record in the COST. SEQ file as follows:
12345600l980074060 666 VALUE000000000146520000
Notice that the decimal points are not written in the record;
the decimal points are implied.

3-19

CREATING AND EDITING A QUERY
DATE
FUNCTION:
The DATE statement turns report dating on or off or
report a specific date value to print in page headings.

gives

FORMATS:
1.

DATE rON]
DATE [OFF]

DATE value

DEFAULT:
If you do not use DATE in a query, report dating is automatically
turned on - lOL puts the date of the run in report headings.
DISCUSSION:
Value can be be an item, constant, or literal.
You can turn
report dating on or off, or change the value of the report date
at any point.
If you use DATE OFF, IOL omits

th~

date from the page heading.

If you use DATE ON, report dating is turned on and IOL places the
date the report is run, formatted as mm/dd/yy, at the top left of
each page heading.
If you furnish a value in DATE, report dating is turned on and
the value is printed at the top left of the page heading. The
value can be a constant, a literal, or an item value. If it is a
constant, it must contain six digits and it is printed with
slashes inserted after the second and fourth digits. If it is a
literal, it is printed exactly as furnished.
If it is an item
value, it is edited per the picture in the dictionary entry for
that item.
RPTDATE is a synonym for DATE. It is carried over from
versions of lOL but should not be used.
EXAMPLES:
1.

DATE 060377

DATE ON

DATE OFF

DATE'3 JUNE 1977'

(prints as 06/03/77)

(prints as 3 JUNE 1977)

3-20

CREATING AND EDITING A QUERY
DISPLAY
FUNCTION:
The DISPLAY statement displays messages or reports on the
terminal while IQL runs the query or turns on or off an automatic
terminal display of reports.
FORMATS:
1.

DISPLAY [ON]
DISPLAY [OFF]

DISPLAY value [ ... value]

DEFAULT:
If you do not use DISPLAY ON or DISPLAY OFF in a query, IQL turns
on the display option.
DISCUSSION:
Value can be an item, literal, or constant.
IQL sends single-spaced lines with no column titles to the
terminal.
IQL displays the item values in the display line from
left to right as they occur in the DISPLAY statement. Unless you
specify otherwise (as described below), IQL places three spaces
horizontally between item values.
If you use an integer in the display statement, IQL places that
many spaces between the item values for the remainder of the
display line or until IQL encounters another such integer in the
DISPLAY statement.
The use of a spacing integer overrides any
other horizontal spacing.
If you omit a spacing value and use the HSPACE statement in a
query, IQL reserves as many spaces between items as you specify
in the HSPACE statement.
Before IQL displays the line, IQL edits the item values as
specified by the picture in the dictionary (or any override
picture you furnish with the PICTURE statement).
Generally you use the DISPLAY statement for short prompts or
progress report messages. To display reports on a terminal, use
the PRINT statement;
it contains more
powerful
built-in
formatting capability.
EXAMPLE:
1.

DISPLAY 'ENTER CUT OFF TI~E'.
ACCEPT XTIME.
OPE'N RACE-RESULTS.
IF ~ACE-TIME LEQ XTIME TALLY XRACER-NAME.
IF XTALLY GEQ 100
DISPLAY 'TOO MANY BEAT THIS TIME; LOWER THE LIMIT'
GO TO XT.
,GO TO NR.
3-21

CREATING AND EDITING A QUERY
FIND ITEM
(for sequential and ISAM files)
FUNCTION:
The FIND item statement performs a sequential read of a secondary
file
(either the second- or third- named file in the OPEN
statement). Thus the FIND item statement permits you to position
a file on either a specific value or the value of some other data
item.
FORMATS:
1.

FIND data-item
FIND data-item

item [FROM BEGINNING]
literal [FROM BEGINNING]

FIND data-item

NEXT [FROM BEGINNING]

DEFAULT:
If you omit the clause, FROM BEGINNING, IQL starts reading from
the current position of the file; that is, the first record read
is the next record after the current record. If you use the FROM
BEGINNING clause, IOL searches for the desired record from the
beginning of the specified file.
DISCUSSION:
You can use the FIND item on either sequential or ISAM files.
For ISAM files, the statement is useful for positioning on other
than the key item.
The item named on the left of the = tells IQL which item in a
file IQL is to read.
The item name must be unique to the
dictionary describing that file. If it is not unique, make it
unique by prefixing the name of the dictionary and a dash to the
item name (that is, SSNO in PERSONNEL is
the
same
as
PERSONNEL-SSNO) .
IQL searches the file until IQL either satisfies
the
relationship or until IOL reaches the end of the file. If IQL
reaches the end of the file, IQL returns all spaces to the.record
and continues.
You can test to see if you are at the end of a file by using IF
EOFn statement.
See the discussion of the IF statement in this
chapter.
EXAMPLES:

OPEN PROJECTS, DEPT-MASTER
FIND DEPT-NO = DEPT FROM BEGGINNING
PRINT PROJECT-LEADER, DEPT, DEPT-NAME
In example 1, the file PROJECTS is automatically read by IQL.
The query uses the data item DEPT in the PROJECTS file to
locate a record in the DEPT-MASTER file that has a matching
value of DEPT-NO.
Then the query uses the department name
value from item DEPT-NAME in the DEPT-MASTER record.
3-22

CREATING AND EDITING A QUERY
2.

OPEN PAYROLL, PERSONNEL.
FIND PERSONNEL-SSNO = PAYROLL-SSNO.
PRINT NAME, SSNO, WITHHOLDING-RATE.
In example 2, the social security number is called SSNO in
both the PAYROLL and PERSONNEL dictionaries. 'In the FINO
statement, it is necessary to qualify which SSNO to find.
In
the PRINT statement, you can use SSNO since by that time both
values of SSNO are the same.

3-23

CREATING AND EDITING A QUERY
FINO KEY
(for ISAM files)
FUNCTION:
The FINO KEY statement reads ISAM files randomly based on either
the value of a data item or one or more specific key values. The
FINO KEY statement permits reading on either full or partial
keys.
FORMATS:
1.

FINO KEY = literal [ ... literal]
FINO KEYn literal THRU literal [ ... literal THRU literal]
FINO literal THRU EOF [ ... literal THRU EOF]

FINO KEY = item
FIND KEYn = item

DISCUSSION:
If you omit the FINO KEY statement and you process an ISAM file,
IQL reads the ISAM file sequentially.
This is useful for
searching items that are not key items.
If you use FIND KEY = literal, IQL advances the file directly to
the record that contains the value of the literal as the full or
partial (leading portion) of the key.
IQL
provides
an
end-of-file response if it does not find the record.
If you use a range of literals (literal THRU literal or literal
THRU EOF) , IQL starts with the first record whose key is in the
range and each time lQL executes the FINO statement, IQL reads
the next record in the range. If you use several such literal
ranges, IQL goes to the first record in the next range when IQL
exhausts the range before it. The end-of-file condition occurs
only when IQL exhausts the last range. It is not necessary that
the ranges be in any specific order of key.
If you use FINO KEY = item, IQL looks for a record that has as a
key the value of the indicated item. If it does not find such a
record, it returns an all-spaces record and continues.
To read a primary file, use the FINO KEY or FINO KEYI statement.
To read a secondary file, use the FINO KEY2 statement; and to
read a tertiary file, use the FINO KEY3 statement.
EXAMPLES:
1.

OPEN PERSONNEL
FIND KEY = '00010', '00020' THRU '00047', '00060' THRU EOF
PRINT EMPLOYEE-NO, DEPT, DATE-HIRED

3-24

CREATING AND EDITING A QUERY
2.

OPEN PERSONNEL
FIND KEY = '00047' THRU '00096'
FIND KEY2 = EMPLOYEE-NO
PRINT EMPLOYEE-NO, HOURS, OVERTIME
In example 2, IQL reads directly in the secondary file,
PAYROLL, based on a value of item EMPLOYEE-NO from the record
IQL just read from PERSONNEL.

3-25

CREATING AND EDITING A QUERY
FIND
(for DBMS data base)
FUNCTION:
The FIND statement reads a DBMS data base file.
FORMATS:
1.

FIND recordname USING item

FIND NEXT recordname RECORD OF
FIND PRIOR recordname RECORD OF
FIND FIRST recordname RECORD OF
FIND LAST recordname RECORD OF

FIND OWNER RECORD OF setname SET

FIND recordname RECORD

~etname ~ SET

areaname AREA

DISCUSSION:
If IOL cannot find a record, or encounters any other data base
error,
IOL
returns an error status ln the special item
ERROR-STATUS and the error count in special item ERROR-COUNT.
You can test ERROR-STATUS and ERROR-COUNT for specific values.
Refer to the DBMS programmer's manual (such as the TOPS-20 Data
Base Management System Programmer's Procedures Manual), for the
meaning of these error/status codes.
For
convenience
of
reference, 307 means end of area and 326 means record not found.
Often you end a query when receiving an error-status of 307, such
as:
IF ERROR-STATUS = 307 GO TO XT.
If you are using the FIND FIRST or FIND NEXT statement, check the
query to be sure that you do not place IOL into an unending loop.
You can suppress currency updates for ALL, RECORD, AREA or SET by
appending a suppresslon clause to the FIND formats described
above. The format of a suppressi~n clause is:
SUPPRESS ALL
CURRENCY UPDATES
SUPPRESS RECORD CURRENCY UPDATES
SUPPRESS AREA
CURRENCY UPDATES
SUPPRESS SET
CURRENCY UPDATES
EXAMPLES:
1.

HEADING 'BRANCHIISORTED'.
OPEN MASTER.
IF FIRSTIME FIND FIRST BRANCH RECORD OF AREAl AREA
ELSE FIND NEXT BRANCH RECORD OF AREAl AREA.
IF ERROR-STATUS = 307 GO TO XT.
IF ERROR-STATUS NEQ 0 GO TO QT.
SORT MASTER ~y BRANCH-NUMBER.
PRINT BRANCH-NUMBER, BRANCH-NAME.
The example prints out, in branch number
branch names and the numbers.
. 3-26

sequence,

all

the

CREATING AND EDITING A QUERY

OPEN STUDENT-DATA-BASE
HEADING 'STUDENT COURSES AND TEACHERS'
* GET THE FIRST OR NEXT STUDENT RECORD
IOIF FIRSTIME FIND FIRST STUDENT RECORD OF STU AREA
ELSE FIND NEXT STUDENT RECORD OF STU AREA
* IF END, IOL IS DONE; OUIT
IF ERROR-STATUS = 307 GO TO XT
* HERE IS A NEW STUDENT; GET THEIR FIRST COURSE RECORD
FIND FIRST COURSE-RECORD OF STU-COURSE SET
GO TO 30
FIND NEXT COURSE RECORD OF STU-COURSE SET
20*IF END OF SET, GO TO THE NEXT STUDENT
30IF ERROR-STATUS = 307 GO TO 10
FIND FIRST TEACHER RECORD OF COURSE-TEACH SET
PRINT STUDENT-NAME, COURSE-NAME, TEACHER-NAME
*GO BACK FOR THE NEXT COURSE FOR THIS STUDENT
GO TO 20
Example 2 illustrates a look-up query in a DMBS data base.
Notice that the query u~es a bottom-up type of look-up logic.

3-27

CREATING AND EDITING A QUERY
FORM-LINES
FUNCTION:
The FORM-LINES statement specifies the number of printed lines
from perforation to perforation on the paper. IOL ~ses the count
to position to the top of ea~h page when output is on a terminal.
FORMAT:
FORM-LINES integer
DEFAULT:
If you omit the FORM-LINES statement in a query, IOL uses a count
of 66 printed lines from one perforation to the next.
DISCUSSION:
The companion to FORM-LINES is PAGE-LINES.
Since you can dynamically change the value of the FORM-LINES
setting at any point, it would be possible to specify more lines
per page than the physical page (form) could hold. IOL resolves
this conflict by not permittins more lines per page than lines
per form. If the integer in PORM-LINES is less than the current
setting of PAGE-LINES, IOL resets FORM-LINES as directed but also
resets PAGE-LINES down to the new value of FORM-LINES.
FORM-LINES and PAGE-LINES are useful when you are preparing
reports on a terminal or a printer and the paper is other than
standard size.
EXAMPLE:
1.

FORM-LINES 44.
PAGE-LINES 36.
OPEN MASTER.
PRINT TITLE, PURPOSE, AMOUNT.
The query in the example produces reports with four blank
lines at the top of the page, the report body formatted with
36 lines per page (including headings and column titles), and
four blank lines at the bottom of the page.

3-28

CREATING AND EDI~ING A QUERY
GO TO
FUNCTION:
The GO TO statement transfers control from the current
by directing IOL to do the following:
1.

Go to a designated statement

Read the next record

End the query stage

End the query run

statement

FORMATS:
1.

GO TO integer
GO TO NR
GO TO XT
GO TO OT

DISCUSSION:
If you use GO TO NR, IOL goes immediately to the statement just
after the OPEN or SORT statement that begins the current stage of
the query.
Unless you are doing your own reading of a data base
or an ISAM file, IOL does a sequential read of the next record of
the primary file at this point.
If you use GO TO XT, IOL closes the current stage of the query,
closes any open files, closes any in-progress summary statements,
and goes to the next stage of the query.
If there is no next
stage, IOL returns to the assistance level.
Do not use the GO TO
XT statement to transfer from one report to the next report in a
multiple report query. Use GO TO integer, where integer is the
next REPORT statement.
See
the
example
following
this
discussion.
~f

you use GO TO OT,
IOL closes any open files,
closes any
In-progress summary statements,
and returns to the assistance
level regardless of whether there is another stage to the query.
The purpose of the GO TO OT statement is to permit you to
terminate a multistage query at any point.
If you use GO TO integer, the integer must be a statement number
used elsewhere in this stage of a query. This form of the GO TO
statement is useful for routing control in a query.
Be sure you
do not route control from the current stage;
the results are
unpredictable.
Each query acts as if it had GO TO NR as the last
each stage;
it is not necessary to write it.

3-29

statement

CREATING AND EDITING A QUERY
EXAMPLE:
1.

*THE FIRST STAGE OF THE QUERY STARTS HERE.
OPEN ACCOUNTS-RECEIVABLE.
*IGNORE ALL BUT THE 'A' RECORDS.
IF STATUS NOT EQ 'A' GO TO NR.
*IGNORE RECORDS WITH AMOUNT LESS THAN $1000.
IF AMT LS 1000 GO TO NR.
TALLY ACCT ( = X ).
*IF TOO MANY RECORDS QUALIFY, QUIT; THE REPORT IS TOO BIG.
IF X GEQ 500 PRINT 'TOO MANY HITS'.
GO TO QT.
SORT BY DESCENDING AMT, ACCT.
*THE SECOND STAGE OF THE QUERY STARTS HERE.
*NOW DECIDE WHICH REPORT THE SORTED RECORD GOES INTO.
IF ZIP LEQ 50000 GO TO 10.
*HERE IF THE ZIP IS IN THE WEST; ZIP IS A HIGH VALUE.
REPORT 1.
HEADING 'WESTERN HIGH BALANCE ACCOUNTS RECEIVABLE'.
PRINT ACCT, AMT, VENDOR, CREDIT-BAL, DATE.
GO TO 20.
10REPORT 2.
HEADING 'EASTERN HIGH BALANCE ACCOUNTS RECEIVABLE'.
PRINT ACCT, AMT, VENDOR, CREDIT-BAL, DATE.
*BOTH REPORTS TERMINATE AT THE NEX, STATEMENT SO IQL CAN
SORT.
20S0RT BY STATE, DESCENDING AMT.
*THE THIRD STAGE OF THE QUERY STARTS HERE.
HEADIN~ 'HIGH BALANCE ACCOUNTS RECEIVABLE BY STATE'.
PRINT STATE, ACCT, AMT.
Notice the use of comments in the example query.
The query
is lengthy in order to ill~strate the many uses of the GO TO
statement.

3-30

CREATING AND EDITING A QUERY

HEADING
FUNCTION:
The HEADING statement turns automatic ?age headings on or off
furnishes specific text for page headings.

FORMATS:
1.

HEADING ON
HEADING OFF

HEADING value [, ... , value]

DEFAULT:
If you omit the HEADING statement in a query, IOL automatically
turns on headings, and the heading text in the center remains
blank.
DISCUSSION:
Value can be an item, constant, or literal;
a constant or
literal must be enclosed in parentheses. You can turn headings
on or off at any point and as often as necessary.
If you turn headings on or off, IOL prints the body of the report
with or without the heading as soon as IQL advances to a new
page.
A page heading consists of the report date on the top left, one
or more lines of report heading text in the center, and a page
number on the top right. You can turn on or off any or all of
these ingredients of the page heading with the DATE, HEADING, and
PAGE statements.
If you use Format 2, headings are turned on.
The text in Format 2 is exactly the same as the text for a PRINT
statement, with the exception that IOL starts a new line if the
literal contains IOL sees a double slash (II). Note that since
you can use items in the heading, part or all of the heading can
come from the current record or variable values.
Each line of heading text is centered at the top of each page.
The center is halfway between the current left and right margins.
If you are creating only one report, the query runs faster if you
put the HEADING statement before the OPEN statement so that IOL
only executes the HEADING statement once.
Headings, once set, remain. set until you change them.
RESUMEHEADING, a synonym for HEADING ON, and NOHEADING, a synonym
for HEADING OFF, are formats carried over from earlier releases
of IOL and will not be supported in future version of IOL.
HEADING ON and HEADING OFF are the recommended formats.
Also see the NEWPAGE and PAGING statements.
3-31

CREATING AND EDITING A QUERY
EXAMPLES:
(The examples are extracted from a query.)
1.

HEADING OFF
OPEN ACCOUNTS
IF FIRSTIME PRINT 'THIS IS MY OWN CUSTOM HEADING'
PRINT ACCOUNT, BUYER, BALANCE.

HEADING -ACCOUNTSIIPAYABlEIISUMMARY BY DEPT-, DEPT.
OPEN PAYABlES.
SORT BY DEPT, PO-DATE.
IF NEWGROUP OF DEPT NEWPAGE.
PRINT PO-DATE, VENDOR, APPROVAL, AMOUNT.

3-32

CREATING AND EDITING A QUERY
HOLD
FUNCTION:

The HOLD statement retains the value of each named item
special holding area so you can retrieve it at any time.

FORMAT:
HOLD item [ ... item]
HOLD variable [ ... variable]
DISCUSSION:
You can hold any numeric or alphanumeric value.
To refer to a held value, prefix the value name with HELD-.
instance: HOLD NAME ... PRINT HELD-NAME.

For

A held value remains intact until you hold that specific value
again.
The length of a held item is exactly the same as the
length of the item being held.
The initial value of a held item is
item and zero for a numeric item.

blank

EXAMPLES:
1.

HEADING ·DUPLCATED NAMES·.
OPEN CLIENT-FILE.
SORT BY NAME.
IF NAME = HELD-NAME PRINT NAME.
HOLD NAME.

HEADING ·BLIZZARDIIDAMAGEIIBY CITY·.
SUMPRINT OFF.
OPEN DAMAGE-REPORTS.
SORT BY CITY.
IF NEWGROUP OF CITY PRINT HELD-CITY, X•.
TOTAL DAMAGE BY CITY ( = X ).
HOLD CITY.

3-33

for

alphanumeric

HSPACE
FUNCTION:
The HSPACE statement sets the default
horizontal
spacing
increment between items when IOL sets up a print or display line.
FORMAT:
HSPACE integer
DEFAULT:
If you omit the HSPACE statement in a query, lOL
spaces between items in a print or display line.

places

three

DISCUSSION:
You can use
necessary.

HSPACE

anyplace

query,

and

often

If you use specific horizontal spacing in a PRINT statement, it
overrides the current HSPACE ~etting. The HSPACE value remains
unchanged.
If you change HSPACE in one report of a multiple report query,
IOL retains the setting from one report to the next report,
unless you change it.
If you are only using one· HSPACE for all reports, place the
HSPACE statement before the OPEN statement so it is executed only
once. IOL runs faster if the HSPACE statement follows the OPEN
statement.
EXAMPLES:
1.

HSPACE 5.
LMARGIN 15.
OPEN PUBLICATIONS.
PRINT LIB-CONGRESS-NO, AUTHOR, TITLE.

OPEN PUBLICATIONS.
REPORT 1.
HSPACE 3.
(to reset from next report)
PRINT AUTHOR, TITLE.
REPORT 2.
HSPACE 10.
IF CAT = 'REF' PRINT PUB-DATE, TITLE, PUBLISHER.

3-34

IF
FUNCTION:
The IF statement specifies a condition for IOL to
test.
Depending on whether the condition is satisfied or not, the query
statements that follow are performed. Control of the IF ends
when IOL encounters a period.
FORMATS:
1.

IF valuel relation value2 [AND
[OR

IF FIRSTIME
IF LASTIME
IF BOFI
IF BOF2
IF BOF3
IF EOFI
IF EOF2
IF EOF3

[ELSE ••. ]
[ELSE ... ]

... [ELSE ... ]
... [ELSE ... ]
[ELSE ... ]
[ELSE ... ].
[ELSE ... ]
[ELSE ... ]
[ELSE ... ]
[ELSE ... ]

DISCUSSION:
Valuel and value2 can be one
literals separated by a comma.

items,

constants,

You can write relationships in any of the following ways:
Relation

lot Acceeted woros/S:rmbols

equal
EO
not equal
NO
less than
LS
GR
greater than
less than or equal to
LEQ
greater than or equal to GEO

EOUALS
NE
LT
GT
LE
GE

•
<>
<

<.
>=

IS
NEO
LESS
GREATER
LO
GO

Note that you can use NOT to reverse a relationship.
For
instance:
NOT EQ is the same as NE; and NOT LEQ is the same as
GR.
You can combine simple relationships to
make
a
complex
relationship by joining them with AND or OR clauses. You can use
parentheses to clarify complex relationships. IOL evaluates all
OR
clauses
before any AND clauses.
You cannot nest IF
statements; that is, IOL does not permit the construct of IF
IF
ELSE
ELSE.
If you use the ELSE clause, lOL performs the statement(s) that
follow the ELSE clause if the condition preceding the clause is
not satisfied.
If you are comparing two numbers, the decimal points are lined up
and any necessary leading or trailing zeros are supplied before
the comparison is made.
If you are comparing two alphanumeric items or literals, any
necessary trailing spaces are added to the shorter item before
the comparison is made.
3-35

EXAMPLES:
1.

Cutting off a query.

HEADING -SALES DETAIL-.
OPEN SALES.
PRINT PO-NO,ACCOUNT.,LINE,ITEM,QTY,AMOUNT.
COMPUTE X = X + 1. IF X GEQ 50 GO TO XT.
2.

Comparing against a held item; exception report.

HEADING 'DUPLICATES IN INVENTORY FILE'.
OPEN INVENTORY.
SORT BY PART-NO.
IF FIRSTIME HOLD PART-NO GO TO NR.
IF PART-NO EQ HELD-PART-NO
PRINT PART-NO GO TO NR.
HOLD PART-NO.
3.

Using AND clauses and OR clauses.

HEADING 'CANDIDATES FOR EXECUTIVE BOARD'.
OPEN PERSONNEL.
IF JOB = 'EXC' OR JOB EQ 'MGR' GO TO 10.
IF SALARY-CLASS GEQ 7 AND YR-HR LEQ 68 GO TO 10.
GO TO NR.
10 PRINT NAME,JOB,DIV,DEPT~SALARY-CLASS,YR-HR.
4.

Using parentheses and ELSE.

HEADING -REGION 9 SPECIAL ATtENTION ACCOUNTS-.
OPEN ACCOUNTS.
IF ( LASTYR GEQ 50000 OR THISYR GEQ 25000 OR
( RATING = -A- AND PROJECTION GEQ 50000 ) ) AND
( STATE EO - CA -, - OR -, • WA -, - UT • )
PRINT CUSTNAME,STATE,LASTYR,THISYR
TOTAL LASTYR-SALES
ELSE TALLY CUSTNAME.

3-36

LMARGIN
FUNCTION:
The LMARGIN statement sets the left margin for printing reports.
FORMAT:
LMARGIN integer
DEFAULT:
If you omit the LMARGIN statement in a query, IQL sets
margin to 1.

the

left

often

DISCUSSION:
You can use
necessary.

LMARGIN

anyplace

query,

and

LMARGIN settings are carried from one multiple report to the next
unless you use LMARGIN to change them.
LMARGIN affects page headings, summary lines,
lines.

and

detail

EXAMPLES:
1.

LMARGIN 15.
HEADING 'MEMBER EXTRACT'.
OPEN MEMBER-FILE.
IF SUBSCRIPTION GEQ 1000
PRINT NAME, DATE, SUBSCRIPTION.

OPEN SALES.
SORT BY STATE.
REPORT 1.
HEADING 'SALES DETAIL'.
LMARGIN 1.
PRINT ACCT, SALESMAN, GROSS, PROJECTION.
TOTAL GROSS. TOTAL PROJECTION.
REF'ORT 2.
HEADING 'HIGH VOLUMEIISUMMARY'.
LMARGIN 10.
IF GROSS GEQ 10000
TALLY ACCOUNT BY STATE
TOTAL GROSS BY STATE.
The LMARGIN 1 statement is necessary to reset the query
the LMARGIN 10 statement in report 2.

3-37

from

MAXIMUM
FUNCTION:
The MAXIMUM statement calculates the maximum value of
item in one of two ways:
1.

Over an entire report.

Within a specific value of
(breaks) .

one

contro~ling

numeric

items

FORMAT:
MAXIMUM item [BY item [ ... item]]

[ (

var iable ) ]

DEFAULTS:
If you do not specify a
maximum is calculated
MAXIMUM statement.

break item (that is, BY item), the
over all records that pass through the

both
Unless you specify otherwise, each maximum statement
calculates the specified maximum and prints it at the proper
time.
DISCUSSION:
The format and use of the MAXIMUM statement are exactly the same
as the other summary statements AVERAGE, MINIMUM, TALLY, and
TOTAL.
If you specify a break item, the maximum is calculated and
printed on the change in the indicated item. If you specify more
than one break item, MAXIMUM breaks on a change in any of the
break items.
Since taking a maximum is an arithmetic operation, the item for
which you get the maximum must be numeric. However, the item
controlling the break can be any type.
Unless the SUMPRINT OFF statement is in effect, lQL prints the
maximum line on the report as a maximum title on the left and the
maximum value on the right. lQL constructs the title for an item
from the top and bottom dictionary titles and from the word MAX:.
IQL constructs the title for a break item from the top and bottom
dictionary titles of the break item and constructs the overall
title for all the break items with the word OVERALL.
You can give a name to the maximum by using
argument at the end of the statement.
variable name with either X or ZZ.

the (
variable)
You must begin the

After defining the variable argument, you can use it like any
other item.
For instance, you can include the variable in
computations. The most frequent use of giving a name to a
maximum is so that you can use it in a print line with other
items, often for printing summaries under detail.

3-38

EXAMPLES:

OPEN PAYROLL.
SORT BY JOB-CLASS.
MAXIMUM SALARY BY JOB-CLASS.
MAXIMUM SALARY.

OPEN TEAM-SCORES.
MINIMUM SCORE ( = XMIN ).
MAXIMUM SCORE ( = XMAX ).
IF LASTTIME
COMPUTE XPCT = 100
XMAX - XMIN ) / XMIN
PRINT ~MAX:MIN peT ~ XPCT.

3-39

MINIMUM
FUNCTION:
The MINIMUM statement calculates the minimum value of
item in one of two ways:
1.

Over an entire report.

Within a specific value of
(breaks) .

one

controlling

numeric

items

FORMAT:
MINIMUM item [BY item [ ... item] ] [ (

var iable ) ]

DEFAULT:
If you do not specify a
minimum is calculated
MINIMUM statement.

break item (that is, BY item), the
over all records that pass through the

both
Unless you specify otherwise, each MINIMUM statement
calculates the specified minimums and prints them at the proper
time.
DISCUSSION:
The format and use of the MINIMUM statement are exactly the same
as the other summary statements AVERAGE, MAXIMUM, TALLY, and
TOTAL.
If you specify a break item, the minimum is calculated and
printed on the change in the indicated item. If you specify more
than one break item, MINIMUM breaks on a change in any of the
break items.
Since taking a minimum is an arithmetic operation, the item you
take the minimum of must be numeric. However the break item can
be any type.
Unless the SUMPRINT OFF statement is in effect, IQL prints the
minimum line on the report as a minimum title on the left and the
minimum value on the right. IQL constructs the title for an item
from the top and bottom dictionary titles and from the word MIN:.
IQL constructs the title for a break item from the top and bottom
dictionary titles of the break item and constructs the overall
title for all the break items with the word OVERALL.
You can give a name to the minimum by using
argument at the end of the statement.
variable name with either X or ZZ.

the (
variable)
You must begin ~he

After defining the variable, you can use it like any other item.
For instance, you can include the variable in computations. One
frequent use of naming the
minimum
is
for
calculating
percentages.
Another is for using the minimum in a print line
with other items, often for printing minimums under detail.

3-40

EXAMPLES:
1.

OPEN ACCOUNTS.
MINIMUM BALANCE BY ACCOUNT-CLASS.
TOTAL BALANCE BY ACCOUNT-CLASS.
MINIMUM BALANCE. MAXIMUM BALANCE.
TOTAL BALANCE.
AVERAGE BALANCE.

OPEN INVENTORY.
MINIMUM QUANTITY ( = ZZQTY ).
MINIMUM V~LUE ( = ZZVAL ).
IF NEWGROUP OF CLASS
PRINT ZZQTY, ZZVAL.
PRINT QUANTITY,VALUE,CLASS.

3-41

NEWPAGE
FUNCTION:
The NEWPAGE statement advances immediately to a new page
current report.

the

FORMAT:
NEWPAGE
DISCUSSION:
Any time you use NEWPAGE, IQL advances immediately to a new page
of the report regardless of whether paging is turned on or off.
When IQL advances a page, IQL prints a page heading, which
consists of the report date On th~ left, the page number on the
right, and one or more lines of report heading prose in the
center.
IQL does this before starting to print the body of the
report on that page. You can individually turn off or set any of
these ingredients of the page heading.
Also see HEADING and PAGING descriptions.
EXAMPLE
1.

HEADING 'BUDGET SUMMARY"BY DEPARTMENT'.
OPEN BUDGET-FILE.
SORT BY DEPT, ACCOUNT.
IF NEWGROUP OF DEPT NEWPAGE.
TOTAL BUDGET-AMOUNT BY ACCOUNT.
TOTAL BUDGET AMOUNT BY DEPT.
The example uses the NEWPAGE statement in an IF

3-42

~tatement.

OPEN
FUNCTION:
The OPEN statement informs IQL which dictionaries
use in a query.

and

files

FORMAT:
OPEN dictionary["file"]

[dictionary["file"]] dictionary[IIfile"]]

DEFAULT:
If you omit a filename in quotes after a dictionary name,
reads from the file whose name it finds in the dictionary.

IQL

DISCUSSION:
Only one OPEN statement can be used in a query.
OPEN statement before any SORT statements.

There must be an

You can use from one to three dictionary names in an OPEN
statement, depending on how many files you wish to process in the
query.
The file described by the first dictionary in the OPEN statement
is called the primary file. This file controls the current phase
of the query. If it is a sequential file,
IQL automatically
reads it, the read coming immediately after the OPEN statement.
If the primary file is an indexed sequential (ISAM) file and you
do not do your own reading with a FIND KEY statement, IQL
automatically reads it sequentially.
If you use more than one dictionary name in OPEN statement, the
files
described by the second and third dictionaries are
secondary files. You must do your own reading of these files by
appropriate use of FIND item or FIND KEyn. Normally secondary
files are read under control of information you get from the
primary file.
When IQL comes to the last statement in the current stage or it
encounters a GO TO NR, IQL goes directly to the statement just
after the OPEN. If it is reading sequentially as described
above,
it reads the next record before carrying out the
statement.
Any statements that come before the OPEN statement are carried
out only once at the beginning of the query and before any
records are read. The query runs faster if you put one-time
formatting statements at the beginning of the query when you are
not going to change formats during the run.
EXAMPLES:

OPEN PERSONNEL.
PRINT SSNO, DATE-HIRE.
In example 1, IQL first looks up dictionary PERSONNEL
then determines which data file to physically open.
3-43

and

OPEN PERSONNEL"EMPLOY.IDX'.
PRINT SSNb, DATE-HIRE.
In example 2, IQL overrides the filename in the dictionary
PERSONNEL and physically opens the EMPLOY.IOX data file.
Notice, however, that the attributes (such as the word length
and the blocking factor)
are taken from the dictionary
personnel.

OPEN PERSONNEL JOB-TABLE 'JOBS.IDX' COLLEGE-TABLE.
FIND KEY2 =PERS-JOB.
FIND COLLEGE-ID = PERS-COLLEGE-ID FROM BEGINNING.
PRINT SSNO, NAME, JOB-TITLE, COLLEGE-NAME.
In example 3, IQL processes three files. For the first and
third files,
IQL uses the files named in the dictionaries
PERSONNEL and COLLEGE-TABLE.
However, for JOB-TABLE, IQL
ignores the filename in the dictionary and opens the file
named JOBS. lOX. The first file is read automatically by IQL.
The second dictionary, JOB-TABLE, describes an ISAM file.
IQL reads the second file randomly with the FINO KEY2 =
PERS-JOB statement.
IQL reads the second file for a record
whose key matches the item PERS-JOB from the record in the
file named in the PERSONNEL dictionary. For the third data
file, IQL reads the sequential file from the beginning of the
file and searchs for a record where the item COLLEGE-IO
matches the item PERS-COLLEGE-IO, which is read from the file
named in the PERSONNEL dictionary. Finally, IQL prints the
information from each of the three files.

3-44

PAGE
FUNCTION:
The PAGE statement sp~cifies a new
automatic page numbering.

page

numbet

that

overrides

FORMAT:
PAGE value
nEFAULT:
If you do not use PAGE in a query, IQL starts page numbers at 1
and automatically increases the page number each time IQL
advances a page.
DISCUSSION:
Value can be an integer, variable, or item.
Unpredictable
results occur if you do not assign the variable a numeric value
before a PAGE variable statement.
EXAMPLE:

PAGE 10 t
OF'EN BANKS.
PRINT BANK-NAME, TOTAL-DEPOSITS.
IQL assigns the first page as page 10.

3-45

PAGE-LINES
FUNCTION:
The PAGE-LINES statement specifies the maximum number of
lines IQL places on each page of the report.

printed

FORMAT:
PAGE-LINES integer
DEFUALT:
If you do not use PAGE-LINES in a query, IQL uses a count
printed lines as the maximum for each page.

DISCUSSION:
The companion to PAGE-LINES is FORM-LINES, which specifies the
number of lines from perforation to perforation of the physical
page.
The difference between FORM-LINES and PAGE-LINES specifies the
total number of blank lines at the top and bottom of each page.
Since you can dynamically change the value of the PAGE-LINES
setting at any point in the query, it would be possible to
specify more lines per page than the physical page. IQL resolves
this conflict by not permitting more lines per page than lines
per form. If the integer in PAGE-LINES is greater than the
current value of FORM-LINES, IQL resets the PAGE-LINES as
directed but also resets FORM-LINES up to the new value of
PAGE-LINES.
FORM-LINES and PAGE-LINES are useful when you are preparing
reports on a printer or terminal and the paper is other than
standard size.
EXAMPLE:
1.

FORM-LINES 44.
PAGE-L.INES 36.
OPEN MASTER.
PRINT TITLE, PURPOSE, AMOUNT.
The query in example 1 produces reports with four blank lines
at the top of the page, the report body formatted with 36
lines per page (including headings and column titles), and
four blank lines at the bottom of the page.

3-46

PAGING
FUNCTION:
The PAGING statement turns on or off automatic report paging.
FORMAT:
PAGING [ON]
PAGING [OFF]
DEFAULT:
If you do not use PAGING in a query, paging is automatically
turned on. IQL goes to a new page when it reaches the bottom of
the current page.
DISCUSSION:
You can turn paging on or off at
necessary.

any

point,

If you have turned paging off, IQL prints
(if any) on the paper.

past

and
the

often

perforation

When IQL pages, it prints a page heading consisting of the report
date on the left, the page number on the right, and one or more
lines of report heading prose before it starts to print the body
of the report. You can individually turn off or set any or all
of these ingredients of the page heading.
If paging is off, then headings are automatically off also.
If
you want a heading at the beginning of the run, use PAGING OFF
after your first PRINT statement.
RESUMEPAGING, a synonym for PAGING ON, and NOPAGING, a synonym
for PAGING OFF, are formats carried over from earlier releases of
IQL and will not be supported in future versions of IQL.
Also see HEADING, NEWPAGE, RPTDATE, RPTHEAD statements.
EXAMPLE:
1.

OPEN ACCOUNTS.
REPORT 1.
PAGING OFF.
ACROSS 3.
PRINT ACCOUNT-NAME,3.
PRINT CITY,1,STATE,ZIP,3.
REPORT 2.
PAGING ON.
HEADING 'SUMMARY OF BALANCES BY ZIP-.
TOTAL BALANCE BY ZIP.
PRINT ACCOUNT-NAME, BALANCE.
The example is taken from a query. The first report prints
three columns of information without any page numbers. The
second report provides a report heading and page numbers.

3-47

PICTURE
FUNCTION:
The PICTURE statement furnishes a picture for one or more items
to override dictionary pictures or to furnish pictures for
variables.
FORMAT:
PICTURE item

"picture" [ ... item

"picture" ]

DISCUSSION:
You can use PICTURE anywhere and repeatedly.
,However, usual
usage is to set a picture for a full run; in this case, put the
PICTURE statement before the OPEN statement so it is set up only
once.
The rules IQL uses for editing a picture are
pictures in a dictionary and pictures in a query.

the

same

for

Pictures for alphanumeric items can contain any character.
The character X indicates a substitution position
a
character from the item is substituted for each X. IQL fills
the characters by proceeding from left to right from the item
value. If there are not enough substitution positions in the
picture, IQL truncates the item;
if there are too many
substitution positions, IQL fills in spaces.

Pictures for numeric items can contain only the characters 9
Z $ ( ) , . S or R. The characters 9 Z $ Rand ( designate
substitution positions;
their
specific
functions
are
described below. In editing a numeric item, IQL lines up the
item with the decimal point (if any), and then substitutes
from the decimal point outwards.

Each 9 is a substitution position - the corresponding digit
from the item value is filled in.
A 9 stops any zero
suppression or floating characters from the left, and a 9
stops rounding via R from the right.

Z can be used only on the left of the picture.
Z positions
indicate where zero suppression is to be used. Only a single
S or $ can be located to the left of the leftmost Z, and only
commas or decimal points can be used between Zs.

Two or more adjacent $ characters on the left of the decimal
point indicate floating dollar sign editing; a $ character
is placed to the left of the most significant digit.
There
can be no character to the left of the $ character in the
pictu~e and only decimal points or commas can be used between
the $ characters. All the $ characters, except the leftmost
character, are substitution positions.

3-48

Two or more adjacent ( characters on the left of the decimal
point indicate a floating left parenthesis. This works the
same as the floating $ character, except that the parentheses
are printed only if the quantity is negative. There must be
a single) character on the right of the picture.

The R characters at the right of the picture indicate
rounding.
IOL rounds from right to left until it encounters
no more R characters. The R positions are not printed.

EXAMPLES:
Item Values
MARLBORO
MARL30RO
MARLBORO
MARLBORO
00123
00123
00123
00123
00123
467939
467939
467939
467939
092173"'84
092173"'84
092173"'84
092946"'72
092946"'72 MINUS
000000"'00
092946"72 MINUS
092946"'72
092173"'84

IQL Picture
XXXXXXXX
XXXX
XXXXXXXXXX
XX-XX-XXOOOXX
99999
ZZZZ9
Z9999
$$$$$9
$99999
9999.99
Z,ZZZ.ZZ
9999
999
$$$$,$$$.99
ZZZ,ZZZ.RR
$$$$RRR.RR
$$$$RRR.RR
SZZZ,ZZZ.99
ZZZ,ZZZ.ZZ
( ( ( ( , ( ( ( .99)
((((,(((.99)
$$$$,$$$.99

3-49

Result
MARLBORO
MARL
MARLBOROBB
MA-RL-BOOOORO
00123
123
0123
$123
$00123
4679.39
4,679.39
4,679
*679 (showing overflow)
$92,173.84
92,174
$92
$93
-092,946.72
(92,946.72)
92,946.72
$92,173.84

PRINT
FUNCTION:
The PRINT statement specifies a print line in a report.
FORMATS:
PRINT value [, ... , value]
DEFAULTS:
If you do not specify otherwise, IQL turns titling on, uses three
spaces horizontally between item values, and single spaces
vertically.
DISCUSSION:
Value can be an item, literal, or integer. Item values are laid
out in the print line from left to right as they occur in your
PRINT statement.
Item values are edited according to their picture in the
dictionary (or any override picture you use in the query) before
being put in the print line.
If you use an integer in the statement, the integer overrides
standard spacing for the PRINT statement. IQL sets the integer
to the horizontal spacing increment for the remainder of the
print statement or until you use another such spacing integer.
For instance, if you use HSPACE 2 and the print statement:
PRINT NAME, STREET, 5, PHONE, TITLE, 1, YEAR
IQL provides two spaces between NAME and STREET, five spaces
between STREET and PHONE, five spaces between PHONE and TITLE,
and one space between TITLE and YEAR.
If you do not use a
spacing integer and use HSPACE in your query, as many spaces are
left between item values as you designate with HSPACE.
If your print line is too long for the space between your current
left and right margins, IQL truncates the print line on the .right
and continues. No error message is issued.
If titling is on, IQL prints two lines of column titles at the
top of each new page.
In laying out space for each item
horizontally, IQL uses the longer of the edited item length or
the length of the column title. Column titles for alphanumeric
items are left justified. Column titles for numeric items are
right justified.
If titling is on, and the current print line is from a different
PRINT statement than the preceding line, IQL prints titles before
printing the body of the current line.
If titling is off, IQL prints only the current line.
In laying
out this line, IQL ignores the title lengths. Note that if you
print a line, turn titling off, and print the line again.
There
can be a difference in alignment since the length of the column
titles can affect the first line but not the second line.
3-50

Vertical spacing is done just before the print line (and title if
any) is printed.
EXAMPLES:

OPEN PERSONNEL.
PRINT LAST-NAME,FIRST-NAME,lNITIAL,OFFICE-PHONE.

SUMPRINT OFF.
PICTURE X = '$$$$,$$$.99'.
OPEN RETAIL-OUTLETS.
COMPUTE X = SALES / SQ-FT.
TOTAL SALES ( = XSALES ).
PRINT STORE,MGR,·SALES/SQ FT RATIO:·,l,X.
IF LASTTIME PRINT 'TOTAL SALES:', X$ALES.

3-51

REPORT
FUNCTION:
The REPORT statement denotes a specific report in a multiple
report query run.
All print, report formatting, or heading
statements between this REPORT statement and the next REPORT
statement (or the end of the query) pertain to that specific
report.
FORMAT:
REPORT integer
DEFAULT:
If you do not use REPORT anywhere in your query, IQL produces a
single report and acts as if you had given REPORT 1 at the
beginning of the query.
DISCUSSION:
You can specify up to 99 reports in a query, that is, the integer
can take any value from 1 to 99. Report number 1 is always
routed directly to the printer. All other reports are spooled
out to a disk file and later separated and printed or displayed
at the end of the run.
When you use a report format setting such as LMARGIN 10 or a
heading such as HEADING "EXCEPTION REPORT", IQL uses the same
setting in each subsequent report until you change it.
EXAMPLE:
1.

OPEN TICKETS.
REPORT 1.
RMARGIN 72.
HEADING ·SEPTEMBERIITICKETS·.
IF MONTH = 'SEPT'
PRINT NAME, DESTINATION, AIRLINE, FLIGHT, AMT.
REPORT 2.
RMARGIN 132.
HEADING 'BURMUDA EXCURSIONS - FALL'.
IF DESTINATION = 'BERMUDA'
AND MONTH = 'SEPT', 'OCT', 'NOV'
PRINT NAME, AGENT, HOTEL, DATE, PLAN.

3-52

RESET
FUNCTION:
The RESET statement resets the value of an item or variable.
FORMAT:
RESET item [ ... item]
RESET variable [ ... variable]
DISCUSSION:
IQL resets items or variables to spaces.

For instance,

RESET ACCOUNT-NAME
is equivalent to:

SET ACCOUNT-NAME

TO' ,

IQL resets numeric items or variables to zero.

For instance,

RESET SALARY
is equivalent to:

COMPUTE SALARY = o.
EXAMPLE:

HEADING 'BONUS PROJECTION'.
OPEN SALES-FILE.
COMPUTE XBONUS = SALARY * ( SALES - QUOTA ) / QUOTA.
IF XBONUS LEa 0 RESET XBONUS.
PRINT NAME, SALES, QUOTA, XBONUS.

3-53

REWRITE
FUNCTION:
The REWRITE statement replaces an
file.

existing

record

ISAM

FORMAT:
REWRITE [RECORD]
DISCUSSION:
The record rewritten is the last one read from the ISAM file.
You can use REWRITE even if you are reading the ISAM file
sequentially (that is, you did not use FIND KEY in your query).
If you have changed information in the record, the changed values
are rewritten into the file as part of the rewritten record.
You should be careful in using REWRITE since it writes over the
original information in the ISAM file.
It is a good idea to
protect ISAM files with a fairly high level password in the
dictionary at the FD rewrite password level.
EXAMPLE:
1.

AUTHORITY Q2R3YA.
OPEN PERSONNEL.
FIND KEY = '00010', '00025' THRU '00047'.
SET ASSIGNMENT TO 'SUPERVISOR'.
REWRITE RECORD.

3-54

FUNCTION:
The RMARGIN statement sets the right margin for printing reports.
FORMAT:
RMARGIN integer
DEFAULTS:
If you do not use RMARGIN in your query, IQL uses a right
of 132.

margin

DISCUSSION:
You can use RMARGIN any place in your
necessary.

query,

and

often

RMARGIN settings are carried from one multiple report to the next
unless you use RMARGIN to change them.
RMARGIN affects page headings, summary lines,
lines.

and

EXAMPLES:
1.

RMARGIN 72.
HEADING 'MEMBER EXTRACT'.
OPEN MEMBER-FILE.
IF SUBSCRIPTION GEQ 1000
PRINT NAME, DATE SUBSCRIPTION.

OPEN SALES.
SORT BY STATE.
REPORT 1.
HEADING 'SALES DETAIL'.
RMARGIN 132.
(to reset from 2nd report)
PRINT ACCT SALESMAN GROSS PROJECTION.
REPORT 2.
HEADING 'HIGH VOLUMEIISUMMARY'.
RMARGIN 72.
IF GROSS GEQ 1000
TALLY ACCOUNT BY STATE
TOTAL GROSS BY STATE.

3-55

detail

SET
FUNCTION:
The SET statement sets a new value into an item.
come from another item, constant, or literal.

The

value

can

FORMAT:
SET value TO value [ ... value TO value]
DISCUSSION:
Value can be an item, constant, or literal. If the item being
set is in a record, the new value replaces the old value in the
record IOL is working with but not in the file itself.
However
if you subsequently write out the record, it contains the value.
When a numeric item is set to a numeric value, the decimal points
are lined up first, then leading and/or trailing zeros are
supplied if necessary. If the integer or decimal portions of the
supplied value are too long, they are truncated with no error
message.
When an alphanumeric item is set to an alphanumeric value, the
supplied value is left justified with blank right fill if
necessary. If the value is too long, it is truncated on the
right with no error message.
SET X TO ...

is equivalent to COMPUTE X =

You can set alphanumeric items to numeric values.
The integer
part of the numeric item is left justified in the alphanumeric
item with blank right fill if necessary.
You can also set numeric items to alphanumeric values, but this
is only legitimate if the alphanumeric value is all digits. As
many digits as necessary are taken from the left of the
alphanumeric value to fill the integer portion of the numeric
item. IOL zeroes the fractional portion, if any~
You should avoid mixing item types, that is, setting alphanumeric
to numeric and vice versa. If done often, these operations are
expensive in computer time.
EXAMPLE:
1.

OPEN SALES-MASTER.
FIND KEY = '456701'
SET QUOTA TO 200,000 REGION TO 'NORTHWEST'.
REWRITE RECORD.

3-56

SORT
FUNCTION:
The SORT statement sorts the primary input file on one or more
keys.
The keys can be data items or variables and can be sorted
in ascending or descending order.

FORMAT:
SORT BY [ASCENDING] value [, ... [ASCENDING] value]
[DESCENDING]
[DESCENDING]
DEFAULT:
If you do not specify ASCENDING or DESCENDING, IQL
ascending order.

sorts

DISCUSSION:
Value can be an item or a variable. There is no maximum number
of sort keys that can be used other than that the number of
characters in all sort keys -taken together- cannot exceed the
total length of the record.
You can sort on calculated variable values.
However, the
calculated value does not pass through the SORT statement. For
instance in example 2 below, if you want to print XRATIO, you
must either recompute it after the sort or use the HOLD statement
to save XRATIO before the SORT statement.
EXAMPLES:

OPEN CONGLOMERATE.
SORT BY ASCENDING UNIT-NO DESCENDING SALES.
TOTAL SALES BY UNIT-NO.

OPEN STORES.
COMPUTE XRATIO = SALES / SQ-FEET.
SORT BY XRATIO, SALES.
PRINT SALES, SQ-FEET, STORE-NAME.

OPEN CANDIDATE-FILE.
COMPUTE XTOTAL = POLL-PCT * PRECINCT-POPULATION.
SORT BY PRECINCT, XTOTAL.
IF NEWGROUP OF PRECINCT
PRINT PRECINCT, CANDIDATE
ELSE PRINT CANDIDATE.

3-57

SUMPRINT
FUNCTION:
The SUMPRINT statement turns on or off the summary print line
a report.

FORMAT:
SUMPRINT [ON]
SUMPRINT [OFF]
DEFAULT:
Unless you specify otherwise, IOL automatically determines the
explanatory text to accompany the printed lines generated by the
AVERAGE, MAXIMUM, MINIMUM, TOTAL, and TALLY statements.
DISCUSSION:
If you use the SUMPRINT OFF statement, IOL calculates summary
quantities (such as averages) but IOL does not automatically
print in a report. If you do not use the SUMPRINT OFF statement
and you want to print a summary quantity, you must give the
summary quantity a name and then use that name in a print or
display statement.
EXAMPLE:
1.

3-58

TALLY
FUNCTION:
The TALLY statement counts the occurrences of an item and
the total in one of two ways:
1.

Over an entire report.

Within a specific value of
(breaks) .

one

TALLY item [BY item [ ... item]]

[ (

var iable ) ]

controlling

enters

items

FORMAT:

DEFAULT:
If you do not specify a break item (that is, BY item), the tally
is calculated over all records that pass through the TALLY
statement.
Unless you specify otherwise, each TALLY statement calculates the
specified tally and prints it at the proper time.
DISCUSSION:
The format and use of the TALLY statement are exactly the same as
the other susmmary statements AVERAGE, MAXIMUM, MINIMUM, and
TOTAL.
If you do not specify a break item (that is, BY item), the
is calculated overall records that pass through the
statement.

tally
TALLY

If you specify a break item, the tally is calculated and printed
on the change in the indicated item. If you specify more than
one break item, TALLY breaks on a change in any of the indicated
break items.
You can tally any type of item or break item, since TALLY .merely
runs an internal counter that increments by one each time lOL
encounters the TALLY statement.
Unless the SUMPRlNT OFF statement is in effect, lOL prints the
tally line on the report as a tally title on the left and the
tally value on the right. IQL constructs the title for an item
from the top and bottom dictionary titles and from the word
TALLY:. lQL constructs the title for a break item from the top
and bottom dictionary titles of the break item and constructs the
overall title for all the ~reak items with the word OVERALL.

3-59

You can give a name to the tally by using
argument at the end of the statement.
variable name with either X or ZZ.

the (
variable)
You must begin the

After defining the variable, you can use it like any other item.
For instance, you can include the variable in computations.
EXAMPLE:
1.

OPEN SCHOOLS.
TALLY STUDENT BY CLASS.

3-60

TITLES
FUNCTION:
The TITLES statement turns on or off the displaying of column
titles or furnishes specific column titles for designated items.
You can provide titles for working items or override the
dictionary titles.
FORMATS:
1.

TITLES ON
TITLES OFF

TITLES item

literal [ ... item

literal]

DEFAULTS:
If you do not use TITLES in your query, titling is
turned on.

automatically

For data items, column titles are obtained from their description
in the dictionary.
For working items, the name of the item is
title.

used

the

column

DISCUSSION:
When IQL is about to print a line, it looks to see if this line
is from a different print statement than the most recent one and
if titling is on. If both conditions are satisfied, IQL prints
two lines of column titles and a line of spaces before printing
the actual line. Otherwise, it prints only the actual line.
If you use TITLES OFF, titling is turned off and no column titles
are printed before the print line.
If you use TITLES ON, titling is turned on.
printed as described above.

Column

titles

are

If you use the second format, IQL turns titling on and sets the
column title for the named item to the literal value. If you use
a double slash (II) in the literal, the top title is to the left
of the II and the bottom title is to the right. If you do not
use a double slash, the literal is used as the top title and the
bottom title is blank . . To force a single title to the bottom,
start with double slashes. For instance: IILAST NAME.
EXAMPLE:

TITLES X = 'SALES//SQ FT'.
OPEN STORES.
COMPUTE X = SALES AREA.
PRINT STORE-NAME, SALES, AREA, X.

3-61

TOTAL
FUNCTION:
The TOTAL statement calculates the total of a numeric item in one
of two ways:
1.

Over an entire report.

Within a specific value of
(breaks) .

one

TOTAL item [BY item [ ... item]]

[ (

var iable ) ]

controlling

items

FORMAT:

DEFAULTS:
If you do not specify a break item (that is, BY item), the total
is calculated over all records that pass through the TOTAL
statement.
Unless you specify otherwise, each TOTAL statement calculates the
specified total and prints it at the proper time.
DISCUSSION:
The format and use of the TOTAL statement are exactly the same as
the other summary statements AVERAGE, MAXIMUM, MINIMUM, and
TALLY.
If you do not specify a break item (that is, BY item), the total
is calculated over all records that pass through the TOTAL
statement.
If you specify a break item, the total is calculated and printed
when IQL sees a change in the indicated item. If you specify
more than one break item, TOTAL breaks if it sees a change in any
of the indicated items.
You can specify more than one break item as long as each is minor
to one preceding it. A total is calculated for each such break
item. When a change in any break item occurs, a change is
assumed to have occurred in each break item to the right of it in
the TOTAL statement.
The purpose of this is to
prevent
inadvertent overlap of minor break items over major ones. For
instance, if you are computing a grade point total for each sex
in each school and you encountered an all-girls school, TOTAL GPA
BY SEX gives a misleading answer whereas TOTAL GPA BY SCHOOL, SEX
gives the correct answer.
Since totaling is an arithmetic operation, the item you total
must be numeric. However the item(s) controlling the break can
be any type.
Unless the SUMPRINT OFF statement is in effect, IQL prints the
total line on the report as a total title on the left and the
total value on the right. IQL constructs the title for an item
from the top and bottom dictionary titles and from the word
3-62

TOTAL:. IQL constructs the title for a break item from the top
and bottom dictionary titles of the break item and constructs the
overall title for all the break items with the word OVERALL.
You can give a name to the total by using
argument at the end of the statement.
variable name with either X or ZZ.

the (
variable)
You must begin the

After defining the variable, you can use it like any other item.
For instance, you can include the variable in computations. One
such usage is to calculate percentages at the end of, a query.
Another usage is to print the total in a print line with other
data; often for printing summaries directly under details.
EXAMPLE:
1.

HEADING 'ORGANIZATIONAL BUDGETS'.
OPEN BUDGET-FILE.
TOTAL BUDGET BY DIV, DEPT.
TOTAL BUDGET.
might give:

HOME DEPT 421 ANNUAL BUDGET TOTAL:
HOME DEPT 427 ANNUAL BUDGET TOTAL:
HOME DEPT 433 ANNUAL BUDGET TOTAL:
HOME DIV 110 ANNUAL BUDGET TOTAL:
OVERALL ANNUAL BUDGET TOTAL:

3-63

23,921.46
37,446.00
12,777.50
74,144.96

VSPACE
FUNCTION:
The VSPACE statement changes the vertical spacing of reports.
FORMAT:
VSPACE integer
DEFAULT:
If you do not use VSPACE in a query, IQL single
that is, it acts as if you had used VSPACE 1.

spaces

reports:

DISCUSSION:
IOL physically vertical spaces just before it prints
the titles that correspond with the line.

line

does

not

You can use VSPACE at any point and repeatedly.
VSPACE only affects reports
affect output from DISPLAY.

produced

PRINT:

If you are producing multiple reports, any VSPACE setting remains
in effect from one report to the next. If you wish to use a
different vertical spacing in reports, use VSPACE to change it.
You must use VSPACE again in the second report to reset vertical
spacing. See the example below.
The integer in VSPACE can be any reasonable value.
EXAMPLE:
1.

OPEN STUDENTS.
REPORT t.
VSPACE :L.
PAGING ON.
HEADING 'HIGH GPA STUDENTS'.
IF GPA GEG 3.5 PRINT NAME, CLASS, GPA, YEAR.
REPORT 2.
*STUDENT ADDRESS LABELS*.
PAGING OFF.
VSPACE 3.
PRINT NAME.
VSPACE 1.
PRINT STREET.
PRINT CITY.
PRINT STATE, ZIP.
IQL single spaces the first report. In the second report,
IQL triple spaces between the labels for each student and
single spades within the label.

3-64 .

CHAPTER 4
CREATING AND EDITING A DATA FILE

Through IQL, you can create, read, and update a data file.
The
create, read, and update data file functions work with sequential and
indexed sequential (ISAM) file structures. For IQL to work with these
file structures, there must be a dictionary that describes the data
file to IQL. Chapter 5 explains the dictionary and the dictionary
commands that you use to create, read, and change the dictionary. You
are not required to read Chapter 5 in order to understand Chapter 4.
You need only understand that IQL requires the dictionary before you
can create, read, or update a data file.
Since IQL performs the functions described in Chapters 4 and 5 as soon
as you enter a command, this guide collectively refers to these
functions as the immediate mode.

4.1

BEGINNING THE IMMEDIATE MODE

You enter the immediate mode to create, read, and update a
with the INPUT, BROWSE, and UPDATE assistance commands.

data

file

If you enter through the UPDATE assistance command, IQL displays the
prompt <QU> and waits for you to respond with a command. The file you
are updating must reside in the directory in which you are logged.
If you enter through the BROWSE assistance command, IQL displays the
prompt <QU> and waits for you to respond with a command. At the
browse level, IQL permits you to read the data file.
However, IQL
does not permit you to input data, change data, or delete data from
the data file. The file you are reading must reside in the directory
in which you are logged.
If you enter through the INPUT assistance command, IQL displays (NEXT
RECORD), displays a prompt for the first item in the record, and waits
for you to respond with a value. Upon receiving the value, IQL issues
the prompt for the next item. IQL continues down the dictionary this
way, issuing a prompt for each input field in the record, until IQL
encounters the end of the dictionary or you tell IQL to perform
another function. See the example session in Appendix B.
If you
enter the INPUT assistance command and the file already exists, IQL
informs you and proceeds to the update level.

4-1

CREATING AND EDITING A DATA FILE
4.2

RECOVERING SEQUENTIAL DATA FILES

IQL updates sequential data files by writing to one file while it is
reading from another file. One of these files is the original file
and the other is a work file,
Whenever you enter the immediate
commands TOP or UP or use a findlist containing FIRST IQL switches
the status of the files.
For instance, the work file becomes the
original file.
The latest original file is the file that is being
read at that particular time.
If you enter the SAVE command, IQL forces all updates into the
original file, which then becomes the latest original file.
If you
experience a computer crash (and you cannot continue after the
computer returns), you lose all updates (from CHANGE, APPEND, INSERT,
or DELETE) from the time the files are last switched
For this
reason, it is good practice to SAVE the file at regular intervals.
If a computer crash does occur, the latest valid file can be either
the original file or the work file. To recover in the latter case,
you must copy the work file to the original file.
IQL provides a
one-record diary file updated with the name of the file. The name of
the diary file is displayed when you enter the immediate mode.
To demonstrate a typical recovery, assume you are updating a
called MYDATA.SEQ described by a dictionary named MYDATA.
dialogue appears as follows:

file
The

@R IQL..@)
«~A>UPDATE ~

*DICTlnNAF~Y NAME: MYDATA@)

(YOUR DIARY FILE IS QL..012U+LPT)
<CH.J>CHANGE BAL TO 2:U IN FIV<ST ACeT 50QiD (you make a change)
<m.J>CHANGE DEPT 42 TO 51 IN ALL RECORDS GQ
(machine crashes)
DECSYSTEM-20 IS NOT RUNNING
@LOG+ +.
(you log back in)
(and look at diary)
@TYF'E (~L012U. LF'T ~
(YOUR LATEST GOOD FILE IS QT012U.TMP)
@COF'Y
(FROM) (~T012U. TMP
(TO) DATA.SEQG!DThis step is
needed only if
the latest good
file is not
your original.)

4.3

IMMEDIATE MODE COMMAND FORMATS

The immediate mode commands use the following command conventions:
1.

First character location
The command begins in the first character location after
<QU> prompt.

Space
One or more spaces separate a command from
separate parameters

the

parameter

and

Lowercase and uppercase characters
A parameter identified by lowercase characters indicates that
you are to supply a variable as indicated by the variable
name"
4-2

CREATING AND EDITING A DATA FILE
A parameter identified by uppercase characters indicates that
you are to supply the exact characters as they are shown in
the text.
4.

Square brackets [ ]
A parameter enclosed in square brackets indicates an optional
parameter
Do not use the square brackets in the immediate
commands you write; the square brackets indicate only an
optional parameter.
When you do not supply the parameter,
the system applies a default value as explained in the
parameter description.
A parameter not enclosed in square
the system requires the parameter.

brackets

indicates

that

Special characters
A parameter containing special characters, such as the equal
sign, quotation marks, parentheses, and arithmetic symbols,
requires the special characters as shown in the commanq
format.

Alphanumeric values
Enter an alphanumeric value as a string of characters
including quoted spaces.
If you do not furnish all the
characters needed to fill the field,
the system
left
justifies the value and inserts spaces to the right of the
value. For instance if you specify SMITH to aID-character
field,
the system stores the value as SMITH66666, where each
delta symbol indicates a space.
If the string contains spaces, enclose the string in either
single
quotes
( ') or double quotes
( .. ).
The system
understands either quote mark but be sure you end the quoted
space with the same quote mark with which you started.
If
you use quotes in the value, set off the quoted value with
the other quote mark. For instance:
'SMITHSONIAN INSTITUTION'
'BOB "CHIP" JONES'
"ROBERT C. SMITH"
To enter all spaces as the value for an
enter the value as ' ,

alphanumeric

field,

Numeric values
Enter a numeric value as a string of special symbols
digits. You can use the following special symbols:

and

comma
dollar symbol
decimal point
signs

$
+ and -

Valid formats include:
$1,234.56
$1,234.56+
+100

+1,234.56
1,234.56+
-100.0

4-3

1,234.56
-100
-100.00

1234.56
100100.00-

CREATING AND EDITING A DATA FILE
The system ignores dollar signs and commas in the numeric
value and accepts signs in the leading or trailing position
of the value.
If you do not enter a sign, the system assumes
a positive value.
The system uses the decimal point that you supply to
vertically align the value, but the system does not actually
store the decimal point. The system knows from the scale in
the dictionary where the decimal point is located in the
numeric field.
For integer constants, you should omit the decimal point or
embed it (such as, 475 or 475.0)
to avoid any possible
confusion between a decimal point and a period ending a
statement.
If you do not furnish enough digits to fill the field,
the
system provides leading and trailing zeros (after the decimal
point) to fill the field.
To furnish an all-zero value for a numeric item, simply enter
the single digit O.
8.

Continuation
You can continue a command on the next line by entering the
characters ++ as the last word on the line you wish to
continue. For instance:
<WJ> DEL.ETE Al.L RECORDS WHERE ++ (ED
<OLJ> DEPT :::: 442 AND CODE :::: ~ A ~ (ED

is the same as:
<QU> DELETE ALL RECORDS WHERE DEPT _. 422 AND CODE _.

~ A ~ (ED

Reserved keywords
There are a number of reserved keywords with special meaning
to the system. These keywords are listed in Chapter 1. If
you must use a reserved keyword as a value, enclose the
keyword in quotes.

10.

Maximums
a.

Field length
The maximum alphanumeric field length is 54 characters.
The maximum numeric field length is 18 digits.

Record length
The maximum length of a record is 768 characters.
Since
the maximum length of a record can be changed at a site,
check with the site software specialist.

Number of items in a dictionary
There is no maximum"

4-4

CREATING AND EDITING A DATA FILE
d.

Number of records in a file.
The maximum of records in a file is limited by
quota in a directory.

the

disk

11.

Examples
In the examples, data you enter is shown in red print whereas
the data the system displays is shown in black print.

4-5

CREATING AND EDITING A DATA FILE
APPEND
FUNCTION:
The APPEND command positions the file at the end
(bottom)
and
then goes into the input level to receive new records.
This
command is exactly the same as (if you entered)
BOTTOM followed
by INSERT.
FORMAT:
APPEND
DISCUSSION:
The first record inserted by APPEND follows the last record of
the current file.
For a detailed description of entering
records, refer to the INSERT command description in this chapter.
EXAMPLE:

«~U>

APPEND G!!)

(AT END OF FILE)

(NEXT RECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N:
*CUSTOMER (CUSTOMER NAME) 16 A:
*BUYER (BUYER NAME) 15 A:
*CYSALES •••••••• +.

4-6

JONESG!!)
BARNABAS~

CREATING AND EDITING A DATA FILE
BOTTOM
FUNCTION:
Positions the file at the end (bottom).
FORMAT:
BOTTOM
DISCUSSION:
If a file is positioned at the end, it is positioned after the
last record. There is no current record. An attempt to list or
otherwise act on the current record results in an error message
and the file is not moved.
EXAMPLE:

1 . . <QU>BOTTOM ~
(AT END OF FILE)
<OU>

4-7

CREATING AND EDITING A DATA FILE
CHANGE
FUNCTION:
The CHANGE command replaces the contents of an item with a new
value.
IQL can change up to 15 items in either the current
record or selected records of the data file.
IQL displays the
changed record(s) if the verify option is on.
FORMAT:
CHANGE item [TO] value [ ... item [TO] value]
[EQ]
[EQ]

[ IN
[IF
[FOR
[WHERE
[WHEN

findlist

]
]
]
],
]

If you do not furnish a findlist, the changes are made
current record only and the file is not repositioned.

[ =]

[=]

[ EQUAL]
[EQUALS]

[EQUAL]
[EQUALS]

DEFAULTS:
the

DISCUSSION:
Item can be a data item, alphavariable, or numeric variable.
A
data-item name must begin with a letter, other than the letter X,
and can be up to 30 alphanumeric characters and dashes.
IQL
lists data-item names under the ITEM NAME column title of a
dictionary display.
An alphavariable must begin with the letter A and can be up to 30
alphanumeric characters and dashes.
A numeric variable must begin with the letter X or the letters ZZ
and can be up to 30 alphanumeric characters and dashes. The
initial value of a numeric variable is zero.
Value can be an alphanumeric or numeric string.
If you specify a findlist, the system makes the specified changes
in the records located by the findlist.
The file remains
positioned at the last record changed. If the findlist starts
with ALL or if a record is not found, the file remains positioned
at the end of the file. Refer to the FINDLIST section in this
chapter for an explanation of the FINDLIST.

4-8

CREATING AND EDITING A OATA FILE
EXAMPLES:
1.

CHANGE DEPT TO 421

CH DEPT 421

CH NAME 'SEISS' IN SSNO 572409987

CHANGE VENDOR TO 'BRAND X' SALESMAN TO ++
JONES REGION = 6 FOR ALL VEND-NO ++
= 50 SALESMAN= 'SMITH'

CHANGE NAME 'SEISS' FOR KEY = '572409987'

4-9

CREATING AND EbITING A DATA FILE
COLUMNS
FUNCTION:
Designates the left and right
record to be displayed by
verify option is on).

columns of the portion of the
LIST (or CHANGE, DOWN, FIND, UP if

FORMAT:
COLUMNS

integer

[integer]

DEFAULTS:
If you do not use COLUMNS in the session, IQL displays the full
record, which causes IQL to display the record on as many
consecutive lines as necessary.
If you do not specify a second integer, IQL displays
a
72-character portion of the record, beginning at the column
designated by the first integer.
DISCUSSION:
The leftmost character in a record is in column 1.
The first
integer designates the first (leftmost) column to be displayed
and the second integer is the last (rightmost) column to be
displayed.
EXAMPLES:
1.

COLUMNS

601

4-10

CREATING AND EDITING A DATA FILE
DELETE
FUNCTION:
Deletes one or more selected records.
FORMAT:
DELETE

[findlist]
[ integer]

DEFAULTS:
If you specify neither a findlist nor a number
deletes the current record.

records,

IQL

DISCUSSION:
If you specify an integer, IQL deletes
records, starting with the current one.

that

many

sequential

If ,you specify a findlist, IQL deletes the records located by the
findlist. See the FINDLIST section.
Regardless of the form of the DELETE command that you use, the
file remains positioned at the record after the last record
deleted. However, if you use a find1ist that starts with ALL or
if the system cannot find a specified record, the file is left
positioned at its end.
EXAMPLES:

DELETE

DE 10

DELETE ALL RECORDS FOR REGION 56

DELETE FIRST RECORD ACCT 7252

DELETE NEXT RECORD WHERE VENDOR NOT = 'BLT'

DE VENDOR NOT BLT

4-11

CREATING AND EDITING A DATA FILE
DOWN
FUNCTION:
Moves the file down (toward the end or bottom) a specified number
of records. If verify option is on, IOL displays the new current
record.
FORMAT:
DOWN

[ integer]

DEFAULT:
The integer is the number of records the file is to be moved
If you omit the integer, IOL moves the file down one
down.
record.
DISCUSSION:
If IOL encounters the end of the file before it has moved down
the requested number of records, it issues an AT END OF FILE
message and leaves the file positioned at its end. If the file
is positioned at its beginning and you use DOWN or DOWN 1, the
new current record is the first record in the file.
EXAMPLES:
1.

[lOWN

[10

[lOWN

[10

600

4-12

CREATING AND EDITING A DATA FILE
eXIT
FUNCTION:
The EXIT command returns you to the assistance level.
FORMAT:
EXIT
DISCUSSION:
Ends the update or browse session and saves the final version
the file.
EXIT and END are synonyms.
EXAMPLES:
1.

EXIT

END

4-13

CREATING AND EDITING A DATA FILE
EXTRACT
FUNCTION:
The EXTRACT command reads selected records from the current ISAM
or sequential data file and writes the records to a new
sequential file.
FORMAT:
EXTRACT

[TO

'file.ext']

[findlist]

DEFAULT:
If you do not furnish a filename, IQL writes the records to the
QTjobX.TMP file, where the smbolic term, job, is the job number
the Operating System assigns when you log into the system.
DISCUSSION:
See the FINDLIST discussion in this chapter.
If you
findlist, IQL copies the first record to the new file.

omit

the

The sequential file, which IQL writes, retains the same data
format (that is, 6-bit ASCII or 7-bit ASCII) as the original
file.
EXTRACT always goes to the beginning of
doing the extract.

the

input

file

before

After EXTRACT, IQL switches to processing the extracted file.
EXAMPLE:
1.

EXTRACT
Copy the first record from the input data file to the new
data file and use the new data file as the input data file.

4-14

CREATING AND EDITING A DATA fILE
FIND
FUNCTION:
Positions the file at a selected record
displays the new current record.

If verify option is on,

FORMAT:
FIND

[findlist]

DEFAULT:
If you do not furnish a findlist, FIND uses the last findlist
that you furnished, which permits you to continue a search by
simply entering FIND or Fl.
DISCUSSION:
See the FINDLIST discussion in this chapter.
If IQL does not
find a record that qualifles, it issues an AT END OF FILE message
and leaves the file positioned at the end.
EXAMPLES:
1.

FIND NEXT RECORD WHERE NAME EQUALS 'SMITH'

FIND NEXT NAME EQ 'SMITH'

FIND NAME 'SMITH'

FI NAME 'SMITH'

FIND KEY = '234581099'

FIND DEPT GR 421 AND DIV EQ 3

FIND ACCOUNT GEQ 6000 AND YEAR NOT LESS 75

FIND ACCOUNT GE 6000 AND YEAR GE 75

(if used after the above FIND, continues the search)

4-15

CREATING AND EDITING A DATA FILE
FINDLIST
FUNCTION:
A findlist is a set of item names, values, and relationships that
direct IQL to locate records in a file. Findlists are used in
the commands CHANGE, DELETE, FIND, and LIST.
An example of a
findlist is:
NEXT RECORD WHERE NAME EQUALS 'SMITH'
FORMATS:
1.

[ALL]
[RECORDS]
[NEXT] [RECORD]
[ FIRST]

KEY

[IF] [i tem [NOT]
[WHEN]
[WHERE]
[FOR]

[EQ] value]
[NEQ]
[GEQ]
[LEQ]
[GR]
[LS]

[[IF ... value]

[AND]

value

DEFAULT:
If you do not specify a relationship, IQL assumes EQUALS.
If you do not use any of the keywo~ds NEXT, FIRST,
search proceeds as if you had used NEXT.

ALL,

the

DISCUSSION:
Remember that a findlist is only part of another command.
See
the discussions of CHANGE, DELETE, FIND and LIST for uses of
findlists.
The referenced item(s) can be any of the defined items in the
dictionary controlling this run. You can specify up to 15 items
and relationships in one statement.
You can write relationships in any of the following ways:
Relation

IQL AcceEted Words/S:tmbols

equal
not equal
less than
greater than
less than or equal to
greater than or equal to

EQ
NQ
LS
GR
LEQ
GEQ

EQUALS
NE
LT
GT
LE
GE

<>
<
>
<=
>=

IS
NEQ
LESS
GREATER
LQ
GQ

Note that you can use NOT to reverse a relationship.
For
instance, NOT ~Q is the same as NE and NOT LEQ is the same as GR.
You can combine simple relationships to
make
relationship by ]Olnlng them with AND clauses.
parentheses to clarify complex relationships.

a
complex
You 'can use

The words RECORDS, RECORD, AND, WHEN, WHERE, FOR, and IF are
optional.
They have no effect on the search and are processed
simply so you can use phrases that read like English.

4-16

CREATING ~ND EDITING A DATA FILE
If you use NEXT, the search begins at the record after the
current record and the file is positioned at the next record that
satisfies the findlist.
If you use FIRST, the search begins at the first record in the
file.
This is the same as if you had used the TOP command and
then used NEXT in your findlist.
If you use ALL, the search begins at the record after the current
one and the file is positioned in turn at each down-stream record
that satisfies the findlist. The file is left positioned at the
end of the file.
The rules for formatting item values in a findlist are the same
as
for furnishing item values in the INSERT command.
A
discussion on formatting item values is presented at
the
beginning of Section 4.3 in this guide.
ERRORS:
IQL issues an error message and rejects the command if it detects
any of the following in a findlist:
1.

Item not contained in a dictionary.

Alphanumerlc value too long.

Numeric value contains illegal alphabetic characters.

Too many decimal or integer places in a numeric value.

4-17

CREATING AND EDITING A DATA FILE
INSERT
FUNCTION:
The INSERT command enters IQL into the input level, where you can
insert one or more new records immediately after the current
record.
IQL prompts you for each new item value in each record
and allows you to furnish numeric values in a variety of formats.
IQL takes care of decimal point alignment, leading zeros, and
trailing zeros or blanks.
FORMAT:
INSERT
DISCUSSION:
If your file is currently positioned at the top
INSERT adds the new records before the first record.

(beginning),

If your file is currently positioned at the bottom (end),
adds the new records after the last record.

INSERT

INSERT operates under control of a dictionary.
For each new
record, IQL starts at the beginning of the dictionary and issues
a prompt for the first input data item. When you respond with a
value for the item, IQL issues the prompt for the next input
item. This process continues until either the end of the
dictionary is reached or you enter an immediate command NEXT,
KILL, or UP.
The prompt issued for each item is contructed from the dictionary
entry for the top and bottom title, the item length, and the
scale (if any). For alphanumeric items, the prompt ends with
nnA, where nn is the length of the item. For numeric items, the
prompt ends with nn.mmN, where nn is the maximum number of
integer positions and mm is the number of decimal positions (if
any). Some examples of prompts appear as:
*LAST NAME 16 A
*EARNINGS 7.2 N

The rules for entering data item values are the same for INSERT
as for other commands.
These rules are explained at the
beginning of Section 4.3 in this guide.
The input level commands
described as follows:
1.

you

can

use

control

INSERT

are

Carriage return, space(s), or quoted space(s)
If you enter a carriage return, all spaces, or
,
alphanumeric items are set to all spaces and numeric items
are set to zero.

KILL
If you make a serious error, enter
rejects the record and permits
record again from the beginning.

4-18

the KILL command.
IQL
you to begin entering the

CREATING AND EDITING A DATA FILE
3.

UP [integer]
If you make an error in entering a value and catch it later
in the same record, you can back up to correct the entry.
When you enter the UP command, IQL moves back that many
entries, prompts you for that item, and continues down the
dictionary again. If you omit the integer, IQL moves back
one prompt.

DOWN [integer]
Move down integer prompts.
IQL moves down one prompt.

If you do not specify an integer,

NEXT
To go on to the next record, enter the NEXT command.
IQL
goes through the rest of the current record, blanking out
alphanumeric input items and setting numeric input items to
zero.
Then it writes out the record and prompts you for the
first value in the next record.

END or EXIT
To terminate INSERT, enter the
response to the first prompt.

END

EXIT

command

ERRORS:
If IQL detects an improper value, it rejects the value with an
error message, reissues the prompt, and waits for you to enter
the value correctly.
Improper values are:
(a) alphanumeric
value too long,
(b)
too many integer or decimal places in a
numeric value, or (c) numeric item contains illegal characters.

4-19

CREATING AND EDITING A DATA FILE
EXAMPLE:
1.

<OU>INSERTC§:)
(NEXT RECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N:
23~
*CUSTOMER (CUSTOMER NAME) 16 A:
'SAVINGS TRUST'~
*BUYER (BUYER NAME) 15 A:
PURCHASING C!ID
*CYSALES (CURR YR SALES) '7.2 N:
LOOO G!Q
% VALUE TOO LONG OR CONTAINS ALPHA
*CYSAI...ES (CURF~ YF~ SALES) 7 + 2 N:
1000 G!Q
*L..YSALES (LAST YR SALES) 7.2 N:
575.98G!Q
*L..PDATE (LAST PO DATE) 6 N:
780112C!ID
(NEXT RECOF~D)
*CUSTNO (CUSTOMER NUMBER) 5 N:
*CUSTOMER (CUSTOMER NAME) 16 A:
*BUYER (BUYER NAME) 15 A:
*CYSAL..ES (CURR YR SALES) 7.2 N:
(NEXT F~ECORD)
*CUSTNO (CUSTOMER NUMBER) 5 Nt
*CUSTOMER (CUSTOMER NAME) 16 A:
*BUYER (BUYER NAME) 15 A:
*CYSALES (CURR YR SALES) 7.2 N:
*CUSTOMER (CUSTOMER NAME) 16 A:
*BUYER (BUYER NAME) 15 A:
*CYSAL..ES (CURR YR SALES) 7.2 N:
*LYSALES (LAST YR SALES) 7.2 N:
*LPDATE (LAST PO DATE) 6 N:
(NEXT RECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N:
*CUSTOMER (CUSTOMER NAME) 16 A:
*BUYER (BUYER NAME) 15 A:

24C§:)
'WINNEBAGO SALES· C!ID
'JERRY COWENS'~

NEXT~
25~

, ROYAL CYLLE' G!D
'RON KLINE'~
UP 2 C!ID
'ROYAL CYCLE'~
'RON KLINE'~
451G:i)
$217.45C!8
780210~

16C!ID
RIETRONICX ~
KILL C!ID

(NEXT RECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N:
*CUSTOMER (CUSTOMER NAME) 16 A:
*BUYER (BUYER NAME) 15 A:
*CYSALES (CURR YR SALES) 7 2 N:
*LYSALES (LAST YR SALES) 7.2 N:
*LPDATE (LAST PO DATE) 6 N:

RIATRONICS ~
• LAUREN L LEE' G£)
-250. C!ID

(NEXT RECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N:

ENDG:i)

<C~U>

4-20

26~

22,250~

780130G£)

CREATING AND EDITING A DATA FILE

LIST
FUNCTION:
The LIST command displays one or more records on the terminal.
IOL can display either a selected portion of each record or only
selected items, depending on the format of the LIST command. You
can list up to 15 items for each record.
FORMATS:
1.

LIST [integer]

[i tern ... item]

LIST [i tern [... item]]

[findlist]

DEFAULTS:
If you use only the word LIST, IOL lists the current
the file is not moved.

record

and

DISCUSSION:
If you do not specify any item names to be listed, LIST displays
the entire record or a part of it, depending on whether you have
used COLUMNS or not.
The following paragraphs summarize the LIST command options.
1.

LIST
Lists the entire current record.

LIST integer
Lists the current and following
number of records are listed.

records

until

the

integer

LIST integer item-name item-name
Lists only the named items, starting with the current record,
until these items have been listed for the specified records.
Signs and decimal points are shown for numeric items~
The
items format is generally easier to read than a continuous
portion of the record, especially if binary items are
involved.

LIST item-name item-name ...
Lists only named items for the current record.
the file.

Does not move

LIST findlist
Lists all records located by the findlist.

LIST item-name item-name
Lists only
findlist.

named

items

findlist
for

4-21

each

record

located

the

CREATING AND EDITING A DATA FILE
IOL leaves the file positioned at the last record listed unless
(1) you used ALL in your findlist or (2) in listing the system
encountered the end of the file. In these cases, it issues an AT
END OF FILE message and leaves the file positioned at the end of
the file.
EXAMPLES:
1.

LIST

ACCOUNT

LIST FIRST ACCOUNT = 6000

LIST ALL ACCOUNT = 6000

LIST LEDGER AMOUNT FOR ALL ACCOUNT = 6000

LIST ACCOUNT LEDGER AMOUNT RATE FOR ALL ++
ACCOUNT GEG 6000 AND YEAR 76

ACCOUNT

LEDGER

AMOUNT

4-22

CREATING AND EDITING A DATA FILE
SAVE
FUNCTION:

Saves the current version of the file.
FORMAT:
SAVE
DISCUSSION:

The current version replaces the original version
The file is left positioned at its beginning.
EXAMPLES~

SAVE

4-23

the

file.

CREATING AND EDITING A DATA FILE

TOP
FUNCTION:
Positions the file at the beginning (top).
FORMAT:
TOP
DEFAULT:
If the file is positioned at
position remains unchanged.

the

beginning

the

file,

the

beginning,

positioned

DISCUSSION:
If the file is positioned at
before the first record.
EXAMPLES:
1.

TOP

4-24

CREATING AND EDITING A DATA FILE
UP
FUNCTION:
Moves the file up (toward its top or beginning) a specified
number of records. If verify option is on, IQL displays the new
current record.
FORMAT:
UP [integer]
DEFAULT:
If you omit the integer value, the system moves the file
record.

one

DISCUSSION:
The integer is the number of records the file is to be moved up.
If IQL encounters the beginning of the file before it has moved
up the specified number Of records, it issues an AT BEGINNING OF
FILE message and leaves the file positioned at its beginning
(before the first record). If the file is positioned at its end
(after the last record) and UP or UP 1 is used, IQL moves the
file up to th~ last record in the file.
ERRORS:
If you enter alphabetic characters in the integer parameter, IQL
issues an error message, rejects the UP command, and does not
move the file.
EXAMPLES:
1.

UP 600

4-25

CREATING AND EDITING A DATA FILE
VERIFY
FUNCTION:
The VERIFY command turns on or off the verify option.
FORMAT:
VERIFY

[ON]
[OFF]

DEFAULT:
When you begin your
automatically on.

update

session,

the

verify

option

DISCUSSION:
If the verify option is on, lOt (1) automatically displays the
new current record located by UP, DOWN, or FIND commands and (2)
automatically displays each changed record as a CHANGE command is
carried out. If the verify option is off, these records are not
automatically displayed.
ERRORS:
If IOL encounters a word other than ON or OFF after VERIFY,
issues an error message and turns on the verify option.
EXAMPLES:

VERIFY

VERIFY ON

VERIFY OFF

4-26

IOL

CHAPTER 5
CREATING AND EDITING A DICTIONARY

IQL controls the access to data files and data bases by using a
prestored
description
of the data files or data bases.
The
description is called a dictionary, which IQL stores as a table on
disk.
A dictionary contains information about where and how each data
item is stored, cosmetic information anticipating printing,
and
password information to protect the data file or data base from
unauthorized access using IQL.
For IQL to access a data file or a data base, you need to define a
dictionary only once;
moreover you need define only those specific
items in which you are interested.
To define or change a dictionary, use the DEFINE assistance command.
IQL issues a full prompt for each field in each dictionary entry, and
you can back up if you make a mistake.
Appendix C shows a full
example of a dictionary.
Also,
in Section 5.5, full examples are
given of DEFINE sequences to create or change a dictionary entry.
A dictionary begins with an FD
file definition
entry, which
identifies the dictionary and describes the data file or data-base.
The main entry in a dictionary that describes a file is the DD data
definition - entry, which describes each data item in the file.
Other
dictionary entries for files describe comments and passwords.
In addition to the item, comment, and password entries, a dictionary
that describes a DBMS data base must contain record, area, and set
entries.

5.1

DEFINING A DICTIONARY FOR DBMS

You can use the DBMS schema (.SCH) file and a program called IQSCH to
initially build a dictionary for
a DBMS data base.
IQSCH creates
specifications for column titles and editing pictures since the schema
does not contain these specifications.
It is strongly recommended that you review the dictionary created by
IQSCH and change the column titles or editing pictures you do not
like.
Please note that dictionaries created with IQSCH do not contain
items below the 02 level in the schema.
Use the following commands to initially create a dictionary for a DBMS
data base.
fin;: IQSCH~
(respond to prompt with name of the .SCH file)
(~R I(~D GID

(now inspect the dictionary generated)
5-1

CREATING AND EDITING A DICTIONARY
@F~

IQLCE2)

<OA> I TEMS

SUBSCHEMA-NAME ~

(IQL then displays the new dictionary.
DEFINE assistance command.)

5.2

change

it,

use

the

DISPLAYING A DICTIONARY

You can request either a terminal displa~T or a full printer listing of
any dictionary in a directory.
The DICTIONARIES assistance command of
IQL produces a
terminal display of the file definitions
in all
dictionaries.
The ITEMS assistance command produces a full terminal
display of a specific dictionary.
Since terminal displays of dictionary information are formatted
72
characters wide, you may find it easier to work with the l32-character
wide printer listing of dictionary.
To produce a printer dictionary
listing, use an action code of P in an FD transaction (see Section 5.5
for more information on the FD transaction).
The types of individual entries in a dictionary are listed below.
All
entry types are not necessarily needed in anyone dictionary.
Each
entry type is described in considerable detail
in its own section
later in this chapter.
1.

FD (file definition) entry
Defines the overall structure and location of a file or data
base.
This is the master definition in each dictionary and
identifies the dictionary itself.
The FD entry must be the
first entry in the dictionary.

DD (data definition) entry
Defines a specific data
item in
entries make up the bulk of a~y
defines not only where and how the
also contains column titles and a
the display of the item.

a
file or dataset.
DD
dictionary.
Each DD entry
data item is stored, but
printing picture to format

PD (password definition) entry
Defines a password, which protects the dictionary against
unauthorized use.
Passwords can be applied at either the
Passwords
are
stored
file or
individual
item level.
scrambled.
Refer
to Section 5.3 for more information on
protecting a data base.

CD (comment) entry
The CD entry places explanatory comments in the
itself.
It does not serve any other purpose.

dictionary

AD (area definition) entry
The AD entry is used only in dictionaries that define DBMS
data bases.
IQL uses AD entries to check area names in DBMS
FIND commands.

5-2

CREATING AND EDITING A DICTIONARY
6.

RD (record definition) entry
The RD entry is used either in dictionaries describing files
with multiple record types or defining DBMS data bases. All
DO (data definition) entrieq that follow a particular RD
entry belong to the record the RD describes.

SO (set definition) entry
The SO entry is used only in dictionaries that define DBMS
data bases.
IOL uses SO entries to check set relationships
that you specify to direct IOL to specific records in a data
base.

5.3

DEFINING DICTIONARY PROTECTION

You define passwords with the FD and PO transactions.
Passwords
protect the data file or data base against anyone accessing sensitive
data through IOL.
If you protect a dictionary with a master password
when defining a dictionary with a FD transaction,
IOL requests
password reference numbers at the end of the FD transaction.
The
password reference numbers point to specific PD entries in the
dictionary that define the individual passwords.
You can protect the data file or data
following levels:
1.

base

any

all

the

READ
A reference to a password here means that IOL will not permit
reading the file or data base unless it receives a password
at the same or higher level than·that referenced.

WRITE
A reference to a password here means that IOL will not write
information from the file
(with COpy or CREATE) unless it
receives a password at the same or higher level than that
referenced.

REWRITE
Rewrite access only applies to ISAM files.
A reference to a
password here means that IOL will not write back into that
ISAM file unless it receives a password at the same or higher
level than that referenced.

Normal practice is to make WRITE protection higher than
READ
protection and REWRITE protection higher than WRITE protection.
Since
mistakenly writing back into an ISAM file can be catastrophic, it is a
good idea to password protect (at least at the REWRITE level) each
dictionary describing an ISAM file.
You can also protect any individual item in a dictionary by putting a
password reference number in the DD entry describing that item. This
overrides READ protection at the file level.
You can also indicate
exclusivity in the DD so that only the referenced password permits
access to the protected item.
Individual item password protection is
convenient if you wish to protect different items at different levels.

5-3

CREATING AND EDITING A DICTIONARY
Since password numbers are a level of protection numbers, any password
with a higher number unlocks access to anything protected in that
dictionary with a lower level password. The only exception to this
rule is an exclusive item protection.

5.4

ORDERING DICTIONARY ENTRIES

The only order required of entries in a dictionary is that the FD
entry must come first and DD entries must directly follow any RD entry
describing the record in which the data items are located. - Within a
record, no specific order is required for DD entries. You can arrange
DD entries by occurrence in the record, by function, or alphabetically
by name.
The following general order
efficient for IOL to process:

makes

dictionaries

easy

use

and

FD entry (required)
PD entries (if any)
AD entries (if any) - only used for DBMS
SD entries (if any) - only used for DBMS
RD entry (if any)
DD entries for above RD or whole dictionary if no RD
RD entry (if any)
DD entries for above RD
... CD entries can be anywhere

5.~

DICTIONARY COMMAND FORMATS

Each type of dictionary command is described in detail in the
remainder of Chapter 5. The AD, CD, DD, FD, PD, RD, and SD commands
invoke a set of prompts referred to as a transaction. As you respond
to the prompts, IOL generates a temporary file. When you use the END
dictionary command, IOL uses the temporary file to change the actual
dictionary entries.
Unless otherwise stated, you can use the following dictionary commands
at any time to control the progress of a transaction.
1.

NEXT
Go on to the next transaction.
This generally means
completed the meaningful part of this transaction.

you

KILL
Kill this transaction and start it over.

END
End prompted input of transactions and use- the transactions
to physically define or change the dictionary. When the
dictionary update is complete, the system returns to the
assistance level.

SCRUB
End prompted input of transactions. Do not physically define
or update the dictionary but go up directly to the assistance
level.
5-4

CREATING AND EDITING A DICTIONARY
5.

BACK integer
Back up integer prompts.
You should use BACK if you find you
made a mistake in the transaction and wish to return to
correct it.
The integer can be one or two digits.

DOWN integer
Move down integer prompts.

Some transactions display the prompt:
or
*ACTION CODE

(A,C~D):

Respond with one of the following action codes.
code to control the transaction.
1.

IQL uses

the

action

The A action code
Add the entry defined by this transaction.
IQL inserts the
entry
immediately
following
the entry that you just
identified to IQL.
For instance, to add a DD entry to the
end of a dictionary, you must first use a FD transaction with
the C action code to identify to IQL the dictionary.
Then
you must use a DD transaction with the C action code to
identify to IQL the last DD entry in the dictionary.
Finally,
you must use the DD transaction with the A action
code to add a DD entry to the end of the dictionary.

The D action code
Delete the entry defined by this transaction.
For FD,
DD,
RD, AD, and SD entries, only the name is necessary to locate
the entry to be deleted.
For PD entries, the full
password
is necessary.
For CD entries, the comment number is needed.

The C action code
Change or identify to IQL the entry defined by
this
transaction.
Only the nonblank fields in the entry replace
the corresponding fields in the entry.
If you wish to force
blanks into a
field
in the entry, enter the special word
BLANK in response to the DEFINE prompt.

The P action code
Create a print-formatted file of the contents of
the
dictionary named by this transaction (FD entry only).
IQL
creates a print-formatted file with the filename QLjobD.LPT,
which you can later print using the TOPS-IO or TOPS-20 PRINT
command.

5-5

CREATING AND EDITING A DICTIONARY
AD
FUNCTION:
The AD transaction creates an AD entry that describes an AREA in
a schema.
The AD entry is used only in dictionaries describing a
DBMS data base.
ELEMENTS:
1.

COMMAND:

AREA NAME:

The name of the area.
Must be the same as the
area in the DBMS schema.
3.

name

the

Always 1. At present, IQL does not use the area origin,
may in future versions.

but

AREA ORIGIN:

DESCRIPTION:
Descriptive remarks up to 76 characters.

DISCUSSION:
IQL uses AD entries to check area names you use in the
record selection expressions in the FIND query statements.
EXAMPLES:
1.

Defining a new AD:

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D):
*AREA NAME:
*AREA ORIGIN:
*DESCRIPTION (IF ANY>:

AD~
A~
PAYf:OLL~

lG:Q

HOLDS PAYROLL INFOG!D

Gives the area description entry:

AD PAYROLL 1 HOLDS PAYROLL INFO
2.

Changing the above AD entry:
*FD,DD,PD~CD,RD,AD,SD,END,SCRUB:

*ACTION CODE (A,C,D>:
*AREA NAME:
*DESCRIPTION (IF ANY>:

AD~

eGO

f'AYROLL~

NEXTG!!)

Gives the revised AD entry:

AD PAYROLL 1 HOLDS PAYROLL INFO

5-6

DBMS

CREATING AND EDITING A DICTIONARY
CD
FUNCTION:
The CD transaction
dictionary.

creates

comment

entry

anywhere

ELEMENTS:
1.

COMMAND:

COMMENT NUMBER:
Where number is one or two digits and can be O.

COMMENT TEXT:
Any string up to 115 characters.

DISCUSSION:
Comment entries serve as notes in a dictionary.
These entries
are especially useful if you are making up a dictionary to be
used later by someone else.
The comment number is there so that you can differentiate between
comment entries if you later wish to change or delete them.
Although you can use a comment number value of 00
(which prints
as spaces because IQL suppresses zeros), you must be careful in
positioning the dictionary at any specific comment if you ever
wish to change or delete it.
EXAMPLES:
1.

Defining a new CD:

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A, C, OR D):
*COMMENT NUMBER (2 DIGITS):
*COMMENT TEXT:

CD~
A~

JOB OPENINGS~

Gives the comment entry:

CD
2.

1 JOB OPENINGS

Changing a CD:

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D):
*COMMENT NUMBER (2 DIGITS):
*COMMENT TEXT:
Gives the comment entry:

1 IOWA JOB OPENINGS

5-7

CD~

cGD
1~

IOWA JOB OPENINGS~

CREATING AND EDITING A DICTIONARY
DD
FUNCTION:
The DD transaction creates a
DD entry that describes
an
individual data item in a data file or data base.
The DD entry
contains information enabling IQL to locate,
extract,
and work
with the item that the DD entry describes.
The DD entry also
contains information for IQL to print or to display the item in a
meaningful format.
ELEMENTS:
1.

COMMAND:

ITEM NAME:

The item name can be up to 30 characters and can contain any
combination of letters numbers and dashes.
The item name
must contain at least one letter and cannot start or end with
a dash.
3.

TOP COLUMN TITLE:
The top column title can be up to 10 characters.
These
characters are printed at the top of each column in a report
listing the item in default column print format.

BOTTOM COLUMN TITLE:
The
The bottom column title can be up to 10 characters.
title is printed
in a
report right under the Top Column
Title.

LOCATION OF FIRST CHARACTER OF ITEM:
The location in your record of the leftmost character of your
item.
The first character location in a record is numbered
1.
Binary items start on a word boundary.

LENGTH OF ITEM:
For an alphabetic or alphanumeric item,
the length of the
item is expressed
in characters.
For a numeric item, the
length is expressed in digits,
exclusive of sign.
For
a
binary item,
it is the length of the item if converted to
decimal digits, exclusive of sign (that is,
a
binary item
that contains
9 digits physically occupies one word;
use
item length of 9).

ITEM TYPE:
The item type is A for
alphabetic or alphanumeric,
N for
numeric,
and B for binary.
Generally it is good practice to
make an item alpha (even if it contains only digits)
unless
you are actually going
to compute with it.
For instance,
there is no need to make a zip code or a social
security
number a numeric item.

5-8

CREATING AND EDITING A DICTIONARY
8.

SCALE:
The scale is the number of decimal positions in the
item.
Use 0 if there is no decimal point or if the item is alpha.
IQL uses scale both in lining up for
computations and for
placing the item value in a picture for displays.
The
decimal point is not actually recorded in the' data.
For
instance, if an item with length 6 and scale 2 is recorded as
039508, IQL prints it (if the picture is ZZZZ.99) as 395.08.

DISPLAY PICTURE:
A group of characters that IQL uses to format the item value
for
displaying
or printing so that you can read
it
conveniently.

10.

INPUT FIELD?

= YES, N = NO):

If you respond with Y, IQL prompts you for
the data item
while in the update or input level.
If you respond with N,
IQL does not prompt you for the data item.
If you supply
neither response, IQL assumes the Y response.
11.

SCAN GROUP NAME:
Respond with a scan group name only if you are defining an
item that repeats.
These items can be processed as one item
by the SCAN capability.
The scan group name is a I-character
common identifier given to all member items in the same scan
group. When IQL is scanning left to right in a scan group,
it jumps ahead from member to next occurrence of the same
member.
Each jump is indicated by the length of the longest
member.
For instance, assume DATE is the longest member of a
group;
and the items following in the dictionary are YEAR,
MONTH,
and DAY, all being members of the same scan group as
DATE.
The scan group name for each of DATE, YEAR, MONTH, and
DAY would be the same (for example: W).
In scanning, IQL
would jump from YEAR to YEAR by the length of DATE.

12.

REPEATS IN GROUP:
The number of times each member of the group is repeated.

13.

SCAN STOP CHARACTER:
The scan stop character
is a unique character that IQL
displays only if the item is a member of a scan group. When
IQL encounters the scan stop character in all positions of a
value for
the item, IQL stops scanning for the item, which
serves to end the scan when all the buckets of the item are
not used.

14.

PASSWORD REFERENCE:
Used only if this item is to be individually protected by a
password.
This is a 2-digit number pointing to an earlier
Password Definition (PD) entry in this dictionary.
IQL does
not permit this item be used unless the referenced password
or a higher level password, depending on the exclusivity,
if
furnished.

5-9

CREATING AND EDITING A DICTIONARY
15.

EXCLUSIVITY:
IQL displays the exclusivity prompt if you specified an item
level of password protection in the previous prompt. If you
enter Y (yes), then only the referenced password unlocks the
item.
If you enter N (no), then either the referenced
password or any higher level password in this dictionary
unlocks the item.

EXAMPLES:
1.

Defining a DD entry for a numeric item:
*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D):
*ITEM NAME (UP TO 30 CHARS):·
*TOP COLUMN TITLE (UP TO 10 CHARS):
*BOTTOM TITLE (UP TO 10 CHARS):
*LOC OF FIRST CHAR OF ITEM:
*LENGTH OF ITEM IN DIGITS OR CHARS:
*ITEM TYPE (A,N OR B)I
*SCALE (NO. OF DECIMAL PLACES):
*DISPLAY PICTURE (IF ANY):
*INPUT FIELD? (Y = YES, N = NO):
*SCAN GROUP NAME (A - Z):

DD~

AG:0

LY-DONATEGD
LAST YEARG!D
DONATIONGED
73G!)
8~

NGD

2GD
$$$$,$$$.99GQ
N~
NEXT~

Gives the following DD entry:
DD LY-DONATE LAST YEAR DONATION 73 8 N 2 $$$$,$$$.99
2.

Defining an alpha item:
*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D):
*ITEM NAME (UP TO 30 CHARS):
*TOP COLUMN TITLE (UP TO 10 CHARS):
*BOTTOM TITLE (UP TO 10 CHARS):
*LOC OF FIRST CHAR OF ITEM:
*LENGTH OF ITEM IN DIGITS OR CHARS:
*ITEM TYPE CA,N OR B):
*SCALE (NO. OF DECIMAL PLACES):

DDGD

AGIQ
COMPANY-NAMEGB
COMPANYGQ
NAME(§)
108~

26GD

AGED
NEXTCEi)

Gives the following dd:
DD COMPANY-NAME COMPANY NAME 108 26 A

5-10

CREATING AND EDITING A DICTIONARY
FD
FUNCTION:
The FD transaction provides an FD entry that identifies the
dictionary, defines the location and overall attributes of the
data file or data base, and protects the dictionary at the file
level.
ELEMENTS:
1.

COMMAND:

DICTIONARY NAME:
Up to 30 characters, consisting of any combination of
letters, numbers, and dashes.
You cannot start or end a
dictionary name with a dash.
The dictionary name must
contain one or more letters. For dictionaries describing
DBMS data bases, the dictionary name must be the same as the
name of the subschema the dictionary describes.

DICTIONARY UNLOCKING PASSWORD:
The password that you specify defines the master password to
IQL.
To display or change privileged areas of a dictionary,
you must supply to IQL the master password.

FILENAME:
The name of the file the dictionary describes. If the file
is part of a DBMS data base, the filename must be the name of
the .SCH file. You can specify up to six filename characters
and up to three extension characters. The filename follows
the regular DIGITAL standard for filenames.

FILE DIRECTORY:
The directory where the file is located. You should respond
with the regular DIGITAL standard for directory names. A
value of spaces is acceptable and is recommended if you are
going to access a file only from the same directory in which
it is located. The directory information in a dictionary is
only documentary.
Refer to Chapter 1 for a description of
how IQL locates files.

FILE TYPE:
Respond with one of the following file types:
TAPE
DISK6
DISK7
DBMS

magnetic tape, ASCII format
disk, 6-bit ASCII format
disk, 7-bit ASCII format
DBMS data base

RECORD LENGTH:
Maximum length of the record in characters.
Files written
with the COpy command have this record length. Not used for
DBMS processing. For 6-bit files, the record length must be
a multiple of six.

5-11

CREATING AND EDITING A DICTIONARY
8.

BLOCKING FACTOR:
The blocking factor defines to IQL the number of records per
physical block of an ISAM file. Most sequential disk files
use a blocking factor of 0, but some have specific blocking
factors.

LOCATION OF ISAM KEY:
Applicable only to ISAM (indexed sequential) files. This is
the location in the record of the leftmost character of the
ISAM key.
(The first character in a record is numbered 1).
IQL assumes the file is ISAM if this field is specified (that
is, not blank or 0).

10.

ISAM KEY LENGTH:
The length of the ISAM key in characters.
files.

11.

ISAM KEY TYPE:
Respond with A for alphabetic and N for
for ISAM files.

12.

Used only for ISAM

~umeric.

Used

only

ISAM KEY SIGN:
a.

Respond with S for signed (only applies to numeric).
b.

Respond with U for unsigned (only used for ISAM files).
13.

READ PASSWORD REFERENCE:
The level of the password, if any, that protects against
unauthorized use of this dictionary to read the specific file
or data base.
(The actual password is defined in a later PO
entry in this dictionary).

14.

COpy PASSWORD REFERENCE:
The level of the password, if any, that protects against the
unauthorized use of the dictionary to write (using th~ COPY,
CREATE, or UPDATE assistance commands) to a data file or data
base described by this dictionary.
(The actual password is
defined in a later PO entry in this dictionary.)

15.

REWRITE PASSWORD REFERENCE:
The level of the password, if any, used to protect against
unauthorized use of this dictionary to write records back in
place in an ISAM file. Not applicable to other than ISAM
files.

5-12

CREATING AND EDITING A DICTIONARY
EXAMPLES:
1.

Defining a new FD.
<QA>DE:rINE~

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D OR P):
*DICT NAME - UP TO 30 CHARS:
*DICT UNLOCKING PASSWORD, IF ANY:
*FILENAME AS XXXXXX.EEE:
*FILE DIRECTORY:
*FILETYPE (TAPE,DISK6,DISK7,DBMS):
*RECORD LENGTH IN CHARS:
*BLOCKING FACTOR (RECS/BLOCK):
*LOC OF ISAM KEY:
*ISAM KEY LENGTH:
*ISAM KEY TYPE (A OR N):
*ISAM KEY SIGN (S OR U):
*READ PASSWORD REF:
*COPY PASSWORD REF:

FD~
A~

JOBSGD
FERNGD

JOB.SEQ~
BILL~
[JISK6~
240~

~
(§)
~

G!D
GID

10~
NEXT~

Gives the FD entry:

DICT FILE
ID NAME NAME
FD JOBS ..JOB. SEQ
2.

REC BL.K KEY KEY K K RD CP RW
DIRECT TYPE LEN FAC LOC LEN T S PW PW PW
....._.................
10
0 0
0
0
0
BILL DISI~6 240

Changing the previous FD (to ISAM file).
<QA>[lEFINE~

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D OR P):
*DICT NAME - UP TO 30 CHARS:
*DICT UNL.OCKING PASSWORD, IF ANY:
*FILENAME AS XXXXXX.EEE:
*FILE DIRECTORY:
*FILETYPE (TAPE,DISK6,DISK7,DBMS):
*RECORD LENGTH IN CHARS:
*BLOCKING FACTOR (RECS/BLOCK):
*LOC OF ISAM KEY:
*ISAM KEY LENGTH:
*ISAM KEY TYPE (A OR N):
*ISAM KEY SIGN (S OR U):
*READ PASSWORD REF:

FDGD

CG:Q

JOBSG!2)
FERN(§)
JOB.IDX(§)

G:D

GD
3GD

10~

12G!!:)
AG!!:)

UG!D

NEXT~

Gives the following revised FD entry:

DICT FIL.E
It' NAME NAME
FD .JOBS JOB. IDX

DIRECT TYPE

REC BLK KEY KEY K K RD CP RW
L.EN FAe LOC L.EN T S PW PW PW

BIL.L DISK6 240

5-13

12 A U 10

CREATING AND EDITING A DICTIONARY
3.

Delete a dictionary.

<GA>DEFINEG!.:D
*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D OR P);
*DICT NAME - UP TO 30 CHARS;

FD~
D~

JACKDIC~
END~

[END OF DICTIONARY TRANSACTION INPUT.]
(END OF DICTIONARY RUN)
<OA>

5-14

CREATING AND EDITING A DICTIONARY
PD
FUNCTION:
The PD transaction creates a PD entry that defines a password to
the corresponding level number.
The password is used to guard
against unauthorized use of the dictionary through IQL.
The FD
entry and/or one or more DD entries can point to this PD entry
using the password level number
in order to reference the
password.
ELEMENTS:
1.

COMMAND:

PASSWORD REFERENCE:
The password reference is 1 or 2 digits, which identifies the
password and glves it a
level of protection power.
This
number is used in the FD entry lf you wish to apply overall
read,
copy,
or
rewrite protection at the file or data base
level.
The password level number can also be used
in a DD
entry if you apply individual password protection to a
specific item.

PASSWORD:
Any string of up to six characters.
spaces.

Cannot contain

embedded

DISCUSSION:
IQL stores passwords in scrambled form in the dictionary.
You can change passwords by deleting the old PD entry and adding
the new one.
This is done so that anyone changing the password
must show proper authority by furnishing the old password.
IQL does not let you change PD entries or password reference
numbers in FD or DD entries unless you have furnished in the FD
entry a dictionary unlocking password for
such change.
This
unlocking password is one which is at the same or higher level
than the one being changed.
EXAMPLES:
1.

Defining a PD entry:

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB:
*ACTION CODE (A,C,D):
*PASSWORD REF (2 DIGITS):
*PASSWORD (6 CHARS):
Gives the PD entry:

PD 20 CAROLE

5-15

PDQID

AG0

20~
CAROl.E~

CREATING AND EDITING A DICTIONARY
2.

Changing a PD entry:

*FD,DD,PD,CD,RD,AD,SD,END,SCRUS:
*ACTION CODE (A,C,D):
*PASSWORD REF (2 DIGITS):
*PASSWORD:
*FD,DD,PD,CD,RD,AD,SD,END,SCRUS:
*ACTION CODE (A,C,D):
*PASSWORD REF (2 DIGITS):
*PAS~:)WOF~D :
Gives the revised PD entry:

PD 20 SHAZAM

5-16

PD~

DG!!)
20~
CAROLE~
PD~

AG£)
20~
SHAZAM~

CREATING AND EDITING A DICTIONARY
RD
FUNCTION:
The RD transaction creates a RD entry that describes a data
record for DBMS or for data files with more than one record type.
For DBMS, the RD transaction maps the IQL input buffers.
For
data files, the RD transaction identifies a data item -DD- as
belonging to a specific record.
ELEMENTS:
1.

COMMAND:

RECORD NAME:
The name of the record in your schema.

RECORD ORIGIN:
For data files, use a record origin of 1.
For DBMS data
bases, the record origin maps the record location in the IQL
composite input buffer. The record origin must start on a
word boundary. When IQL is reading a data base, IQL reads in
different record types side by side into a composite buffer.
The record origin is the leftmost character position where
IQL stores the record. For instance, if you wish to read a
data base with two 6-bit record types, the first record type
is a length of 100 and the second record type is a length of
200.
For it to start on a 6-bit word boundary, the record
origin for the RD for the first record is 1 and the record
origin for the second record is 103. By mapping the records
like this, you have all the items from all the current
related records available at the same time.

RECORD LENGTH:
The length of the record in characters.

RECORD NUMBER:
Use 1 in the first RD in the dictionary, 2 in the next RD,
and so on.
This Record Number is used in IQL's SD (Set
Definition) entry to show which records the set relates.

DESCRIPTION:
Up to 76 characters of remarks.

5-17

CREATING AND EDITING A DICTIONARY
EXAMPLE:
1.

Defining a new RD entry:

*FD,DD,PD,CD,RD,AD,SD,END,SCRUB
*ACTION CODE (A,C,D):
*RECORD NAME (UP TO 30 CHARS):
*RECORD ORIGIN (UP TO 4 DIGITS):
*RECORD LENGTH (UP TO 4 DIGITS):
*RECORD NUMBER (UP TO 3 DIGITS):
*DESCRIPTION (IF ANY):

RDGIQ

A~
DETAIL-RECORD~
439~

120G!!)

DETAIL RECORD FOR MEMBERG!!)

Gives the RD entry:

RD DETAIL-RECORD 438 120 2 DETAIL RECORD FOR MEMBER

5-18

CREATING AND EDITING A DICTIONARY
SD
FUNCTION:
The SD transaction creates a SD entry that describes a DBMS
base and the records it relates.

data

ELEMENTS:
1.

COMMAND:

SET NAME:

The name of the set.
in your schema.
3.

Must be the same as the name of the set

OWNER RECORD NUMBER:
The number of the record
of the set.

(see the RD entry) that is the owner

MEMBER RECORD NUMBER:
The number of the record (see
member record of the set.

the

entry)

that

the

DESCRIPTION:
Up to 76 characters of remarks or descriptive text.

DISCUSSION:
IQL uses SD entries to check set names in the
record
expressions that you specify in the FIND commands.

selection

EXAMPLE:
1.

Defining a new PD entry:
*FD,DD~PD,CD,RD,AD,SDYEND,SCRUB:

*ACTION CODE (A,C,D):
*SET NAME:
_
*SET OWNER RECORD NO.:
*SET MEMBER RECORD NO.:
*DESCRIPTION (IF ANY>:

SD~

AC§)

CUSTOMER-SETGIi)
10~
12~

RELATES SALESMAN/OWNER~

Gives the SD entry:

SD CUSTOMER-SET 10 12 RELATES SALESMAN/OWNER

5-19

CHAPTER 6
RUNNING IQL IN BATCH

You can specify any IQL function in batch. Write a control
file
(a
file with the extension .CTL) using a DIGITAL text editor, and place
the IQL commands and responses in the proper place preceded by an
asterisk
(*).
If you wish to place comments in the control file, use
a semicolon (;) as the first character of the line.
To submit the batch job, enter a monitor command, such as the TOPS-20
SUBMIT command, followed by the name of the control file.
To specify
a time limit or other limits, see the appropriate Operating System
reference manual, such as the TOPS-20 Batch Reference Manual.
The following three batch control files show representative IQL
jobs:
1.

batch

QBATCH.CTL
(~R

I(~L.QI0

9SPECIFY A REPORT AND RUN IT~
*WRITE~
*1-iEADING "BRCH(EN REJECTS -- MARCH II .~
*OPEN RE,JECTS.C§:)
*IF I:~EAS(JN :::: .' B.' AND MO :~~ ;-5 AND YR :::: 78~
*
F'F<INT F'ART"--Nfh PRICE, CUSTOMER.0IQ
*~$
*EUN~
*~i:UN~
*EXIT~

The first line begins with @ to signify an Operating System
command to run IQL.
The lines starting with an asterisk (*)
contain exactly the same information that you enter on the
terminal
keyboard.
To submit the above control file, you
might enter:
mSUBMIT QBATCH.CTL/TIME:00:05:00~

QSTACK.CTL
@R I(~L~
;RUN A STACKED SET OF ALREADY-WRITTEN QUERIESGIO
*F~UN REPAIR .."SCHEDULE GIO
; THE FOLLOWING CUJERY HAS ALREADY BEEN ANALYZED AND SAVED~
*EXECUTE PEF~FORMANCE""-ANALYSIS~
*I~UN MAINTENANCE:----BACKLfJG~

yWE KNOW THAT THE ABOVE QUERY WILL ASK FOR A DATE:~
; SUPPLY IT HERE.~
*020178 ~
*EX:rT~

You might submit the above with @SUBMIT QSTACK/PAGES:IOO.

6-1

RUNNING IQL IN BATCH
3.

QFIX.CTL
@F~

IQL~

;UPDATE THE REPAU-:: FILE ~
*UPDATE r~EPAIRS ~
*CHANGE MONTH TO 05 FOR ALL DEPT 21 AND MO :;:: 04 ~
*TOP~
*CHANGE DATE TO 051.!7j78 FOR CUSTOMER "SUBANO"~
*EXIT~
H~ERE ARE BACK AT IC:~L ASSISTANCE LEVEL..~
,NOW RUN A REPORT AGAINST THE UPDATED FILE~
*RUN REPA I I=<·-SCHEDULE G!D
*EXITG.l:D

You might submit the above with @SUBMIT QFIX.

6-2

APPENDIX A
EXAMPLE ASSISTANCE SESSION

The example below shows a representative assistance session. Although
it does not demonstrate all of the assistance commands, the example
illustrates the various levels of IQL.
@R

I(1L G!D

«~A>JOB Q!D

.JOB NUMBER: 14
«~A>(~UEF<IES ~

QUERIES STORED IN YOUR DIRECTORY ARE:
WEEKLY-SUMMARY
DRTLY-FORECAST

ACCOUNT-DETAIL
EXECUTIVES

WRAPUP

WX1Z
202-REPORT

«M>ITEMS RE.JECTS ~
FILE .... IN
NAME

FILE

N(.~.ME

TYPE

f<E.JECTS

SQ DSK7 RE.JECTSEQ

ITEM
ID NAME

TOP
TITLE

BOTTOM
TITL.E

DD
DD
DD

PART
SUPPLIER
UNIT

NUMBER
NAME
PRICE

PARTNO
SUPPLIER
PRICE

F<EC BLI( KEY KY KY ~"<D CP RW
LEN FAC LOC LN TP PW PW PW

DIF<
ECT

DICT

150

1ST NO. T S PRINTING
CHAF< CHAR Y C PICTU""~E
1
9
63

g A
18 A
4 N 2

XX~XXXX-XX

Z2.99

... (dictionary printout continues) ...

<QA>UPDATE ""~E.JECTS ~
(YOUR DIARY FILE IS QL014U.LPT)
«1U>FIND PAF<TNO AlJBELT47~
AUBELT47DELBERTSON DRIVES 42 AIRDALE ST.
0123921472567012178SUBANDA
<QU>CHANGE RE.JECT-DATE TO ()12378 ~
AUBELT47DELBERTSON DRIVES 42 AIRDAL.E ST.
0123921472567()12378SUBANDA
<QU>EXIT~

(END OF UPDATE SESSION)

A-I

PROVIDENCE RI
PROVIDENCE RI

SCAN
GNNS

EXAMPLE ASSISTANCE SESSION
<QA)WRITE @)
INPUT: QC014S~CRD
0010() HEAD I NG F~EJECTSI IDUE TO CORROS I ON .~
O()200
DISPLAY ON.,~
00300 OPEN F~E.JECTS. ~
0040() IF REASON ::: C '~
00500
PR INT F'Af~TNO, SUPPL.. IEF~, PRI CE, RE.JECT-. DATE, CUSTOMEF~ ~
00600
TALLY PARTNO.~
00700 ~ $
.I

*E~

[QCOl4S ~ CF~D]

<OA>RUN ~
03/~50/78

PAGE l

F~E.JECTB

DUE TO CORROSION
PART
NO.

aUF'PL I EI:~
NAME

UNIT
PRICE

DATE
RE.JECTED

CUSTOMER
NAME

A2-BKKT-72
W3-FRME-21
P3-PSTN-76

ALUMINIZER
WESTERN
RANDALL..

.78
2.47
7.50

O:L/21/78
02/22/78
12/20/77

SUBANDA
HAWTHORNE
RACINE PRODUCTS

... (report continues} ...
«~A>STOf~E

CORI~OS I ON-RF'T ~
(CORROSION-RPT STORED)

<OA>DEL..ETE ACCOUNT-DETAIL
(ACCOUNT-DETAIL DELETED)
(WX 1. Z DELETED)
<C~A>QUER I ES

WX1Z~

OUERIES STORED IN YOUR DIRECTORY ARE:
WEEKLY-SUMMARY
202-REPORT

WRAPUP
CORROSION-RPT

QRTRL..Y-FORECAST

<QA>EXIT~

(END OF IQL SESSION)

A-2

EXECUTIVES

APPENDIX i3
EXAMPLE IMMEDIATE MODE SESSION

Shown below is an example of a representative immediate mode session.
First, the example illustrates creating a new file at the input level
and inputing a few records. Then the example illustrates ending the
input level and entering the update level to do the following:
1.

Browse through the file.

Change a few records.

Insert more records.

Browse through the file.

The following condensed dictionary is referenced in the example. Note
that the fields marked with asterisks (that is: DD*) are used to
control retrieval but do not prompt for input. Thus, you can redefine
fields for use in retrieval without IOL prompting for the field while
at the input level.

DIeT
NAME

FILE
TYPE

FIL..E·. ·IN
NAME

DIR
ECT

LEN

BLK
LEN

SALES

DISKt)

SALES.SEA

DI R·n·SALES

120

ITEM
D NAME:

[lD CUSTNO

TOP
TITLE
CUSTOMEI:~

DD CUSTOMER CUSTOMEr~
BUYEF~
DD BUYEF~
DD CYSALES Cl.JF~F~
DD L..YSALES LAST YR
LAST PO
DD I...F'DATE
LAST PO
DD*LPYR
LAST PO
DD*L..PMO
LAST PO
DD*LF'DAY

BOTTOM
TITLE
NUMBEF~

NAME
NAME
SALES
SALES
DATE

F~EC

NO. T S PRINTING
CHAR Y C PICTLJF~E
._............. .... .- _._.- ................
e:'
...1 N 0 (';9999
l.
16 A 0
6
15 A 0
22
:37
9 N 2 ZZZZZZZ.99
46
9 N 2 $$$$$,$$$.99
~:;5
6 N 0 99/99/99

1ST

CHAf'~

YEAF~

:5~:;

MONTH
DAY

:57

2 N 0 99
2 N 0 99
2 N 0 99

In the dialogue shown below, the information you would enter is
in red print.

shown

The example shows starting the session by running IQL and then
entering INPUT as an IQL command. The system prompts you for the name
of the dictionary, displays progress report information, and goes
immediately to the input level. You then furnish the data to build
the file from scratch. Next you list all the records in full, look
for a specific record on a condition, change a value in a record, and
insert a new record.
B-1

EXAMPLE IMMEDIATE MODE SESSION
Following the insertion, you go to the top of the file and this time
you list selected fields for all records.
Then you move up two
records, make a single change, move down one record, and make a double
change.
Now you append a record to the end of the file. After
appending, you go to the top of the file and list specific fields for
only records that meet a specific criterion. Finally, you list all
the fields in all the records.
This example shows some of the different formats of the commands
some of the different ways item values can be furnished.
@R

I cn. G!!.)
INPUT SALES ~

«~A>

(NEXT RECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N: 1G!D
*CUSTOMER (CUSTOMER NAME) 16 A: HEARTHSIDE HOMES G!!.)
'LOIS J BCRIBNER'G!D
*BUYER (BUYER NAME) 15 A:
*CYSALES (CURR YR SALES) 7.2 N: 4:::j"OOO~
*LYSALES (LAST YR SALES) 7.2 N: $2351456. 78~
7fJ0127~
*LPDATE (LAST PO DATE) 6 N:
(NEXT F~ECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N: 5GZi)
*CUSTOMER (CUSTOMER NAME) 16 At -RIORDAN INC."G!!.)
NRALPH HOPWOOD·~
*BUYER (BUYER NAME) 15 A:
*CYSALES (CURR YR SALES) 7.2 N: ~)OO~
*LYSALES (LAST YR SALES) 7.2 N: O~
780110CE:D
*LPDATE (LAST PO DATE) 6 N:
(NEXT RECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N:
*CUSTOMER (CUSTOMER NAME) 16 A:
*BUYER (BUYER NAME) 15 A:
*CYSALES (CURR YR SALES) 7.2 N:
*LYSALES (LAST YR SALES) 7.2 N:
*LPDATE (LAST PO DATE) 6 N:

12~

, HEAr~T ASSOCIATES' ~
PUF,CHAS I NG G!2)
$11,463 ~
10000G!D
780217G!D

(NEXT I:~EC[)RD)
>l<Cl.JSTNO (CUSTOMEF~ NUMBER) 5 N: END G!D
<au> TOP~
(AT BEGINNING OF FILE)
<au> LIST ALL~
00001HEARTHSIDE HOMESLOIS J SCRIBNER004500000002345678780127
00005RIORDAN INC.
RALPH HOPWOOD 000050000000000000780110
00012HEART ASSOCIATESPURCHASING
001146300001000000780217
(AT END OF FILE)
<t~u> FIND FIF~ST CUSTNO :::: 5 G!D
00005RIORDAN INC.
RALPH HOPWOOD 000050000000000000780110
<au> CHANGE CYSALES TO 1,,111~
00005RIORDAN INC.
RALPH HOPWOOD 000111100000000000780110
<t~U> INSERT ~
(NEXT ~\:ECORD)
*CUSTNO (CUSTOMER NUMBER) 5 N:
7G!D
*CUSTOMER (CUSTOMER NAME) 16 A: -FLORIDA YACHTSIIG!D
'COL. RAY AHAB'~
*BUYER (BUYER NAME) 15 A:
*CYSALES (CURR YR SALES) 7.2 N: 650.0~5~
*LYSALES (LAST YR SALES) 7.2 N: 1.)50G!D
780130~
*LPDATE (LAST PO DATE) 6 N:

B-2

and

EXAMPLE IMMEDIATE MODE SESSION
(NEXT F~ECOr';:D)
*CUBTNO (CUSTOMEF~ NUMBER) 5 N:

ENDGEO

«~U> TOP~

(AT BEGINNING OF FILE)

<WJ> LIST CUSTNO CUSTOMER BUYER CYSALES FOF~ ALL RECORDS~
00001 HEARTHS IDE HOMES LOIS J SCRIBNER
45000.00
00005 RIORDAN INC+
RALPH HOPWOOD
1111.00
00007 FLORIDA YACHTS
COL. RAY AHAB
650.03
00012 HEART ASSOCIATES PURCHASING
11463.00
(AT END OF FIL.E)
«~U> UP 2~
00007FLORIDA YACHTS COL. RAY AHAB 000065003000065000780130
<au> CHANGE CYSALES TO -·~.=jOO~
00007FLORIDA YACHTS COL. RAY AHAB 00005000]000065000780230
<au> DOWN ~
00012HEART ASSOCIATESPURCHASING
001146300001000000780217
<au> CHANGE BUYER TO HFLOYD C CALHOUN" CYSALES TO :L2y46:3~
00012HEART ASSOCIATESFLOYD C CALHOUN00124630000:L000000780217
<au> APPEND ~
(AT END OF FILE)
(NEXT REC(H~D)
*CUSTNO (CUSTOMER NUMBER) 5 N: 17~
*CUSTOMER (CUSTOMER NAME) 16 A: "BATATTA BRANDyH~
JACWJES L.EROUX "~
*BUYER (BUYER NAME) 15 A:
*CYSALES (CURR YR SALES) 7.2 N: 10()0~
*LYSALES (LAST YR SALES) 7.2 N: $lY234.7~
*LPDATE (LAST PO DATE) 6 N:
7B011.5GEQ
H

(NEXT REC()J~D)
*CUSTNO (GUSTO~1ER NUMBER) !7; N: END ~
«~U> TOpGEQ
(AT BEGINNING OF FILE)
<CW> LIST CUSTNO CUSTOMEF, CYSALES FO~~ ALL.. CYSAL..ES GE(~ 10,O()0~
00001 HEARTHS I DE HOMES
45000.00
00012 HEART ASSOCIATES
:1.246:3.00
(AT END OF FILE)
<au> TOP ~
(AT BEGINNING OF FILE)
(QU> LIST CUSTOMER BUYER CYSALES LYSALES ALL.. ~
HEARTHS I DE HOMES LOIS J SCRIBNER
45000.00
$23,456.78
RIORDAN INC.
RALPH HOPWOOD
1111.00
$.00
FLORIDA YACHTS
COL. RAY AHAB
500.00S650.00
HEART ASSOCIATES FLOYD C CALHOUN
12463.00
$10,000.00
BATTATA BRANDY
JACQUES LEROUX
1000.00
$1,234.70
(AT END OF FILE)
<t~u> EXIT~

(AT END OF UPDATE SESSION)
«~A>

(here we are back at assistance level)

B-3

APPENDIX C
EXAMPLE DICTIONARIES

The following dictionary describes an ASCII Indexed Sequential file:
nICT
NAME

FILE
TYPE

PERSONNEL

IS [lSK7 PERSONIDX

ITEM
1D NAME

TOP

TITLE

FILE-IN
NAME

DIRECT

REC
LEN

BLK
FAC

<IQL30·~·[tIST>

300

---.,..---

BOTTOM
TITLE

FOX

1ST NO. T C' PRINTING
CHAR CHAR Y C_. PICTURE
-_.,...._. ---_. - .__.......... - _. -

EMPLOY

NUMBER

nIl LNAME-CH LNAME

CHAF~

nn SEX

SEX

271

[Itt CAT

. , AU 10 30 50

----

SCAN
GNNS PT

50
30
10

PII TIGER
PD BEAR
PII

,.)

-------- ---------- -_._---_._--

DII EMPNO

KEY I(Y KY RD CF' RW
LOC LN TP PW F'W PW

CAT
CO
[lIV
DEPT

nn CO
nn DIV
nn DEPT
[III LOCATOR
LOCATOR
FULL
F'HONE
!lD PHONE
SECURITY
DII SOC-SEC SOCIAL
[III LNAME
LAST
NAME
nIl FNAME
NAME
FIRST
I
no INIT
FULL NAME
nn NAME
STREET
no STREET
[lD COLLEGE-ID
COLL
CODE
nIl JOB-III
JOB
CODE
CITY
Dn CITY
STATE
no STATE
nIl MAILCODE ZIP
ZIP
no ZIP
CODE
DII AREA
AREA
CODE
no LCL-PHN LOCAL
PHONE
nD SALARY
SALARY
WEEKLY
nIl HRLY
HOURLY
RATE
nn OT-HRLY OVT-TME
RATE
DII OLD-SAL PREVIOUS
SALARY
nIl OLD-HRL PREV·-HRt Y RATE
no DATE-LR LAST RAISE YY-MM-D[I
lin [JATE-LRA DATE
LRA
nn YR-LR
YR
LR
nD MO-LR
MO
LR

7
10
14
7
212
19
28
43
53
28
55
77
79
154
181
207
207
212
215
222

228
233
238
244
249
249
249
251
C-l

5 N 0 ZZZZ9
1 A 0
1 A 0
1 A 0
3 N 0 ZZ9
4 N 0 ZZZ9
5 A 0
12 A 0 xxx-xxxx-xxxxx
10 N 0 (999)999-9999
9 N 0 999-99-9999
15 A 0
10 A 0
1 A 0
26 A 0
20 A 0
2 A 0
2 N 0 99
20 A 0
14 A 0
5 N 0 99999
5 N 0 99999
3 N 0 (999)
7 N 0 999-9999
6 N 2 SZZZ9.99
5 N 3 Z9.999
5 N 3 Z9.999
6 N 2 ZZZ9.99
5 N 3 Z9.999
6 N 0 99-99-99
6 A 0 xx-xx-xx
2 N 0
2 N 0

30
30

EXAMPLE DICTIONARIES
DAY
DD DA-LR
nn DATE··-HR DATE
YR
Df! YR····HR
MO
nn MO--HR
DAY
nn DA--HR
Df! DATE-flD DATE
YR
DD YR--Bn
MO
nn MO-BD
DAY
Dn DA-BD
TEST
Dn TEST
ACT
Dn ACT
[lD SKILL1
SKILL..
CDE
Dn CODE1
l.VL.
[lD LVLl
SKIL.l.
Dn SKILL2
CDE
Dn COf!E2
LVL
Dn LVL2
SKILL
Dn SKIL.L3
CDE
Dn CODE3
I... VI...
Df! L..VL3
[In SKILl.4
SKILL
CDE
DD CODE4
l..Vl..
Dn L..VL4
SKIl.L
DD SKILL5
CDE
DD CODE5
LVL
Df! LVL5
SKILL
Df! SKILL6
[In CODE6
CDE
LVL
Df! LV1.6
SKILL
DO SKILL7
CDE
DD CODE7
LVL..
[If!·LVL7
DD DATE-CH CHANGE
'CH
DD YR-CH
CH
Df! MO-CH
[lD DA-CH
CH
1)D SKILL
JOB
SKL
DD SK-CDE
S
DD 5K-C1
[lD 5K-C2
S
[If! SK-C3
S
[lD SK--LVL
SKL

L..R
HIRED
HR

253
")r:c....
~I,.'

255

257

HR
HR

.2~.:i9

BIRTH
[CD

Bf!
Bf!
RESULT
STAT
1
:1.

:L
~.~
:~
::.~

3
~5

:5
4
4
4
5

5
J::'

6
6

6
7
7
7
DATE
YR
MO
DA
SKILL
CDE
1
2
3
LVL

26:1.
261,
263
26:=:i

267
271.
273
273
276
277
277
280
281
281
284
285
285
288
289
289
292
293
293
296
297
297
300
81
81
83
85
273
273
273
274
275
276

(END LIST OF ITEMS)

C-2

2 N 0
6 N 0 99-99-99
2 N 0
2 N 0
2 N 0
6 N 0 99-99---99
2 N 0
2 N 0
;.~ N 0
4 N "'-.'') Z9.99%

:1. A 0
4 A 0 xxx·-x
~3 A 0

l. A 0

4 A 0 xxx-x
3 A 0
1 A 0
4 A () xxx-x
~3 A 0
:1. A 0
4 A 0 xxx-·x
3 A 0
1 A 0
4 A 0 xxx-x
3 A 0
1 A 0
4 A 0 xxx-x
3 A 0
1 A 0
4 A 0 xxx-x
3 A 0
1 N 0
6 N 0 99-99-99
2 N 0 5Z(j)
2 N 0 5Z9
2 N 0 5Z9
4 A 0 xxx-x
3 A 0
3 A 0
3 A 0
3 A 0
1 A 0 X

A129
A129
A129
A129
B07
[c07
B07
B07
B07
B07

EXAMPLE DICTIONARIES
The following dictionary describes an ASCII sequential file:

DrCT
NAME

FILE
TYPE

CUSTOMERS

sa [lSK7 CtJSTMRSEa

ITEM
III NAME

TOF'
TITLE

lI[I CUSTNO

CUSTOMER'S VEN[lOR NO.
CUSTOMER
NAME
BUYER
NAME
CUST
STREET
CUST
CITY
CUST
ST
CUST
ZIP
YR TO DATE PURCHASES
Y-T-II
PAID
CRE[lIT
lIMIT
SALESMAN
NUMBER

FILE-IN
NAME

[lIRECT

------

BOTTOM
TITLE

-------- -_ ..... ------- ---_._-----

[III CNAME

nrl BUYER
nn STREET
n[l CITY
STATE
D[I ZIP
Dn CYSAlES
II [I CYF'AID
[1[1 CLIMIT
[III SlSMAN

nIl

REC
LEN

BlK
FAC

145

KEY KY KY R[t Cf' RW
lOC IN Tf' f'W PW PW
0

1ST NO. T S PRINTING
CHAR CHAR Y C PICTURE

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

1
6
36
62
87

112
114
119
128
137
2

(ENII lIST OF ITEMS)

C-3

5 N 0 SZZZZ9
30 A 0
26 A 0
25 A 0
25 A 0
2 A 0
5 N 0 SZZZZ9
9 N 2 $$,$$$,$$$.$$
9 N 2 $$,$$$,$$$.$$
9 N 2 $$,$$$,S$$.$$
4 N 0 SZZZ9

SCAN
GNNS PT

The following dictionary describes a DBMS data base:

FILF-··JN
NAME

REC
LEN

BLK
FAC

600

KEY KY KY R[t Cf' RW
LOC LN TF' F'W F'W F'W

DIeT
NAME

FILE
TYPE

EMPLOYEES

DTABASE EMPLOYSCH

ITEM
II) NAME

1ST NO. T S PRINTING
BOTTOM
TOP
C PICTURE
CHAR CHAR Y
TITLE
TITLE
._ ....._..... _. _.,
_..... - .._--- -- ..... _. .-..... -'- -.. -., ......... _.....

.....- .... -- ....... ..

DIRECT
.... - .._.._.........

_ _ • _. _ . , _ ........ u _ _......... _

AD F' ERSON ._. ARE A

()

AD PAYROLl . ···AREA

AD CO L.l.. EGE-, ARE A

JOB NAME· . ARE A

RD PERSONNEL
NO
EMPLOY
DD EMF-NO
CHAR
Dft LNAME-CH L..NAME
SEX
nft SEX
CAT
Dft CAT
[1[1 CO
CO
DIV
D[I DIV
[/[1 DEPT
DEPT
LOCATOR
nD LOCATOR EMPLOYEE
PHONE
FULL
DD PHONE
SECt.mITY
[lD SOC,-SEC SOCIAL
NAME
L.AST
nn L.NAME
NAME
FIRST
DD FNAME
[If! INIT
I
NAME
nn NAME
STREET
DD STREET
YEAR
[In YRl
Fn-;:ST
MNTH
FRST
DD MOl
DAY
FRST
liD [tAl
DATE
FIRST
DD DATEl
CITY
DD CITY
{lD STATE
STATE
D[I MAIlCOftE ZIP
CODE
n[l AREA
AREA
[tIl lCl.-PHN LOCAL
PHONE
WEEKLY
SALARY
Dft SALARY
RATE
HOURLY
DD HRLY
RATE
Dft OT-HRLY OVT-TME
[lD OLD-SAL PREVIOUS
SALARY
DD OL.D-HRL F'REV-HRLY RATE
[lD DATE-'LR
LAST RAISE YY-MM·-DD
YR
LR
DD YR,··LR
LR
MO
fill MO-LR
DAY
I...R
nD DA·-LR
HIRED
on DATE-HR DATE
HR
YR
DII YR-HR
HR
MO
DD MO-HR
HR
DAY
nn DA-HR
BIRTH
DD DAlE-BD DATE
YR
BD
Dn YR-BD
[III HO-BIt
MO
BII
BD
DAY
DIt DA-BIt
RESULT
TEST
nn TEST

1
1
28
271
6
7

10
14
1
212
:I.(»
20

43
~.)3

28
1::'1::'
~J,.1

8:1.
8:~

81
1 ~)4
181
207
212
215
~~2~~

228
233
238

244
249
249
251
253
25~:i
,,)cot::"
.:.,
..,<J

257
259
261
261
263
265
267
C-4

SCAN
GNNS PT
............ _.

300 OOt Q5
,J N 0 SZZZZ9
1 A 0
1 A 0
:L A 0
3 N 0 ZZ9
4 N 0 ZZZ9
5 A 0
lB A 0
10 N () (999) ('J99'-99S'9
(» N () 999···99·-9999
15 A 0
to A 0
1 A 0
26 A ()
20 A 0
.:.. N 0
"-. N 0
N 0
"-.
6 N 0 99/99/99
20 A 0
14 A 0
5 N 0
3 N 0 (999)
7 N () 999--9999
6 N "-. SZZZ9.99
,., N 3 Z9.999
5 N :3 19.999
6 N 2 ZIZ9.99
5 N 3 Z9.999
6 N 0 99··.. 99-99
2 N 0
2 N 0
2 N 0
6 N 0 99·"99-99
2 N 0
Ie"

")
~)

r.:'

2 N 0
2 N 0
6 N 0 99-·99-99
2 N 0
2 N 0
2 N 0
4 N 2 Z9.99X

EXAMPLE DICTIONARIES

nn ACT
Dn SKILL1
D[I conE:!.
0[1 L.VL1
[1[1 SKILL2
D[I C()[lE2
D[I l.VL2
[1[1 BKIL..L3
D[I C()[lE3
Drr I...VL..3
[In SKILI..4
DD CODE4
D[I /...VL4
D[I SKILL5
[1[1 CODE5
D[I l.VL:7j
D[I SKILL6
1)D CODE6
D[I LVL6
DD SKILL7
DD CODE7
D[I LVL7
DD DATE--CH
DIt YR-CH
[ID MO-CH
Dft DA-CH
II It SKILL
[In Sf(-CDE
[lIt SK-Cl
DD SK-C2
OIl SK-C3
DD SK-L.VL
RD PAYROLL
DII P-JOBID
OD "JOBNO
0[1 COLLNO
DD PAYNO
DD P-COLID
DII P-NAME
Dn P-SSNO
DII P-CAT
0[1 DEf'NDTS
D[I P-HRLY
Dn P-OT
nIl P-SAL

ACT
SKILl...
CDr
LVI...
SKILL
CDF.
LVI...
SKILL
CDF.
LVI...
SKILL
cnr
LVI..
SKILL
C[lE
l.VL
SKILL
CDF.
l.VL
SKILL
CDE
LVL
CHANGE
CH
CH
CH
JOB
SKL
S
S
S
SKL

STAT

JOB
PAY
PAY
PAY
COLLEGE

ID
JNO
CNO
NO
III

SOCIAL..

SECURITY
CATEGORY
CLAIMED
RATE
TIME
SALAf,Y

DEPNDTS
HOURLY
OVER

RIt COLLEGE
nD DB-CNO
nIt DB-CNAME COLLEGE
RD JOEIS
[III DB-JNO
[III DB-JNAME

1
1
")

.:..

2
'2

3
3
;:~

27:1.
2'73
273
276
277
277
280
281
28:1.
284
28~:.)

285

4
4

288
~)

",,-

,.1

6
6
6
7
7
7
DATE
YR
MO
IIA
SKILL
CItE
1

3
LVL

289
289
292
293
293
296
297
297
300
81

81
8:~

273
273
273
274
275
276
301
6
6
8
1

8
1.
10

19
20
22

27
32

401
1
NAME

501
1

,JOB

NAME

1 A 0
4 A 0 xxx-x
3 A 0
:I. A 0
4 A 0 xxx-x
3 A 0
1 A 0
4 A 0 xxx-x
3 A ()
1 A 0

4 A 0 xxx-·x
3 A 0
1 A 0
4 A () xxx-x
3 A 0
1 A 0
4 A 0 xxx···x
;3 A 0
1 A 0
4 A 0 xxx-x
3 A 0
1 N 0
6 N 0 99-99-·99
N 0 SZ9
2 N 0 SZ9
2 N 0 SZ9
4 A 0 xxx-x
3 A 0
3 A 0
3 A 0
3 A 0
1 A 0 X
")

1<-

100 002 Q5
2 N 0 SZ9
2 N 0 SZ9
2 N 0 SZ9
5 N 0 SZZZZ9
2 N 0 SZ9
5 N 0 ZZZZ9
9 N 0 999-99-9999
:I. A ()
2 N 0 SZ9
5 N :3 Z9.999
5 N :3 Z9.999
6 N 2 SZZZ9.99
003 Q5
N 0 SZ9
30 A 0

:LOO
2

100 004 Q5
2 N 0 SZ9
30 A 0

S[I PERSON-SET

S[I PAYROLL-SET

S[I JOB-SET

SII COLLEGE-SET

( ENtl LIST OF ITEMS)
C-5

A129
A129
A129
A129
S07
B07
B07
B07
B07
B07

APPENDIX D
MAXIMUMS

The following maximums apply to each lOL query and the files and
items that lOL processes:

data

Input files to a query
Output files from a query

1 copy file
1 created file per query stage

Sorts

100 approximately
The number varies
query.

depending

upon

the

Sort keys

100 approximately
The number of sort keys cannot exceed
the length of the record, which varies
with the query and with the length of
all the keys taken together.

Reports

Length of a query

200 statements, approximately

Length of a literal

72 characters

Length of a numeric item

18 digits

Length of an alpha item

354 characters
However, lOL only tests the first
characters in an IF query statement.

Length of a variable

Record lengths:
Input sequential files

6-bit format
7-bit format

4095 characters
3410 characters

Original ISAM file

6-bit format
7-bit format

1207 characters
1207 characters

2nd and 3rd ISAM files

6-bit format
7-bit format

768 characters
640 characters

Copied or created files

6-bit format
7-bit format

768 characters
640 characters

D-l

MAXIMUMS
Aggregate limits

The sum of all the input file record
lengths, all held item lengths, and all
alphavariable lengths cannot exceed 4095
characters.
The sum of all the records to be sorted
and the aggregate length of the sort key
cannot exceed 4095 characters.
The sum of the number of all the data
items,
alphavariables,
numeric
variables, constants,
literals,
and
reports cannot exceed 200.

Many of the limits can be changed, if necessary,
software specialist assigned to the site.

D-2

the

DIGITAL

APPENDIX E
SUMMARY OF EDITOR COMMANDS

The EDIT and WRITE assistance commands invoke an editor.
Use the
WRITE assistance command to create a query: use the EDIT assistance
command to change a query.
On the TOPS-IO Operating System, you
invoke the editor supplied with IQL. On the TOPS-20 Operating System,
you invoke the EDIT editor, which is supplied with the system.

E.I

IQL EDITOR

The IQL editor uses the colon C:> for its string delimiter.
The IQL
editor does not use line numbers. The editor displays an asterisk and
awaits for a command. The IQL editor commands which are listed below:

Delete the current line of the query.

Move down one line and list it.

END

If the editor is at the insert level
terminate it and return to the command
level of the editor.
If the editor is
at the command level, exit the editor
and return to the assistance level.

Fstring:

Move to and list the next line
contains the designated string.

Insert one line of text after this line.
End the line with a carriage return.

Insert several lines of text after this
line.
Continue to insert lines until
you enter a carriage return as the first
character of a line.

Display the current line.

P:ALL

Display the current
subsequent lines.

line

Sstringl:string2:.

Substitute string2 for
current line.

stringl

which

and

all

the

Sstringl:string2:ALL

Substitute string2 for stringl in
current and all following lines.

the

TOP

Go to the beginning of the query.

E-1

SUMMARY OF EDITOR COMMANDS

E.2

TOPS-20 EDITOR

The TOPS-20 editor is described in the TOPS-20 EDIT Reference Manual.
However, the following TOPS-20 EDIT command summary is provided:

The editor displays an asterisk
(*)
on
the terminal to indicate that the editor
is ready to accept a command.

The dollar symbol denotes the escape key
on the terminal.

Delete the current line of the query.

linefeed key

Move down one line.

escape key

If the editor is at the insert level,
terminate it and return to the command
level of the editor. If the editor is
at
the
command level, display the
previous line of text.

Fstring$

Move to the next query statement that
designated string and
contains
the
display it.

Insert one line of text after this line.
The editor prompts you fo~ a new line by
displaying the line number and waits for
you to enter the line. End the line
with a carriage return.

I. ,2

Insert several lines of text after this
line.
Continue to insert lines until
you enter the escape key as the first
The editor
character
in
a
line.
increments the line numbers by two.

Display the current line.

Display the current line and the next 15
lines.

Sstringl$string2$.

Substitute string2 for
current line.

p ....

Display the first line in the query.

Pnn

Display line nn.

P nn:mm

Display lines nn through mm.

Exit the editor
assistance level.

E-2

and

stringl

return

the

APPENDIX F
IQL ERROR MESSAGES

Error messages from IQL are preceded by either a question mark
(?) ,
which indicates a fatal error or a percent sign (%), which indicates
either a warning message or an information message.
When IQL
encounters a fatal error, IQL displays the error message, terminates
IQL, and returns you to the Operating System. When IQL encounters a
nonfatal error, IQL displays the warning or information message and
continues the operation.
IQL issues the error messages listed in this appendix at various
locations during the use of IQL~ For instance in the immediate mode,
IQL displays an error message after you enter the offending command or
data value. In the deferred mode, IOL displays an error message after
IQL reads the offending command in the query or at the completion of
the query run.
In either case, the error message and the indicated
corrective action are self-explanatory; hence no additional text is
given in this appendix.
A lowercase word in the message text indicates that IQL fills
word before issuing the message.

the

If you receive any other error message from IQL and the meaning is not
immediately clear, it may be a problem with IQL itself and you should
promptly report it as an SPR.

F.l

ERROR MESSAGES FROM IMMEDIATE MODE

The following error messages apply to the overall assistance level:
%invalid response - please reenter.
%dummy files isamf6.idx and isamf7.idx are not in your
directory/ppn. you need them to run a query.
The following messages can occur when you store, run, or get a query:
%THERE IS NO QUERY TO STORE.
%THERE IS NO QUERY TO REPLACE.WITH.
%THERE IS NO CURRENT QUERY TO RUN.
%THERE IS NO CURRENT QUERY.
%query-name IS ALREADY STORED. PLEASE DELETE IT OR
STORE UNDER A NEW NAME.

F-l

IOL ERROR MESSAGES
The following messages can appear on a TOPS-IO Operating System during
an edit of a query:
%COMMAND ERROR.
%STRING LONGER THAN 40.
%STRING NOT FOUND.
%POSSIBLE STRING OVERFLOW.
IQL displays the following error messages resulting from a
definition:

dictionary

%FIRST DEFINITION WAS NOT FD: RENTER.
%ILLEGAL ENTRY CODE - REJECTED.
%ACTION CODE ILLEGAL.
%TRANSACTION REJECTED - REENTER.
%THIS IS A RESERVED WORD; CHANGE OR USE A SUFFIX.
%NAME MISSING.
%NAMES MAY NOT CONTAIN SPACES OR COMMAS.
%NAMES MAY CONTAIN ONLY A-Z,0-9,DASH.
%FD ACTION TYPE NOT A,C,D,S OR P.
%THE "s" ACTION CODE WILL DESTROY ALL CURRENT
DICTIONARIES IN YOUR DIRECTORY/PPN. DO YOU
YOU REALLY WANT TO DO THIS? IF SO REENTER S;
IF NOT ENTER THE ACTION CODE YOU REALLY WANT.
%FILE NAME IMPROPERLY FORMATTED.
%RECORD SIZE TOO LARGE.
%RECORD SIZE TOO SMALL.
%BLOCK SIZE TOO LARGE.
%BLOCK FACTOR MUST BE NON-O FOR ISAM.
%FILE TYPE ILLEGAL.
%NO KEY POSITION FOR ISAM FILE.
%KEY POSITION OUTSIDE OF ISAM RECORD.
%NO LENGTH FOR ISAM KEY.
%LENGTH FOR ISAM KEY EXCEEDS MAX.
%BLOCK SIZE NOT MULTIPLE OF REC SIZE.
%ISAM KEY TYPE NOT ALPHA (0) OR NUMERIC (1).
%ISAM KEY SIGN INCORRECT.
%ITEM NAME STARTS WITH ILLEGAL "X" OR "ZZ".
%NO FIRST CHAR LOCATION.
%ITEM OUTSIDE RECORD.
%NO ITEM LENGTH.
%ITEM LENGTH TOO LONG.
%ITEM TYPE ILLEGAL.
%SCALE LARGER THAN ITEM LENGTH.
%PIC POSITIONS/ITEM MISMATCH.
%NO SCAN GROUP NAME.
%SCAN REPEATS RUN OUT OF RECORD.
%NO SCAN REPEATS.
%ILLEGAL PASSWORD EXCL FLAG.
%NOT NUMERIC.
%TITLES MAY NOT EXCEED 10 CHARS.
IQL displays an message listed in this section after you enter an END
or EXIT dictionary command and IOL cannot apply the transactions you
define to a dictionary.
There are some duplications with the error
messages that may occur during prompted definition, because in some
cases you can generate dictionary transactions by other than prompting
(that lS,
by a program such as IQSCH) and IQL must perform all the
checks at this time.
%RESULTING FD ENTRY MAY NEED CORRECTION.
%RECORD LGTH WAS TOO LARGE- CHANGED TO SYSTEM MAXIMUM.

F-2

IOL ERROR MESSAGES
%RECORD LGTH WAS TOO SMALL- CHANGED TO SYSTEM MINIMUM.
%BLOCK FACT FOR ISAM FILES MUST BE > 0: SET TO 1.
%BLOCK FACT WAS TOO SMALL- CHANGED TO 1.
%FILE TYPE WAS ILLEGAL- CHANGED TO 7 (ASCII DISK).
%NO KEY POSITION FOR ISAM FILE- CHANGED TO 1.
%KEY POSITION OUTSIDE OF ISAM RECORD- CHANGED TO 1.
%NO LENGTH FOR ISAM KEY- CHANGED TO 1.
%BLOCK FACT NOT MULTIPLE OF REC LEN - SET TO O.
%field-name WAS NOT NUMERIC- SET TO O.
%KEY DATA FURNISHED FOR NON-ISAM FILE - IGNORED.
%ILLEGAL KEY TYPE FOR ISAM FILE- SET TO ALPHABETIC.
%ILLEGAL KEY SIGN FOR ISAM FILE- SET TO UNSIGNED.
%DICT NAME WAS BLANK- SET TO "BAD-NAME".
%0 BLOCKSIZE ONLY VALID FOR SEQUENTIAL DISK FILES.
%00 TRANSACTION REJECTED.
%ACTION CODE WAS ILLEGAL.
%ITEM NAME STARTED WITH X OR ZZ.
%NO FIRST CHAR LOCATION.
%ITEM PARTLY OR ALL OUTSIDE OF RECORD.
%NO ITEM LENGTH.
%ITEM TYPE WAS ILLEGAL.
%SCALE WAS LARGER THAN ITEM LENGTH.
%PICTURE POSITIONS/ITEM MISMATCH.
%PICTURE DECIMAL DID NOT MATCH SCALE.
%NO SCAN GROUP NAME.
%SCAN REPEATS RAN OUTSIDE OF RECORD.
%NO SCAN REPEATS.
%NO PO FOR REFERENCE PROTECTION.
%ILLEGAL VALUE FOR PROT EXCL FLAG.
%field-name WAS NOT NUMERIC.
%NAME WAS ALL BLANKS.
%LENGTH OF MEMBER EXCEEDS GROUP LENGTH.
%PD TRANSACTION REJECTED.
%PROTECTION NO. WAS NOT NUMERIC.
%DICT NOT UNLOCKED FOR PW CHANGES.
IQL displays the error messages listed
input, update, or browse a data file.

this

section

while

%NO DICTIONARIES FOUND IN YOUR DIRECTORY/PPN: RUN ENDED.
%dictionary-name DICTIONARY NOT FOUND.
%CANNOT PROCESS NON-DISK FILES.
%file-name NOT FOUND: TRY AGAIN.
%file-name NOT FOUND: ENTERING INPUT.
%file-name ALREADY THERE: ENTERING UPDATE
%COMMAND ERROR: PLEASE REENTER.
%TOO MANY FIND ITEMS.
%VALUE-RELATIONSHIP ERROR.
%ITEM-ITEM TESTS NOT IN THIS VERSION.
%ONLY BROWSE PERMITTED - REJECTED.
%item-name NOT FOUND IN DICTIONARY.
%DICTIONARY CAPACITY EXCEEDED.
%OUTSIDE OF RECORD
%COLUMNS EXCEED RECORD LENGTH
%NO CURRENT RECORD TO DELETE.
%TOO MANY CHANGE ITEMS
%TOO MANY LIST ITEMS.
%DISPLAY LINE WILL BE TRUNCATED.
%item-name VALUE TOO LONG OR BAD FORMAT.
%RECORD REJECTED
%THIS VERSION CANNOT INPUT ISAM FILES.
%APPEND NOT MEANINGFUL FOR ISAM: ENTERING INPUT.
%KEY ENTRY MYST BE AT START OF FINDLIST.
%SAVE NOT MEANINGFUL FOR ISAM.
F-3

you

IOL ERROR MESSAGES
%THIS VERSION CANNOT EXTRACT ISAM FILES.
%ISAM RECORD NOT FOUND TO DELETE.
%INSERTED ISAM RECORD ALREADY EXISTS: USE CHANGE
OR DELETE AND REINSERT.
%KEY VALUE NOT FOUND IN ISAM FILE.
%ILLEGAL TO MODIFY ISAM READ KEY.

F.2

ERROR MESSAGES FROM DEFERRED MODE

IQL displays the error messages listed in this section after you enter
the RUN or SAVE assistance command.
%ITEM-NAME NOT DEFINED.
%item-name NOT NUMERIC.
%item-name NOT ALPHABETIC.
%STATEMENT EXPECTED.
%VERB EXPECTED.
%NON VERB EXPECTED.
%INVALID CHARACTER.
%VALUE BEYOND RANGE.
%file-name FILE NOT FOUND.
%TOO MANY RIGHT PAREN.
%NO ENDING QUOTE.
%QUERY SIZE EXCEEDED.
%item-name INVALID ITEM TYPE.
%INVALID/MISSING PASSWORD FOR.
%LITERAL EXPECTED.
%LITERAL MAX EXCEEDED.
%NO ENDING PAREN.
%ISAM FILE REQUIRED.
%HOLD BUFFER FULL.
%INVALID OPERATOR.
%INVALID PICTURE.
%variable-name VARIABLE USED ONCE.
%QUERY NOT TERMINATED.
%OPERATOR EXPECTED.
%OPERAND EXPECTED.
%= INCORRECTLY USED.
%= OPERATOR EXPECTED.
%INVALID RELATIONAL OPERATOR.
%VERB USE LIMIT IS 1.
%WORD MAX 30 CHARS.
%INVALID DEV:FILE.EXT.
%INVALID ( = ZZITEM ).
%NUM VAR NAMES BEGIN WITH X.
%UNDEFINED DATA NAME OR ELSE AN
ALPHA VAR SPELLED INCORRECTLY.
%DICTIONARY NOT FOUND FOR FILE.
%OPEN STATEMENT-DUPLICATE NAMES.
%IF STATEMNT HAS NO VERB PHRASE.
%FILE NAME INCORRECTLY USED.
%NO CREATE ITEMS DESIGNATED OR
POSSIBLY FILENAME NOT QUOTED.
%INCORRECTLY USED VOCAB WORD.
%CAN TAKE NO QUALIFICATION.
%LACK DETAIL INFO DM ITEM.
%VERB EXPECTS A DATA ITEM LIST.

F-4

IQL ERROR MESSAGES
IOL can display the following error messages after you enter
or EXECUTE assistance command:
?ILLEGAL DATA BASE ... SIXBIT CANNOT BE
MIXED WITH ASCII IN THIS VERSION OF IOL.
?CANNOT FIND INPUT FILE file-name; ENDING RUN.

F-5

the

RUN

APPENDIX G
ASSOCIATED DOCUMENTS DESCRIPTIONS

ASSOCIATED DOCUMENTS
TOPS-IO Introduction to IQL
DEC-IO-LIQLA-A-D
The TOPS-IO Introduction to IQL provides a general understanding of
the interactive query language software. The manual presents general
concepts and several examples in the personnel, marketing,
and
accounting fields.
Getting Started With TOPS-IO Commands
DEC-IO-OTSCA-A-D
Getting Started With TOPS-IO Commands is a simplified guide for
the
inexperienced user of the TOPS-IO Operating System. The commands
described in this manual are a subset of the monitor commands that are
most useful to the beginning user.
The TOPS-IO Operating System
Commands Manual describes all of the monitor commands.
TOPS-IO Operating System Commands Manual
AA-0916C-TB
The TOPS-IO Operating System Commands Manual is a complete reference
manual describing the commands available in the TOPS-IO Operating
System.
Getting Started With TOPS-20
AA-4187C-TM
Getting Started With TOPS-20 is a simplified
guide
for
the
inexperienced user of the TOPS-20 Operating System.
The commands
described in this manual are a subset of the monitor commands that are
most useful to the beginning user.
The TOPS-20 User's Guide describes
all of the monitor commands.
TOPS-20 User's Guide
AA-4179B-TM
The TOPS-20 User's Guide is a complete reference manual describing the
commands available in the TOPS-20 Operating System.

G-l

ASSOCIATED DOCUMENTS DESCRIPTIONS
TOPS-20 EDIT User's Guide
DEC-20-UEUGA-A-D
The TOPS-20 EDIT User's Guide is a simplified guide for
the
inexperienced user of the TOPS-20 EDIT text editor.
The commands
described in this manual are a subset of the editor commands that are
most useful to the beginning user.
The TOPS-20 EDIT Reference Manual
describes all the editor commands.
TOPS-20 EDIT Reference Manual
AA-5415A-TM
The TOPS-20 EDIT Reference Manual
is a complete reference manual
describing the commands available in the TOPS-20 EDIT text editor.
TOPS-IO Data Base Management System Programmer's Procedures Manual
AA-090IC-TB
The TOPS-IO Data Base Management System Programmer's Procedures Manual
contains a description of the TOPS-IO Data Base Management System from
the point of view of the programmer who writes programs to access the
data base.
TOPS-20 Data Base Management System Programmer's Procedures Manual
AA-4149B-TM
The TOPS-20 Data Base Management System Programmer's Procedures Manual
contains a description of the TOPS-20 Data Base Management System from
the point of view of the programmer who writes programs to access the
data base.
TOPS-IO Beginner's Guide to Multiprogram Batch
DEC-IO-OMPBA-C-D
The TOPS-IO Beginner's Guide to Multiprogram Batch is a simplified
guide for
the inexperienced user of the TOPS-IO Batch System. The
commands described in this manual are a subset of the batch commands
that are most useful to the beginning user.
The TOPS-IO Multiprogram
Batch Reference Manual describes all of the batch commands.
TOPS-IO Multiprogram Batch Reference Manual
DEC-IO-OMBRA-A-D
The TOPS-IO Multiprogram Batch Reference
reference manual describing the commands
Batch System.

Manual is a
complete
available in the TOPS-IO-

TOPS-20 Getting Started With Batch
DEC-20-0BGSA-A-D
TOPS-20 Getting Started With Batch is a simplified manual
for
the
inexperienced
user of the TOPS-20 Batch System.
The commands
described in this manual are a subset of the batch commands that are
most useful to the beginning user.
The TOPS-20 BATCH Reference Manual
describes all of the batch commands.

G-2

ASSOCIATED DOCUMENTS DESCRIPTIONS

TOPS-20 BATCH Reference Manual
DEC-20-0BRMA-A-D
The TOPS-20 BATCH Reference Manual is a complete reference
describing the commands available in the TOPS-20 Batch System.

G-3

manual

INDEX
ASCII,
defined, xi
Advance,
report page, 3-42
Analyze and Save,
nonanalyzed query, 2-3,
2-25
Analyzed Query,
EXECUTE, 2-14
RUN, 2-3
Assemble,
logical print lines, 3-8
Assistance,
BROWSE, 2-4, 2-6
DEFINE, 1-5, 2-4, 2-8
DELETE, 2-3, 2-9
DICTIONARIES, 2-10, 2-4
EDIT, 2-2, 2-12, 1-5
EXECUTE, 2-14, 1-5, 2-3
EXIT, 2-15, 2-2
GET, 2-16, 2-3
INPUT, 2-17, 2-4, 1-5
ITEMS, 2-19, 2-4
JOB, 2-2, 2-20
LIST, 2-3, 2-21
QUERIES, 2-3, 2-22
REPLACE" 2-3, 2-23, 1-5
RUN, 2-24, 2-3, 1-5
SAVE, 2-25, 2-3, 1-5
STORE, 2-27, 2-3, 1-5
UPDATE, 2-28, 2-4, 1-5
WRITE, 2-29, 2-2, 1-5
command abbreviations, 2-2
command conventions, 2-4
level,
defined, xi
enter, 2-1
Browse,
defined, xi
Calculate,
average, 3-12
maximum, 3-38
minimum, 3-40
total value, 3-62
total occurrences, 3-59
value, 3-14
Command Conventions,
assistance, 2-4
Compute a value, 3-14
Condition Test,
IF, 3-35
Constant,
defined, xi

Copy,
record, 3-16
Create,
file, 3-18
search path, 1-4
Current Record,
defined, xi
DBMS,
defined, xii
file,
explained, 1-4
read, 3-26, 3-43
record(s),
COPY, 3-16
DISK6,
defined, xii
DISK7,
defined, xii
Data Base,
DBMS,
data structure, 3-16
explained, 1-4
read, 3-26, 3-43
Data File,
ISAM,
DISPLAY columns, 4-10
data structure, 3-16
file,
SAVE, 4-23
explained, 1-4
read, 3-24, 3-43
update, 3-54, 2-28
item (s) ,
CHANGE, 4-8
record(s) ,
APPEND, 4-6
DELETE, 4-11
DISPLAY, 4-26
EXTRACT, 4-14
INSERT, 4-18
LIST, 4-21
sequential,
DISPLAY columns, 4-10
data structure, 3-16
file,
SAVE, 4-23
explained, 1-4
read, 3-43, 3-22
update, 2-28
item(s),
CHANGE, 4-8
record (s) ,
APPE, 4-6
DELE, 4-11
DISP, 4-26

Index-l

INDEX (CaNT.)

Data File (Cont.),
sequential (Cont.),
record (s) (Cont.),
EXTR, 4-14
INSE, 4-18
LIST, 4-21
Data item,
defined, xii
Date,
defaul t, 3-20
turn off, 3-20
turn on, 3-20
Default,
automatic paging, 3-47
date, 3-20
device, 1-4
directory, 1-4
horizontal spacing, 3-50,
3-34, 3-21
logical print lines, 3-8
page number, 3-45
report format, 3-1
report heading, 3-31
report left margin, 3-37
report paper size, 3-28
report right margin, 3-55
report size, 3-46
report vertical spacing,
3-64, 3-50
Define,
ASCII, xi
DBMS, xii
DISK6, xii
DISK7, xii
FINDLIST, xii
assista.nce level, xi
browse, xi
constant, xi
current record, xi
data item, xii
dictionary, 3-43, xii
dictionary name, 5-11
dictioRary password, 5-15,
5-11
file, 3-43
immediate mode, 4-1
integer, xiii
item, xii
literal, xii
master password, 5-11
operating system, xiii
password, xiii
query, xiii
report level, xiii
report paper size, 3-28
search path, xiii

Define (Cont.),
string, xiii
summary, xiii
update level, Xlll
variable, xi xiv
Delete,
analyzed query, 2-3
nonanalyzed query, 2-9,
2-3
Dictionary,
BACK, 5-5
DBMS Set (SD), 5-19
DOWN, 5-5
END, 5-4
KILL, 5-4
NEXT, 5-4
SCRUB, 5-4
command conventions,
5-4
comment (CD), 5-7
comments in, 5-7
contents of,
display, 2-4
to printer, 5-5
to terminal, 2-19
create, 2-4
data item, 5-8
data record, 5-17
define password, 5-15
defined, 7, 5-11
delete name of, 5-11
edit, 2-8
entry,
add, 5-5
change, 5-5
delete, 5-5
print, 5-5
list names of, 2-4,
2-10
schema (AD), 5-6
wr i te, 2-8
Display,
dictionary contents,
2-19, 5-5, 2-4
item, 3-21
job number, 2-2, 2-20
nonanalyzed query,
2-3, 2-21
turn off, 3-21
turn on, 3-21
Edit,
dictionary, 2-8, 2-4
nonanalyzed query,
2-12, 2-2

Index-2

INDEX (CONT.)

FINDLIST,
defined, Xl.l.
format, 4-16
File,
CREATE.OUT, 3-18
LOGIN. CMD, 1-4
QLjobU.LPT, 1-5
QPDICT.SEQ, 1-5
QPQRYS.SEQ, 2-27, 2-12
QTjobX.TMP, 4-14
create, 3-18
input-file.OUT, 3-16
name.QRY, 2-25, 2-24
naming, 1-5
search path, 1-4
structure explained,
1-4
Generate Report, 2-24,
2-14, 2-3
Horizontal Spacing,
default, 3-34, 3-21
set, 3-50, 3-21
ISAM,
DISPLAY columns, 4-10
file,
SAVE, 4-23
TOP, 4-24
explained, 1-4
read, 3-43, 3-24
update, 2-28, 3-54
item (s)' ,
CHANGE, 4-8
record (s) ,
APPEND, 4-6
COPY, 3-16
DELETE, 4-11
DISPLAY, 4-26
EXTRACT, 4-14
INSERT, 4-18
LIST, 4-21
record,
BOTTOM, 4-7
DOWN, 4-12
FIND, 4-15
UP, 4-25
Immediate Mode, 4-1
Immediate,
APPEND, 4-6
BOTTOM, 4-7
CHANGE, 4-8

Immediate (Cont.),
COLUMNS, 4-10
DELETE, 4-11
DOWN, 2-17, 4-12
END, 2-17, 4-19
EXIT, 2-17, 4-13
EXTRACT, 4-14
FIND,
ISAM, 4-15
sequential, 4-15
INSERT, 4-18
KILL, 2-17, 4-18
LIST, 4-21
NEXT, 2-17, 4-19
SAVE, 4-23
TOP, 4-24
UP, 2-17, 4-19, 4-25
VERIFY, 4 ... 26
command conventions, 4-2
mode, 2-6, 2-28, 2-17
Integer,
. defined, xiii
Item,
defined, xii
display, 3-21
reset, 3-53
save, 3-33

Job Number,
display, 2-20, 2-2

LOGIN.CMD,
file, 1-4
Level,
analysis, 2-24, 1-5,
2-14, 2-3, 2-25
assistance, 2-1
dictionary, 2-4, 1-5
edit, 4-16, 1-5, 2-29,
2-2, 1-5, 2-12
execute, 2-3, 2-14, 1-5
execution, 2-24
input, 2-17, 2-4, 1-5
report, 2-14, 2-24
update, 2-6, 2-4
2-28, 1-5, 2-17
List,
names of,
dictionaries, 2-4, 2-10
nonanalyzed queries,
2-3, 2-22
Literal,
defined, xii

Index-3

INDEX (CONT.)

Logical Print Lines,
assemble, 3-8
default, 3-8

Master Password,
defined, 5-11
Messages,
explained, 2-2
Mode,
immediate, 4-1, 2-28,
2-17, 2-6
Nonanalyzed Query,
DELETE, 2-9, 2-3
DISPLAY, 2-21
EDIT, 2-12, 2-2
REPLACE, 2-23, 2-3
RUN, 2-3, 2-24
STORE, 2-3, 2-27
WRITE, 2-2, 2-29
analyze and save, 2-3,
2-25
display, 2-3
list names· of, 2-3
Nonanalyzed query,
list names of, 2-22

Open,
dictionary, 3-43
file, 3-43
Operating System,
defined, xiii
Override,
picture, 3-48

Page Number,
default, 3-45
Password,
defined, xiii
Picture,
override, 3-48
Position,
ISAM,
file,
TOP, 4-24
record,
BOTTOM, 4-7
DOWN, 4-12
UP, 4-25
select, 4-15

Position (Cont.),
sequential,
file,
BOTTOM, 4-7
TOP, 4-24
record,
DOWN, 4-12
UP, 4-25
select, 4-15
Print,
report line, 3-50
Prompt,
explained, 2-1
item values, 3-6
Query,
Statement,
AUTHORITY, 3-10
analyzed,
run, 2-14
comments in, 3-2
defined, xiii
nonanalyzed,
DELETE, 2-3, 2-9
DISPLAY, 2-21, 2-3
EDIT, 2-12, 2-2
REPLACE, 2-23, 2-3
RUN, 2-3, 2-24
STORE, 2-27, 2-3
WRITE, 2-29, 2-2
analyze and save, 2-25
list names of, 2-22,
2-3
staging defined, 3-2
statement,
ACCEPT, 3-6
ACROSS, 3-8
AVERAGE, 3-12
COMPUTE, 3-14
COPY, 3-16
CREATE, 3-18
DATE, 3-20
DISPLAY, 3-21
FIND,
DBMS, 3-26
ISAM, 3-24
sequential, 3-22
FORM-LINES, 3-28
GO TO, 3-29
HEADING, 3-31
HOLD, 3-33
HSPACE, 3-34
IF, 3-35
LMARGIN, 3-27
MAXIMUM, 3-38

Index-4

INDEX (CONT • )

statement (cont.),

MINIMUM, 3-40
NEWPAGE, 3-42
OPEN, 3-43
PAGE, 3-45
PAGE-LINES, 3-.46
PAGING, 3-47
PICTURE, 3-48
PRINT, 3-50
REPORT, 3-52
RESET, 3-53
REWRITE, 3-54
RMARGIN, 3-55
SET, 3-56
SORT, 3-57
SUMPRINT, 3-58
TALLY, 3-59
TITLES, 3-61
TOTAL, 3-62
VSPACE, 3-64
conventions, 3-3
order, 3-2

Read,
DBMS data base, 3-3, 3-26,
3-1
ISAM data file, 3-24, 3~1,
2-6, 2-4
sequential data file,
3-22, 2-4, 2-6
3-1
Record,
copy, 3-16
Replace,
nonanalyzed query, 2-3,
2-23
Report.,
automatic paging, 3-47
column titles, 3-61
date, 3-20
default format, 3-1
default size, 3-46
generate, 2-14, 2-3
heading,
default, 3-31
turn off, 3-31
turn on, 3-31
horizontal spacing,
default, 3-50
set, 3-34
justifying,
alphanumeric, 3-50
numeric, 3-50
left margin,
default, 3-37
set, 3-37

Report (Cont.),

level, 2-14, xiii, 2-24
logical print lines,
assemble, 3-8
default, 3-8
page advance, 3-42
page numbert 3-45
paper size,
default, 3-28, 3-28
print line, 3-50
printed size, 3-46
right margin,
default, 3-55
set, 3-55
spacing,
horizontal, 3-34, 3-50
vertical, 3-50, 3-64
summary print lines, 3-58
vertical spacing,
default, 3-64, 3-50
set, 3-64
Request,
item values, 3-6
Reserved Words, 1~4
Reset,
item, 3-53
variable, 3-53
Run,
query,
analyzed, 1-5, 2·14
nonanalyzed, 2-3, 2-24
STORE,
nonanalyzed query, 2-3
Save,
item, 3-33
Search Path,
created, 1-4
defined, xiii
explained, 1-4
Sequential,
column(s) ,
DISPLAY, 4-10
file,
BOTTOM, 4-7
SAVE, 4-23
TOP, 4-24
read, 3-22, 3-43
structure explained, 1-4
update, 2-28
item (s) ,
CHANGE, 4-8
record (s) ,
APPEND, 4-6
COPY, 3-16
DELETE, 4-11
Index-5

INDEX (CONT . )

Sequential (Cant.),
record (s) (Cant.),
DISPLAY, 4-26
DOWN, 4-12
EXTRACT, 4-14
INSERT, 4-18
LIST, 4-21
UP, 4-25
select, 4-15
Set,
horizontal spacing, 3-34,
3-50
page number, 3-45
report,
left margin, 3-37
paper size, 3-28
printed size, 3-46
right margin"3-55
vertical spacing, 3-64
value, 3-56
Sort,
value, 3-57
Specify,
password, 3-10
Statement Conventions,
query, 3-3
Store,
nonanalyzed query, 2-27
String,
defined, xiii
Summary Print Lines,
turn off, 3-58
turn on, 3-58
Summary,
defined, xiii
Terminate,
DEFINE, 5-4
EDIT, E-l, E-2
INSERT, 4-19
IQL, 2-15
WRITE, E... l, E-2
assistance level, 2-15
browse level, 4-13
immediate mode, 4-13
input level, 4-13
update level, 4-13
Transaction,
explained, 5-4
Transfer,
query control,
GO TO, 3-29
IF, 3-35

Turn Off,
automatic paging, 3-47
date, 3-20
report column titles, 3-61
report heading, 3-31
summary print lines, 3-58
terminal display, 3-21
Turn On,
automatic paging, 3-47
date, 3-20
report column titles, 3-61
report heading, 3-31
summary print lines, 3-58
terminal display, 3-21

Update Level,
defined, xiii
Update Session,
, explained, 2-2
Update,
ISAM data file, 3-54, 2-28,
2-4
level, 2-6, 2-17, 2-28
sequential data file, 2-28,
2-4

Value,
set, 3-56
sort, 3-57
Variable,
defined, xiv, xi
picture, 3-48
reset, 3-53
Vertical Spacing,
default, 3-50, 3-64
set, 3-64

WRITE,
nonanalyzed query, 2-29,
2-2
Words,
reserved, 1-4
Write,
data file,
ISAM, 2-4, 2-17
sequential, 2-4, 2-17
dictionary, 2-8, 2-4

Index-6

TOPS-IO/TOPS-20
Interactive Query
Language User's Guide
AA-H282A-TK
READER'S COMMENTS
NOTE:

This form is for document comments only.
DIGITAL will
use comments submitted on this form at the company's
discretion.
If you require a written reply and are
eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR
form.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Cl>
C

o
c
.....
:::>
o

Did you find errors in this manual?
page number .

If so, specify the error and the

Cl>

on
C
Cl>

c...

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify) ________________________________________

Name

Date _________________________

Org ani za tion ___________________________ Telephone ___________________
Street ______________________________________________________________
Ci ty______________________ S ta te _________ Zip Code _________
or
Country

I
I
I

-----m-.-

-0
00

I
I
,

mN.ot oTear. t- fooald Haere and Tape- - - - - - - - - - - - - - - - - - - - -

Tfrill --------~~~~;;,~~ --

-::!

if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

I
I
I
I
I
I
I
I
I
I
I
I
I
I

SOFTWARE PUBLICATIONS
200 FOREST STREET MRl-2/E37
MARLBOROUGH, MASSACHUSETTS 01752

-- - - - - -

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

....::I