Tandem ENFORM 058057, ENFORM Reference Manual

Data Management Library

™

ENFORM
Reference Manual

Abstract This manual provides detailed information about the syntax of the ENFORM language.

Part Number 058057

Tandem Computers Incorporated

Document History Edition Part Number Operating System Version Date

First Edition 82348 A00 GUARDIAN A04/E05 October 1982
Second Edition 82348 B00 GUARDIAN A05/E06 April 1983
Update 1 82194 GUARDIAN A06/E07 December 1983
Update 2 82205 GUARDIAN B00/E08 March 1985
Third Edition 058057 GUARDIAN B00/E08 July 1991

The second edition of this manual, including updates 1 and 2, was reformatted in July 1991; no changes
were made to the manual’s content at that time. The reformatted manual became the third edition.

Copyright All rights reserved. No part of this document may be reproduced in any form, including photocopying or

translation to another language, without the prior written consent of Tandem Computers Incorporated.
Copyright  1991 Tandem Computers Incorporated.

Document History Edition Part Number Operating System Version Date

First Edition 82348 A00 GUARDIAN A04/E05 October 1982
Second Edition 82348 B00 GUARDIAN A05/E06 April 1983
Update 1 82194 GUARDIAN A06/E07 December 1983
Update 2 82205 GUARDIAN B00/E08 March 1985
Third Edition 058057 GUARDIAN B00/E08 July 1991

The second edition of this manual, including updates 1 and 2, was reformatted in July 1991; no changes were made to the manual’s content at that time. The
reformatted manual became the third edition.

Ordering Information For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact your

local sales representative.

Document Disclaimer Information contained in a manual is subject to change without notice. Please check with your authorized Tandem

representative to make sure you have the most recent information.

Export Statement Export of the information contained in this manual may require authorization from the U.S. Department of Commerce.

Examples Examples and sample programs are for illustration only and may not be suited for your particular purpose. Tandem does

not warrant, guarantee, or make any representations regarding the use or the results of the use of any examples or sample
programs in any documentation. You should verify the applicability of any example or sample program before placing the
software into productive use.

U.S. Government

Customers

FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED SOFTWARE:
These notices shall be marked on any reproduction of this data, in whole or in part.
NOTICE: Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this computer

software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in Section 52.227-19
of the FARS Computer Software-Restricted Rights clause.

RESTRICTED RIGHTS NOTICE: Use, duplication, or disclosure by the Government is subject to the restrictions as set
forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013.

RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions as set forth
in paragraph (b)(3)(B) of the rights in Technical Data and Computer Software clause in DAR 7-104.9(a). This computer
software is submitted with “restricted rights.” Use, duplication or disclosure is subject to the restrictions as set forth in
NASA FAR SUP 18-52 227-79 (April 1985) “Commercial Computer Software — Restricted Rights (April 1985).” If the
contract contains the Clause at 18-52 227-74 “Rights in Data General” then the “Alternate III” clause applies.

U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule Contract.
Unpublished — All rights reserved under the Copyright Laws of the United States.

New and Changed Information

This update to the ENFORM Reference Manual describes the following principal
changes:

The @ CENTER-PAGE Option Variable clause now centers the entire report body
on the page. The CENTER clause centers items on the page independently of
@ CENTER-PAGE.

ENFORM now issues error message 123 when the file type given in the DDL
record description does not match the physical file type read by the query
processor.

The following areas have been clarified, and examples have been added:

Reserved words
Subscript ranges
Qualification aggregates and target records
BEGINS WITH and CONTAINS
Aggregates and scale
Display format and scale
Default display format
Default time display format
Conversion of a WHERE clause to conjunctive normal form
Examples of summary reports (with LIST statement)

Other minor technical and editorial changes have been made.

All changes from the last edition are marked with a revision bar in the margin. Each
page containing a change carries the message “March 1985” at the bottom of the page.

It is assumed that the user has already integrated the December, 1983 update package
into the manual.

058057 Tandem Computers Incorporated iii

New and Changed Information

(This page left intentionally blank)

iv 058057 Tandem Computers Incorporated

New and Changed Information

058057 Tandem Computers Incorporated v

Contents

Preface xv
Notation Conventions xvii

Section 1 Introduction

ENFORM Terminology 1-1

Section 2 Running ENFORM

Interactive Mode 2-2
Noninteractive Mode 2-2
The Current Output Listing File 2-3
Pressing the Terminal BREAK Key 2-3
Logical File Assignments 2-5
Passing Parameters to Compiled Query Files 2-6
A Server Query Processor 2-6

The Command Interpreter ASSIGN Command 2-8
The Command Interpreter PARAM Command 2-8
The Command Interpreter QP Command 2-9
Example of Server Query Processor Creation 2-9

Generic Files 2-10

Generic Files and a Dedicated Query Processor 2-12
Generic Files and a Server Query Processor 2-13
Generic Files and the Current Output Listing File 2-13

Section 3 ENFORM Language Elements

Reserved Words 3-3
Special Characters 3-4
Comments 3-4
Statements 3-5
Clauses 3-5
Commands 3-5
Rules for Naming User-Defined Elements 3-6
Rules for Referencing Data Base Elements 3-6

Record Name References 3-6
Field Name References 3-6
Primary Key References 3-7

058057 Tandem Computers Incorporated v

Contents

Subscripts 3-9
Aggregates 3-12

Predefined Aggregates 3-14
User Aggregates 3-15
Target Aggregates 3-16

Target Aggregate with OVER ALL Syntax 3-16
Target Aggregate with OVER Syntax 3-17

Qualification Aggregates 3-18

Qualification Aggregate with OVER ALL Syntax 3-18
Qualification Aggregate with OVER Syntax 3-18
Qualification Aggregates and Target Records 3-19
Qualification Aggregate with Embedded WHERE Clause 3-21

Aggregates and Scale 3-21

Literals 3-22

Numeric Literals 3-22
String Literals 3-22

Arithmetic Expressions 3-23

Evaluation Order of Arithmetic Expressions 3-23
Scale Factor of the Result 3-24

Logical Expressions 3-24

Effect of Parentheses on Compound Logical Expressions 3-26
BEGINS WITH and CONTAINS 3-27
Range of Values in Logical Expressions 3-27

Pattern-Match in Logical Expressions 3-28
IF/THEN/ELSE Expressions 3-28
Parameters 3-29
User Variables 3-29

User Variable as a Target-item 3-30

A User Variable in Request-Qualification 3-32

User Tables 3-32
Arithmetic Overflow Conditions 3-32

vi 058057 Tandem Computers Incorporated

Section 4 Statements

AT END Statement 4-3

Specifying a Field Name in an AT END Statement 4-3

Spacing Considerations 4-3

AT END Information for Current Report or All Reports 4-4

Cancelling Session-Wide AT END Information 4-4
AT START Statement 4-5

Specifying a Field Name in an AT START Statement 4-5

Spacing Considerations 4-5

AT START Information for Current Report or All Reports 4-6

Cancelling Session-Wide AT START Information 4-6
CLOSE Statement 4-7

The Effect of a CLOSE Statement on the Internal Table 4-7

Contents

DECLARE Statement 4-8

Declaring a User Aggregate 4-9

Declaring a User Variable or User Table 4-10
DELINK Statement 4-11
DICTIONARY Statement 4-12

Identifying the Location of the Dictionary 4-12

Clearing the Internal Table 4-13
EXIT Statement 4-14
FIND Statement 4-15

Output Record Dictionary Description 4-16

Group Definition and Sorting 4-17

Output Fields 4-17

Input Elements 4-19

Request-Qualification 4-20

Summary Records 4-20

Statements and Clauses that Do Not Apply to the FIND Statement 4-22
FOOTING Statement 4-23

Specifying a Field Name within a FOOTING Statement 4-23

Spacing Considerations 4-23

Footing for Current Report or All Reports 4-24

Cancelling Session-Wide Footing 4-24
LINK Statement 4-25

Duration of Link Established by LINK or LINK OPTIONAL

Statement 4-26

LINK Statement Considerations 4-26

058057 Tandem Computers Incorporated vii

Contents

LINK OPTIONAL Statement Considerations 4-27

Rules for Using LINK OPTIONAL Statements 4-27
How ENFORM Handles “Non-Contributing” Record

Descriptions 4-28

LIST Statement 4-31

Input Record Description 4-33

Group Definition and Sorting 4-33

How Values Are Displayed in Report Columns 4-33

Request-Qualification 4-35

Conditional Printing 4-35

Summary Reports 4-35

Optional Clauses 4-37
OPEN Statement 4-39

Using OPEN AS A COPY OF 4-39
PARAM Statement 4-40

How ENFORM Treats Parameters 4-41
SET Statement 4-42

Initializing User-Defined Elements 4-43

Redefining Option Variables 4-43
SUBFOOTING Statement 4-44

Specifying Field Names within a SUBFOOTING Statement 4-44

Spacing Considerations 4-44

Subfooting for Current Report or All Reports 4-45

Cancelling Session-Wide Subfooting 4-45
SUBTITLE Statement 4-46

Specifying a Field Name within a SUBTITLE Statement 4-46

Spacing Considerations 4-46

Subtitle for Current Report or All Reports 4-47

Cancelling Session-Wide Subtitle 4-47
TITLE Statement 4-48

Specifying a Field Name within a TITLE Statement 4-48

Spacing Considerations 4-48

Title for Current Report or All Reports 4-49

Cancelling Session-Wide Title 4-49

viii 058057 Tandem Computers Incorporated

Section 5 Clauses

AFTER CHANGE Clause 5-4

Specifying a Field Name within an AFTER CHANGE Clause 5-4

Spacing Considerations 5-4
ASCD and DESC Clauses 5-6
AS Clause 5-7

Repeatable Edit Descriptors 5-9

Nonrepeatable Edit Descriptors 5-14

Modifiers 5-15

Decorations 5-19

Contents

Alphanumeric Edit Descriptor 5-10
Integer Edit Descriptor 5-10
Fixed Format Edit Descriptor 5-11
Mask Edit Descriptor 5-12

Scale Factor Edit Descriptor 5-14
Optional Plus Edit Descriptor 5-15

Field Blanking Modifiers 5-16
Fill Character Modifier 5-16
Overflow Character Modifier 5-17
Justification Modifiers 5-17
Symbol Substitution Modifier 5-18

Conditions 5-20
Location 5-20
Processing Order 5-20
Default Decorations 5-21

AS DATE Clause 5-23

Default Display Format 5-23

Examples of Date Display Formats 5-24
AS TIME Clause 5-25

Default Display Format 5-25

Examples of Time Display Formats 5-26
AT END PRINT Clause 5-27

Specifying a Field Name within an AT END PRINT Clause 5-27

Spacing Considerations 5-27

AT END Information for Current Report or All Reports 5-28

Overriding Session-Wide AT END Information 5-28

058057 Tandem Computers Incorporated ix

Contents

AT START PRINT Clause 5-29

Specifying a Field Name in an AT START PRINT Clause 5-29

Spacing Considerations 5-29

AT START Information for Current Report or All Reports 5-30

Overriding Session-Wide AT START Information 5-30
BEFORE CHANGE Clause 5-31

Specifying a Field Name within a BEFORE CHANGE Clause 5-31

Spacing Considerations 5-32
BY and BY DESC Clauses 5-33
CENTER Clause 5-34

Centering Single Report Items 5-34

Centering All Report Items 5-34

Centering a Print List 5-34
CUM Clause 5-35

CUM with OVER ALL 5-35

CUM with OVER 5-35

CUM Clause Used with User Variable 5-36

Restrictions 5-36
FOOTING Clause 5-37

Specifying a Field Name within a FOOTING Clause 5-37

Spacing Considerations 5-37

Footing for Current Report or All Reports 5-38
FORM Clause 5-39

FORM Clause with a By-item 5-39

FORM Clause with a Target-item 5-39

FORM Clause within a Print List 5-39
HEADING Clause 5-40

Default Headings 5-40

Multiple Line Headings 5-40

Printing / in a Column Heading 5-41

Heading for Subscripted Elements 5-41
INTERNAL Clause 5-43
JULIAN-DATE Conversion Clause 5-44

Conversion to Internal Format 5-44

Display Format 5-45
NOHEAD Clause 5-46

No Headings for Single Report Items 5-46

No Headings for All Report Items 5-46

x 058057 Tandem Computers Incorporated

NOPRINT Clause 5-47

Suppress Single Report Items 5-47

Suppress All Report Items 5-47
Option Variable Clauses 5-48
PCT Clause 5-55

Using PCT OVER ALL 5-55

Using PCT OVER By-item 5-55

Combining Percentages and Subtotals 5-56

PCT Clause Used with User Variable 5-56

Restrictions 5-56
SKIP Clause 5-57

SKIP Clause with a LIST Target-item or By-item 5-57

SKIP Clause with a Print List 5-57

Contents

SPACE Clause 5-58

SPACE Clause with a LIST Target-item or By-item 5-58

SPACE Clause with a Print List 5-58
SUBFOOTING Clause 5-59

Specifying Field Names in a SUBFOOTING Clause 5-59

Spacing Considerations 5-59

Subfooting for Current Report or All Reports 5-60
SUBTITLE Clause 5-61

Specifying a Field Name in a SUBTITLE Clause 5-61

Spacing Considerations 5-61

Subtitle for Current Report or All Reports 5-62
SUBTOTAL Clause 5-63
SUPPRESS Clause 5-64
System Variable Clauses 5-65

Printing the Current Date or Time 5-65

Printing Line Numbers 5-65

Printing Page Numbers 5-65
TAB Clause 5-66

TAB Clause with a LIST Target-item or By-item 5-66

TAB Clause with a Print List 5-66
TIMESTAMP-DATE Clause 5-67
TIMESTAMP-TIME Clause 5-68

058057 Tandem Computers Incorporated xi

Contents

TITLE Clause 5-69

Specifying Field Names in a TITLE Clause 5-69

Spacing Considerations 5-69

Title for Current Report or All Reports 5-70

Overriding Session-Wide Title 5-70
TOTAL Clause 5-71
WHERE Clause 5-72

Using the WHERE Clause to Establish a LINK 5-72

Section 6 Commands

?ASSIGN Command 6-2
?ATTACH Command 6-5
?COMPILE Command 6-6
?DICTIONARY Command 6-7

Identifying the Dictionary 6-7

Clearing Internal Tables 6-7
?EDIT Command 6-8
?EXECUTE Command 6-9
?EXIT Command 6-10
?HELP Command 6-11
?OUT Command 6-13
?RUN Command 6-14
?SECTION Command 6-15
?SHOW Command 6-16
?SOURCE Command 6-18

Appendix A ENFORM Syntax Summary

Language Elements A-1
Statements A-3
Clauses A-7
Commands A-13
ENFORM Procedures A-14

xii 058057 Tandem Computers Incorporated

Appendix B Error Messages

ENFORM Initialization Messages B-2
!!! Error and ***Warning Type Messages B-3
*** File Error Type Messages B-19
ENFORM Trap Messages B-23
BUILDMK Messages B-23

Appendix C LINKS and the LINK OPTIONAL Statement Rules

How ENFORM Defines a LINK C-1

Links Initiated by a LINK Statement C-1

Links Initiated by a LINK OPTIONAL Statement C-1

Links Initiated by a WHERE Clause C-2

How ENFORM Handles a WHERE Clause C-2
When a WHERE Clause Establishes a Link C-3
Comparison of the WHERE Clause and the LINK Statement C-4

Links Due to the Transitive Property of Links C-5

Contents

Review of Rules for the LINK OPTIONAL Statement C-6

Examples of Illegal Links C-7

Examples of Legal Links C-10
Comparison of the LINK Statement, the LINK OPTIONAL Statement, and the

WHERE Clause C-12

Glossary Glossary–1

Index Index–1

058057 Tandem Computers Incorporated xiii

Contents

Figures Figure 1-1. Typical ENFORM Session 1-2

Figure 2-1. Server Query Processor with Several Compiler/Report Writer

Processes 2-7
Figure 3-1. ENFORM Language Elements 3-2
Figure 3-2. Records with Duplicate Field Names 3-7
Figure 3-3. Query Outline of Target-Aggregate with OVER ALL Syntax 3-16
Figure 3-4. Query Outline of Target-Aggregate with OVER Syntax 3-17
Figure 3-5. Query Outline of Qualification Aggregate with OVER Over-item

Syntax 3-20
Figure 3-6. Qualification Aggregate with Embedded WHERE Clause 3-21

Tables Table 2-1. ENFORM Generic Files and Their Uses 2-11

Table 2-2. ENFORM Output Files 2-14
Table 3-1. ENFORM Reserved Words 3-3
Table 3-2. Special Characters 3-4
Table 3-3. Arithmetic Operators 3-23
Table 3-4. Conditional Operators 3-24
Table 4-1. Summary of Statements 4-1
Table 5-1. ENFORM Clauses and Their Functions 5-1
Table 5-2. Permissible Modifiers and Edit Descriptors 5-15
Table 6-1. Summary of Commands 6-1
Table 6-2. Environment Information Displayed by ?SHOW Command 6-16
Table C-1. Truth Table C-12

xiv 058057 Tandem Computers Incorporated

Preface

This manual is one of three volumes that describe the ENFORM language. It concerns
syntax only and should be used as a reference by experienced ENFORM users. For
other information about ENFORM and related products, refer to the publications
listed below.

Data Definition Language (DDL) Reference Manual
EDIT Manual
ENFORM User’s Guide
ENSCRIBE Programming Manual
GUARDIAN Operating System Utilities Reference Manual
GUARDIAN Operating System User’s Guide
GUARDIAN Operating System Programmer’s Guide
System Procedure Calls Reference Manual
Introduction to ENFORM

058057 Tandem Computers Incorporated xv

Preface

(This page left intentionally blank)

xvi 058057 Tandem Computers Incorporated

Preface

058057 Tandem Computers Incorporated xvii

Notation Conventions

This table describes the characters and symbols used in this manual’s syntax notation.
For distinction, syntactical elements appear in a typeface different from that of
ordinary text.

Notation Meaning
UPPERCASE LETTERS All keywords and reserved words appear in capital letters. If a keyword

can be abbreviated, the part that can be omitted is enclosed in brackets.
lowercase italic letters Lowercase italic letters represent variable items that you supply.
Brackets Square brackets ([ ]) enclose all optional syntax elements. A vertically-

aligned group of elements enclosed in brackets represents a list of

selections from which to choose one or none.
Braces A vertically-aligned group of syntax elements enclosed in braces ({ })

represents a list of selections from which exactly one must be chosen.
Ellipsis When an ellipsis (...) immediately follows a pair of brackets or a pair of

braces, the enclosed syntax can be repeated any number of times.
Punctuation Parentheses, commas, and other punctuation or symbols not described

above must be entered precisely as shown. If any of the punctuation

above appears enclosed in quotation marks, that character is not a

syntax descriptor but a required character, and must actually be entered.

058057 Tandem Computers Incorporated xvii

Notation Conventions

(This page left intentionally blank)

xviii 058057 Tandem Computers Incorporated

1 Introduction

This publication documents:

The syntax of the Command Interpreter ENFORM command needed to call the
ENFORM process, the Command Interpreter commands needed to create a server
query processor, and the names of generic files that can be assigned using either
the Command Interpreter ASSIGN command or the ENFORM ?ASSIGN
command.

The syntax of the ENFORM language elements including statements, clauses,
commands, aggregates, expressions, literals, and variables. These elements are
alphabetized wherever appropriate.

The error messages generated by ENFORM.

The special features of ENFORM, such as using the host language interface, writing an
ENFORM server, or redefining ENFORM reserved words and message text are not
discussed. For this information and for information about using the ENFORM
language elements, refer to Introduction to ENFORM or to the ENFORM User's Guide.

The examples in this manual use the data base described in the ENFORM User's Guide.

ENFORM Terminology This manual uses special terms to describe the various components and features of the

ENFORM language. Figure 1-1 illustrates these terms by showing a typical ENFORM
session (the period of time that begins when you enter the ENFORM command and
ends when you exit ENFORM). The following paragraphs describe some of the terms
illustrated in Figure 1-1. Become familiar with these terms, because they are used
throughout the manual.

058057 Tandem Computers Incorporated 1–1

Introduction

ENFORM Terminology

Figure 1-1. Typical ENFORM Session

Begin Session :ENFORM

Enter Query Specifications
>?DICTIONARY $mkt.sample
>OPEN employee;
>LIST BY empnum,

empname,salary,

WHERE salary GT 2000;

Report

Report Writer

Compiler/

Query

Processor

Command
Statement

By-item
Clause

Target-items

Clause
Request-Qualification

Target-

Records

Target-

list

Statement

Query

Dictionary

Data Base

The important terms are:
Query specifications. The language elements (statements, clauses, commands, ...) that

you specify to provide ENFORM with the information it needs to retrieve data and to
establish the query environment.

Query. One complete LIST or FIND statement. Both statements specify the information
to be retrieved.

Target-list. A part of the query; a target-list consists of target-items and a special type of
target-item called a by-item.

Target-items. Any record names, field names, variable names, aggregate names, literals,
or expressions, excluding by-items, whose values you want to appear as output from
your query.

1–2 058057 Tandem Computers Incorporated

Introduction

ENFORM Terminology

By-items. Field names modified by the BY or BY DESC clauses described in Section 5.
The values of the fields are used to sort and group the query output.

Request-qualification. A condition or conditions that a data base element must meet
before it is selected to contribute to your query output. A request-qualification begins
with a WHERE keyword followed by a logical expression.

Compiler/report writer. The ENFORM process that compiles your query and writes a
report (if one is requested). The compiler/report writer issues error messages for
syntax errors. If no errors exist, the compiler/report writer passes your compiled
query specifications along with information obtained from the dictionary to the query
processor. After the query processor returns the retrieved data (in the form of the
target-records described later in this section), the compiler/report writer formats and
writes the report.

Dictionary. Physical files that contain information called record descriptions. A record
description provides ENFORM with information about the name of the record being
accessed, the name and data type of any fields within the record, the record and field
length, the name of any primary or alternate key fields, and the name of the physical
file associated with the record description. The dictionary is created by the Data
Definition Language (DDL) compiler from record descriptions written in DDL. The
dictionary must exist before your query specifications are processed. Refer to the Data
Definition Language (DDL) Programming Manual and the ENFORM User’s Guide for
more information about the dictionary.

Query processor. The ENFORM process that uses the information provided by the
compiler/report writer to retrieve information from the data base. The query
processor also performs other functions such as creating a new physical file and
transmitting records to a host language program. Creating a new physical file is
described with the FIND statement in Section 5 of this manual. The host language
interface is described in the ENFORM User’s Guide.

Target-records. The records built by the query processor from which your ENFORM
output is produced. The query processor returns the target-records to the
compiler/report writer if the ENFORM output is to be formatted and written as a
report.

Data base. The collection of physical files from which the query processor retrieves
data. Any physical file from which data is retrieved must be associated with the
record description obtained from the dictionary.

058057 Tandem Computers Incorporated 1–3

Introduction

ENFORM Terminology

(This page left intentionally blank)

1–4 058057 Tandem Computers Incorporated

2 Running ENFORM

The ENFORM command issued from the Command Interpreter calls the ENFORM
subsystem. If no parameters are specified, the ENFORM command appears as:

:ENFORM

The terminal from which the ENFORM command is entered is called the home
terminal. The syntax for the ENFORM command is:

ENFORM [ / [ IN
[ , [ OUT
[

dict-subvol-name

IN

input-filename

specifies either the name of an EDIT file containing ENFORM source code or the
name of a compiled query file.

If this option is specified, ENFORM executes the code in the specified file and
returns you to the Command Interpreter prompt at the end of execution.

If this option is omitted, the ENFORM prompt (>) appears and you can enter
commands and statements either directly by typing them or indirectly by
specifying either the ?RUN or ?SOURCE commands. When this option is omitted,
the home terminal becomes the default input file.

OUT

output-filename

specifies the name of the physical file to which output is directed. If this option is
omitted, ENFORM directs the output to the current output listing file (explained
later in this section.)

dict-subvol-name

is the name of the volume and subvolume upon which the dictionary resides. If
this parameter is omitted, ENFORM assumes the dictionary resides on the current
volume and subvolume. Either the DICTIONARY statement or the
?DICTIONARY command can be used to supply or change the dictionary name.

input-filename

output-filename

] [ ,

message-table-filename

]

] ] / ]

]

message-table-filename

is the name of the key-sequenced file containing a user-defined ENFORM message
table. ENFORM retrieves error and informational message text, help message text,
and/or the list of any redefined reserved words, system variables, option
variables, or command names from this file when this parameter is specified. If
this parameter is omitted, ENFORM retrieves message text from a message table
supplied by Tandem. Refer to the ENFORM User’s Guide for information about
creating a user-defined message table.

The Command Interpreter ASSIGN command (described later in this section) can be
used to make up to 32 logical file assignments before the ENFORM subsystem is
called.

058057 Tandem Computers Incorporated 2–1

Running ENFORM

Interactive Mode

Interactive Mode ENFORM functions in interactive mode when the ENFORM source code is entered

from a terminal keyboard. ENFORM prompts for input by printing the right angle
bracket (>). When a carriage return is entered, ENFORM issues another prompt. For
example:

:ENFORM ENFORM - T9102C09 - (02APR82) DATE - TIME: 6/16/81 ­ 10:14:52 >

ENFORM commands and statements can be entered either directly or indirectly.
Commands and statements are entered directly when you type them in response to the
ENFORM prompt. Commands and statements are entered indirectly when you use
either the ?RUN or ?SOURCE commands to supply the ENFORM source code.

When you enter commands and statements directly, the Command Interpreter FC
command allows you to edit or repeat a line. Refer to the GUARDIAN Operating
System Utilities Reference Manual, for more information about this command.

When you specify the ?EDIT command, the Edit prompt (*) appears and all the
functions of the Edit process are available for your use. Either the ?RUN or the
?SOURCE command can be used to execute the source code created in the Edit
process. These commands are described in Section 6.

Exit interactive mode by entering the EXIT statement, the ?EXIT command, or by
pressing the CTRL and Y terminal keys simultaneously.

Noninteractive Mode ENFORM functions in noninteractive mode when commands and statements are

entered through an input file other than a terminal. The input file can be an edit file or
a compiled query file. For example:

:ENFORM /IN

In this example, ENFORM reads the commands and statements from the input file.
When ENFORM functions in noninteractive mode, all commands, statements, and

clauses must be part of the input file. When the file specified in the IN option is a
compiled query file, values for parameters can be specified by using the PARAM
command of the Command Interpreter prior to the ENFORM command. More
information about passing parameters to compiled ENFORM queries appears later in
this section.

ENFORM terminates when an end-of-file, EXIT statement, or ?EXIT command is
encountered on the input file.

input-filename

, OUT

output-filename

/

2–2 058057 Tandem Computers Incorporated

Running ENFORM

Pressing the Terminal Break Key

The Current Output

Listing File

The current output listing file is the file to which ENFORM directs output. During the
course of an ENFORM session, the current output listing file can change.

At the beginning of an ENFORM session, the current output listing file is the default
output file. ENFORM determines the default output file by the following process:

If the OUT option is included in the ENFORM command, the default output file is
the file specified in the OUT option.

If the OUT option is omitted from the ENFORM command, the default output file
is the file specified in the IN option of the ENFORM command if that file is a
terminal.

If the file specified for the IN option is not a terminal, the default output file is the
home terminal.

If both the IN option and the OUT option are omitted from the ENFORM
command, the default output file is the home terminal.

As the session progresses, the current output listing file might change as follows:

If a QUERY-COMPILER-LISTING file is specified, that file becomes the current
output listing file whenever ENFORM commands and statements are being
processed.

If either a QUERY-REPORT-LISTING file or an ?OUT command file is specified,
that file becomes the current output listing file whenever a report (the output from
a LIST statement) is being processed.

Pressing the Terminal

Break Key

The QUERY-COMPILER-LISTING file and the QUERY-REPORT-LISTING file are
discussed later in this section. The ?OUT command file is discussed in Section 6.

ENFORM acknowledges the terminal BREAK key whenever the input file is a
terminal. The input file is a terminal under the following conditions:

the IN option is omitted from the ENFORM command making the home terminal
the default input file.

the terminal (whether the home terminal or another terminal) is the file specified
in the IN option of the ENFORM command.

Pressing the terminal BREAK key on any terminal, including the home terminal, has
no effect unless the terminal is the input file.

058057 Tandem Computers Incorporated 2–3

Running ENFORM

Pressing the Terminal Break Key

The current activity determines the action taken as follows:

Pressing the terminal BREAK key when ENFORM is processing a query,
producing a report, or producing output from the ?SHOW command, returns the
terminal to the ENFORM prompt (>). Query execution and any output (the report
or the output produced by the ?SHOW command) terminates. If you press the
BREAK key while ENFORM is performing a sort operation, ENFORM does not
respond to the BREAK key until the sort operation finishes.

Pressing the terminal BREAK key when commands or statements are being
entered (either directly or indirectly), returns the terminal to the Command
Interpreter prompt (:).

Pressing the terminal BREAK key when you have entered the EDIT process from
the ENFORM prompt has the same effect as when the EDIT process is entered
from the Command Interpreter prompt with one exception: pressing the terminal
BREAK key at the EDIT prompt (*) has no effect.

If the @BREAK-KEY option variable (described in Section 5) is set to OFF, pressing the
BREAK key returns the terminal to the Command Interpreter prompt. It neither
terminates output nor query execution. In this case, ENFORM continues to run and
any output directed to the terminal is temporarily interrupted. The PAUSE command
of the Command Interpreter can be issued to resume output.

2–4 058057 Tandem Computers Incorporated

Running ENFORM

Logical File Assignments

Logical File

Assignments

ENFORM allows logical file assignments to be made either before or after the
Command Interpreter ENFORM command is entered. When the logical file
assignment is made from within the ENFORM subsystem, use the ENFORM ?ASSIGN
command described in Section 6. When the logical file assignment is made before the
ENFORM command is entered, use the Command Interpreter ASSIGN command to
either associate a physical file with a dictionary record description or to assign some
form of ENFORM output to a generic file.

When ENFORM is used in noninteractive mode, the Command Interpreter ASSIGN
command overrides an ENFORM ?ASSIGN command that is part of the input file.
When ENFORM is used in interactive mode, the ENFORM ?ASSIGN command
overrides any Command Interpreter ASSIGN commands.

The syntax of the Command Interpreter ASSIGN command is:

ASSIGN




record-name

{}

generic-file-name



record-name

is the name of a dictionary record description.

generic-file-name

is the name of one of the following generic files: QUERY-WORK-AREA, QUERY­SORT-AREA, QUERY-QPSTATISTICS, and QUERY-QPSTATUS-MESSAGES. All
other names are ignored.

‚

physical-filename

[‚

exclusion-mode




]



physical-filename

is a fully qualified Tandem file name. Refer to the GUARDIAN Operating User’s
Guide for the exact form of a Tandem file name.

exclusion-mode

is either SHARED, PROTECTED, or EXCLUSIVE. The default is SHARED for an
input file. Valid values for generic files are described later in this section.

Refer to the GUARDIAN Operating System Utilities Reference Manual for more
information about the ASSIGN command.

058057 Tandem Computers Incorporated 2–5

Running ENFORM

Passing Parameters to Compiled Query Files

Passing Parameters to

Compiled Query Files

ENFORM allows you to pass parameters to a compiled query file. The compiled query
file must contain a PARAM statement defining the parameter. The PARAM statement
is discussed in Section 4.

Use the PARAM command of the Command Interpreter to specify parameters prior to
execution of the compiled query file. The PARAM command overrides any values
specified in a SET statement for a parameter. The syntax of the Command Interpreter
PARAM command is:

PARAM [

parameter-name parameter-value

] ,...

parameter-name

is the name of a parameter defined in a PARAM statement.

parameter-value

is the value to be assigned to parameter-name. parameter-value can have either of the
following forms:

character-string

"

character-string

If the first form is used, the string must not contain any embedded commas, and
leading and trailing blanks are not included as part of parameter-value.

"

A Server Query

Processor

If the second form is used, all the characters, including leading and trailing blanks,
between the quotation marks are included as part of parameter-value.

Refer to the GUARDIAN Operating System Utilities Reference Manual for more
information about the PARAM command.

Unless otherwise specified, each ENFORM session uses a dedicated query processor.
To avoid some overhead, several compiler/report writer processes can be assigned to
share a single server query processor and sort process. The assignment is made by an
?ATTACH command. A server query processor processes one query at a time.
Figure 2-1 shows several compiler/report writer processes assigned to one server
query processor.

One or more server query processors can be created. Each server query processor runs
as a NonStop process pair, handling queries from one compiler/report writer process
at a time.

A host language program (described in the ENFORM User’s Guide) can also use a
server query processor.

2–6 058057 Tandem Computers Incorporated

Running ENFORM

Passing Parameters to Compiled Query Files

Figure 2-1. Server Query Processor With Several Compiler/Report Writer Processes

ENFORM

Report

Dictionary A

Compiler/

Report Writer

Process

Output

File

Compiled
ENFORM

Query

Dictionary B

Report

ENFORM
Compiler/

Report Writer

Process

Host

Language

Program

ENFORM
Compiler/

Report Writer

Process

Data Base A

ENFORM

Server Query

Processor

Data Base B

ENFORM server query processors are created by a system manager, using the
Command Interpreter ASSIGN and PARAM commands followed by the Command
Interpreter QP command.

058057 Tandem Computers Incorporated 2–7

Running ENFORM

Passing Parameters to Compiled Query Files

The Command Interpreter

ASSIGN Command

For every physical file an ENFORM application accesses, the server query processor
must do open/close operations that add to the processing time. This processing time
can be reduced significantly if ENFORM applications that frequently use the same
physical files are processed by a common server query processor. A server query
processor allows for heavily accessed physical files to be kept open.

The ASSIGN command of the Command Interpreter defines the physical file or files
kept open. The syntax is:

F

ASSIGN

F

number

specifies the logical file name. Legal values for logical file names range from F1
through F31.

generic-file-name

is the name of one of the following generic files: QUERY-WORK-AREA, QUERY­SORT-AREA, QUERY-QPSTATISTICS, and QUERY-QPSTATUS-MESSAGES. All
other names are ignored.

physical-filename

number

{}

generic-file-name

‚

physical-filename

[‚

exclusion-mode

]

The Command Interpreter

PARAM Command

is a fully qualified Tandem file name. Refer to the GUARDIAN Operating System
User’s Guide for the exact form of a Tandem file name.

exclusion-mode

is either SHARED, PROTECTED, or EXCLUSIVE. The default is SHARED for an
input file. Valid values for generic files are described later in this section.

To create a server query processor, you must include a PARAM command specifying a
REQUESTORS parameter. The REQUESTORS parameter defines the maximum
number of requestors the server query processor can accept. The other parameters are
optional and can be specified in the same or in a different PARAM statement.

‚COST

PARAM REQUESTORS

REQUESTORS

sets the maximum number of requestors a query processor can accept. A
requestor can be any ENFORM application or a host language program. (Host
language programs are described in the ENFORM User’s Guide).

max-requestors

max-requestors



‚TIMEOUT




‚READS

max-cost

time-out

max-reads



,...




2–8 058057 Tandem Computers Incorporated

Running ENFORM

Passing Parameters to Compiled Query Files

COST

max-cost

sets a strategy cost limit for each ENFORM query using this server query
processor. If an ENFORM query exceeds the limit, it is terminated and an error
message is displayed. Refer to the @COST-TOLERANCE Option Variable in the
Option Variable clauses in Section 5 for an explanation of strategy cost limits.

Max-cost must be an integer between one and eight. The default is no limit.

The Command Interpreter

QP Command

TIMEOUT

time-out

sets the number of minutes a server query processor sits idle before stopping itself.
The default is no limit, meaning the query processor continues to run indefinitely.

READS

max-reads

sets the maximum number of logical data base reads per ENFORM session. If that
many reads are performed, the ENFORM session is terminated and an error
message is displayed.

Max-reads must be an integer. The default is no limit.

After the parameters are initialized and the physical files to be kept open are specified,
the server query processor is created. The syntax is:

QP / [ NOWAIT ] , NAME
[ , PRI

NAME

process-name

process-name

priority

[ , CPU

] [ , MEM

pages

number

] /

]

is a process name for the server query processor. The name must begin with a
dollar sign ($) followed by an alphabetic character and one to four alphanumeric
characters.

CPU

number

is the number of the CPU where this server query processor resides. The default is
the same CPU where the Command Interpreter resides.

PRI

priority

is the priority at which this server query processor is to run.

MEM

pages

is the maximum number of virtual data pages used for this server query processor.
It must be an integer from one to 64. The default is 64.

Example of Server Query

Processor Creation

Issue the following instructions to create a server query processor named $qp1 that

Keeps open parts, order, and odetail
Accepts up to 15 requestors

058057 Tandem Computers Incorporated 2–9

Running ENFORM

Generic Files

Generic Files A generic file is a file that is used to store some form of ENFORM output. ENFORM

Sets a limit of 2 on the cost strategy
Waits up to three minutes before stopping.

:ASSIGN F1, $data.database.parts
:ASSIGN F2, $data.database.order
:ASSIGN F3, $data.database.odetail
:PARAM REQUESTORS 15, COST 2, TIMEOUT 3
:QP / NOWAIT, NAME $qp1 /

The server query processor keeps open those files that have been assigned “F” names.
In the example, these are F1, F2, and F3. The query itself still refers to these files by
their names as described in the data dictionary: parts, order,and odetail.

(Note that FIND files may not be kept open in this manner.)

produces many different forms of output, such as statistics and error messages. To
enable control over each class of output, generic file names have been defined for each
class. These generic file names can be used in Command Interpreter ASSIGN
commands or ENFORM ?ASSIGN commands (described in Section 6) as the record­name to be assigned to a physical-file-name.

When you assign an ENFORM generic file to a physical file, the physical file must exist
at the time ENFORM attempts to open the file. If you specify an exclusion mode, it is
used. An unspecified or meaningless exclusion mode (for example, protected for
terminals) causes the default (SHARED for terminals and EXCLUSIVE for other
devices) to be used. If you specify an exclusion mode for the generic files QUERY­WORK-AREA and QUERY-SORT-AREA, it is ignored.

Assigning a generic output file name to a process name causes the process to be
treated as if it were the spooler. ENFORM OPENs the process, calls SETMODE, and
WRITEs to the process. It is not possible to ASSIGN a FIND file to a process because
ENFORM will create an unstructured file and rename the file as the last step in
processing the FIND statement. Table 2-1 shows the ENFORM generic file names and
their uses.

2–10 058057 Tandem Computers Incorporated

Running ENFORM

Generic Files

Table 2-1. ENFORM Generic Files and Their Uses

Generic File Name Use
QUERY-COMPILER-LISTING All compilation output produced during an ENFORM session

(that is, entering a query either directly or indirectly ); compiler
errors and warnings; including output, errors, and warnings
from other ENFORM commands (such as ?ASSIGN and
?SHOW).

Output is produced in ASCII with a record length of 132 bytes.

QUERY-REPORT-LISTING All reports produced as a result of the execution of a LIST

statement.
Output is produced in ASCII with a record length of 132 bytes.

QUERY-STATISTICS All statistics produced during an ENFORM session by the

query processor while processing a FIND or LIST statement
when @STATS is SET to ON. Several sets of statistics can
be produced during a session. A set is identified by the
requestor’s PID and the beginning and ending times of the
query execution.

Output is produced in ASCII. For each query processed, the
output consists of (72 * (the number of record-types in the
query + 3 )). For display purposes, each output record is
72 characters long.

QUERY-STATUS-MESSAGES All compiler/report writer error and warning messages

produced during an ENFORM session. All error messages
produced during an ENFORM session by the query processor
or SORT while processing a FIND or LIST statement. These
messages also appear in the listings.

The output is produced in ASCII with a record length of
132 bytes.

QUERY-WORK-AREA The volume where all temporary files (except SORT work files)

are built by the query processor while processing a FIND or
LIST statement during an ENFORM session. The QUERY­WORK-AREA file name should contain only a volume name.

QUERY-SORT-AREA The location where all temporary files are built by the SORT

process while processing a FIND or LIST statement during an
ENFORM session. The QUERY-SORT-AREA file name can
be a volume name or an explicit file name.

058057 Tandem Computers Incorporated 2–11

Running ENFORM

Generic Files

Table 2-1. ENFORM Generic Files and Their Uses (continued)
Generic File Name Use
QUERY-QPSTATISTICS The statistics produced for every FIND or LIST statement that

is successfully processed by the query processor during an
ENFORM session (regardless of the setting of @STATS).
Each set of statistics is identified by a line containing the
requestor’s PID and the beginning and ending times of the
query execution.

If @STATS is set to ON, statistics are also reported to the
QUERY-STATISTICS file.

The output is produced in ASCII. For each query processed,
the output consists of (72 * (the number of record-types in the
query + 3)). For display purposes, each output record is
72 characters in length.

QUERY-QPSTATUS-MESSAGES All error messages produced by the query processor or SORT

during the processing of a FIND or LIST statement during an
ENFORM session. To identify the query in error, each
message is preceded by the requestor’s PID and the time of
the error.

Errors are also reported to the QUERY-STATUS-MESSAGES
file.

The output is produced in ASCII with a record length of
132 bytes.

Generic Files and a

Dedicated Query Processor

In most cases, a generic output file is an unstructured file. When ENFORM opens an
unstructured file to write records, the records are written starting at the beginning of
the file and the existing records are overwritten.

The generic files QUERY-WORK-AREA, QUERY-SORT-AREA, QUERY­QPSTATISTICS, and QUERY-QPSTATUS-MESSAGES can be specified for a dedicated
query processor by using either the ENFORM ?ASSIGN command (see Section 6) or
the Command Interpreter ASSIGN command (see Logical File Assignments earlier in
this section). The ASSIGN command is passed through the ENFORM compiler/report
writer to the query processor for each LIST or FIND statement until the ASSIGN is
cleared.

The query processor opens both QUERY-QPSTATISTICS and QUERY-QPSTATUS­MESSAGES for every FIND or LIST request. Generally, statistics and errors for
multiple requests to a dedicated query processor cannot be collected in a disc file
because the results are written over each other. However, by assigning the generic file
to a process, the statistics and errors can be collected for multiple requests to a
dedicated query processor.

2–12 058057 Tandem Computers Incorporated

Running ENFORM

Generic Files

Generic Files and the

Server Query Processor

Generic Files and the

Current Output Listing File

The generic files QUERY-WORK-AREA, QUERY-SORT-AREA, QUERY­QPSTATISTICS, and QUERY-QPSTATUS-MESSAGES can be held open for the
lifetime of a server query processor if the Command Interpreter ASSIGN command
(see A Server Query Processor earlier in this section) is specified at the time the server
query processor is created.

By using the generic file names with a server query processor, you can specify where
the server query processor: builds the temporary files, performs sorts, sends statistics,
and sends error messages. Since the QUERY-QPSTATISTICS and QUERY­QPSTATUS-MESSAGES files are held open for the lifetime of the associated server
query processor, collection of statistics and errors for multiple requests is possible.

The Command Interpreter ASSIGN commands specified when the server query
processor is started cannot be overridden by either ENFORM ?ASSIGN commands nor
Command Interpreter ASSIGN commands specified when the ENFORM process is
initiated. (The server query processor must be stopped and restarted to alter these file
assignments.)

If you assign generic files by specifying either the ENFORM ?ASSIGN command
(during ENFORM processing) or the Command Interpreter ASSIGN command (before
ENFORM is initiated) the server query processor directs output to these generic files
until you clear the ASSIGN command. Generic files that were not assigned when the
server query processor was created are re-opened for each FIND or LIST statement.

If the Generic files QUERY-REPORT-LISTING and QUERY-COMPILER-LISTING are
assigned, these files become the current output listing files under the following
conditions:

QUERY-COMPILER-LISTING file is the current output listing file whenever
ENFORM statements and commands are processed.

QUERY-REPORT-LISTING file is the current output listing file whenever a report
(the output from the LIST statement) is produced unless the ?OUT command
specifies an ?OUT file.

Assignment of any of the other generic files does not affect the current output listing
file.

Table 2-2, shows the forms of ENFORM output (that is, reports, statement and
command output, statistics, and error messages) and the corresponding output file
when generic files are assigned. The default output file is described earlier in this
section.

058057 Tandem Computers Incorporated 2–13

Running ENFORM

Generic Files

Table 2-2. ENFORM Output Files

ENFORM Output Output File
ENFORM banner and trailer

Commands

1) The QUERY-COMPILER-LISTING file if assigned, otherwise

2) to the default output file.
Statements
Command output (e.g.,?SHOW)

Report from a LIST statement 1) The ?OUT file if specified, otherwise

2) QUERY-REPORT-LISTING file if assigned, otherwise

3) to the default output file.
Statistics

@STATS on

The QUERY-QPSTATISTICS file if assigned and, in addition, to
the following:

1) QUERY-STATISTICS file if assigned, otherwise

2) QUERY-COMPILER-LISTING file if assigned, otherwise

3) to the default output file.

1) The QUERY-QPSTATISTICS file if assigned, otherwise
@STATS off

Error messages from the
command processor and query
compiler

2) the output is not written.

The QUERY-STATUS-MESSAGES file if assigned and, in
addition, to the following:

1) QUERY-COMPILER-LISTING if assigned, otherwise

2) to the default output file.

Note that if the QUERY-STATUS-MESSAGES file is not assigned
and the QUERY-COMPILER-LISTING file is not the default output
file, the error messages are also written to the default output file.

Error messages from the
report writer

The QUERY-STATUS-MESSAGES file if assigned, and, in
addition, to the following:

1) ?OUT file if specified, otherwise

2) QUERY-REPORT-LISTING if assigned, otherwise

3) to the default output file.

Note that if the QUERY-STATUS-MESSAGES file is not assigned
and the list file is not a default output file, the error messages are
also written to the default output file.

Error messages from the Query
processor or SORT

The QUERY-QPSTATUS-MESSAGES file if assigned, and to the
QUERY-STATUS-MESSAGES file if assigned, and in addition to
the following:

1) QUERY-COMPILER-LISTING if assigned, otherwise

2) to the default output file.

Note that if the QUERY-STATUS-MESSAGES file is not assigned
and the current output listing file is not the default output file, the
error messages are also written to the default output file.

The numbers in the Output File column indicate the order in which ENFORM directs output to the files.
If the file with the number 1 exists, ENFORM directs output to this file only. If this file does not exist,
ENFORM directs output to the file with the number 2, and so on.

2–14 058057 Tandem Computers Incorporated

3 ENFORM Language Elements

An ENFORM query is built with elements of the ENFORM language. This section
contains:

An explanation of the ENFORM language elements that are used throughout
query specifications. These elements are: reserved words, special characters, and
comments.

A brief explanation of the functions of the ENFORM statements, clauses, and
commands. The syntax of these language elements is described later in this
manual.

The syntax and functions of the ENFORM language elements that can be used
either in a target-list or in request-qualification. ( Both target-lists and request­qualification are defined in Section 1). These language elements include
aggregates, literals, arithmetic expressions, logical expressions, IF/THEN/ELSE
expressions, parameters, user variables, and user tables.

The rules to be used when referencing data base records, fields, and primary keys,
when including subscripts, and when naming using defined elements such as user
variables, user tables, user aggregates, or parameters.

Figure 3-1 shows a query specification and some of the language elements discussed in
this section.

058057 Tandem Computers Incorporated 3–1

ENFORM Language Elements

Figure 3-1. ENFORM Language Elements

?DICTIONARY $mkt.sample

DECLARE user-var;

AT END PRINT "The End";

OPEN employee;

LIST empnum,empname,salary,

Command
Keyword
Special Character

Statement
Special Character
User Variable
Keyword

Statement
Special Character
String Literal
Keywords

Statement
Special Character
Record Name
Keyword

Field Names

user-var : = (salary + 10)

WHERE salary EQ AVG (salary OVER empnum) ;

Arithmetic Expression

Numeric Literal
Special Character
User Variable

Aggregate
Clause

Special Character
Logical Expression
Keyword
Keyword

3–2 058057 Tandem Computers Incorporated

ENFORM Language Elements

Reserved Words

Reserved Words Reserved words are words with special meaning to ENFORM. Both in syntax and

elsewhere in this publication reserved words are shown in uppercase characters.
Reserved words must be spelled exactly as shown.

Do not use reserved words to name records, fields, variables, tables, or parameters.
Reserved words can be redefined or translated to a language other than English. Refer
to the ENFORM User’s Guide for instructions on redefining the ENFORM reserved
words. Table 3-1 shows the ENFORM reserved words.

Table 3-1. ENFORM Reserved Words and Characters

AFTER DELINK LESS PRINT VIA
ALL DESC LIST SET WHERE
AND DICTIONARY LINK SKIP WITH
AS ELSE LT SPACE ZERO
ASCD END MAX START ZEROS
AT EQ MIN SUBFOOTING ’
AVG EQUAL NE SUBTITLE (
BEFORE EXIT NOHEAD SUBTOTAL )
BEGINS FIND NOPRINT SUM *
BLANK FOOTING NOT SUPPRESS +
BLANKS FORM NULL TAB ­BY GE OF THAN .
ENTER GREATER OFF THEN /
CHANGE GT ON THRU ;
CLOSE HEADING OPEN TIME <
CONTAINS IF OPTION TIMESTAMP-DATE =
COPY INTERNAL OPTIONAL TIMESTAMP-TIME >
COUNT IS OR TITLE @
CUM JULIAN-DATE OVER TO [
DATE KEY PARAM TOTAL ]
DECLARE LE PCT UNIQUE !

058057 Tandem Computers Incorporated 3–3

ENFORM Language Elements

Special Characters

Special Characters Table 3-2 shows the ENFORM special characters and describes their functions within a

query.

Table 3-2. Special Characters

Character Name Character Description
blank Separates keywords and other language elements.

quotation mark ” Serves as delimiter for various language elements, such

as alphanumeric literals, and some display formats.
assignment syntax := Assigns a value to a target-item.
apostrophe ’ Serves as a delimiter for display formats, some

conditional operators.
parenthesis ( ) Delimits various language elements. Must appear in

balanced pairs.
brackets [ ] Delimits subscripts, modifiers, and decorations. Must

appear in balanced pairs.
question mark ? Denotes commands when directly followed by a keyword.
comma , Separates multiple query specifications in the same

statement; always optional.
semicolon ; Terminates statements.

Comments A comment clarifies and documents the purpose of the your query. A comment is

denoted by the exclamation character (!). A comment can be the only text on a line, the
last text on a line, or text embedded within a line. When a comment is embedded
within a line, it must be enclosed with exclamation marks. For example, consider the
following comments:

!This query produces Finance Report 301

DICTIONARY finance.subvol; ! Information is confidential

OPEN finance1, !Only two files are needed! finance2;

3–4 058057 Tandem Computers Incorporated

ENFORM Language Elements

Commands

Statements Statements contain specifications for selecting and formatting elements from your data

base. Composed of keywords, clauses, and target-lists, the ENFORM statements LIST
and FIND provide the basic specifications for information selection. Additional
statements establish the query environment and provide some report structuring
capability.

With the exception of the LIST and FIND statement, ENFORM statements remain in
effect (unless cancelled, reset, or overridden) for the duration of an entire ENFORM
session. ENFORM requires the LIST and FIND statements to be terminated with a
semicolon. The other ENFORM statements should be terminated with a semicolon
since ENFORM does not report errors until it encounters either a terminating
semicolon or the beginning of a new statement.

Refer to Section 4 for the syntax of the ENFORM statements.

Clauses Clauses are optional elements of ENFORM statements. With the exception of the

option variable clauses and the system variable clauses, ENFORM clauses only apply
to the LIST or FIND statement of which they are a part.

Some of the operations performed by ENFORM clauses are:

Sorting and grouping target-records.
Calculating subtotals, totals, percentages, and running totals.
Printing user supplied information within a report.
Formatting a report.
Extracting the current date, time, line number, and page number.
Converting data to internal or display format.

Refer to Section 5 for the syntax of the ENFORM clauses.

Commands Commands are compiler directives that tell the compiler/report writer to perform a

specific action. For example, commands tell the compiler/report writer to:

Associate a new physical file with a record description.
Attach a specific query processor.
Enter the Tandem text editor without leaving ENFORM.
Compile a program and save it in a compiled query file.
Compile and execute an EDIT file containing source code.
Execute a compiled query file.
Include part of an EDIT file in the input to ENFORM.
Display information about the current ENFORM environment.

Refer to Section 6 for the syntax of the ENFORM commands.

058057 Tandem Computers Incorporated 3–5

ENFORM Language Elements

Rules for Naming User Defined Elements

Rules for Naming User

Defined Elements

Rules for Referencing

Data Base Elements

Record Name References When you reference a record name within a query, the record name must be unique.

When you name variables, tables, aggregates or parameters, the name:

Must be unique.
Must start with either an alphabetic character or a circumflex (^).
Can contain numbers, hyphens (-), or circumflexes (^).
Can be from 1 to 31 characters in length.
Must not contain embedded blanks.
Must not end with a hyphen (-).

When you reference a data base element within your query, you must follow certain
rules. The rules used to reference a record name, a field name, and a primary key are
described in the following paragraphs.

If a record name is the same as a field name in an open record description, ENFORM
assumes the unqualified reference refers to the field name.

Referencing a record name as a target-item is the same as referencing each occurrence
of each of the fields individually. A record name cannot be specified as an element in
a print list. ( A print list is part of the AT END statement and clause, the AT START
statement and clause, the FOOTING statement and clause, the SUBFOOTING
statement and clause, the SUBTITLE statement and clause, the TITLE statement and
clause, and the BEFORE CHANGE and AFTER CHANGE clauses.)

Field Name References The same field name can exist in more than one data base file. If your query involves

data base files with duplicate field names, the field name must be uniquely qualified.
Field names can be qualified by using two different conventions. The first convention

joins the record or group name to the field name with a period:

record-name.field-name

or

group.name.field-name

The second convention joins the record or group name to the field name with the
keyword OF. When the OF syntax is used the field name or group name is written
first followed by OF and the qualifier needed:

field-name

or

field-name

OF

record-name

OF

group-name

3–6 058057 Tandem Computers Incorporated

ENFORM Language Elements

Rules for Naming User Defined Elements

A field name requires as much qualifying as necessary to uniquely identify the field to
ENFORM. The necessary qualification might be as simple as combining the field
name with the record name or group name. It might require combining the field name
with both a group name and a record name or with two group names. Consider the
record descriptions shown in Figure 3-2.

Figure 3-2. Records with Duplicate Field Names

RECORD stock-items. RECORD shelf-items.
FILE IS "stock" KEY-SEQUENCED. FILE is "shelf" KEY-SEQUENCED.
02 depot-num PIC 99. 02 dept-num PIC 99.
02 cont-num PIC 99. 02 dept-name PIC X(10).
02 erasers. 02 cont-num PIC 99.
05 ink PIC 99. 02 pens.
05 gum PIC 99. 05 b-point PIC 99.
05 pink PIC 99. 05 felt-tip PIC 99.
02 ink-pens. 02 erasers.
05 felt-tip PIC 99. 05 ink PIC 99.
05 b-point PIC 99. 05 gum PIC 99.
05 fountain PIC 99. 05 gray PIC 99.

If both the stock-items and shelf-items record descriptions are open, ink must be
qualified. To qualify ink within shelf-items, one of the following must be entered:

ink OF erasers OF shelf-items
shelf-items.erasers.ink

Primary Key References The records in data base files can be uniquely identified by the value of a primary key.

For data base files with key-sequenced file structure, the primary key is part of the
record. For data base files with relative, unstructured, or entry-sequenced file
structure, the primary key is not part of the record. Primary keys can be referenced in
two forms:

KEY OF

record-name

or

record-name

.KEY

The form record-name.KEY can appear for only one relative, entry-sequenced, or
unstructured file per query.

058057 Tandem Computers Incorporated 3–7

ENFORM Language Elements

Rules for Naming User Defined Elements

The primary key for files with key-sequenced file structure is a field within the record.
For key-sequenced files, referencing the primary key using the form record-name.KEY
is the same as explicitly naming the field described as the primary key. The advantage
of the form record-name.KEY is that you do not have to know the name of the primary
key field in order to reference it. A listing of the primary key values of the parts file
can be obtained by:

The record with the primary key value of 1403 can be referenced by:

For files with relative file structure, the primary key is a record number. The record
number is the ordinal position of the record relative to the beginning of the physical
file. The first record in the physical file has position zero. A listing of the primary
keys of a relative file can be obtained by:

OPEN parts;
LIST parts.KEY;

WHERE parts.KEY = 1403

OPEN rell;
LIST KEY OF rell;

The primary key of the fifth record in the file can be referenced by:

WHERE KEY OF rell = 4

Remember, the fifth record in a file with relative file structure has position four
because the first record has position zero.

For entry-sequenced and unstructured files, the primary key is a record address—the
byte address of the record’s block plus the relative record number within the block. A
record address is always an even number. For more information about file structures,
consult the ENSCRIBE Programming Manual.

A listing of the primary keys of an entry-sequenced file can be obtained by:

OPEN entryseq;
LIST entryseq.KEY;

The third record in the file entryseq has a primary key whose byte offset is 16. The
record can be referenced by:

WHERE entryseq.KEY = 16

For more information about file structures, refer to the ENSCRIBE Programming
Manual.

3–8 058057 Tandem Computers Incorporated

ENFORM Language Elements

Subscripts

Subscripts Subscripts, although they are not required, are usually used to reference elements in a

user table or data base table. (A data base table is created when the dictionary
description of a data base field contains an OCCURS clause.) Subscripts are needed
for references to user tables and data base tables because all the elements in such tables
have the same name. Subscripts can be used in references to data base fields and user
variables although they are not necessary.

The syntax for including subscripts is:

field-name-ref1

{}

user-table-name

"["

grp-name





field-name-ref1

is the qualified name of a data base field.

user-table-name

is the name of a user table defined by the DECLARE statement.

subscript

is an integer. The lowest valid value for subscript is 1. The highest valid value is
the maximum number of elements defined for the user or data base table. (Refer
to the following discussion for more information.)

subscript-range

has the form

subscript

"["

subscript-range

subscripti

"["

{}

subscript

"["

subscript-range

"]"





"]"

:

subscriptj

"]"

"]"

.

field-name-ref2

"["

subscript

{}

"["

subscript-range

"]"

"]"

subscripti

subscriptj

058057 Tandem Computers Incorporated 3–9

is the first element being referenced.

is the last element being referenced.

ENFORM Language Elements

Subscripts

grp-name

is the name of a group described in the dictionary. A group is defined as a record
element whose level number (02, 03, 04,...) is less than that of the next record
element.

field-name-ref2

is the name of a subordinate field. A subordinate field is defined as a record
element whose level number (05, 06, 07,...) is greater than that of grp-name.

When a subscript is included with a reference to a table name, a user variable name, or
a field name, ENFORM determines whether the subscript is a valid subscript value
allowed for the table, variable, or field. A valid subscript value for a field or user
variable is 1. Valid subscript values for a user table are defined in the DECLARE
statement. For example, consider the following user table declaration:

DECLARE u-var[ 24 ];

The valid subscript values for u-var are 1 through 24. Valid subscript values for data
base tables are defined by the OCCURS clause in the dictionary description of the
table. For example:

02 monthly-sales OCCURS 12 TIMES.

The valid subscript values for monthly-sales are 1 through 12.
Both user and data base tables can be referenced without a subscript. ENFORM

assumes a subscript of 1. For example:

u-var Refers to the first element of the user table.
monthly-sales Refers to the first element of the data base table.

Including a subscript with a user or data base table reference identifies the individual
elements of the table. For example:

u-var [ 2 ] Refers to the second element of the user table.
monthly-sales [ 4 ] Refers to the fourth element of the data base table.

3–10 058057 Tandem Computers Incorporated

ENFORM Language Elements

Subscripts

Subscript-range can be included in user or data base table references when the table is
the target-item in a LIST statement. Subscript-range is illegal if a data base table is
modified by a BY, BY DESC, ASCD, or DESC clause. (Refer to Section 5 for
information about these clauses.) Including subscript-range is the same as referencing
the table elements individually. For example:

u-var [ 3:8 ] Refers to the third through eighth elements of the user

table.

monthly-sales [ 1:4 ] Refers to the first through fourth elements of the data

base table.

ENFORM does not allow arithmetic on subscript ranges. For example,

LIST (employee [1:5].salary * 1.10)

is illegal.
In the dictionary record description, a data base table can be defined as a group

element with subordinate data base field entries. For example:

02 sales OCCURS 12 TIMES.
10 month PIC X(3).
10 top-dept PIC 9999.

ENFORM allows you to refer to the subordinate data base fields as follows:

sales Refers to month and top-dept within the first element of

sales.

sales [ 2 ].top-dept Refers to top-dept within the second element of sales.
sales [ 2:3 ].month Refers to month within the second through third

elements of sales.

The subordinate elements of a data base table can themselves contain a data base table
resulting in nested data base tables. For example, consider the following record
description:

02 tot-sales OCCURS 12 times.
10 month PIC X(3).
10 top-dept PIC 999.
10 wkly-sales PIC 99999 OCCURS 4 TIMES.

058057 Tandem Computers Incorporated 3–11

ENFORM Language Elements

Aggregates

Aggregates An aggregate is the result of a cumulative operation performed for each value that

ENFORM allows you to reference nested data base tables. For example:
tot-sales Refers to month, top-dept, and the first

through last elements of wkly-sales within
the first element of tot-sales.

tot-sales[4].wkly-sales[2] Refers to the second element of wkly-sales

within the fourth element of tot-sales.

tot-sales[1:5].wkly-sales[3] Refers to the third element of wkly-sales

within the first thru fifth elements of tot-
sales.

tot-sales[2:3].wkly-sales[1:4] Refers to the first thru fourth elements of

wkly-sales within the second thru third
elements of tot-sales.

contributes to the aggregate. An aggregate yields a single value for the group of
values over which it is processed. Aggregates can only be specified as a target-item or
in a request-qualification. Aggregates specified as a target-item are called target
aggregates. Aggregates specified in a request-qualification are called qualification
aggregates.

ENFORM provides two types of aggregates: predefined and user-defined.
The syntax used for an aggregate is:

AVG












AVG

COUNT



MAX
MIN



SUM

user-aggregate



AVG



COUNT



SUM



MAX



MIN



user-aggregate

is a predefined ENFORM aggregate that computes an average value for a set of
numbers or expressions.



field-name

(

{}

expression

OVER ALL

[]

OVER



[ WHERE

logical-expression







( [ UNIQUE ]




[ WHERE



field-name

logical-expression

over-item

[ OVER ALL ]

])‚

])‚












3–12 058057 Tandem Computers Incorporated

ENFORM Language Elements

COUNT

is a predefined ENFORM aggregate that tallies the occurrences of a field defined
as either numeric or alphanumeric.

MAX

is a predefined ENFORM aggregate that finds the highest number in a set of
numbers or expressions, or finds the alphanumeric string with the highest value
based on the ASCII collating sequence.

MIN

is a predefined ENFORM aggregate that either finds the lowest number in a set of
numbers or expressions or finds the alphanumeric string with the lowest value
based on the ASCII collating sequence.

SUM

Aggregates

is a predefined ENFORM aggregate that totals a set of numbers or expressions.

user-aggregate

is the name of an aggregate defined by a DECLARE statement. (See Section 4).

field-name

is the name of a data base field.

expression

is a arithmetic or IF/THEN/ELSE expression (explained later in this section.)

over-item

is a field used to sort and group the records over which the aggregate is processed.
For a target aggregate, over-item must be a by-item (the name of a field modified by
a BY or BY DESC clause). For a qualification aggregate, over-item can be any field
name.

OVER ALL

defines the range of the aggregate operation as over all the values specified.

058057 Tandem Computers Incorporated 3–13

ENFORM Language Elements

Aggregates

OVER

defines a range for the aggregate operations. The aggregate operation takes place
only over the specified over-item. The operation yields one aggregate value for
each unique value of over-item.

UNIQUE

excludes duplicate values from contributing to the collecting operation of the
aggregate. UNIQUE adds considerable processing overhead and should not be
specified unless you know unwanted duplicate values exist. UNIQUE is
redundant with MAX or MIN. While the same answer is returned when UNIQUE
is specified with these aggregates, processing time increases greatly.

Predefined Aggregates The five predefined ENFORM aggregates are: AVG, COUNT, MAX, MIN, and SUM.

AVG finds an average value for a set of numbers. For each record containing a field
value to be averaged, the field value is added to the running total of the contributing
field values. After all contributing field values are processed, the final total is divided
by the number of field values that made up the total. The following example finds the
average of the partcost field over the suppnum field:

LIST BY suppnum,
AVG(partcost OVER suppnum);

COUNT tallies the instances of an element. In the following example, the number of
parts kept in stock are counted by counting the part numbers in parts:

OPEN parts;
LIST COUNT(partnum);

MIN determines the lowest number in a set of numbers or expressions. MAX
determines the highest number in a set of numbers or expressions. The following
example finds both the lowest and the highest price of a part:

OPEN fromsup;
LIST BY partnum,
MIN(partcost OVER partnum),
MAX(partcost OVER partnum);

SUM totals a set of numbers or expression values. In the following example, the sum
of the sales made by each salesman is obtained:

OPEN order,odetail,parts;
LINK order to odetail VIA ordernum;
LINK odetail to parts VIA partnum;
LIST BY salesman,
SUM (price * quantity) OVER salesman);

3–14 058057 Tandem Computers Incorporated

ENFORM Language Elements

Aggregates

User Aggregates When the predefined aggregates do not meet your needs, you can define your own

aggregates with a DECLARE statement. A user-defined aggregate can be used
anywhere a predefined aggregate can appear with two exceptions:

A user aggregate cannot be referenced in the end expression of the declaration of
another user aggregate.

A user aggregate declared with an end expression cannot be used as a
qualification aggregate OVER a by-item.

The syntax of a user-defined aggregate is shown in Section 5 with the DECLARE
statement. The syntax is also shown here to clarify this discussion.

user-aggregate-name

[ , [

end-expression

(

formal-argument

] [ ,

initialize-constant

) = (

step-expression

] ] )

user-aggregate-name

is a unique name you give your aggregate. The name must follow the naming
rules described earlier in this section. This name is also used to obtain the current
value of the aggregate in step-expression and end-expression.

formal-argument

is a unique name used to represent the actual field name or expression in the
aggregate definition.

step-expression

is an arithmetic expression to be computed for each value contributing to the
aggregate. Normally step-expression includes a reference to the user-aggregate-name
so that a value is accumulated over the contributing values.

end-expression

is an arithmetic expression to be computed after all qualifying values for the
aggregate are processed. End-expression can contain a pre-defined aggregate name.
If end-expression is omitted and initialize-constant is present, an extra comma must
precede initialize-constant.

initialize-constant

is a numeric literal that is the starting value of the aggregate. Zero is the default.
When end-expression is omitted and initialize-constant is present, an extra comma

must precede initialize-constant.
Parentheses must appear exactly as shown in this syntax.
Consider the following user aggregate:

DECLARE grossavg (x) = (grossavg + 1.10 * x, grossavg/COUNT

(x));

058057 Tandem Computers Incorporated 3–15

ENFORM Language Elements

Aggregates

Target Aggregates A target aggregate appears as part of the ENFORM output. When you specify a target

The user-aggregate name is grossavg. The formal-argument is x. The step-expression is
(grossavg + .10 * x). The end-expression is grossavg/COUNT (x).

This user-aggregate could be used to compare the new gross salaries to the old
average salary:

LIST AVG (salary), grossavg (salary);

aggregate, follow these rules:

The field names in the target aggregate syntax can come from different data base

records.

Over-item must be a by-item.

Target aggregates cannot be nested; that is, one aggregate cannot be used as the

argument for another aggregate.

The UNIQUE syntax cannot be used with an aggregate computed over a by-item.

Target Aggregate with OVER ALL Syntax

When you specify a target aggregate without specifying either OVER or OVER ALL,
ENFORM assumes OVER ALL. Figure 3-3 shows both a query outline using the
OVER ALL syntax and an output diagram.

Figure 3-3. Query Outline of Target-Aggregate with OVER ALL Syntax

LIST BY by-item-1, BY by-item-2,
target-item-1...,
target-item-2...,
AVG(target-item-2 OVER ALL);

by-item-1 by-item-2 target- target- AVG
item-1 item-2 Target-item-2

|---------|
xxxxx xxxxxx xxxxxx | xxxxxxx | xxxxxxxxxxx
xxxxxx | xxxxxxx |
xxxxxx | xxxxxxx |
xxxxxx xxxxxx | xxxxxxx |
xxxxxx | xxxxxxx |
xxxxx xxxxxx xxxxxx | xxxxxxx |
xxxxxx | xxxxxxx |
xxxxxx | xxxxxxx |
xxxxxx | xxxxxxx |
|---------|

total/number of target-item-2=

3–16 058057 Tandem Computers Incorporated

ENFORM Language Elements

Aggregates

Specifying the aggregate shown in Figure 3-3 is the same as specifying:

AVG(target-item-2);

The query groups target-item-1 and target-item-2 within by-item-2. The aggregate
AVG is used and the average value of target-item-2 is found by totaling all of the
values of target-item-2 and dividing that total by the number of target-item-2 values.
Notice that AVG target-item-2 prints as a separate column on the report with only one
non-blank entry. This entry corresponds to the aggregate value of all records in the
report.

When a target aggregate is specified in a FIND statement with OVER ALL either
present or assumed, only the first target-record contains the aggregate value. This
field is blank in all other target-records generated by the FIND statement.

Target Aggregate with OVER Syntax

If you specify a target aggregate in a LIST or FIND statement with the OVER syntax, a
single aggregated value is returned for each grouped value. Consider the query
outline and output diagram shown in Figure 3-4.

Figure 3-4. Query Outline of Target-Aggregate with OVER Syntax

Query outline:

LIST BY by-item-1,
BY by-item-2,
target-item-1
AVG(target-item-1 OVER by-item-2);

Output Diagram:

|---------|
by-item-1 by-item-2 | target- | AVG
| item-1 | target-item-1

--------- --------- |---------| ------------­ xxxxxxx xxxxxxx | xxxxxxx | xxxxxxxxxxxxx
| xxxxxxx | (total/4)
| xxxxxxx |
| xxxxxxx |
|---------|
xxxxxxx | xxxxxxx | xxxxxxxxxxxxx
| xxxxxxx | (total/2)
|---------|
xxxxxxx xxxxxxx | xxxxxxx | xxxxxxxxxxxxx
| xxxxxxx | (total/3)
| xxxxxxx |
|---------|

058057 Tandem Computers Incorporated 3–17

ENFORM Language Elements

Aggregates

In this example, AVG target-item-1 prints as a separate report column with a non­blank entry only on the first line of each new by-item-2 group. This entry represents
the average of target-item-1 over the by-item-2 group.

When a target aggregate is specified in a FIND statement with the OVER syntax, the
aggregate value is present only in the first target-record for a by-item. This field is
blank for all other target-records.

Qualification Aggregates

Qualification aggregates must be specified in a WHERE clause. When specifying a
qualification aggregate, follow these rules:

Qualification aggregates cannot be nested; that is, one aggregate cannot be used as

the argument for another aggregate.

A qualification aggregate can contain an embedded WHERE clause.

The embedded WHERE clause can contain another qualification aggregate;

however, that qualification aggregate must be computed OVER ALL.

All field names used for each individual qualification aggregate expression (the

field being aggregated, any field name appearing in an expression being

aggregated, any field name appearing in the WHERE clause associated with an

aggregate, and any over-item) must come from the same data base record.

The UNIQUE syntax cannot be used with an aggregate computed over an

over-item.

Qualification Aggregate with OVER ALL Syntax

When you specify a qualification aggregate without specifying either OVER or OVER
ALL, ENFORM assumes OVER ALL. ENFORM computes the value for the
qualification aggregate over all the records in the original data base (not over the
target-records). For example:

LIST odetail,

WHERE quantity > AVG (quantity );

restricts the records returned from odetail to those whose quantity field is greater than
the average of all the values of the quantity field.

Qualification Aggregates with OVER Syntax

When a qualification aggregate is used with the OVER syntax, ENFORM computes
one value for each over-item group. When the WHERE clause is evaluated, ENFORM
uses the qualification aggregate value for the particular group to restrict the records
selected. Figure 3-5 shows a query outline and the process that occurs when the OVER
syntax is used.

3–18 058057 Tandem Computers Incorporated

ENFORM Language Elements

Aggregates

Qualification Aggregates and Target Records

A qualification aggregate functions as a full subquery. This means that ENFORM
computes the value for the aggregate over all the records in the data base file, (not over
the target records selected in the rest of the LIST or FIND statement) and uses the
result as input to the target list.

For example, the statement:

LIST BY job,

empname,

AVG (salary)

WHERE salary < AVG (salary);

gives:

All employees whose salaries are less than the average

The average of all salaries that are less than the average

058057 Tandem Computers Incorporated 3–19

ENFORM Language Elements

Aggregates

Figure 3-5. Query Outline of Qualification Aggregate with OVER Over-item Syntax

OPEN employee;

LIST regnum,

branchnum,

WHERE salary GT AVG( salary OVER regnum );

The qualification aggregate value for each group is:

regnum AVG salary

1 24666

2 28333

5 38000

99 39500

If employee has the following form when grouped by regnum and branchnum:

regnum branchnum salary

1 1 36000

19000

25000

26000

12000

2 30000

2 1 37000

25000

23000

5 3 38000

99 1 39500

The report produced is:

Region Branch

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

2 1

1 1

1 1

1 1

1 2

3–20 058057 Tandem Computers Incorporated

ENFORM Language Elements

Aggregates

Qualification Aggregate with an Embedded WHERE Clause

If a qualification aggregate contains a WHERE clause that restricts the records for the
aggregate calculation, ENFORM processes the embedded WHERE clause before the
aggregate. If any record for an over-item does not satisfy the restriction specified in the
embedded WHERE clause, ENFORM excludes that record from the aggregate
calculation.

For example consider Figure 3-6. This figure shows an ENFORM query containing a
qualification aggregate with a WHERE clause. The query prints the part number and
the amount in stock of all the parts where the price of the part is greater than the
average price of all parts not in stock.

Figure 3-6. Qualification Aggregate with Embedded WHERE Clause

OPEN parts;

LIST partnum,

inventory,

WHERE price GT AVG (price WHERE inventory LT 0);

The report produced is:

Part Number INVENTORY

212 7

244 3
1403 21
5502 6
5504 –1
5505 0
7102 20

Aggregates and Scale

All the aggregates except COUNT take their display format from the formats of the
input values. (COUNT always returns a value with a scale of zero, or no digits to the
right of the decimal point.) Consequently, if a field is defined as an integer and the
aggregate yields a fractional value, the aggregate returns only the whole portion of the
value. If the field is defined as a decimal, the value returned is accurate to the number
of decimal places provided by the DDL data definition for the field.

058057 Tandem Computers Incorporated 3–21

ENFORM Language Elements

Literals

Literals Literals can be used in both a target-list and a request-qualification. Literals can also

If you want the aggregate to return a value with a scale other than that of the input
field, assign the result to a user variable declared with the appropriate scale. For
example:

DECLARE fixit INTERNAL F6.2;
LIST fixit := AVG (price OVER partnum);

The average of “price” over “part number” will now be returned with six total digits,
with two digits to the right of the decimal point.

be used in many ENFORM statements and clauses. Literals are used in titles,
headings, special text printed within a report’s body, and in expressions. The two
types of literals are numeric and string.

Literals cannot be continued across lines. The maximum length of a literal is
127 characters.

Numeric Literals Numeric literals are used in all arithmetic expressions. They can be used in logical

expressions when the literal is compared to a data base element described in the data
dictionary as numeric. Numeric literals:

Are not enclosed in quotation marks.
Are composed of the digits 0-9.
Can be preceded or followed by a plus or minus sign.
Must be enclosed in parentheses if they are specified outside of a logical

expression or a TAB, SPACE, SKIP, or FORM clause.

Numeric literals can stand alone as target-items in a LIST or FIND statement. In this
case they must be enclosed in parentheses.

The following are examples of numeric literals:

(104) (123.0444) (+267) (.006) (-15)

String Literals String literals can be used in many of the ENFORM statements and clauses. String

literals can be used in logical expressions if the data base element to which the string
literal is compared is declared alphabetic or alphanumeric in the data dictionary.
String literals:

Can be composed of any character in the ASCII character set.
Must be enclosed in quotation marks. If a quotation mark is part of a string literal,

the quotation mark must be doubled.

The following are examples of string literals:

"This is a string literal"

"This string literal contains a "" quotation mark"

"1234.99"

3–22 058057 Tandem Computers Incorporated

ENFORM Language Elements

Arithmetic Expressions

String literals can stand alone as target-items in a LIST statement. Using a string literal
in this manner allows printing of one or more constant characters between two
columns of data. For example:

LIST customer,"....",address;

produces the following report:

CUSTOMER ADDRESS

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

CENTRAL UNIVERSITY....UNIVERSITY WAY

BROWN MEDICAL CO ....100 CALIFORNIA STREET

Arithmetic

Expressions

Arithmetic expressions are some combination of numeric literals, field values,
variables, or aggregates that are added, subtracted, multiplied, or divided to yield a
single value. A JULIAN-DATE clause, TIMESTAMP-DATE clause, or a TIMESTAMP­TIME clause can also be used in an arithmetic expression. Arithmetic expressions
must be enclosed in parentheses.

Table 3-3 shows the arithmetic operators and their functions.

Table 3-3. Arithmetic Operators

Operator Function
+ Addition

– Subtraction
* Multiplication
/ Division

Spaces are not required before any of the arithmetic operators with the exception of
the subtraction sign (–). At least one space must precede a subtraction sign that
follows a field or variable name.

Arithmetic expressions can be simple:

(price + 10.00)

or they can be complex:

((price + 10.00)* quantity)

Evaluation Order of

Arithmetic Expressions

Arithmetic expressions are evaluated in this order:

1. Nested parenthesized expressions are evaluated first, beginning with the
innermost expression.

2. Within a nested parenthesized expression, multiplication and division operations
are evaluated next.

3. Within a nested parenthesized expression, addition and subtraction operations are
evaluated last.

058057 Tandem Computers Incorporated 3–23

ENFORM Language Elements

Logical Expressions

Scale Factor of the Result The scale of the result is determined by the number of digits after the decimal point.

In an arithmetic expression, the result has the same number of digits after the decimal
point as the field or variable in the expression with the greatest precision. This could
result in loss of significant digits if too great a precision is used for the field or variable.

The resulting scale factor can be controlled by assigning the result of the arithmetic
expression to a user variable. (User variables are explained later in this section.) The
precision of the user variable can be specified by an INTERNAL clause within the
DECLARE statement that defines the user variable. The maximum number of digits
allowed is 18. All calculations with ENFORM are performed with QUAD arithmetic.

Logical Expressions Logical expressions evaluate to a truth value—either true or false based on a condition

specified within the expression. Both the conditions that can be specified and the
conditional operators are shown in Table 3-4.

Table 3-4. Conditional Operators

Condition Keyword Abbreviation Symbol
Equal EQUAL

EQ =

IS
Not equal NE < >
Greater than GREATER [THAN] GT >
Greater than or equal to GE >=
Less than LESS [THAN] LT <
Less than or equal to LE <=

ENFORM provides two other conditional operators: BEGINS WITH and CONTAINS.
The three symbols ‘]’ are synonymous with BEGINS WITH and the three symbols ‘>‘
are synonymous with CONTAINS.

3–24 058057 Tandem Computers Incorporated

The syntax of a logical expression is:

ENFORM Language Elements

Logical Expressions

[NOT]

condition

condition

has one of the following forms:



{}







[

not



field-name

variable



field-name




expression

conditional-operator








[NOT]



[NOT]




AND
OR

]

[NOT]

BEGINS WITH



']'



CONTAINS



'>'





conditional operator

EQUAL



EQ



IS



=



NE



<>

conditional-operator

condition





value-range



{}

"["







...







string-literal






pattern-match

variable



field-name




expression

"]"

















is one of the conditional operators shown in Table 3-4.

expression

is an IF/THEN/ELSE or arithmetic expression.

pattern-match

is a pattern of numbers or characters, enclosed within both quotation marks and
brackets. The syntax for a pattern-match is:

"["





n

nn
m‚n string-literal

--

is an integer indicating that exactly n number of characters must precede or
follow string-literal when it is found in a field value.

...

m‚n

"]"





058057 Tandem Computers Incorporated 3–25

ENFORM Language Elements

Logical Expressions

string-literal

is the pattern of characters or numbers to which the field is being compared.
String-literal must be enclosed in quotation marks.

m,n

is two integers separated by comma indicating that at least m characters but
not more than n characters must precede or follow string-literal when it is
found in a field value.

-

is a dash indicating any number of characters (0 thru 255) can precede or
follow string-literal when it is found as a field value. Specification of a dash
indicates you do not care about the contents of this part of the field.

value-range

Effect of Parentheses on

Compound Logical

Expressions

is a range of values with the form: value-1 THRU value-2

A logical expression can be simple or compound. A simple logical expression consists
of one condition. A compound logical expression uses the boolean operators AND,
OR, and NOT to operate over two or more logical expressions.

Using the boolean operators AND, OR, and NOT has the following effect on the
evaluation of the logical expression:

When you precede a condition with the boolean operator NOT, the result of the
expression is evaluated as true if the condition is evaluated as false.

When you join two or more conditions with the boolean operator AND, the result
of the expression is evaluated as true only if all the conditions are evaluated as
true.

When you join two or more conditions with the boolean operator OR, the result of
the expression is evaluated as true if any of the conditions are evaluated as true.

Compound logical expressions are evaluated in this order:

1. Conditions within parentheses are evaluated first.

2. Conditions preceded by the boolean operator NOT are evaluated second.

3. Conditions joined with the boolean operator AND are evaluated third.

4. Conditions joined with the boolean operator OR are evaluated last.

3–26 058057 Tandem Computers Incorporated

ENFORM Language Elements

Logical Expressions

BEGINS WITH and

CONTAINS

BEGINS WITH and CONTAINS are special conditional operators that can be used to
yield a true or false value if a field either begins with or contains a specific
alphanumeric string.

The BEGINS WITH operator determines if a field starts with a specified alphanumeric
string. For example, the following can be used to limit the data retrieved from the
supplier field to only those records whose suppname field begins with TANDEM:

LIST supplier WHERE suppname BEGINS WITH "TANDEM",

In this example, the logical expression is evaluated as true only if the field begins with
a value where TANDEM is in uppercase characters.

The BEGINS WITH operator can only be used with fields specified as alphanumeric in
the data dictionary. A field is alphanumeric when its corresponding data description
entry is specified as PIC X.

The CONTAINS operator determines if a field contains a specified alphanumeric
string. For example, the following determines whether the empname field contains
the value GEORGE:

empname CONTAINS "GEORGE"

ENFORM does not support variable-length parameters. The following query, in
which xyz has been defined as a five-character field, will not work if you pass xyz a
three-character value:

Range of Values in Logical

Expressions

PARAM xyz INTERNAL A5;
OPEN order;
LIST order WHERE KEY BEGINS WITH "xyz";

ENFORM will look for a value of “xyz” plus two blanks, and the query will fail.

A field can be compared to a range of values in a logical expression. In the range,
value-1 must be less than value-2. Values used in a range can be either numeric
literals or string literals.

Specifying field EQ value1 THRU value2 is equivalent to specifying:

field-name GE value-1 AND field-name LE value-2

A range can contain a numeric literal if the field being examined is defined as numeric
in the data dictionary. The inventory field of the parts file is defined as PIC 999. The
following logical expression is evaluated as true if the value of the inventory field falls
within the range of 5 to 15, including the values 5 and 15:

inventory EQ 5 THRU 15,

058057 Tandem Computers Incorporated 3–27

ENFORM Language Elements

IF/THEN/ELSE Expressions

A range expression can also use a string literal if the field being examined is defined as
alphanumeric in the data dictionary. The partname field is defined as PIC X(18). The
following logical expression is evaluated as true if partname field contains a value that
falls with in the range of A to L:

partname EQ "A" THRU "LZZZZZZZZZZZZZZZZZ"

Note that the second string literal is 18 characters long, the length of the partname
field. Specifying the literal in this manner ensures that all of the part names beginning
with L are included.

Pattern-Match in Logical

Expressions

IF/THEN/ELSE

Expressions

In a logical expression a field described as alphanumeric in the data dictionary can be
compared to a pattern-match. A pattern-match is actually a comparison template that
the field value is compared to. In the following logical expression, the partname field
is compared to a pattern-match:

partname = [-"DISK" - "MB"-],
OR partname = [-"DISK"-"Mb"-],
OR partname = [-"Disk"-"MB"-],
OR partname = [-"Disk"-"Mb"-],

In the following logical expression, two numbers precede the string-literal indicating
that at least one character but no more than two characters must precede string-literal
in the field value:

partname EQ [1,2 "T"-],

IF/THEN/ELSE expressions yield a value determined by the result of a logical
expression. IF/THEN/ELSE expressions can be used wherever an arithmetic
expression can be used. IF/THEN/ELSE expressions can be nested. The syntax of an
IF/THEN/ELSE expression is:

(IF

logical-expression

THEN

value-1

ELSE

value-2

)

logical-expression

is a logical expression that evaluates as true or false.

value-1 or value-2

is a field name, an arithmetic expression, or IF/THEN/ELSE expression, or one of
the following value keywords: NULL, BLANK, BLANKS, ZERO, ZEROS.

If the logical expression is evaluated as true, value-1 is used. If the logical expression is
evaluated as false, value-2 is used. Value-1 and value-2 must be the same data type,
either both numeric or both alphanumeric.

3–28 058057 Tandem Computers Incorporated

ENFORM Language Elements

User Variables

The value keywords NULL, BLANK, and BLANKS print blanks on reports. The value
keywords ZERO and ZEROS print zeros on reports.

Consider the following IF/THEN/ELSE expression:

IF partnum = 2001 THEN ZEROS ELSE partnum,

This expression specifies that if partnum is equal to 2001, then zeros are to be printed
on the report. If partnum has any other value except 2001, partnum prints.

Parameters You can use a parameter either for request qualification or as a target-item. You can

pass a parameter to a stored compiled query file. Define parameters by issuing the
PARAM statement, described in Section 5.

ENFORM handles parameters syntactically as if they were literals. ENFORM handles
any parameter declared with an alphanumeric internal format as a string literal.
ENFORM handles all other parameters as numeric literals. You must enclose a
parameter with parentheses wherever you would have to enclose a numeric literal
with parentheses.

User Variables A user variable can be used to store numeric or string literals, save a field value, or

hold the result of a calculation for later printing.
Before the user variable is specified in a query, the DECLARE statement (see Section 4

for the syntax of the DECLARE statement) must be entered. This statement defines the
variable name and optionally defines the internal storage format (the default internal
storage format is a 64-bit signed integer), a default display format, and a default
heading. The name given to the user variable must conform to the naming
conventions described in this section.

The default value of a user-declared-variable is zero. An initial value for the user
variable can be defined with the SET statement.

058057 Tandem Computers Incorporated 3–29

ENFORM Language Elements

User Variables

User Variable as a

Target-item

When a user variable is specified as a target-item, ENFORM uses the default value or
the initial value, whichever is appropriate. When a user variable is a target-item in a
LIST statement, assignment syntax can be used to specify a new value for the user
variable. The value of a user variable changes as target list elements are evaluated, so
that at any time, the value of the user variable depends upon the value most recently
assigned.

Assignment syntax is:

field-name



aggregate



user-variable-name-1

user-variable-name-1

is the name of the user variable being defined.

field-name

is the name of a data base field.

aggregate

:=

literal



user-variable-name-2



expression



user-table-element









is the value of a predefined or user aggregate.

literal

is a numeric or string-literal that agrees in type with the user variable.

user-variable-2

is the name of a previously defined user variable.

expression

is an arithmetic or IF/THEN/ELSE expression.

user-table-element

is the subscripted name of a user table element. You cannot assign a subscript
range to a user variable.

3–30 058057 Tandem Computers Incorporated

ENFORM Language Elements

User Variables

When assignment syntax is used, ENFORM reassigns a value to the user variable for
each target-record; therefore, the value of the user variable might be different for each
target-record. For example:

LIST u-var, u-var := salesman;

ENFORM uses the default or initial value for the first occurrence of u-var in every
target-record. For the second occurrence of u-var ENFORM uses the value of the
salesman field. This value changes for every target-record.

A user variable can be assigned the value of an expression that contains the user
variable. For example:

DECLARE u-var;
SET u-var TO 10;
OPEN parts;
LIST partname,
u-var:= (u-var + 10);

ENFORM uses the initial or default value of the user variable to determine the value of
the expression. In the example the value of the expression is 20. ENFORM then
assigns this value to the user variable. Within the same LIST statement, assignment
syntax can subsequently be used to assign the user variable to another expression
containing the user variable. For example:

DECLARE u-var;
SET u-var TO 10;
OPEN parts;
LIST partname,
u-var:= (u-var +10),
u-var:= (u-var +20);

ENFORM uses 20, the value assigned in the first assignment syntax (u-var + 10) for the
value of u-var in the second expression. After determining the value of the expression
(u-var +10) +20)), ENFORM assigns the value of the expression (40) to the user
variable.

ENFORM performs this process for every target-record. ENFORM continues the
process of re-evaluating the value of a user variable until it encounters the end of the
target-list.

058057 Tandem Computers Incorporated 3–31

ENFORM Language Elements

Arithmetic Overflow Conditions

A User Variable in

Request-Qualification

User Tables User tables are special kinds of user variables that can store more than one value.

A user variable can be specified in a request-qualification. When a user variable is
used for request qualification, ENFORM always uses either the default or initial value
whichever is appropriate. Consider the following:

SET u-var to 10;
LIST ordernum,
u-var:= (ordernum + u-var)
WHERE u-var > 10;

The preceding query always returns zero target-records even though in every target­record the value of u-var (ordernum + u-var) is greater than 10. No target-records are
returned because ENFORM uses the initial value of the user variable to evaluate the
WHERE clause. Since u-var is set to 10, no target-records are selected for a WHERE
clause with a logical expression u-var > 10.

Currently a user table can have a maximum of 64 elements called occurrences.
ENFORM issues an error message if you attempt to define a table with more than 64
occurrences.

The individual elements of a user table can be referenced by using subscripts. Refer to
the discussion of subscripts in this section for more information.

Like user variables, user tables can be initialized by the SET statement. The default
value of all elements in a user table is zero. When a user table is specified as a target­item, ENFORM determines its value in the same manner the value of a user variable is
determined. Assignment syntax can be used to assign values to single elements of a
table.

Arithmetic Overflow

Conditions

An arithmetic overflow condition can occur when ENFORM computes a value for:

an arithmetic expression.
a predefined aggregate (such as: SUM or AVG) or a user-defined aggregate.

An arithmetic overflow condition does not cause ENFORM to issue either an error or a
warning message. Instead, ENFORM truncates the result of the computation. If an
arithmetic overflow condition occurs when ENFORM is computing an intermediate
result, ENFORM uses the truncated result to complete the computation.

3–32 058057 Tandem Computers Incorporated

4 Statements

This section contains the syntax of the ENFORM statements. The statements are
arranged in alphabetical order to provide ease of access.

The ENFORM statements, with the exception of the LIST and FIND statement, have a
session-wide affect unless cancelled or overridden. The LIST and FIND statements
effect only the queries of which they are a part.

The AT END, AT START, FOOTING, SUBFOOTING, SUBTITLE, and TITLE
statements apply only to queries containing a LIST statement. These statements
supply information to be printed in a report.

The LIST and FIND statements must be terminated with a semicolon. The other
ENFORM statements should be terminated with a semicolon. ENFORM neither
executes the statement nor reports any syntax errors until it encounters either a
terminating semicolon or the keyword indicating the start of the next statement;
therefore, if you enter a ?SHOW command after a statement without a terminating
semicolon, the effect of the statement is not shown in the output produced by the
?SHOW command.

Table 4-1 shows the ENFORM statements and their functions.

Table 4-1. Summary of Statements

Information Selection

Statement Function
LIST specifies the information selected for a report and prints the report.

FIND specifies the information retrieved from the data base and either writes the

information to a physical file or transmits the information to a host language
program.

Query Environment

Statement Function
CLOSE deletes a user variable, aggregate, or table, a parameter, or a record description

from the internal table.
DECLARE defines a user variable, user aggregate, or user table.
DELINK clears a connecting relationship between record descriptions.
DICTIONARY identifies the subvolume containing a dictionary. It also clears the internal table

and reclaims table space.
EXIT terminates the current ENFORM session.
LINK specifies a connecting relationship between record descriptions.
OPEN accesses a record description.
PARAM names and defines a parameter that can receive a value from a Command

Interpreter PARAM command.
SET initializes a user variable, user table, or a parameter and resets option variables.

058057 Tandem Computers Incorporated 4–1

Statements

Table 4-1. Summary of Statements (continued)

Report Information Formatting

Statement Function
AT END prints information at the end of all subsequent reports in the current session. See

also the AT END PRINT clause in Section 5.
AT START prints information just before the first set of column headings for all subsequent

reports in the current session. See also the AT START PRINT clause in

Section 5.
FOOTING prints a footing at the bottom of each report page for all subsequent reports in the

current session. See also the FOOTING clause in Section 5.
SUBFOOTING prints a subfooting at the bottom of each report page for all subsequent reports in

the current session. See also SUBFOOTING clause in Section 5.
SUBTITLE prints a subtitle at the top of each page immediately following the title for all

subsequent reports in the current session. See also the SUBTITLE clause in

Section 5.
TITLE prints a title at the top of each page for all subsequent reports in the current

session. See also the TITLE clause in Section 5.

4–2 058057 Tandem Computers Incorporated

Statements

AT END Statement

AT END Statement The AT END statement allows you to specify information that is printed at the end of

all subsequent reports in the current session unless cancelled or reset by another AT
END statement or overridden by an AT END clause. (See the AT END PRINT clause
in Section 5.) The syntax of the AT END statement is:

AT END [ PRINT

print-list

[ CENTER ] ] [ ; ]

print-list

can contain any combination of literals, FORM, SKIP, SPACE, or TAB clauses.
Print-list can also contain the following elements that can be modified by AS, AS
DATE or AS TIME clauses: field names, arithmetic expressions, IF/THEN/ELSE
expressions, System Variable clauses, JULIAN-DATE clauses, TIMESTAMP-DATE
clauses, TIMESTAMP-TIME clauses, user tables, user variables, or parameter
names.

The clauses that can appear as part of a print-list are described in Section 5. The
other elements are described in Section 3.

Specifying a Field Name in

an AT END Statement

If you specify a field name within the print-list of an AT END statement, ENFORM
prints the same field value as in the last row of the report. A field name appearing
within the print-list of an AT END statement need not be explicitly included within the
following LIST statements. If the field name is not included, ENFORM in effect adds
the field name with a NOPRINT clause.

Spacing Considerations By default the information you specify in the print-list of an AT END statement begins

printing in the same column position as the leftmost column of the report. Using
either the SPACE or TAB clause as the first element in the print-list overrides the
default. The SPACE or TAB clause can appear anywhere within the print-list. For
example, the SPACE clause in the following AT END statement causes the two literals
to be separated by 15 spaces:

AT END PRINT "Report" SPACE 15 "Total Sales";

Report Total Sales

If you specify either a SKIP clause or the symbol / (slash) within a print-list, ENFORM
advances one or more lines before printing the rest of the AT END print-list. The
number of lines advanced can be affected by one or more of the following: the digit (if
any) following the keyword SKIP, the number of slashes specified, or the option
variable @VSPACE. In the following example, the SKIP clause in the AT END
statement causes ENFORM to print two lines:

AT END PRINT "End of Report for" SKIP "Region " regnum;

End of Report for
Region 1

Using a FORM clause within an AT END statement causes ENFORM to print the
remainder of the AT END print-list on a new page and to increment the page number.

058057 Tandem Computers Incorporated 4–3

Statements

AT END Statement

Using the CENTER clause following the print-list of an AT END statement centers the
information on the page.

The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in
Section 5.

AT END Information for

Current Report or All

Reports

Cancelling Session-Wide

AT END Information

An AT END statement prints information at the end of all subsequent reports in the
current session. The current AT END statement can be reset by specifying a new AT
END statement with a different print-list. Using an AT END PRINT clause temporarily
overrides an AT END statement. An AT END PRINT clause only prints information
for the current report.

You can cancel the AT END statement by:

Using the AT END statement without the print-list parameter.
Using either the DICTIONARY statement or the ?DICTIONARY command (which

removes the AT END statement information from the internal table).

4–4 058057 Tandem Computers Incorporated

Statements

AT START Statement

AT START Statement The AT START statement allows you to specify information that is printed just before

the first set of column headings for all subsequent reports in the current session unless
cancelled or reset by another AT START statement or overridden by an AT START
clause. (See the AT START PRINT clause in Section 5.) The syntax of the AT START
statement is:

AT START [ PRINT

print-list

[ CENTER ] ] [ ; ]

print-list

can contain any combination of literals, FORM, SKIP, SPACE, or TAB clauses.
Print-list can also contain the following elements that can be modified by AS, AS
DATE, AS TIME clauses: field names, arithmetic expressions, IF/THEN/ELSE
clauses, System Variable clauses, JULIAN-DATE clauses, TIMESTAMP-DATE
clauses, TIMESTAMP-TIME clauses, user variables, or parameter names.

Clauses that can be used in a print-list are described in Section 5. The other
elements are described in Section 3.

If you specify both an AT START statement and a TITLE or SUBTITLE statement, the
AT START information is printed after the title or subtitle. The AT START statement
differs from the TITLE statement in that the AT START information is printed only on
the first page of a report while the title or subtitle is printed on every page of a report.

Specifying a Field Name in

an AT START Statement

If you specify a field name within the print-list of an AT START statement, ENFORM
prints the same field value as in the first row of the report. A field name appearing
within the print-list of an AT START statement need not be explicitly included within
the following LIST statements. If the field name is not included, ENFORM effectively
adds it with a NOPRINT clause.

Spacing Considerations By default the AT START information begins printing in the same column position as

the leftmost report column. Using SPACE or TAB clauses as the first element of the
print-list overrides this default. SPACE or TAB clauses can also appear anywhere
within the print-list. In the following example, the SPACE clause causes the two
literals to be separated by 15 spaces:

AT START PRINT "Report" SPACE 15 "Total Sales";

Report Total Sales

058057 Tandem Computers Incorporated 4–5

Statements

AT START Statement

If you specify either a SKIP clause or the symbol / (slash) within a print-list, the printer
advances one or more lines before printing the rest of the AT START print-list. The
number of lines advanced can be affected by one or more of the following: the digit (if
any) following the keyword SKIP, the number of slashes specified, or the option
variable @VSPACE. In the following example, the SKIP clause of the AT START
statement causes two lines to be printed:

AT START PRINT "Report For" SKIP "Region " regnum;

Report For
Region 2

Using the FORM clause within an AT START statement causes the remainder of the
AT START print-list to be printed on a new page and increments the page number.

Using the CENTER clause following the print-list of an AT START statement centers
the information on the page.

AT START Information for

Current Report or All

Reports

Cancelling Session-Wide

AT START Information

The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in
Section 5.

An AT START statement prints information just before the first set of column headings
for all subsequent reports in the current session. The current AT START statement can
be reset by specifying a new AT START statement with a different print-list. Using the
AT START PRINT clause within a LIST statement temporarily overrides the AT
START statement for the report generated by the LIST statement.

You can cancel the AT START statement by:

Using the AT START statement without the print-list parameter.
Using either the DICTIONARY statement or the ?DICTIONARY command (which

clears the AT START information from the internal table).

4–6 058057 Tandem Computers Incorporated

Statements

CLOSE Statement

CLOSE Statement The CLOSE statement allows you to delete a user variable, user aggregate, user table, a

parameter, or a record description from the internal table. The syntax of the CLOSE
statement is:

record-name



user-variable-name

CLOSE

record-name

user-variable-name



user-aggregate-name



user-table-name





param-name

is the name of a dictionary record description previously accessed by an OPEN
statement.





, ... [ ; ]






The Effect of a CLOSE

Statement on the

Internal Table

is the name of a user variable previously defined by a DECLARE statement.

user-aggregate-name

is the name of a user aggregate previously defined by a DECLARE statement.

user-table-name

is the name of a user table previously defined by a DECLARE statement.

param-name

name of a parameter previously defined by a PARAM statement.

As a session progresses, ENFORM maintains an internal table for opened record
descriptions, links of record descriptions, and definitions of user variables, user
aggregates, user tables, and parameters. This internal table grows with each new
OPEN, LINK, DECLARE, or PARAM statement entered.

ENFORM has no way of knowing when a table entry is no longer required for a
subsequent query within the current session. For this reason, ENFORM allows you to
clear unwanted table entries from the internal table with a CLOSE statement. The
CLOSE statement does not reclaim space from the internal table, but it does eliminate
the effect that unwanted entries might have on subsequent queries. Furthermore,
regular use of CLOSE statements reduces the need to qualify fields that are present in
more than one record description.

Closing a dictionary record description also clears all links for that particular record
description.

An alternative to the CLOSE statement is the DICTIONARY statement or
?DICTIONARY command. Both completely clear the ENFORM internal table and
reclaim table space.

058057 Tandem Computers Incorporated 4–7

Statements

DECLARE Statement

DECLARE Statement The DECLARE statement allows you to define a user variable, user aggregate, or user

table. The syntax of the DECLARE statement is:

user-variable-name



DECLARE



user-table-name









user-aggregate-name(formal-argument





=(





step-expression˚

[‚

initialize-constant

"["

max-subscript

[‚[

"]"

)

end-expression

]])








]



[ INTERNAL
[AS

display-format

[ HEADING

internal-format

]

heading-string



]



,... [ ; ]



]





user-aggregate-name, user-variable-name

is the name of the declared element. Names of user-defined elements should
conform to the rules described in Section 3.

" [ "

formal-argument

step-expression

max-subscript

is the number of occurrences for the user table; the maximum number allowed is

64. Max-subscript must be enclosed within brackets [ ]. Refer to Section 3 for a
discussion of subscripts.

is the name used to represent the actual argument of the user aggregate.

is the operation to be performed for each record contributing to the user aggregate.

" ] "

, or

user-table-name

end-expression

is the operation to be performed after all qualifying records for the user aggregate
are processed by the step-expression.

initialize-constant

is the numeric literal that will be the starting value for the user aggregate.

4–8 058057 Tandem Computers Incorporated

Statements

DECLARE Statement

internal-format

is the internal format for storing the user variable, aggregate or table.

display-format

is the default display format for printing the declared item.

heading-string

is a string literal that is the default heading for the declared element. Remember
string literals must be enclosed in quotation marks (“ ”).

Specify the DECLARE statement before you reference a user variable, user aggregate,
or user table. ENFORM stores information about each user-defined element in the
internal table. This information remains in the internal table until you issue a
subsequent CLOSE statement for the user-defined element, issue a DICTIONARY
statement or a ?DICTIONARY command, or end the ENFORM session.

Declaring a User Aggregate User aggregates are processed just like the predefined aggregates. The step-expression

of a user aggregate can contain:

Arithmetic expressions
IF/THEN/ELSE expressions.

The optional end-expression is the final operation to be performed after all of the
qualifying records are processed by the step-expression. The end-expression can contain
any of the following:

Predefined aggregates
Arithmetic expressions
IF/THEN/ELSE expressions.

By default, the starting-value for a user aggregate is zero unless the user aggregate is
defined with alphanumeric internal format. In this case, the default value is blanks.
An initial value is supplied when you specify initialize-constant. If you omit end-
expression but specify initialize-constant, precede initialize-constant with two commas.

The following example uses the DECLARE statement to define a user aggregate:

DECLARE project (x) = ( IF x < 2000 THEN project + x + .05 * x
ELSE project + x + .04 * x ) ;

More information about user aggregates can be found in Section 3.

058057 Tandem Computers Incorporated 4–9

Statements

DECLARE Statement

Declaring a User Variable

or User Table

A user variable or table declaration remains in effect until the end of the current
ENFORM session unless you override the user variable or table by declaring a new
variable or table with the same name.

By default both user variables and elements in user tables are stored as 64-bit signed
integers. To change this default, specify the optional INTERNAL clause described in
Section 5. In the following example, the user variable no-orders is defined. The
INTERNAL clause indicates that no-orders is to be stored as alphanumeric with a
length of 9 bytes:

DECLARE no^orders INTERNAL A9;

The default display format for either a user variable or an element in a user table is a
fourteen character integer. To change this default, specify the optional AS clause. The
display format specified in the AS clause formats the user variable or table element
unless you provide an explicit AS clause in the LIST statement. The AS clause is
described in Section 5.

Specify the HEADING clause to provide a default heading for either a user variable or
a user table. ENFORM uses the default heading for the user variable or table
whenever an explicit HEADING clause is not specified in the LIST statement. The
HEADING clause is described in Section 5. In the following example, the default
display heading “Quarterly Totals” is supplied for the table qtr^totals:

DECLARE qtr^totals [4] HEADING "Quarterly Totals";

Initialize both user variables and user tables by using the SET statement discussed
later in this section.

Section 3 provides more information about user variables and user tables.

4–10 058057 Tandem Computers Incorporated

DELINK Statement

DELINK Statement The DELINK statement allows you to clear a connecting relationship between

dictionary record descriptions. The syntax of the DELINK statement is:

Statements

record-name1



DELINK

record-name1

field-name

qualified-field-name1

Both forms of the DELINK statement are equivalent. The field names must be
specified in the DELINK statement in the same order as the corresponding LINK
statement. For example, if the LINK statement is:

the corresponding DELINK statement can be:







are the names of dictionary record descriptions.

is the name of a field common to both of the record descriptions.

are the names of fields uniquely identified as components of record-name1 and
record-name2 respectively.

LINK parts TO odetail VIA partnum;

record-name2

qualified-field-name1

qualified-field-name2

or

record-name2

[ TO [OPTIONAL] ]

VIA

field-name

[ TO [ OPTIONAL ] ]

or

qualified-field-name2





, ... [;]






DELINK parts.partnum TO odetail.partnum;

ENFORM stores all links of record descriptions in the current ENFORM internal table.
All links apply to all subsequent LIST or FIND statements of the current ENFORM
session until you issue a DELINK, CLOSE, DICTIONARY statement, or
?DICTIONARY command. Since unnecessary links can produce undesirable results,
delete relationships which do not apply to the current query from the internal table.
Use a DELINK statement to clear a a linking relationship between two record
descriptions without affecting other links.

If you want to clear all links, use a CLOSE statement, a DICTIONARY statement, or a
?DICTIONARY command. A CLOSE statement for a record description deletes all
links referencing that record description from the internal table. A DICTIONARY
statement or ?DICTIONARY command clears the entire internal table.

058057 Tandem Computers Incorporated 4–11

Statements

DICTIONARY Statement

DICTIONARY

Statement

Identifying the Location of

the Dictionary

The DICTIONARY statement allows you to identify the subvolume containing your
dictionary. It also allows you to clear the internal table. The DICTIONARY statement
has the same effect as the ?DICTIONARY command. The syntax of the DICTIONARY
statement is:

DICTIONARY [

dict-subvol-name

]

dict-subvol-name

is the name of the subvolume where your dictionary files reside. Refer to the
GUARDIAN Operating System Programmer’s Guide for information on specifying
Tandem file names.

The dictionary identified in a DICTIONARY statement must be created by the Data
Definition Language compiler. ENFORM issues an error message if you attempt to
use a dictionary compiled with a version of DDL that is not current. You must then
recompile the dictionary with a current version. Refer to the Data Definition Language
(DDL) Reference Manual for more information about creating and compiling a
dictionary.

You can identify the location of the dictionary by:

Specifying the volume and subvolume where the dictionary resides as a part of the
Command Interpreter ENFORM command. If you do not specify a volume and
subvolume, ENFORM assumes the dictionary resides on your default volume and
subvolume.

Specifying either the DICTIONARY statement or ?DICTIONARY command to
identify where the dictionary resides. Use of either the DICTIONARY statement
or the ?DICTIONARY command overrides the dictionary identified at the time of
the Command Interpreter ENFORM command. When a new dictionary is
specified, the internal table associated with the old dictionary is cleared.

In the following example, the DICTIONARY statement is used to identify the volume
that the dictionary resides on as $data and the subvolume as database:

DICTIONARY $data.database;

4–12 058057 Tandem Computers Incorporated

Statements

DICTIONARY Statement

Clearing the Internal Table Entering the DICTIONARY statement without a volume and subvolume name is a

simple means of clearing the entire internal table and reclaiming table space without
changing the dictionary. To clear only certain elements of the internal table, refer to
the CLOSE and DELINK statements in this section. The elements cleared by the
DICTIONARY statement are:

All dictionary record descriptions from previous OPEN statements.
All previous links.
All user variable, user aggregate, and user table definitions.
All parameter definitions.
All information from AT END, AT START, FOOTING, SUBFOOTING, SUBTITLE,

and TITLE statements.

The DICTIONARY statement does not change the value set for any option variable
(such as: @HEADING or @STATS).

058057 Tandem Computers Incorporated 4–13

Statements

EXIT Statement

EXIT Statement The EXIT statement terminates the current ENFORM session. The syntax of the EXIT

statement is:

EXIT [ ; ]

The EXIT statement returns control to the invoking process, usually the Command
Interpreter. The EXIT statement is the same as the ?EXIT command. Pressing the
CTRL and Y terminal keys simultaneously is an alternate way to exit ENFORM.

4–14 058057 Tandem Computers Incorporated

Statements

FIND Statement

FIND Statement The FIND statement allows you to specify the input fields and records that contribute

to the target-record and either write output records to a physical file or transmit
output records to a host language program. The FIND statement must end with a
semicolon. The syntax of the FIND statement is:

FIND [ UNIQUE ]



(

[ WHERE

UNIQUE

output-record-name

output-field-name



[






logical-expression

is an option that prevents duplicate output records. UNIQUE adds processing
overhead and should be avoided unless you know unwanted duplicate records
exist.

is the name of the dictionary record description of the output record.

is the name of a field in the dictionary record description of the output record.
ENFORM allows you to qualify output-field-name. If you do not qualify output-
field-name, ENFORM qualifies output-field-name with output-record-name. In either
case, output-field-name must be sufficiently qualified to avoid ambiguity between it
and any other name specified in the query.

output-record-name

output-field-name

:= ]

] ;

BY

by-item



BY DESC



target-item



ASCD





DESC

by-item

target-item
target-item













,... )






by-item

is an input field name. An input field name must be sufficiently qualified to avoid
ambiguity between it and any other name specified in the query. You cannot
specify more than 63 by-items for your query.

058057 Tandem Computers Incorporated 4–15

Statements

FIND Statement

target-item

is an input field. Valid values for an input field are: a field name, a string literal
enclosed in parentheses, a predefined aggregate, a user aggregate, an arithmetic
expression, an IF/THEN/ELSE expression, a user table name, a user variable, or a
System Variable. An input field name must be sufficiently qualified to avoid
ambiguity between it and any other name specified in the query.

logical-expression

is an expression returning a true or false value.

Output Record Dictionary

Description

Before the FIND statement executes, you must include a description of the output
record in the dictionary. When the FIND statement executes, ENFORM either writes
the output records to the physical file specified in the dictionary or transmits the
output records to a host language program. In either case, the Data Definition
Language (DDL) record description must describe the file type as unstructured.

The following example shows the DDL source code used to produce a dictionary
record description for the output record findfil:

RECORD findfil.
02 custname PIC X(18).
02 custnum PIC 9(4).
02 partcost PIC 9(6)V99.
end

ENFORM allows you to specify data base tables (see the description of subscripts in
Section 3 for information about data base tables) in the record description of the output
record. The following record description contains a data base table named child:

RECORD newemp.
02 name PIC X(18).
02 child PIC X(18) OCCURS 4 times.
end

You can specify that the output records are to be written to a particular physical file
either by including the DDL FILE IS clause in the dictionary record description or by
specifying the ?ASSIGN command. You can also use the ?ASSIGN command to tell
ENFORM to write the records to a file different from the one described in the
dictionary. The physical file generated by a FIND statement is always an unstructured
file.

In the record description, an output field can differ in data format (picture size, scale,
BINARY vs. ASCII numeric string, ...) from the description of the input field as long as
the output field has the same data type (numeric or alphanumeric ) as the input field.
ENFORM performs the data format conversion automatically, including: truncation or
padding with blanks for alphanumeric input and output fields of different lengths,
binary to ASCII string conversion (or vice versa), and scaling conversion for numeric
input and output fields.

4–16 058057 Tandem Computers Incorporated

Statements

FIND Statement

Group Definition and

Sorting

The BY and BY DESC clauses group and sort records. The appearance of a BY or BY
DESC clause in a FIND statement causes every occurrence of a grouped by-item value
to be written to the output record (unlike the LIST statement where only the first
occurrence of a grouped value is written to the output record). The BY and BY DESC
clauses are described in Section 5.

The ASCD and DESC clauses sort records in ascending or descending order. They do
not identify a group. The ASCD and DESC clauses are also described in Section 5.

When a FIND statement contains more than one BY, BY DESC, ASCD, or DESC clause,
ENFORM determines a major to minor sort precedence by the order in which the BY,
BY DESC, ASCD, or DESC clauses appear in the FIND statement. The first clause has
highest priority and is sorted first, the next one second priority, down to the last
clause.

Output Fields When the FIND statement executes, ENFORM takes the values from the input

elements and stores them in the output field. Values are stored in the output field by
name (when the output field has the same name as an input field) or by assignment
syntax (:=). ENFORM allows you to qualify output-field-name.

ENFORM allows you to use subscripted output field names in a FIND statement when
the record description of the output record contains a data base table; however, a
subscript range is not valid anywhere in a FIND statement. (Refer to the discussion of
subscripts in Section 3 for the syntax used to include subscripts.) For example, the
following FIND statement is valid:

FIND newemp (name := emp.name,
child [ 1 ] := emp.child1,
child [ 2 ] := emp.child2,
child [ 3 ] := " ",
child [ 4 ] := " " );

The following rules apply to output-field-name:

1. Output-field-name can be qualified or subscripted.

2. Output-field-name cannot contain a subscript range.

058057 Tandem Computers Incorporated 4–17

Statements

FIND Statement

3. If you omit output-field-name, ENFORM assumes that it is the same as the input

field name (including any subscripts or qualifications that apply to the input field
name). Consider, for example, the following record descriptions and FIND
statements:

RECORD OLD. RECORD new.
FILE IS old KEY-SEQUENCED. FILE IS new UNSTRUCTURED.
02 A PIC XX. 02 A PIC XX.
02 B PIC 99. 02 B PIC 99.
02 C OCCURS 2 times 02 D1 PIC AA.
04 DD PIC AA. 02 D2 PIC AA.
04 EE PIC XX. 02 E1 PIC XX.
KEY 0 IS A. 02 E2 PIC XX.
END END

OPEN old, new;
FIND new ( A, B, C);

The preceding FIND statement omits the output-field-names. Therefore, ENFORM
assumes that the name of the output fields are new.A, new.B, and new.C. Since
the new record description does not contain a field named C, the query fails and
ENFORM issues an error message.

4. Output-field-name can be a group name; however, ENFORM might not store the

fields within the group in the manner you expect. To understand the way that
ENFORM stores group elements, you must first understand what a group is. A
group is defined in DDL as any field whose level number (03, 04, ...) is less than
that of the next field in the record. Consider, for example, the following DDL
record description:

RECORD findfl.
FILE IS $mkt.sample.findfl key-sequenced.
02 account-num.
05 type PIC 9(4).
05 num PIC BINARY 16.
02 custnum PIC 9(4).

Within this record, account-num is a group. The data type of a group is always
alphanumeric. When a group name is specified as output-field-name within a FIND
statement, ENFORM stores each element within the group as alphanumeric data. If
one of the fields within the group is defined as binary, using a group name as output-
field-name results in an output record that might contain undesirable data. (The
undesirable results occur because the binary representation of some numbers does not
correspond to the ASCII representation of these same numbers.)

Before the FIND statement executes, the dictionary must include a record description
that defines the structure of the input record. This record description also defines the
file type (key-sequenced, relative, entry-sequenced, or unstructured) of any data file
that can be associated with the record description. The actual file type of the data file
must be the same as the file type specified in the record description; otherwise, your
query might return incorrect results.

4–18 058057 Tandem Computers Incorporated

FIND Statement

Input Elements The output fields receive values from any combination of the following input

elements:

The value of a field from the input record. The assignment to an output-field-name
is optional. When you do not specify the output-field-name, ENFORM assumes it is
the same as the field name from the input record. When the output-field-name is
omitted, the input field name must be fully qualified.

FIND ...
( parts.partnum,
...) ;

The value of a numeric literal. Remember to enclose numeric literals within
parentheses.

FIND ...
(region := (5),
... );

Statements

The value of a string literal. A string literal must be enclosed in parentheses.

FIND ...
( jobtitle := ("manager"),
... ) ;

The value of an arithmetic expression. Enclose an arithmetic expression within
parentheses. Use any combination of numeric fields, numeric literals, numeric
user variables, predefined aggregates, or user aggregates for the arithmetic
expression.

FIND ...
( sales := (price * quantity),
... ) ;

The value of an IF/THEN/ELSE expression. Enclose the IF/THEN/ELSE
expression within parentheses.

FIND ...
(stock := (IF inventory GT 100 THEN inventory
ELSE ZERO),
...);

The value of a user variable. Define the user variable by a DECLARE statement
before referencing it in a FIND statement. The SET statement should be used to
initialize the user variable. If the user variable is not initialized, the value is zero.

058057 Tandem Computers Incorporated 4–19

DECLARE region;
SET region TO 5;
FIND ...
( reg := region,
... ) ;

Statements

FIND Statement

The value of either a user aggregate or a predefined aggregate.

FIND ...
( BY employee.job,
employee.salary,
rate := AVG (salary OVER job),
... ) ;

A group name. ENFORM allows you to specify a group name as an input
element. Avoid this specification, however, unless the data type of the fields
receiving the data is exactly the same as the data type of the input group.

Although ENFORM allows you to specify an output field name as an input element,
this specification is not recommended and might lead to unexpected results.

The following rules apply to input elements:

1. An input element can be qualified or subscripted.

2. An input element cannot contain a subscript range.

3. An input element must be sufficiently qualified to avoid any ambiguity between it

and any other element specified in the query.

Request-Qualification Use the WHERE clause to limit the records written to the physical output file or

transmitted to the host language program. The WHERE clause is described in
Section 5.

Summary Records A FIND statement can be specified that either creates a new file containing only

summary records or transmits only summary records to a host language program.
Such summary records contain only the first target-record from each group (created by
a BY or BY DESC clause) down to some level. Summary records can only be generated
by a query that contains an aggregate.

The two methods of obtaining summary records are:

Explicitly request summary records by setting the @SUMMARY-ONLY option
variable to ON before issuing the FIND statement.

Implicitly request summary records by specifying only by-items and aggregates
over by-items in the query.

4–20 058057 Tandem Computers Incorporated

Statements

FIND Statement

When you explicitly request summary records you get target-records summarized
down to the lowest level where an aggregate is calculated over that level. For
example:

SET @SUMMARY-ONLY TO ON;
FIND findfil
( BY employee.dept,
BY employee.job,
BY employee.empname,
employee.salary,
COUNT(employee.empname OVER employee.job);

returns one target-record for each job in each department. Only the first employee
name (empname) for each job is returned.

When you implicitly request summary records, you get target-records summarized
down to the lowest level where an aggregate is computed over that level. (A query
requesting only by-items and aggregates over ALL is not an implicit request for
summary records). For example:

SET @SUMMARY-ONLY TO OFF;
FIND findfil
(BY employee.dept,
BY employee.job,
BY employee.empname,
numemp:= COUNT (employee.empname OVER employee.job));

returns one target-record for each job in each department. Only the first employee
name (empname) for each job is returned.

If you want summary records that consist of only by-items and aggregates to include
those where the last value of a by-item has not changed but a subordinate by-item
value has changed, then you must include a target-item in the target-list that has not
appeared as a by-item or aggregate. Of course, you must also set @SUMMARY-ONLY
to OFF. For example:

SET @SUMMARY-ONLY TO OFF;
FIND findfil2
(BY employee.dept,
BY employee.job,
BY employee.empname,
employee.salary,
numemp:= COUNT (empname OVER job));

058057 Tandem Computers Incorporated 4–21

Statements

FIND Statement

Statements and Clauses

That Do Not Apply to the

FIND Statement

ENFORM queries with a FIND statement produce records only. There are no report
features such as headings, titles, summary information, and special formatting. The
following statements and clauses apply only to queries using the LIST statement and
cannot be used with the FIND statement.

AFTER CHANGE clause
AS clause
AS DATE clause
AS TIME clause
AT END statement and AT END PRINT clause
AT START statement and AT START PRINT clause
BEFORE CHANGE clause
CENTER clause
CUM clause
FOOTING statement and clause
FORM clause
HEADING clause
NOHEAD clause
NOPRINT clause
PCT clause
SKIP clause
SPACE clause
SUBFOOTING statement and clause
SUBTITLE statement and clause
SUBTOTAL clause
System Variable clauses
TAB clause
TITLE statement and clause
TOTAL clause

4–22 058057 Tandem Computers Incorporated

Statements

FOOTING Statement

FOOTING Statement The FOOTING statement allows you to specify a footing to be printed at the bottom of

each report page for all reports in the current session unless overridden or reset by
another FOOTING statement or temporarily overridden by a FOOTING clause. (See
Section 5 for the FOOTING clause.) The syntax of the FOOTING statement is:

FOOTING [

print-list

[ CENTER ] ] [ ; ]

print-list

can be any combination of literals, FORM, SKIP, SPACE or TAB clauses. Print-list
can also contain the following elements that can be modified by AS, AS DATE, or
AS TIME clauses: field names, arithmetic expressions, IF/THEN/ELSE
expressions, System Variable clauses, JULIAN-DATE clauses, TIMESTAMP-DATE
clauses, TIMESTAMP-TIME clauses, user variables, or parameter names.

The clauses that can be part of a print-list are discussed in Section 5. The other
elements are discussed in Section 3.

Specifying A Field Name

within a FOOTING

Statement

If you specify a field name within the print-list of a FOOTING statement, ENFORM
prints the same field value as in the last row of data on the current page. A field name
appearing within the FOOTING statement need not be explicitly included within the
following LIST statements. If the field name is not included, ENFORM effectively
adds it to the LIST statement with a NOPRINT clause.

Spacing Considerations By default, the footing begins printing in the same column position as the leftmost

report column. Using SPACE or TAB clauses as the first element of the print-list
overrides this default. SPACE or TAB clauses can also appear anywhere within the
print-list. In the following example, the SPACE clause causes the two literals to be
separated by 15 spaces:

FOOTING "Inventory" SPACE 15 "Parts in Stock";

The following footing appears at the bottom of the next report that is generated
without a LIST statement FOOTING clause.

Inventory Parts in Stock

If you specify either a SKIP clause or the symbol slash (/) within a print-list, ENFORM
advances one or more lines before printing the rest of the FOOTING print-list. The
number of lines advanced can be affected by one or more of the following: the digit (if
any) following the keyword SKIP, the number of slashes specified, or the option
variable @VSPACE. In the following example, the SKIP clause in the FOOTING
statement causes two lines to be printed:

FOOTING "Report 2-A" SKIP "Total Sales";

The following footing appears at the bottom of the next report that is generated
without a LIST statement FOOTING clause.

Report 2-A
Total Sales

058057 Tandem Computers Incorporated 4–23

Statements

FOOTING Statement

Using a FORM clause within a FOOTING statement forces a new page. ENFORM
continues with the remainder of the FOOTING print-list. The page number remains
the same. A single logical page can span multiple physical pages such that a TITLE
can appear on one page, the data on the next, and a FOOTING on the next. The same
page number applies to all physical pages in a logical page.

Using the CENTER clause within the FOOTING statement centers the footing on the
page.

The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in
Section 5.

Footing for Current Report

or All Reports

Cancelling Session-Wide

Footing

A FOOTING statement prints a footing at the bottom of each page for all subsequent
reports in the current session. Specifying a new FOOTING statement with a different
print-list resets the current FOOTING statement. Using the FOOTING clause within a
LIST statement temporarily overrides the FOOTING statement. A FOOTING clause
within a LIST statement prints a footing only for the current report.

You can cancel the FOOTING statement by:

Using a FOOTING statement without the print-list parameter.
Using either a DICTIONARY statement or a ?DICTIONARY command (which

clears the FOOTING information from the internal table).

4–24 058057 Tandem Computers Incorporated

LINK Statement

LINK Statement The LINK statement allows you to specify a connecting relationship between

dictionary record descriptions. The syntax of the LINK statement is:

Statements

record-name1



VIA



LINK



qualified-field-name1





record-name1

are the names of dictionary record descriptions containing a common field.

field-name

is the name of a field common to both of the record descriptions.

qualified-field-name1

are the names of fields uniquely identified as components of the record
descriptions being linked.

OPTIONAL

indicates that ENFORM is to build logical records for the link by including all of
the records from the data file whose record description is specified on the left side
of the LINK OPTIONAL statement. ENFORM includes each record from this data
file even when no matching record is found in the data file whose record
description is specified on the right side of the LINK OPTIONAL statement.

field-name

qualified-field-name2

and

[ TO ] [ OPTIONAL ]

[ TO ] [ OPTIONAL ]

record-name2

and

qualified-field-name2

record-name2





,...[ ; ]






Both the LINK statement and the LINK OPTIONAL statement establish a connecting
relationship, called a link. (You can also establish a link with a WHERE clause.) A
link allows you to view your data in a new manner. When you specify either
statement, ENFORM establishes a new logical record description that consists of fields
from both linked record descriptions. ENFORM then builds a set of logical records for
the new logical record description.

ENFORM builds the set of logical records by selecting records from each of the data
files associated with the linked record descriptions. When you use either statement,
you must identify a field (called a linking field) from each record description.
ENFORM uses the data value of these linking fields to determine which records from
each data file become part of the set of logical records. ENFORM then uses the set of
logical records to build the target records from which your ENFORM output is
produced. If you include a non-linking WHERE clause (refer to Section 5 for a
definition of non-linking WHERE clauses) in a query, such as:

WHERE empnum GT 100

the target records include information only from those logical records that satisfy the
restriction specified in the WHERE clause.

058057 Tandem Computers Incorporated 4–25

Statements

LINK Statement

Duration of Link

Established by LINK or

LINK OPTIONAL Statement

LINK Statement

Considerations

When you use either the LINK statement or the LINK OPTIONAL statement, you
establish a link that exists for the duration of the ENFORM session. You can clear such
a link by entering one of the following:

a CLOSE statement for one of the record descriptions.
a DELINK statement for the link.
a DICTIONARY statement or a ?DICTIONARY command that clears the entire

internal table. When you clear the internal table, you also clear all links.

ENFORM allows you to specify up to 32 LINK or LINK OPTIONAL statements. If
you include the LINK OPTIONAL statement in your query specifications, be sure to
follow the rules described later in this section under “LINK OPTIONAL Statement
Considerations.”

When you use a single LINK statement, ENFORM builds a set of logical records by
searching through the data files associated with the linked record descriptions. A
record from one data file becomes part of the set of logical records only if the content
of its linking field matches the content of the linking field in a record in the other data
file.

When you use a LINK statement, you indicate that the values of the linking fields
must be equal. (If you want to indicate inequality for the values of the linking fields,
you must use a WHERE clause.) A single LINK statement is equivalent to the
following form of the WHERE clause:

WHERE qualified-field-name1 EQ qualified-field-name2,

When you use a LINK statement, the order in which you enter the record description
names is unimportant. For example:

LINK employee.empnum TO branch.manager;

is the same as:

LINK branch.manager TO employee.empnum;

4–26 058057 Tandem Computers Incorporated

Statements

LINK Statement

LINK OPTIONAL Statement

Considerations

When you establish a link by specifying the LINK OPTIONAL statement, you preserve
all of the information from the data file whose record description is specified on the
left side of the statement. You preserve this information because ENFORM builds the
logical records for such a link in a different manner than it does for a link established
by a LINK statement. For example, suppose that you entered the following LINK
OPTIONAL statement:

LINK employee TO OPTIONAL branch VIA branchnum;

This statement causes ENFORM to build:

A logical record description that consists of fields from both employee and branch.
One logical record for each matching employee and branch record. (Each logical

record contains field values from both records.)
One logical record for each employee record for which there is not a corresponding

branch record. ENFORM builds this logical record by supplying blanks for the
fields in the logical record that correspond to the branch record description.

Because of the way that ENFORM builds the logical records for this type of link, the
order in which you enter the record description names is important. For example:

LINK employee TO OPTIONAL branch VIA branchnum;

is not the same as:

LINK branch TO OPTIONAL employee VIA branchnum;

The first LINK OPTIONAL statement preserves the information in the employee
records; the second preserves the information in the branch records.

Note If you specify a LINK OPTIONAL statement for record descriptions that are associated with data files

containing variable length records, the linking field must be present in all of the records from both data
files. If the linking field is not present, a sort operation might fail.

Rules for Using LINK OPTIONAL Statements

When you include LINK OPTIONAL statements in your query specifications,
ENFORM requires you to adhere to certain rules for all of the links that affect your
query. These rules exist to eliminate the possibility of ambiguous links and to
eliminate links that are not supported by the current query processor.

058057 Tandem Computers Incorporated 4–27

Statements

LINK Statement

ENFORM uses these rules to determine whether your query specifications contain
legal links. (Unless otherwise stated, the word link applies to a link established by a
WHERE clause, a LINK statement, or a LINK OPTIONAL statement.) These rules are:

1. A record description on the right side of a LINK OPTIONAL statement must not

be linked back to the record description on the left side of the same LINK
OPTIONAL statement.

2. A given record description must not appear on the right side of more than one

LINK OPTIONAL statement. A record description appears on the right side of
more than one LINK OPTIONAL statement when you:

specify the same record description on the right side of two or more LINK
OPTIONAL statements.

specify a link (either with a LINK statement or a WHERE clause) between two
record descriptions, both of which appear on the right side of a LINK
OPTIONAL statement.

Note When checking your query for violations of these rules, ENFORM ignores any links (initiated by either a

LINK statement or a WHERE clause) that reference the same record descriptions as referenced in a LINK
OPTIONAL statement. In effect, ENFORM “cancels” any other link between the record descriptions when
determining the legality of the links. ENFORM ignores these links only when checking for violations of the
LINK OPTIONAL rules. After ENFORM determines that all the links in your query are legal, ENFORM
uses each LINK statement and WHERE clause to evaluate your query.

Refer to Appendix C for more detailed information about links and the LINK
OPTIONAL statement.

How ENFORM Handles “Non-Contributing” Record Descriptions

When your query specifications include LINK OPTIONAL statements, ENFORM
produces target records from the logical records built for the link in a normal manner
with certain exceptions. These exceptions involve “non-contributing” record
descriptions. For a given logical record, a record description is “non-contributing” if
the logical record does not contain any data values from the data file associated with
the record description. For example, consider the following query specifications:

OPEN employee, branch;
LINK employee TO OPTIONAL branch VIA branchnum;
LIST empname, branchname;

Each logical record built for the preceding query will contain data values from the
employee records; therefore, the employee record description is said to “contribute” to
each logical record. However, some of the logical records might not contain data
values from the branch records. For these logical records, the branch record description
is said to be “non-contributing.”

4–28 058057 Tandem Computers Incorporated

Statements

LINK Statement

Any record description that is linked to a “non-contributing” record description is also
“non-contributing.” For example, consider the following query specifications:

OPEN employee, region, order;
LINK order.salesman TO OPTIONAL employee.empnum;
LIST ordernum, empname, regname
WHERE employee.regnum = region.regnum;

If the employee record description is “non-contributing” for a given logical record, the
region record description is also “non-contributing” for that logical record.

ENFORM handles “non-contributing” records as follows:

1. If your query specifications contain a WHERE clause, ENFORM evaluates each

logical record to determine whether it satisfies the terms of the WHERE clause.

For a given logical record, ENFORM ignores any term in a WHERE clause that references
a “non-contributing” record description. If several record descriptions are “non-

contributing” for a given logical record, ENFORM ignores all terms in the WHERE
clause that reference the “non-contributing” record descriptions. If all of the record
descriptions referenced in the WHERE clause contribute to the logical record,
ENFORM uses all the terms in the WHERE clause.

2. For a given logical record, ENFORM supplies null values for any fields that

correspond to a “non-contributing” record description. If your query
specifications include expressions or aggregates that reference these null field
values, ENFORM computes the expression or aggregate value by using blank
values. In some cases, this use of blanks might cause undesirable results. For
example:

If you specify that the aggregates COUNT, MAX, or MIN (or a similar user
aggregate) are to be performed for a field containing null values, ENFORM
will count or compare the null values just like any other value.

If you specify that the aggregates SUM or AVG (or a similar user aggregate)
are to be performed for a binary numeric field containing null values,
ENFORM will include the null values as ASCII blanks in the resulting
computations.

If you include the UNIQUE specification with an aggregate, the null value will
be considered a UNIQUE value. (This will occur if null values are not stored in
the field for which the aggregate is being computed.)

If a binary numeric field that contains null values is included in an arithmetic
expression, ENFORM will include the null values as ASCII blanks in the
specified computations. Because null values correspond to a very large binary
number, this could result in a very large, and probably, meaningless, result.

058057 Tandem Computers Incorporated 4–29