Tandem-EnFORM Reference Manual
Tandem-EnFORM Reference Manual
April 1983
Part No. 82348 BOO Printed in U.S.A.
October 1982 Manual released.
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.
INFOSAT is a trademark in which both Tandem and American Satellite have rights.
iii
- - - - - _ . -_...._ .._ _--_ _
.... .. .... -
CONTENTS
PREFACE ........................................................................... xi
v
Contents
vi
--------------------------------------------------------------------------------------------
Contents
vii
Contents
viii
---------------------------------------------------------------------------------------
Contents
ix
Contents
FIGURES
TABLES
------------- ._--------
PREFACE
This manual is one of three volumes that describe the ENFORM language. This manual, which con-
cerns syntax only, should be used as a reference by experienced EN FORM users. For other infor-
mation about ENFORM and related products, refer to the publications listed in alphabetical order
below.
xi
SYNTAX CONVENTIONS IN THIS MANUAL
This table describes the characters and symbols used in this manual's syntax notation. For distinc-
tion, syntactical elements appear in a typeface different from that of ordinary text.
Notation Meaning
UPPERCASE All keywords and reserved words appear in capital letters. If a keyword can be
LETTERS abbreviated, the part that can be omitted is enclosed in brackets.
lowercase All variable entries supplied by the user are shown in lower-case characters.
letters
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.
Ellipsis When an ellipsis C.. ) 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.
xiii
SECTION 1
INTRODUCTION
• The syntax of the Command Interpreter ENFORM command needed to call the ENFORM pro-
cess, 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 com-
mand or the EN FORM ?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 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 infor-
mation and for information about using the ENFORM language elements, refer to Introduction to
ENFORM or to the ENFORM Users Guide.
The examples in this manual use the data base described in the ENFORM Users 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.
1-1
Introduction
r-------------------------
f
~?
:'1
~l
II~'-;J
)~
,I
1''::'::1'' :1
,
r--------------------------~
I
>?DICTIONARY $mkt.sample ., Command
I
> LIST BY empnum,
I ----- By-item
' - - - - - - - - - - - -...
.,.. Clause T~~~t-
empname,salary,
Statement
---------1.,..... Target-items
L..I
Query
- ______ Request-Qualification
L_- _ _ _ _ _ _ _ _ -_ _ _ _ _ _ -_ _ _ _ _ _ _ _ _ _.J
Report
,;::::~
I I
Taooet- I
I Records I
\ .... _ _ ... 1
L __
""--------------------------,--
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.
Targe t-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.
By-items - field names modified by the BY or BY DESC clauses described ltn Section 5. The
values of the fields are used to sort and group the query output.
1-2
Introduction
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) Reference 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 func-
tions 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 pro-
duced. The query processor returns the target-records to the compiler/report writer if the EN FORM
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.
1-3
SECTION 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:
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.
2-1
Running ENFORM
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 messaglB 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 Users 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.
INTERACTIVE MODE
EN FORM 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. Com-
mands and statements are entered indirectly when you use either the ?RUN or ?SOURCE com-
mands to supply the ENFORM source code.
When you enter commands and statements directly, the Command Interpreter FC command pro-
vides you with the ability to edit or repeat a line. Refer to the GUARDIAN Operating System Com-
mand Language and Utilities Manua~ 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.
EN FORM 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 lIN input-fiLename, OUT output-fiLenamel
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 P ARAM command of the Command Interpreter prior to
the ENFORM command. More information about passing parameters to compiled ENFORM queries
is available later in this section.
2-2
Running EN FORM
The current output listing file is the file to which EN FORM 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.
EN FORM 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.
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.
• 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.
• Pressing the terminal BREAK key when commands or statements are being entered (either
directly or indirectly), returns the terminal to the Command Interpreter prompt (:).
2-3
Running ENFORM
'. Pressing the terminal BREAK key when you have entered the EDIT process from the
EN FORM 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.
ENFORM allows logical file assignments to be made either before or after the Command Inter··
preter ENFORM command is entered. When the logical file assignment is made from within the
ENFORM subsystem, use the EN FORM ?ASSIGN command described in Section 6. When the
logical file assignment is made before the ENFORM command is entered, use the Command Inter-
preter ASSIGN command to either associate a physical file with a dictionary record description or
to assign some form of EN FORM output to a generic file.
When ENFORM is used in noninteractive mode, the Command Interpreter ASSIGN command over-
rides an EN FORM ?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.
where
record-name
generic-fiLe-name
physicaL-fiLename
is a fully qualified Tandem file name. Refer to the GUARDIAN Operating System
Programming Manual for the exact form of a Tandem file name.
excLusion-mode
Refer to the GUARDIAN Operating System Programming Manual for more information about the
ASSIGN command.
2-4
,----------------------------------------------------------------------------------
Running ENFORM
ENFORM allows you to pass parameters to a compiled query file. The compiled query file must con-
tain 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:
where
parameter-name
parameter-value
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.
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 Command Language and Utilities 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 NonStop,
handling queries from one compiler/report writer process at a time.
A host language program (described in the ENFORM Users Guide) can also use a server query
processor.
2-5
Running ENFORM
Figure 2-1. Server Query Processor With Several Compiler/Report Writer Processes
:~NFORM server query processors are created by a system manager, using the Command Inter-
preter ASSIGN and PARAM commands followed by the Command Interpreter ~~P command.
2-6
------,-----------------------,--,-----,_._---,-,-----,
Running ENFORM
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:
where
Fnumber
specifies the logical file name. Legal values for logical file names range from Fl through
F31.
generic-file-name
physical-filename
is a fully qualified Tandem file name. Refer to the GUARDIAN Operating System Pro-
gramming Manual for the exact form of a Tandem file name.
exclusion-mode
2-7
Running ENFORM
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.
where
REQUESTORS max-requestors
sets the maximum number of requestors a query processor can accept. A requestor can
be any EN FORM application or a host language program. (Host language programs are
described in the ENFORM Users Guide).
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 Sec-
tion 5 for an explanation of strategy cost limits.
Max-cost must be an integer between one and eight. The default is no limit.
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 sessilon. If that many
reads are performed, the ENFORM session is terminated and an error message is
displayed.
CPU number
is an integer value that sets the number of the CPU where a server query processor
resides.
2-8
-----------------------------------------,--------------------,-------------------------------
Running ENFORM
After the parameters are initialized and the physical files to be kept open are specified, the server
query processor is created. The syntax is:
where:
NAME process-name
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. A CPU number specified in the QP
command overrides a CPU number specified in the PARAM command.
PRI priority
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.
Issue the following instructions to create a server query processor named $qpl that keeps open
parts, order, and odetail, accepts up to 15 requestors, sets a limit of 2 on the cost strategy, and waits
idle up to 3 minutes before stopping.
2-9
Running ENFORM
GENERIC FILES
A generic file is a file that is used to store some form of ENFORM output. ENFOHM 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. EN FORM 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.
QU ERY -STATUS-M ESSAG ES All compiler/report writer error and warning messages pro-
duced during an ENFORM session. All error messages pro-
duced during an ENFORM session by the query processor or
SORT while processing a FIND or LIST statement. These
messages also appear in the listings.
2-10
Running ENFORM
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.
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.
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.
2-11
Running EN FORM
lBy 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 EN FORM 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.
• 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 l:isting 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.
2-12
Running ENFORM
Error messages from the The QUERY·QPSTATUS·MESSAGES file if assigned, and to the
Query processor or SORT QUERY·STATUS·MESSAGES file if assigned, and in
addition to the following:
1) QUERY·COMPILER·LlSTING if assigned, otherwise
2) to the default output fi Ie.
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-13
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -. . .- -. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .I
SECTION 3
An ENFORM query is built with elements of the EN FORM language. This section contains:
• An explanation of the ENFORM language elements that are used throughout query specifica-
tions. 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 Sec-
tion 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.
3-1
EN FORM Language Elements
-------_._----------"._----_._-_._------------
~--------------------------
String Literal
L...- - - - - - - - - - - - - - - -. . . . . . . . . . .
.. Keywords
~------------------------... Keyword
LIST empnum,empname,salary,
-
TL.._ _ _ _ _ _ _ _ _ _ _ _ _ _._ _ _ _........... Field Names
I.
~--------------------......
--------1...... SpeCial Character
User Variable
1..---------..... Aggregate
3-2
ENFORM Language Elements
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
Users Guide for instructions on redefining the ENFORM reserved words. Table 3-1 shows the
ENFORM reserved words.
Keywords are reserved words that indicate the beginning of statements or clauses to the ENFORM
compiler.
3-3
}t~NFORM Language Elements
SPECIAL CHARACTERS
Table 3-2 shows the EN FORM special characters and describes their functions within a query.
COMMENTS
A comment clarifies and documents the purpose of the your query. A comment is denoted by the
exclamation character (D. 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:
STATEMENTS
Statements contain specifications for selecting and formatting elements from your data base. Com-
posed of keywords, clauses, and target-lists, the EN FORM statements LIST and FIND provide the
basic specifications for information selection. Additional statements establish the query environ-
ment and provide some report structuring capability.
3-4
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -_ _ _ _ _ _ _ _ _. . . .1. . . . . . .
ENFORM Language Elements
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.
CLAUSES
Clauses are optional elements of ENFORM statements. With the exception of the option variable
clauses and the system variable clauses, EN FORM clauses only apply to the LIST or FIND state-
ment of which they are a part.
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:
3-5
ENFORM Language Elements
o Must be unique.
o Must start with either an alphabetic character or a circumflex (").
o Can contain numbers, hyphens (-), or circumflexes (").
o Can be from 1 to 31 characters in length.
o 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.
When you reference a record name within a query, the record name must be unique. 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 oceurrence 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
dause, the TITLE statement and clause, and the BEFORE CHANGE and AFTER CHANGE
elauses.)
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 OF record-name
or
field-name OF group-name
3·-6
ENFORM Language 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.
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:
sheLf-items.erasers.ink
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.
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:
OPEN parts;
LIST parts. KEY;
3-7
ENFORM Language Elements
The record with the primary key value of 1403 can be referenced by:
OPEN re II i
LIST KEY OF rell;
The primary key of the fifth record in the file can be referenced by:
For files with entry-sequenced and unstructured file structures, the primary key is a record
address. A record address is the byte offset from zero of the record you want . .A record address is
always an even number. A listing of the primary keys of an entry-sequenced file can be obtained by:
OPEN entryseqi
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 Data Base Manager Program-
ming ManuaL
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.
3-8
ENFORM Language Elements
fieLd-name-ref1} {"["SUbscriPt"]" }
{user-tabLe-name "["subscript-range"]"
where
fieLd-name-ref1
user-tabLe-name
subscript
is an integer. The lowest valid value for subscript is 1. The highest valid value is the max-
imum number of elements defined for the user or data base table. (Refer to the following
discussion for more information.)
subscript-range
where
subscripti
subscriptj
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
3-9
ENFORM Language Elements
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. 11'or example, consider the following user table
declaration:
DECLARE u-var[ 24 Ji
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 exa.mple:
Both user and data base tables can be referenced without a subscript. ENFORM assumes a
subscript of 1. For example:
Including a subscript with a user or data base table reference identifies the individual elements of
the table. For example:
Subscript-range can be included in user or data base table references when the table is used as a
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 J Refers to the third through eighth elements of the user table.
monthly-sales [ 1:4 J Refers to the first through fourth elements of the data base
table.
In the dictionary record description, a data base table can be defined as a group element with sub--
ordinate data base field entries. For example:
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:3 J.month Refers to month within the second through third elements of
sales.
3-10
ENFORM Language Elements
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:
ENFORM allows you to reference nested data base tables. For example:
AGGREGATES
An aggregate is the result of a cumulative operation performed for each value that 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.
AVG
COUNT [UNIQUE] field-name
SUM
MAX [ WHERE logicaL-expression] )
MIN
user-aggregate
' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -.--.-------
3-11
EN FORM Language Elements
where
AVG
is a predefined EN FORM aggregate that computes an average value for ;a set of numbers
or expressions.
COUNT
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 EN FORM 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
user-aggregate
fieLd-name
expression
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.
3-12
-
ENFORM Language Elements
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. UNIQ UE is redundant with MAX or MIN. While
the same answer is returned when UNIQUE is specified with these aggregates, process-
ing 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 con-
tributing 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)i
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 partsi
LIST COUNT(partnum)i
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 fromsuPi
LIST BY partnum,
MIN(partcost OVER partnum),
MAX(partcost OVER partnum)i
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,partsi
LINK order to odetaiL VIA ordernumi
LINK odetaiL to parts VIA partnumi
LIST BY saLesman,
SUM (price * quantity) OVER saLesman)i
3-13
gNFORM Language Elements
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.
'rhe syntax of a user-defined aggregate is shown in Section 5 with the DECLAHE statement. The
syntax is also shown here to clarify this discussion.
where
user-aggregate-name
is a unique name you give your aggregate. The name must follow tlhe 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
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-cons tant.
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.
3-14
ENFORM Language Elements
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:
Target Aggregates
A target aggregat~ appears as part of the ENFORM output. To specify a target aggregate, follow
these rules:
• The field names in the target aggregate syntax can come from different data base records.
• Target aggregates cannot be nested; that is, one aggregate cannot be used as the argument for
another aggregate.
TARGET AGGREGATE WITH OVER All SYNTAX. When you specify a target aggregate without
specifying either 0 VER or 0 VER ALL, ENFORM assumes 0 VER ALL. Figure 3-3 shows both a
query outline using the 0 VER ALL syntax and an output diagram.
I --------- I
by-item-1 by-item-2 target- I target- I AVG
item-1 I item-2 I target-item-2
------ ------ ------ I ------ I -----------
xxxxx xxxxxx xxxxxx I xxxxxxx I xxxxxxxxxxx
xxxxxx I xxxxxxx I
xxxxxx I xxxxxxx I
xxxxxx xxxxxx I xxxxxxx I
xxxxxx I xxxxxxx I
xxxxx xxxxxx xxxxxx I xxxxxxx I
xxxxxx I xxxxxxx I
xxxxxx I xxxxxxx I
xxxxxx I xxxxxxx I
'---T--- '
total/number of target-item-2 =
3-15
]~NFORM Language Elements
Query outline:
LIST BY by-item-1,
BY by-item-2,
target-item-1
AVG(target-item-1 OVER by-item-2);
Output Diagram:
xxxxxxx
xxxxxxx
In this example, AVG target-item-l 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-l
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.
8-16
ENFORM Language Elements
• Qualification aggregates cannot be nested; that is, one aggregate cannot be used as the argu-
ment for another aggregate.
• 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 names appearing in an expression being aggregated, and any field names
appearing in the WHERE clause associated with an aggregate) must come from the same data
base record.
QUALIFICATION AGGREGATE WITH OVER ALL SYNTAX. When you specify a qualification
aggregate without specifying either 0 VER or 0 VER ALL, ENFORM assumes 0 VER 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 odetai l,
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.
3-17
ENFORM Language Elements
~-------------------------------------------------------
OPEN employee;
LIST regnum,
branchnum,
WHERE salary GT AVG (salary OVER regnum);
1 24666
2 28333
5 38000
99 39500
If employee has the following form when grouped by regnum and branchnum:
1 1 36000
19000
25000
26000
12000
2 30000
2 1 37000
25000
23000
5 3 38000
99 1 39500
Region Branch
2 1
1 1
1 1
1 1
1 2
Figure 3-5. Query Outline of Qualification Aggregate With OVER Over-item Syntax
3-18
ENFORM Language Elements
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.
OPEN parts;
LIST partnum,
inventory,
WHERE price GT AVG (price WHERE inventory LT 0);
Part
Number INVENTORY
------ ----------
212 7
244 3
1403 21
5502 6
5504 -1
5505 0
7102 20
LITERALS
Literals can be used in both a target-list and a request-qualification. Literals can also 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:
3-19
EN FORM Language Elements
• 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.
String Literals
String literals can be used in many of the EN FORM 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:
• Must be enclosed in quotation marks. If a quotation mark is part of a string literal, the quotation
mark must be doubled.
"1234.99"
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:
CUSTOMER ADDRESS
CENTRAL UNIVERSITY .... UNIVERSITY WAY
BROWN MEDICAL CO .... 100 CALIFORNIA STREET
3-20
ENFORM Language Elements
ARITHMETIC EXPRESSIONS
Arithmetic expressions are some combination of numeric literals, field values, variables, or aggre-
gates 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.
+ Addition
- Subtraction
* Multiplication
/ Division
Spaces are not required before any of the arithmetic operators with the exception of the subtrac-
tion sign ( -). At least one space must precede a subtraction sign that follows a field or variable
name.
(price + 10.00)
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.
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.
3-21
ENFORM Language Elements
'rhe resulting scale factor can be controlled by assigning the result of the arithm,etic 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 i.s 18. All calculations with ENFOHM are per-
formed 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.
Equal EOUAL EO
IS
EN FORM provides two other conditional operators: BEGINS WITH and CONTAINS. The three
symbols T are synonymous with BEGINS WITH and the three symbols '>' ar4~ synonymous with
CONTAINS.
3-22
.. _------------------_._-----
ENFORM Language Elements
where
condition
{
variable
field-n~me
}
[NOT] condi tiona l-operator {;~:~:~~;me}
expreSSlon expreSSlon
where
conditional-operator
expression
pattern-match
{
"[" n
m, n string-literal •..
n
m, n
If]"}
3-23
ENFORM Language Elements
------------
where
string-l iteral
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
A logical expression can be simple or compound. A simple logical expression consists of one condi-
tion. 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 r,esult of the
expression is evaluated as true if any of the conditions are evaluated as true.
3-24
-------------------------------------------------------------------------------------,------------------
EN FORM Language Elements
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:
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 exam-
ple, the following determines whether the empname field contains the value GEORGE:
A field can be compared to a range of values in a logical expression. In the range, value-l must be
less than value-2. Values used in a range can be either numeric literals or string literals.
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 expres-
sion 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:
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:
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.
3-25
F~NFORM Language Elements
In a logical expression a field described as alphanumeric in the data dictionary caltl 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 patte~rn-match:
In the following logical expression, two numbers precede the string-literal indic:ating that at least
one character but no more than two characters must precede string-literal in the field value:
IF/THEN/ELSE EXPRESSIONS
where:
logical-expression
value-1 or value-2
If the logical expression is evaluated as true, value-l is used. If the logical expression is evaluated as
false, value-2 is used. Value-l and value-2 must be the same data type, either both numeric or both
alphanumeric.
The value keywords NULL, BLANK, and BLANKS print blanks on reports. The value keywords
ZERO and ZEROS print zeros on reports.
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.
3-26
ENFORM Language Elements
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 P ARAM statement,
described in Section 5.
EN FORM 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 syn-
tax 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.
When a user variable is specified as a target-item, EN FORM uses the default value or the initial
value, whichever is appropriate. When a user variable is a target-item in a LIST statement, assign-
ment 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
1
user-variable-name-1 := literal
user-variable-name-2
expression
~ser-table-element
where
user-variable-name-1
field-name
aggregate
3-27
ENFORM Language Elements
literal
user-variable-name-2
expression
user-table-element
is the subscripted name of a user table element. You cannot assign a subscript range to a
user variable.
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:
EN FORM 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 expres-
sion. 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 Hu-var + 10) + 20)),
EN FORM assigns the value of the expression (40) to the user variable.
EN FORM performs this process for every target-record. ENFORM continues the process of
reevaluating the value of a user variable until it encounters the end of the target-list.
8·28
ENFORM Language Elements
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:
The preceding query always returns zero target-records even though in every target-record the
value of u-var (ordernum + 10) 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.
User Tables
User tables are special kinds of user variables that can store more than one value. 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 discus-
sion 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 deter-
mines 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.
3-29
--------------------------------------------------------------------------------------------
SECTION 4
STATEMENTS
This section contains the syntax of the EN FORM statements. The statements are arranged in
. alphabetical order to provide ease of access.
The EN FORM 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. EN FORM 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 state-
ment without a terminating semicolon, the effect of the statement is not shown in the output pro-
duced by the ?SHOW command.
4-1
Statements
Summary of Statements
Statement Function
Information Selection
LIST specifies the information selected for a report and prints the report.
FIND specifies the information retrieved from the data base and eitller write"'s the
information to a physical file or transmits the information to a host la nguage
program.
---------------------------------
Query Environment
DICTIONARY identifies the subvolume containing a dictionary. It also clears the int ernal
table and reclaims table space.
PARAM names and defines a parameter that can receive a value from a Comm and
Interpreter PARAM command.
SET initializes a user variable, user table, or a parameter and resets optio n
variables.
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 subse-
quent reports in the current session. See also the AT START PRINT cl ause 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 subsequ ent
reports in the current session. See also SUBFOOTING clause in Secti on 5.
SUBTITLE prints a subtitle at the top of each page immediately foliowin!J the tit Ie for all
subsequent reports in the current session. See also the SUBTITLE cia use 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
Statements
A T END Statement
AT END STATEMENT
The AT END statement allows you to specify information that is printed at the end of all subse-
quent 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
A T END statement is:
where
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.
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:
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:
4-3
Statements
AT END Statement
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.
Using the CENTER clause following the print-list of an AT END statement centers the information
within the leftmost and rightmost columns of the report.
The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in Section 5.
An AT END statement prints information at the end of all subsequent reports in the current ses-
sion. 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.
Cancel the AT END statement by specifying the AT END statement without the print-list
parameter.
4-4
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:
where
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.
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:
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:
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 informa··
tion within the leftmost and rightmost columns of the report.
'rhe 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 speci-·
fying a new AT START statement with a different print-list. Using the AT START PHINT clause
within a LIST statement temporarily overrides the AT START statement for the report generated
by the LIST statement.
Cancel the AT START statement by using the AT START statement without the print-list
parameter.
4-6
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:
r----------------------------------------------
record-name
user-variable-name
CLOSE user-aggregate-name , .•. [
user-table-name
param-name
where
record-name
user-variable-name
user-aggregate-name
user-table-name
param-name
As a session progresses, EN FORM 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 state-
ment 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 subse-
quent 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 ?DICTION ARY com-
mand. Both completely clear the ENFORM internal table and reclaim table space.
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
[ INTERNAL internaL-format
[ AS dispLay-format]
[ HEADING heading-string]
}....
where
is the name of the declared element. Names of user-defined elements should conform to
the rules described in Section 3.
II [ II max-subscript II ] II
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.
formaL-argument
is the name used to represent the actual argument of the user aggregate.
step-expression
is the operation to be performed for each record contributing to the user aggregate.
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.
internal-format
is the internal format for storing the user variable, aggregate or table.
4-8
,---------------------------------
Statements
DECLARE Statement
display-format
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
EN FORM session.
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:
4-9
Statements
DECLARE Statement
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:
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
qtrAtotals:
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
Statements
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:
where
record-name1 or record-name2
field-name
qualified-field-name1 or qualified-field-name2
are the names of fields uniquely identified as components of record-namel and record-
name2 respectively.
------------------"--
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:
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 refer-
encing that record description from the internal table. A DICTIONARY statement or
?DICTION ARY command clears the entire internal table.
4-11
Statements
DICTIONARY Statement
DICTIONARY STATEMENT
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 ] [
where
dict-subvol-name
is the name of the subvolume where your dictionary files reside. Refer to the Guardian
Operating System Programming Manual for information on specifying Tandem file names.
The dictionary identified in a DICTIONARY statement must be created by the Data Definition
Language compiler. Release T9102C10 of ENFORM accepts only dictionaries produced by DDL ver-
sion T9100DOO or later. ENFORM issues an error message if an attempt is made to use a. dictionary
compiled with an earlier version of DDL. These dictionaries must be recompiled with DDL version
T9100DOO or later. Refer to the Data Definition Language (DDL) Programmin[)' Manual for more
information about creating and compiling a dictionary.
• 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, EN FORM
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 com-
mand 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 dic-
tionary is cleared.
In the following example, the DICTIONARY statement is used to identify the volume that the dic-
tionary resides on as $data and the subvolume as database:
DICTIONARY $data.database;
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:
4-12
Statements
EXIT Statement
EXIT STATEMENT
The EXIT statement terminates the current ENFORM session. The syntax of the EXIT state-
ment 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-13
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 state-
ment is:
BY by-i tern }
BY DESC by-item
({[ output-field-name := ] target-item , . .. )
{ ASCD target-item
DESC target-item
[ WHERE logical-expression]
where
UNIQUE
is an option that prevents duplicate output records. UNIQUE adds processing overhead
and should be avoided unless you know unwanted duplicate records exist.
output-record-name
output-field-name
is the name of a field in the dictionary record description of the output record. ENFORM
allows you to qualify output1ield-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.
by-item
is an input field name. An input field name must be sufficiently qualified to avoid ambi-
guity between it and any other name specified in the query.
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 arithmeth! 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 another
name specified in the query.
logical-expression
4-14
Statements
FIND Statement
Before the FIND statement executes, you must include a description of the output record in the dic-
tionary. When the FIND statement executes, EN FORM either writes the output records to the
physical file specified in the dictionary or transmits the output records to a host language program.
The following example shows the Data Definition Language (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. EN FORM writes a physical file
generated by the FIND statement with an unstructured file type regardless of the file type you
specify in the data dictionary.
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 con-
version for numeric input and output fields.
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.
4-15
Statements
FIND Statement
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
output1ield-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!:
3. If output-fieLd-name is omitted and the input field name is subscripted or qualified, ENFORM
assumes that the same qualifications and subscripts apply to output-fieLd-name,.
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 EN:~ORM 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 ele-
ment 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.
4-16
Statements
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),
) ;
• A group name. EN FORM allows you to specify a group name as an input element. A void 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.
4-17
Statements
FIND Statement
Although ENFORM allows you to specify an output field name as an input element, this specifica-
tion is not recommended and might lead to unexpected results.
'fhe following rules apply to input elements:
Request·Qua I ification
Use the WHERE clause to limit the records written to the physical output file OJ' 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.
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:
4-18
Statements
FIND Statement
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:
EN FORM 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.
4-19
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 state-
ment 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] ] [ ; ]
where
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.
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:
4-20
Statements
FOOTING Statement
The following footing appears at the bottom of the next report that is generated without a LIST
statement FOOTING clause.
If you specify either a SKIP clause or the symbol slash (f) 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:
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
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 within the leftmost
and rightmost columns of the report.
The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in Section 5.
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.
Cancel the FOOTING statement by using the FOOTING statement without the print-list
parameter.
4-21
Statements
LINK Statement
LINK STATEMENT
1'he LINK statement allows you to specify a connecting relationship between dictionary record
descriptions. The syntax of the LINK statement is:
r----------------------------------------------------------------------------~
where
field-name
are the names of fields uniquely identified as components of the record descriptions being
linked.
OPTIONAL
indicates that all of the records from the first file specified in the LINK statement are
included whether or not records with matching linking fields are found in the second file.
All of the records in the first file must have a value in the linking field or a sort operation
might fail.
Only one LINK OPTIONAL statement can be specified for a LIST or FIND statement.
While LINK OPTIONAL is in effect, other linking relationships such as another LINK
statement or a linking WHERE clause cannot be specified.
---------------------------------------------------------------_.
A LINK statement does not actually link physical files, but forms a logical relationship between the
dictionary record descriptions. Up to 32 linking relationships can exist.
The LINK statement is a convenient way of expressing a connecting relationship between two
record descriptions. In subsequent LIST or FIND statements, EN FORM treats the linked record
descriptions as one logical record description. The LINK statement is equivalent to the following
'WHERE clause in a LIST or FIND statement:
Before a LIST or FIND statement is executed, ENFORM actually converts the LINK statement
into a WHERE clause and adds it to the LIST or FIND statement. When several LINK statements
exist, an extra clause for each LINK statement is added to the WHERE clause in the LIST or FIND
statement.
4-22
Statements
LINK Statement
Clearing a LINK
EN FORM stores each LINK and LINK OPTIONAL statement in the internal table. The LINK
statement remains in effect until:
LINK statements that are not used in processing a query act as unwanted WHERE clauses in
subsequent LIST or FIND statements. Thus, any LINK statements that might be unnecessary
should be cleared when no longer needed.
Unlike the LINK statement, a WHERE clause associated with a LIST or FIND statement clears
after ENFORM processes the statement.
4-23
Statements
LIST Statement
LIST STATEMENT
The LIST statement allows you to select the information printed in a report and prints the report.
The LIST statement must end with a semicolon. The syntax of the LIST statem'ent is:
-----------
LIST [ UNIQUE] BY by-i tem }
BY DESC by-item
target-item
ASCD target-item
{ DESC target-item
user-var-name := target-item
CUM [ OVER ALL
CUM OVER by-item
PCT [ OVER ALL ]
PCT OVER by-item
TOTAL
SUBTOTAL
SUBTOTAL OVER by-item
NOHEAD
NOPRINT
CENTER
HEADING string-literal
AS display-format , ...
AS DATE display-format
AS TIME display-format
[ ~~~~ ~ ~ ~
[ / ]
SPACE n]
1, ••• , ...
TAB [ n ] ]
WHERE logical-expression
NOHEAD ALL ]
NOPRINT ALL ]
CENTER ALL ]
[ SUPPRESS [ WHERE] logical-expression]
[ BEFORE CHANGE [ON] by-item PRINT print-List CENTER
[ AFTER CHANGE [ON] by-item PRINT print-list CENTER
[ AT START PRINT print-list CENTER
[ AT END PRINT print-list CENTER
[ TITLE print-list CENTER
[ SUBTITLE print-list CENTER
[ FOOTING print-list CENTER
[ SUBFOOTING print-list CENTER
where
UNIQUE
prevents identical records from contributing to the report. UNIQUE adds processing
overhead and should not be used unless undesirable duplicate records are known to exist.
~
Statements
LIST Statement
by-item
is the name of a field modified by a BY or a BY DESC clause. The report is sorted and
grouped according to the value of this field.
target-item
user-var-name
string-literal
display-format
is a symbol that is equivalent to the SKIP clause. You can specify as many of these sym-
bols as you want to indicate the number of lines to advance.
logical-expression
print-list
contains any combination of literals, FORM, SKIP, SPACE or TAB clauses. A 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, and parameter names.
BY and BY DESC clauses group and sort records. ENFORM prints the by-item value for a group
only for the first record of all the records that have the same value for the by-item. By-items can be
referred to by CUM OVER, PCT OVER, SUBTOTAL OVER, AFTER CHANGE, and BEFORE
CHANGE clauses. These clauses are described in Section 5.
ASCD and DESC clauses sort records in ascending or descending order. They do not identify a
group. The ASCD and DESC clauses are described in Section 5.
When a LIST statement contains more than one BY, BY DESC, ASeD, or DESC clause, ENFORM
determines a major to minor sorting precedence. ENFORM determines the sorting precedence by
the order in which the clauses appear in the LIST statement. The first clause has highest priority
and is sorted first, the next one second priority, down to the last specified clause.
4-25
Statements
LIST Statement
EN FORM displays target-items and by-items in report columns, one column per item. If a record
name is a target-item in a LIST statement, EN FORM expands the record to as many target-items as
the number of elementary fields in the record. If a field within the record is described with an
OCCURS clause, ENFORM prints each occurrence of the field in a separate column of the report. Do
not specify a record name as a target-item if it is the same as a field name in a record. Hefer to Sec-
tion 3 for information about field names. A target-item in a LIST statement can be:
• a record name
LI ST ... ,
parts;
LIST ••• ,
partnum;
LIST ••• ,
(5);
• a string literal.
LIST ... ,
"manager";
• an arithmetic expression enclosed in parentheses. The expression can use any combination of
numeric fields, numeric literals, numeric user variables, predefined aggregates, user aggre-
gates, JULIAN-DATE clauses, or system variable clauses.
LI ST •.. ,
(price * quantity);
LIST .•. ,
(IF inventory GT 0 THEN inventory ELSE ZERO);
• a user variable. Define the user variable with a DECLARE statement. The variable should be
either initialized with a SET statement or assigned a value with assignment syntax. If the
variable value is neither initialized nor assigned, the default value is zero. A user variable can-
not be assigned the values of a subscript range.
DECLARE new-sal;
SET new-sal TO (salary * 1.20);
LIST ••• ,
new-sal;
LIST ••• ,
@LINENO AS 15;
4-26
Statements
LIST Statement
LI ST ••• ,
COUNT (branchnum OVER regnum)i
LIST ..•
months 1:6 Ji
• a parameter name. Parameters that have not been declared with an alphanumeric internal
format must be enclosed in parentheses. Parameters declared with an alphanumeric internal
format must not be enclosed within parentheses.
PARAM numi
LIST ... ,
(num)i
ENFORM allows you to specify a group name as a target-item within a LIST statement; however,
EN FORM might not display the fields within the group in the manner you expect. To understand
the way that ENFORM displays group elements, you must first understand what a group is. A
group is defined in DDL as any field whose level number (03, 04, 05, ... ) is less than that of the next
field. For example, consider the following DDL record description:
RECORD test.
FILE IS "$mkt.sample.test" key-sequenced.
02 account-num.
OS type PIC 9(4).
OS num TYPE BINARY 16.
02 custnum PIC 9(4).
end
Within this record, account-num is a group. The data type of group is always alphanumeric. When a
group name is specified as a target-item within a LIST statement, ENFORM displays each field
within the group as alphanumeric data. If one of the fields within a group contains binary data,
using a group name as a target-item causes undesirable results. For example, specifying:
LIST account-numi
Request·Qual ification
Use the WHERE clause to limit the records that contribute to the report. The WHERE clause is
described in Section 5.
Conditional Printing
Use the SUPPRESS clause to define a condition or conditions that prevent specific records from
printing throughout a report. ENFORM still includes the suppressed records in AFTER CHANGE
and BEGIN CHANGE clauses, subtotals, totals, and other calculations specified for the report.
Note that the value of the first record of an AFTER CHANGE clause or the last record of a
BEFORE CHANGE clause is used for the print-list whether or not that record is printed. The
SUPPRESS clause is described in Section 5.
4-27
Statements
LIST Statement
Summary Reports
Summary reports contain only the first target-record from each group (created by a BY or BY
DESe clause) down to some level. Summary reports can only be generated by a query that contains
an aggregate.
When you explicitly request a summary report, you get a report summarized down to the lowest
level where an aggregate is calculated over that level. For example:
returns one record for each job in each department. Only the first employee name (empname) for
each job is returned.
When you implicitly request a summary report, you get a report summarized down to the lowest
level where an aggregate is computed over that level. (A query requesting only b?l-items and
aggregates over ALL is not an implicit request for a. summary report). For example:
returns one record for each job in each department. Only the first employee name (empname) for
each job is returned.
If you want a report that consists of only by-items and aggregates to contain all report lines
(including 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. This target-item can be modified by the NOPRINT clause if desired. Of
course, you must also set @SUMMARY-ONLY to OFF. For example:
returns more than one record for each job in each department. All the employee names (empname)
for each job are returned.
4-28
Statements
LIST Statement
Optional Clauses
These clauses are optional and are described in Section 5. If you use one of these clauses to modify a
target-item that contains a subscript range, the clause modifies each element in the range. Briefly,
the clauses do the following:
• AFTER CHANGE clause prints information preceding the records for each by-item within a
printed report.
• BEFORE CHANGE clause prints information following the records for each by-item within a
printed report
• NOHEAD clause suppresses the printing of the column heading for a target-item or by-item
• SUPPRESS clause defines a condition that prevents specific records from printing in a report.
4-29
Statements
OPEN Statement
OPEN STATEMENT
The OPEN statement accesses the dictionary record description. The syntax of the OPEN state-
ment is:
OPEN { record-name }
record-name2 [ AS ] COpy [ OF ] record-name1 , ... [
where
Specifying an OPEN statement does not actually open a physical file, rather the OPEN statement
causes ENFORM to access the dictionary record description of the file. One OPEN statement can
open several record descriptions. ENFORM stores the record description in the internal table. The
record description remains open until:
'. Either a DICTIONARY statement or ?DICTIONARY command clears the entire internal table.
The OPEN AS COpy OF statement is useful when a record description is designed so that records
within a file relate to other records within the identical file. Because LINK statements only
associate record descriptions with different record names, the OPEN AS COpy OF statement
refers to the same record description by a different record name.
Note that although the OPEN AS COpy OF statement opens record-name2, you must open record-
namel before specifying this statement.
4-30
Statements
P ARAM Statement
PARAM STATEMENT
The PARAM statement allows you to name and define a parameter that can receive a value from a
Command Interpreter PARAM command. The syntax of the PARAM statement is:
where
param-name
is the name of the parameter being defined. The name must conform to the naming con-
ventions described in Section 3.
internaL-format
is the internal format for storing the parameter. Valid values for internal-format are:
Up to 32 parameters can be defined per ENFORM session. The SET statement can initialize the
value of the parameter. The following PARAM statement defines a parameter named regno:
Values for parameters can only be passed to an executing compiled query file. (A compiled query
file is created by the ?COMPILE command described in Section 6.) Before executing the stored com-
piled query file, a Command Interpreter PARAM command can be used to pass a value for the
parameter. The value specified by the Command Interpreter PARAM command supersedes the
parameter value specified by a SET statement. The Command Interpreter PARAM command must
precede the Command Interpreter ENFORM command. Refer to the GUARDIAN Operating
System Command Language and Utilities Manual for more information about the Command Inter-
preter PARAM command.
Parameter values can also be passed through the host language interface. Refer to the ENFORM
User's Guide for information about the host language interface.
4-31
Statements
P ARAM Statement
Notice that reptnum is enclosed in parentheses when specified in the TITLE statement. To provide
a value for reptnum, enter the following Command Interpreter P ARAM command:
REPORT 333
Part
Number PARTNAME INVENTORY LOCATION PRICE
------------------ --------- --------- ---------
212 SYSTEM 192KB CORE 7 J87 92000.00
244 SYSTEM 192KB SEMI 3 B78 87000.00
1403 PROC 96KB SEMI 21 A21 22000.00
You can use a parameter wherever a literal is allowed. In certain cases, ENFOHM allows you to use
a parameter but treats the parameter strictly as a numeric literal. Therefore, you cannot change
the value of the parameter at execution time. ENFORM treats a parameter strictly as a numeric
literal when you use the parameter as:
• a subscript
• the "max-subscript" in the declaration of a user table
• the integer in a FORM, SKIP, TAB, or SPACE clause
• the integer in a pattern-match string of a logical expression.
ENFORM issues a warning message when you have specified a parameter in this manner.
4-32
Statements
SET Statement
SET STATEMENT
The SET statement allows you to initialize or reset a user variable, user table, or a parameter. The
SET statement also allows you to reset option variables. The syntax of the SET statement is:
r - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----- - - - - - - - -
user-variable-name string-literal I
user-table-name"[" subscript"J"
param-name
[TOJ
!
numeric-literal\
SET
option-variable-name [TOJ ON , . .. [
OFF
unsigned-digit
string-l iteral
display-format
where
user-variable-name or user-table-name"["subscript"J"
param-name
string-literal
unsigned-digit
option-variable-name
numeric-literal
is an integer.
display-format
is the default display format enclosed in quotation marks for printing dates or times
when AS DATE * and AS TIME * clauses are used.
' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --- - - - - - - -
4-33
Statements
SET Statement
When initializing a user variable, user table, or a parameter, specify values that are consistent with
the internal format type. If the internal format type is alphanumeric, specify a a string literal; if the
internal format type is numeric, specify a numeric literal. In the following example, the user
variable u-var is defined as numeric by the DECLARE statement and set to the value of 99 by the
SET statement:
The SET statement can initialize a user table. An unsigned numeric integer subscript must be used.
In the following example, the third element of the months table is set to MARCH:
Use the SET statement to redefine option variables. There are several option variables, each with
default values assigned by ENFORM. Refer to the description of the Option Variable Clause in Sec-
tion 5 for information about valid values for the option variables.
4-34
Statements
SUBFOOTING Statement
SUBFOOTING STATEMENT
The SUBFOOTING statement allows you to specify a subfooting to be printed at the bottom of each
report page for all reports in the current session unless overridden or reset by another
SUBFOOTING statement or temporarily overridden by a SUBFOOTING clause. See the
SUBFOOTING clause in Section 5. The syntax of the SUBFOOTING statement is:
where
print-list
can be any combination of literals, FORM, SKIP, SPACE or TAB clauses. A print-list can
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 used in a print-list are discussed in Section 5. The other elements
are discussed in Section 3.
If you specify a field name within a print-list of a SUBFOOTING statement, the field value printed
is the same value as in the last row of data on the current page. A field appearing within the
SUBFOOTING statement need not be explicitly included within the following LIST statements. If a
SUBFOOTING statement field is not included, EN FORM effectively adds it to the LIST statement
with a NOPRINT clause.
Spacing Considerations
By default, the subfooting begins in the same column position as the leftmost report column. Using
either SPACE or TAB clauses as the first element of the print-list overrides this default. The
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:
The following subfooting will appear at the bottom of the next report that is generated without a
LIST statement SUBFOOTING clause.
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 SUBFOOTING 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 SUBFOOTING statement causes the subfooting to print on two lines:
4-35
Statements
SUBFOOTING Statement
The following subfooting will appear at the bottom of the next report that is g-enerated without a
LIST statement SUBFOOTING clause.
Report 2-A
TotaL SaLes
Using the FORM clause within a SUBFOOTING statement forces a new page. The remainder of the
SUBFOOTING print-list is printed on the new page. 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 SUBFOOTING on the next. The same page number applies to all physical pages in a
logical page.
Using the CENTER clause within the SUBFOOTING statement centers the subfooting within the
leftmost and rightmost columns of the report.
The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in Section 5.
A SUBFOOTING statement prints a subfooting at the bottom of each page for all subsequent
reports in the current session. Specifying a new SUBFOOTING statement with a new print-list
resets the current SUBFOOTING statement. A SUBFOOTING statement can be temporarily over-
ridden by a SUBFOOTING clause within a LIST statement. A SUBFOOTINGclause only prints a
subfooting for the current report.
A SUBFOOTING statement can be cancelled by using the SUBFOOTING statement without the
print-list parameter.
4-36
Statements
SUBTITLE Statement
SUBTITLE STATEMENT
The SUBTITLE statement allows you to specify a subtitle for all subsequent reports in the current
session. The subtitle is printed at the top of each page immediately following the title. The
SUBTITLE statement can be overridden or reset by another SUBTITLE statement or temporarily
overridden by a SUBTITLE clause. The syntax of the SUBTITLE statement is:
where
print-list
can contain any combination of literals, FORM, SKIP, SPACE, or TAB clauses. A 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 specified in a print-list are discussed in Section 5. The other
elements are discussed in Section 3.
If you specify a field name within the print-list of a SUBTITLE statement, the field name has the
same value as in the first row of the page. A field name appearing within the SUBTITLE 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 subtitle 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:
If you specify either a SKIP clause or the slash symbol (f) within a print-list, ENFORM advances one
or more lines before printing the rest of the SUBTITLE 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 SUBTITLE statement causes two lines to be printed:
Report 2-A
Total Sales
4-37
Statements
SUBTITLE Statement
Using the FORM clause within a SUBTITLE statement forces a new page. ENFORM prints the
remainder of the SUBTITLE print-list, starting at the top of the next physical page. The page num-
ber remains the same. A single logical page can span multiple physical pages such that a
SUBTITLE 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 a SUBTITLE statement centers the subtitle within the leftmost
and rightmost columns of the report.
The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in Section 5.
A SUBTITLE statement prints a subtitle at the top of each page immediately following the title for
all subsequent reports in the current session. The SUBTITLE statement can be reset by specifying
a new SUBTITLE statement with a different print··list. A SUBTITLE clause within a LIST state-
ment temporarily overrides the SUBTITLE statement. A SUBTITLE clause within a LIST state-
ment prints a subtitle only for the current report.
Cancel a SUBTITLE statement by using the SUBTITLE statement without the print-list
parameter.
4-38
Statements
TITLE Statement
TITLE STATEMENT
The TITLE statement allows you to specify a title to be printed the top of each page for all subse-
quent reports in the current session unless cancelled or reset by another TITLE statement or tem-
porarily overridden by a TITLE clause. (See the TITLE clause in Section 5.) The syntax of the
TITLE statement is:
where
pri nt-l i st
can contain any combination of literals, FORM, SKIP, SPACE, or TAB clauses. A 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 used in a print-list are discussed in Section 5. The other elements
are discussed in Section 3.
If you specify a field name within the print-list of a TITLE statement, the field has the same value
as in the first row of the page. A field appearing within the TITLE statement need not be explicitly
included within the following LIST statements. If it is not included, ENFORM effectively adds it
with a NOPRINT clause.
Spacing Considerations
By default the title 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:
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 TITLE 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 TITLE statement causes two lines to be printed:
Report 2-A
Total Sales
4-39
Statements
TITLE Statement
Using the FORM clause within a TITLE statement forces a new page. The remainder of the TITLE
print-list is printed, starting at the top of the next physical page. The page nlllmber 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 a TITLE statement centers the title within the leftmost and
rightmost columns of the report.
'The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in Section 5.
A TITLE statement prints a title at the top of each page for all subsequent reports in the current
session. Specifying a new TITLE statement resets the TITLE statement to the value of the new
print-list. A TITLE statement can be temporarily overridden by a TITLE clause within a LIST
statement. A TITLE clause within a LIST statement only prints a title for the eurrent report.
A TITLE statement can be cancelled by using the TITLE statement without the print-list
parameter.
4-40
SECTION 5
CLAUSES
This section describes the syntax of the ENFORM clauses. The clauses are specified in alphabetical
order.
ENFORM clauses are components of statements. They provide additional specifications of the
ENFORM program to be performed. Most of the ENFORM clauses remain in effect only for the
query associated with the LIST OR FIND statement of which they are a part.
An ENFORM program with a FIND statement produces records only; it has no report features such
as headings, titles, summary information, and special formatting. The following clauses are appli-
cable only to EN FORM programs with a LIST statement and cannot be used in programs with a
FIND statement:
5-1
Clauses
JlJNFORM Clauses and Their Functions
ASCD and DESC sort target-records in ascending or descending order respectively according
to the value of a specified field.
BY and BY D ESC group and sort target-records according to the value of a specified field.
SUPPRESS eliminates certain records from being printed in the report, but does not
limit the records from contributing to the report calculations.
CUM prints a running total for a numeric target-item. The CUM OVER clause
prints the running group total for a numeric target-item.
PCT prints the value of the percentage of the grand total for a numeric target-
item. The peT OVER clause prints the percentage that each grouped value
is of the total of all values in the group.
SUBTOTAL prints the value of the target-·item subtotals for each group.
Extracting Current Values for Date, Time, Line Number, and PagEt
~.-----------------------------------------
System Variable return the current value for the current date, time, line number, and page
number.
TIMESTAMP-DATE extracts the date portion of a timestamp field that has be.~n created by
the GUARDIAN procedure TIMESTAMP.
TIMESTAMP-TIME extracts the time portion of a timestamp field that has been created by
the GUARDIAN procedure TIMESTAMP.
AFTER CHANGE prints information for the current report preceding the records for each
grouped field value.
AT END PRINT prints information at the end of the current report. See also the AT END
statement in Section 4.
AT START PRINT prints information just before the first set of column headings for the cur-
rent report. See also the AT START statement in Section 4.
BEFORE CHANGE prints information for the current report following the records for each
grouped field value.
5-2
-----------------------------------------------------------------------------------------------------...
Clauses
ENFORM Clauses and Their Functions
FOOTING prints a footing at the bottom of each page for the current report. See
also the FOOTING statement in Section 4.
SUBFOOTING prints a subfooting at the bottom of each page immediately preceding the
footing for the current report. See also the SUBFOOTING statement in
Section 4.
SUBTITLE prints a subtitle at the top of each page immediately following the title for
current report. See also the SUBTITLE statement in Section 4.
TITLE prints a title at the top of each page for the current report. See also the
TITLE statement in Section 4.
Formatting a Report
HEADING overrides the default column title for a target-item or by-item in a report.
Option Variable redefines the default values for several operational variables ..
~--------------------------------------------------------
5-3
Clauses
AFTER CHANGE Clause
The AFTER CHANGE clause prints information preceding the records for each group for the cur-
rent report. The AFTER CHANGE clause is an optional part of a LIST statement. The syntax of
the AFTER CHANGE clause is:
where
by-item
print-list
contains any combination of literals, FORM, SKIP, SPACE or TAB clauses. A 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 used in a print-list are described in this section. The other
elements are described in Section 3.
The AFTER keyword of the AFTER CHANGE clause refers to the values printed, not to the loca-
tion of the printed information. For the exact location of where the AFTER CHANGE information
is printed within a report, refer to the ENFORM Users Guide.
When more than one AFTER CHANGE clause is specified, the specified information prints in the
order in which the AFTER CHANGE clauses are entered.
If you specify a field name within the print-list of an AFTER CHANGE clause, ENFOHM uses the
same field value as in the first row of the next group. A field name appearing within the print-list of
an AFTER CHANGE clause need not be explicitly included within the LIST statement. If the field
name is not included, ENFORM effectively adds it with a NOPRINT clause.
Spacing Considerations
By default the AFTER CHANGE clause information begins printing in the same column position as
the leftmost report column. Using SPACE or TAB clauses as the first element of the p1-int-list over-
rides this default. SPACE or TAB clauses can also appear anywhere within the print list. In the
following example, the SPACE clauses causes the two literals to be separated by five spaces:
5-4
Clauses
AFTER CHANGE Clause
If you specify either a SKIP clause or the slash symbol (f) within a print-list, ENFORM advances one
or more lines before printing the rest of the AFTER CHANGE 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 within the AFTER CHANGE clause causes two lines to be printed:
Using the CENTER clause following the print-list of an AFTER CHANGE clause centers the infor-
mation within the leftmost and rightmost columns of the report.
The CENTER, Option Variables, SKIP, SPACE, and TAB clauses are described in this section.
5-5
Clauses
ASCD and DESC Clauses
The AS CD and DESC clauses sort target-records, in ascending or descending order respectively,
according to the value of the specified field. The syntax of the ASCD and DESC clauses is:
1ASCD} target-item
lDESC
where
target-item
is the name of a field from an input record which serves as a sort key for the target
records.
The ASCD and DESC clauses do not group field values. If you want field values both grouped and
sorted, use the BY or BY DESC clauses described in this section.
When more than one ASCD, BY, BY DESC, or DESC clause is specified in a LIST or FIND state-
ment, ENFORM uses a major to minor sorting precedence. ENFORM determines the sorting
precedence by the order in which the AS CD or DESC clauses appear in the LIST or FIND state-
ment. The first sort clause has the highest priority, the next one second priority, down to the last
specified clause.
The following ASCD clause indicates that the target records are to be sorted on the value of partnum:
ASCD partnum,
5-6
-------------------------------------------------------------------------------------------------
Clauses
AS Clause
AS CLAUSE
The AS clause specifies a display format for printing a target-item or by-item. The syntax of the AS
clause is:
report-item AS nonrepeatabLe-edit-descriptors
repeatabLe-edit-descriptors
repeatabLe-edit-descriptors II
( nonrepeatabLe-edit-descriptors
repeatabLe-edit-descriptors ) II
where
report-item
nonrepeatabLe-edit-descriptors
repeatabLe-edit-descriptors
specify data conversion to the GUARDIAN Formatter for printing the report-item
values. Valid values for repeatable-edit-descriptors are:
where
5-7
Clauses
AS Clause
"["decorations"]"
where
conditions
location
char-string
"["modifiers"]"
5-8
Clauses
AS Clause
where
char
pr-of-symbols
The AS clause identifies how an target-item or by-item is printed in the current report. When the
AS clause is not specified, ENFORM uses the display format from one of these sources:
The AS clause allows you to utilize some of the capabilities of the GUARDIAN Operating System
Formatter. When you specify a display-format, EN FORM passes your format specifications to the
Formatter. Refer to the GUARDIAN Operating System Programming Manual for more informa-
tion about the Formatter.
Repeatable edit descriptors specify the conversion of data values by the Formatter for the target-
item or by-item being printed. The word repeatable has no real meaning in the context of ENFORM;
the word is used to simplify cross references to the FORMATTER terminology. Currently,
ENFORM makes only single target-items or by-items available for modification by edit descriptors.
ALPHANUMERIC EDIT DESCRIPTOR. The alphanumeric edit descriptor specifies the target-item
or by-item is to be printed using alphanumeric display format. The syntax is:
A [w]
where
is an unsigned integer that specifies the width in characters of the value of the target-
item or by-item to be printed. The maximum value for w is 255 characters.
L-_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
If you specify w, ENFORM prints the number of characters specified for the value of the target-
item or by-item. If you omit w, ENFORM prints the actual number of characters in the value of the
target-item or by-item. In either case, ENFORM prints the value of the target-item or by-item left-
justified with blank fill.
If w is too small for the value of the target-item or by-item, an overflow condition occurs and
ENFORM truncates the value.
5-9
Clauses
AS Clause
Examples of the Alphanumeric Edit Descriptors. The following examples show the affect of the A
edit descriptor:
INTEGER EDIT DESCRIPTOR. The integer edit descriptor specifies an integer display format. The
syntax is:
Iw [. m]
where
is an unsigned integer that specifies the number of digits that must be printed. The value
of m must not exceed the value of w.
When you modify an target-item or by-item with an integer edit descriptor, ENFORM prints the
value right-justified with blank fill. ENFORM always prints at least one digit for the valiue of such a
. target-item or by-item. If you specify m, ENFORM prints the number of digits specified, using
leading zeroes if necessary.
Note that if the value to be printed is zero and you specify Iw.O, ENFORM prints blanks.
Examples of the Integer Edit Descriptor. The following examples show the effect of the integer
edit descriptor.
5-10
Clauses
AS Clause
FIXED FORMAT EDIT DESCRIPTOR. The fixed format edit descriptor specifies a fixed point
display format. The syntax is:
Fw.d [.m]
where
is an unsigned integer that defines the total width of the target-item or by-item value.
is an unsigned integer that defines the number of digits that are to appear to the right of
the decimal point.
is an unsigned integer that defines the number of digits that are to appear to the left of
the decimal point.
When you specify the fixed format edit descriptor, ENFORM prints the value of the target-item or
by-item right-justified with leading blanks if necessary. If the value is negative, ENFORM prints a
minus sign before the first digit. Both the minus sign and the decimal point occupy one position of
the format; therefore, w must be wide enough to accomodate the total size of the output field
including the minus sign and the decimal point. if w is not wide enough, an overflow condition
occurs.
If you specify m, ENFORM prints that number of digits using leading zeros if necessary.
Examples of the Fixed Format Edit Descriptor. The following examples show the effect of the
fixed format edit descriptor.
5-11
Clauses
AS Clause
MASK EDIT DESCRIPTOR. The mask edit descriptor specifies a display format according to a
template. The syntax is:
M mask
where
mask
is a set of symbols or characters enclosed within quotation marks (" "), apostrophes (' '),
or angle brackets « ». The symbols in a mask that serve a special function are:
Z is a digit selector. Z specifies that if no digit exists, zeros are suppressed. Z can be
used with alphanumeric or numeric data. Note: only a capitol Z is the special
symbol.
9 is a digit selector. If no digit exists, zeros are printed; used for numeric data only.
V indicates decimal alignment for the display format. When V is specified, the decimal
point is not printed. Note: only a capitol V is the special symbol.
indicates decimal alignment for the display format. When the symbol. (period) is
used, the decimal point is printed.
Numeric Values. If the mask specified for a numeric value is too small, an overflow condition
occurs.
The special symbols Z and 9 describe numeric values. If the digit selector is a 9, ENFORM prints the
corresponding data digit. If the digit selector is a Z, ENFORM prints the corresponding data digit
unless it is a leading or trailing zero. In this case, ENFORM blank fills the position held by the zero.
Decimal point location can be indicated for numeric values by using either the symbol. or the sym-
bol V. When the symbol. is used, a decimal point prints. When the symbol V is used, it indicates only
decimal alignment and no decimal point prints. If neither the symbol. nor the symbol V is specified,
I~NFORM assumes the decimal point is the rightmost character of the entire mask.
Alphabetic Values. Alphabetic values must be specified by the symbol Z in a mask edit descriptor.
Examples of the Mask Edit Descriptor. The following examples show the affect of the mask edit
descriptor.
5-12
Clauses
AS Clause
amount AS M<$ZZ,ZZ9>,
date AS M<Z9/Z9/99>,
district AS A8,
telephone AS M«999) 999-9999>
Nonrepeatable edit descriptors indicate some ways target-items or by-items are to be printed.
Values described by the nonrepeatable edit descriptors do not require data conversion by the For-
matter; however, the Formatter does process these values. When nonrepeatable edit descriptors
are specified with modifiers or decorations, both the nonrepeatable edit descriptor and the
repeatable edit descriptor must be enclosed in parentheses. The types of nonrepeatable edit
descriptors are:
SCALE FACTOR EDIT DESCRIPTOR. The scale factor edit descriptor specifies a scale of lO**n for
a fixed point (F) number. The value printed equals the internally represented number multiplied by
lO**n. The syntax is:
nP
where
5-13
Clauses
AS Clause
Examples of the Scale Factor Edit Descriptor. The following examples show the effect of the scale
factor edit descriptor.
OPTIONAL PLUS EDIT DESCRIPTOR. The optional plus edit descriptors are used to control the
printing of a plus (+) sign. The syntax is:
where
S or SS
SP
When an object-item or by-item with a positive value is printed, ENFORM does not normally
precede the value with a plus (+ ) sign. Specify SP when you want EN FORM to precede a value
with an optional plus sign.
Examples of the Optional Plus Edit Descriptor. The following examples show the effect of the
optional plus edit descriptor.
Modifiers
Modifiers alter the normal effect of edit descriptors. A modifier must immediately precede the edit
descriptor it modifies. Modifiers are enclosed within brackets ([ ]) and separated by commas.
Table 5-2 indicates which modifiers can be used with which edit descriptors. An X indicates the com-
bination is permitted.
1>-14
Clauses
AS Clause
Edit Descriptors
Modifiers
A F I M
BZ, BN X X X X
LJ, RJ X
OC X X X
FL X X X X
SS X X
FIELD BLANKING MODIFIERS. Field blanking modifiers indicate under what circumstances to
print blanks. The syntax is:
where
BN
prints a blank field if value is null.
BZ
prints a blank field if value is zero.
Although most edit descriptors cause a minimum number of characters to be printed regardless of
the value of the field, a field blanking modifier causes the entire field to be filled with blanks if the
specified condition is met.
Examples of the Field Blanking Modifiers. The following examples show the effect of the field
blanking modifiers.
Format Item VaLue Printed Item
"[BZ] F10.2"
----------
.00
------------
"[BN] F10.2" nuLL vaLue
"[BN] F10.2" 100.00 100.00
FILL CHARACTER MODIFIER. The fill character modifier specifies the fill character that is used in
the current display format. The default fill character is a blank. The syntax is:
FL char
where
char
is a single ASCII character enclosed within apostrophes (' ').
5-15
Clauses
AS Clause
A fill character prints in each appropriate character position when one of the following occurs:
alphanumeric data contains fewer characters than the field specified by the alphanumeric edit
descriptor, leading zero suppression is performed, or embedded text in an mask edit descriptor is
not printed because its neighboring digits are not printed.
Examples of the Fill Character Modifier. The following examples show the affect of the fill
character modifier.
OVERFLOW CHARACTER MODIFIER. The overflow character modifier temporarily overrides the
global default overflow indicator for the current display format. The overflow indicator is printed
when a value exceeds the width specified in the display format. The syntax is:
OC char
where
char
The overflow condition occurs if there are more characters to be printed than the display format
specifies. When the overflow condition occurs, ENFORM prints the overflow character. The default
overflow character is an asterisk (*). The overflow character modifier allows you to temporarily
substitute another ASCII character for the asterisk (*). The overflow character modifier applies
only to the display format where it is specified. The overflow modifier does not apply to the
alphanumeric (A) edit descriptor.
If you want to change the default overflow character for all display formats in the current session,
use the @OVERFLOW option variable described in this section.
Examples of the Overflow Character Modifier. The following examples show the effect of the
overflow character modifier.
5-16
Clauses
AS Clause
JUSTIFICATION MODIFIERS. The justification modifiers specify right or left justification for the
values of an alphanumeric target-item or by-item. The syntax is:
where
LJ
specifies that an item is to be printed justified to the left of the specified display format
width.
RJ
specifies that an item is to be printed justified to the right of the specified display format
width.
The justification modifiers apply only to alphanumeric (A) edit descriptors. Alphanumeric target-
items or by-items are normally left-justified. Padding of the item width automatically takes place. If
the item value is wider than the width specified, truncation occurs.
Examples of the Justification Modifiers. The following examples show the effect of the justifica-
tion modifiers.
SYMBOL SUBSTITUTION MODIFIER. The symbol substitution modifier allows you to change the
standard symbols ('9', 'V', 'Z', '.' and ',') used in edit descriptors. The syntax is:
SS pair-of-symbols
where
pair-of-symbols
are the standard and substitute symbols enclosed within apostrophes (' '). The standard
symbol must appear first, followed by the substitute symbol.
The symbol substitution modifier allows you to replace the standard symbols used in edit descrip-
tors. You can change the symbols for 9, Z, V, . and , in the mask (M) edit descriptor or change the
symbol for decimal point (.) in the fixed point (F) edit descriptor.
The symbol substitution modifier is useful when you need to specify a character string, that is also a
standard mask symbol. An example would be 9 in a mask for a date. Refer to the last example below.
5-17
Clauses
AS Clause
Examples of the Symbol Substitution Modifier. The following examples show the effect of the
symbol substitution modifier.
Decorations
Decorations specify character strings that can be printed along with the value of a target-item or
by-item. Decorations also specify the conditions under which the character string- is added, the loca-
tion at which the character string is added, and whether the character string is added before normal
formatting is done or after it is completed. The syntax of a decoration is:
------------------.-------
condition location char-string
where
condition
location
An absolute position n.
F floating.
P prior.
char-string
5-18
Clauses
AS Clause
You are responsible for ensuring that the display format width is large enough to contain both the
target-item or by-item value and the inserted character string.
CONDITIONS. The condition specifiers (negative, positive, zero, null, or overflow) indicate that a
character string prints only when the specified condition occurs. A null condition takes precedence
over negative, positive, and zero conditions. The overflow condition test is done after the other con-
ditions are tested. Conditions specified for alphanumeric target-items or by-items can be positive or
null only.
More than one condition specifier can exist for a decoration. Conditions are coded without
separators.
LOCATION. The location specifier indicates where the character string prints in relation to the
value of the target-item or by-item. The uses of the location specifiers are as follows:
• The A location specifier indicates the character string is to be printed starting in the absolute
position n.
• The F specifier indicates the character string is to occupy the position or positions immediately
to the left (for right-justified values) of the leftmost data character. If the value is left-justified,
the F specifier indicates the character string occupies the position or positions immediately to
the right of the rightmost data character.
• The P location specifier indicates that prior to normal formatting, the string is to be inserted in
either the rightmost position (for right-justified values) or the leftmost position for left-justified
values. The data values are shifted an appropriate number of positions.
3. If the P location decoration is specified, the character string is added to the item value.
4. Normal formatting according to the edit descriptor (alphanumeric (A), integer (I), or fixed point
(F) is performed.
5. Decorations for alphanumeric and fixed point edit descriptors are performed.
5-19
Clauses
AS Clause
DEFAULT DECORATIONS. When decorations are not specified, ENFORM prints a negative value
with a preceding negative ( - ) sign. In other words, [MF' - '] is assumed.
If a decoration is specified that tests for a positive value, such as [PF' + '], the default [MF' - '] no
longer automatically applies. In this case, the negative condition must be explicitly indicated if you
want EN FORM to print the negative sign.
When an overflow condition occurs, ENFORM replaces the value by enough asterisks (lie) to fill the
field. In other words, [OA1'***** ... ***'] is assumed. The OC char modifier temporarily overrides the
default asterisk (*) overflow character.
5-20
----,----,
Clauses
AS Clause
5-21
Clauses
AS DATE Clause
AS DATE CLAUSE
The AS DATE clause allows you to specify the display format for printing a date. The syntax of the
AS DATE clause is:
date-in-internal-format AS DATE { * t
di sp lay-format ~
where
date-in-internal-format
is the name of a variable or field that contains a date in internal format. The option
variable @DA TE can be specified to give the current date in internal format.
*
specifies the default display format. The default display format specifies the date in the
form month/day/year. It is comparable to the display-format "M2/D2/Y2"
display-format
is the format for printing a date. Display-format must be specified within quotation
marks (" "). Display-format can include date keywords, and other characters such as
blanks, commas, hyphens, or slashes. The date keywords are:
M specifies a month.
D specifies a day.
Y specifies a year.
A abbrieviates or completely spells out the month or day. If n is specified with the
keyword A, only n letters are displayed.
When you want a date printed, the date must be in internal format. For instructions on how to con-
vert a date to internal format, refer to the JULIAN-DATE or TIMESTAMP-DATE clause in this
section. The date can be a target-item within a LIST statement or any element that can be modified
by an AS DATE clause within a print list.
5-22
Clauses
AS DATE Clause
required. Change the default format by redefining the @DA TE-FORMA T option variable discussed
in this section.
5-23
Clauses
AS TIME Clause
AS TIME CLAUSE
The AS TIME clause allows you to specify the display format for printing a time. The syntax of the
AS TIME clause is:
*
specifies the default display format which specifies the hour, minut(~, and second as
HB2:MB2:SB2 (see the following description of display-format). When the default display
format is used military time is displayed.
display-format
is the format for printing the time. Displayjormat must be specified within quotation
marks (U "). Display-format can be specified by using time keywords and other characters
such as blanks, commas, hyphens, or slashes. In addition alphanumeric characters enclosed
in apostrophes (' ') can be embedded within display-format. The time keywords are:
H specifies an hour.
M specifies a minute.
S specifies a second.
P expresses the hour as modulo 12 with AM or PM.
B suppresses leading zeros.
n an integer digit specifying the number of digits (1 or 2) printed.
-------------------------------------~
If you want ENFORM to print the time, it must be in internal format. For instructions on how to
convert a time to internal format, refer to the TIMESTAMP-TIME clause in this section. The time
can be a target-item within a LIST statement or any element that can be modified by an AS TIME
clause within a print list.
Default Time Display Format
ENFORM's default time format, uHB2:MB2:SB2", might handle most of the time formatting
required. Change the default format by redefining the @TIME-FORMA T option variable discussed
in this section.
Examples of the Time Display Format
These time keywords produce the following:
HB2 1, 2, .... ,24
HP2 01,02, .... ,12 AM or PM
HPB2 1, 2, .... ,12 AM or PM
M2 00,01, .... ,59
MB2 0, 1, .•.. ,59
S2 00,01, .... ,59
SB2 0, 1, .... ,59
5-24
Clauses
A T END PRINT Clause
The AT END PRINT clause prints information at the end of the current report. This clause is an
optional part of the LIST statement. The syntax of the AT END PRINT clause is:
where
print-list
contains any combination of literals, FORM, SKIP, SPACE and 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.
Clauses that can be used in a print-list are described in this section. The other elements
are described in Section 3.
If you specify a field name within the print-list of an AT END PRINT clause, ENFORM prints the
same value as in the last row of the report. A field name appearing within the print-list of an AT
END PRINT clause need not be explicitly included within the associated LIST statement. If the
field name is not included, ENFORM in effect adds the field to the LIST statement with a
NOPRINT clause.
Spacing Considerations
By default, the information you specify in the print-list of an AT END PRINT clause begins printing
in the same column position as the leftmost column of the report. Using the SPACE or TAB clause
as the first element of the print-list overrides the default. SPACE or TAB clauses can be used
anywhere within the print-list. In the following example, the SPACE clause causes the two literals
to be separated by 15 spaces:
If you specify either a SKIP clause or the slash symbol (f) within a print-list, EN FORM 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 print-list causes ENFORM to print two lines:
Using the FORM clause within the print-list causes ENFORM to start a new page, increment the
page number, and continue with the rest of the print-list.
5-25
Clauses
AT END PRINT Clause
Using the CENTER clause following the print-list centers the information within the leftmost and
rightmost columns of the report.
The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in this section.
The optional AT END PRINT clause prints information only for the current report. This clause tern··
porarily overrides the session-wide AT END statement. If you want to print information at the end
of all subsequent reports in the current session, use the AT END statement.
Temporarily override session-wide AT END information by specifying the AT gND PRINT clause
with" " for the print-list parameter.
5-26
Clauses
AT START PRINT Clause
The AT START PRINT clause allows you to specify information to be printed just before the first
set of column headings for the current report. This clause is an optional part of the LIST statement.
The syntax of the AT START PRINT clause is:
where
print-list
contains any combination of literals, FORM, SKIP, SPACE or TAB clauses. A 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 appear in a print-list are described in this section. The other
elements are described in Section 3.
The AT START PRINT clause differs from both the TITLE and SUBTITLE statements and clauses
in that a title or subtitle is printed on every page of a report while the AT START PRINT informa-
tion is printed only on the first page of a report. The information supplied in an AT START PRINT
clause prints after either a title or a subtitle.
If you specify a field name within a print-list of an AT START PRINT clause, ENFORM prints the
same field value as in the first row of the report. A field name appearing within the print list of a AT
START PRINT clause need not be explicitly included within the associated LIST statement. If the
field name is not included, ENFORM in effect adds it with a NOPRINT clause.
Spacing Considerations
By default the AT START PRINT 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:
5-27
Clauses
AT START PRINT Clause
If you specify either a SKIP clause or the slash symbol (f) within a print-list, EN FORM advances one
or more lines before printing the rest of the 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 causes two
lines to be printed:
The use of the FORM clause within a print-list causes ENFORM to start a new page, increment the
page number, and continue with the rest of the print-list.
Using the CENTER clause following the print-list of the AT START PRINT clause centers the
information within the leftmost and rightmost columns of the report.
The CENTER, Option Variables, SKIP, SPACE, and TAB clauses are described in this section.
An AT START PRINT clause only prints information for the report generated by the associated
LIST statement. It temporarily overrides the session-wide AT START statement. If you want to
print the same information just before the first set of column headings for all subsequent reports in
the current session, use the AT START statement.
Temporarily override the session-wide AT START statement by using the AT START PRINT
clause with" " for the print-list parameter.
5-28
iW, _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ,
Clauses
BEFORE CHANGE Clause
The BEFORE CHANGE clause allows you to specify information to be printed following the
records for each group for the current report. The BEFORE CHANGE clause is an optional part of
the LIST statement. The syntax of the BEFORE CHANGE clause is:
where
by-item
is any combination of literals, FORM, SKIP, SPACE or TAB clauses. A 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 used in a print-list are described in this section. The other
elements are described in Section 3.
The keyword BEFORE in the BEFORE CHANGE clause refers to the values printed, not to the
location of the printed information. For the exact location of where the BEFORE CHANGE infor-
mation is printed within a report, refer to the ENFORM Users Guide.
When more than one BEFORE CHANGE clause is specified, ENFORM prints the BEFORE
CHANGE information in the order in which the BEFORE CHANGE clauses are entered.
If you specify a field name within a print-list of a BEFORE CHANGE clause, ENFORM prints the
same field value in the last row of the previous group; that is, before the value changes. A field
name appearing within the print-list of a BEFORE CHANGE clause need not be explicitly included
within the LIST statement. If the field name is not included, ENFORM in effect adds it with a
NOPRINT clause.
Spacing Considerations
By default the BEFORE CHANGE clause 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 five spaces:
5-29
Clauses
BEFORE CHANGE Clause
If you specify either a SKIP clause or the symbol / (slash) within a print-list, EN FORM advances one
or more lines before printing the rest of the BEFORE CHANGE print-list. The number of lines
advanced can be affected by one or more of the following: the digit (if any) fol1owing the keyword
SKIP, the number of slashes specified, or the option variable @VSPACE. In the following example,
the SKIP clause causes two lines to be printed:
Using the CENTER clause following the print-list of a BEFORE CHANGE clause centers the infor-
mation within the leftmost and rightmost columns of the report.
The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in in this section.
5-30
Clauses
BY and BY DESC Clauses
The BY and BY DESC clauses group and sort target-records according to the value of a specified
field. The syntax of the BY and BY DESC clauses is:
BY } by-i tem
{ BY DESC
where
by-item
is the name of a field from an input record whose values are to be used to group and sort
target-records.
BY and BY DESC clauses group and sort records according to the field values. The BY clause sorts
the records in ascending order according to the value of the specified field; the BY DESC clause
sorts in descending order. The following example groups and sorts the partnum field:
BY partnum,
When more than one sort is specified. EN FORM uses a major to minor sort precedence. EN FORM
determines the sort precedence by the order in which a BY or BY DESC clause appears in a LIST or
FIND statement. The first BY or BY DESC clause has the highest priority. the next one second
priority. down to the last BY or BY DESC clause.
When a BY or BY DESC clause is used with a LIST statement. EN FORM prints only the first
instance of a grouped value in a report. When a BY or BY DESC clause is used with a FIND state-
ment. EN FORM writes all of the values of a grouped value to the physical output file or transmits
all of the values to the host language program.
Several clauses require that a field be grouped by a preceding BY or BY DESC clause. Refer to the
CUM. PCT. SUBTOTAL. AFTER CHANGE and BEFORE CHANGE clauses in this section and
Target Aggregates in Section 3.
5-31
Clauses
CENTER Clause
CENTER CLAUSE
The CENTER clause centers an object within its context. The syntax of the CENTER clause is:
{ bY-ltem
tar~et-item } CENTER
CENTER ALL
where
target-item
is a record name, a field name, a string literal, a predefined aggregate, a user aggregate,
an arithmetic expression, an IF/THEN/ELSE expression, a user variable, or a System
Variable clause.
by-item
The CENTER clause causes a target-item or by-item to be centered under its column heading.
Numeric data is normally right-justified; alphabetic data is normally left-justified. Target-items and
by-items are centered based on the width for which they are formatted, not their actual values. If
the space divides unevenly, ENFORM places the extra space to the right of the item.
The CENTER ALL clause causes all elements in a LIST statement to be centered under their
headings. It must follow the WHERE clause in the LIST statement. Refer to the Byntax of the LIST
statement in Section 4 for the relative locations of the clauses within a LIST statement.
The CENTER clause following the print list of an AT END statement or clause, an AT START
statement or clause, an AFTER CHANG]~ clause, a BEFORE CHANGE clause, a FOOTING state-
ment or clause, a SUBTITLE statement or clause, a SUBFOOTING statement or dause, or a TITLE
statement or clause, centers the print list information within the leftmost and rightmost columns of
the report.
5-32
,,'-,--------------------,--------------
Clauses
CUM Clause
CUM CLAUSE
The CUM clause allows you to specify printing of a running total for a numeric target-item either
for all the instances of the target-item or for the instances of the target-item grouped within the
each value of a by-item. The syntax of the CUM clause is:
where
target-item
by-item
When you specify the CUM OVER ALL clause, ENFORM prints a running total in place of each
value of the numeric target-item. When you specify only CUM, ENFORM assumes CUM OVER
ALL.
When you specify the CUM OVER by-item clause, ENFORM prints a running total for the instances
of the numeric target-item within the by-item in place of the value of the numeric target-item. The
by-item must be previously defined by a BY or BY DESC clause. The running total begins anew
each time the by-item value changes. The following example prints the running total of all parts for
each location:
LIST BY location,
partnum,
inventory,
inventory CUM OVER location;
Part CUM
LOCATION Number INVENTORY INVENTORY
-------- --------- ---------
L98 5103 8 8
5502 6 14
V66 6603 40 40
5-33
Clauses
CUM Clause
When a numeric target-item with a CUM clause is assigned to a user variable, ENFORM assigns the
value to the user variable first, before the running total is calculated. When the user variable is
referenced as a target-item element in a LIST statement or as an element within a LIST target-
item, ENFORM uses the value of the user variable. When the user variable is referenced in a print
list, EN FORM uses the value of the running total.
Restrictions
Note that you cannot combine the CUM clause with the PCT clause, the TOTAL clause" or the SUB-
TOTAL clause.
5-34
Clauses
FOOTING Clause
FOOTING CLAUSE
The FOOTING clause allows you to specify information for printing at the bottom of each page for
the current report. This clause is an optional part of the LIST statement. The syntax of the
FOOTING clause is:
where
print-List
can be any combination of literals, FORM, SKIP, SPACE, or TAB clauses. A print-list can
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 variable names, or parameter names.
The clauses that can be used in a print-list are described in this section. The other
elements are described in Section 3.
If you specify a field name within a print-list of a FOOTING clause, ENFORM prints the same field
value as in the last row of data on the current report page. A field name appearing within the
FOOTING clause need not be explicitly included within the LIST statement. 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:
If you specify either a SKIP clause or the slash symbol (J) 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 causes two lines to be printed:
Report 2-A
TotaL SaLes
5-35
Clauses
FOOTING Clause
Using a FORM clause within a FOOTING statement forces a new page. Printing eontinues with the
remainder of the FOOTING print-list, starting at the top of the next physical page. 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 the logical page.
Using the CENTER clause centers the footing within the leftmost and rightmost columns of the
report.
The CENTER, Option Variables, SKIP, SPACE, and TAB clauses are described in this section.
A FOOTING clause within a LIST statement prints a footing only for the (~urrent report. A
FOOTING clause temporarily overrides a sessionwide FOOTING statement. A FOOTING state-
ment prints a footing at the bottom of each page for all subsequent reports in the current session.
5-36
Clauses
FORM Clause
FORM CLAUSE
The FORM clause allows you to control when to skip to a new page. The syntax of the FORM clause
is:
FORM [ number ]
where
number
is an unsigned integer.
When the FORM clause follows a field name that has been grouped with a BY or BY DESC clause,
ENFORM starts a new page whenever the field value changes. If number is specified, ENFORM
starts a new page only if there are fewer than that number of lines remaining on the current page.
The following example shows the use of the FORM clause with a by-item:
BY regnum FORM,
When the FORM clause precedes a target-item, ENFORM starts a new page each time the target-
item is printed. When the FORM clause follows a target-item, ENFORM prints the target-item
before starting a new page. The number parameter is not allowed when the FORM clause modifies a
target-item.
The FORM clause can be part of a print list for an AFTER CHANGE, AT START PRINT, AT END
PRINT, BEFORE CHANGE, FOOTING, SUBFOOTING, SUBTITLE, or TITLE clause or state-
ment. ENFORM starts printing on a new page everytime the FORM clause is processed. When used
with a print list, the FORM clause does not use the number parameter.
5-37
Clauses
HEADING Clause
HEADING CLAUSE
The HEADING clause allows you to override the default column title for a target-item or by-item in a
report. The HEADING clause also allows you to define a column title for target-items, such as
arithmetic expressions, that do not have a default column title. The syntax of the HEADING clause is:
where
by-item
target-item
is a record name, a field name, a numeric literal, a predefined aggregate, a user ag-
gregate, an arithmetic expression, an IF/THEN/ELSE expression, a lLlser variable, a
System Variable clause, or a JULIAN-DATE clause.
heading-string
is a string literal. Remember string literals must be enclosed within quotation marks (" ").
Default Headings
When the HEADING clause is not specified explicitly, EN FORM obtains a heading from one of
these sources:
• the field name specified in the dictionary or name of the user variable, aggregate, or table
specified in a DECLARE statement
If you want to print more than one target-item or by-item under the same column heading, use a
NOHEAD clause to prevent ENFORM from printing the unwanted heading. The NOHEAD clause
is discussed later in this section.
Multiple line headings are created by using a slash (f) within the heading string.
Sometimes, the / character needs to appear within a column heading. In this case, use the SET state··
ment described in Section 4 to change the @NEWLINE option variable from a / to a different
character. After the new line character is redefined, the new special character can be used within
the heading string instead of the / character. In the following example, the new line character is
changed to a number sign (H) causing Region and Number to print on two lines, and the symbol / in-
side the print list is printed between Branch and Number.
5-38
Clauses
HEADING Clause
Region
Number Branch/Number
Notice that when the / symbol appears outside of the heading clause, it causes ENFORM to advance
1 line before printing the next target-item. Changing the @NEWLINE character does not affect
this use of the / symbol.
When a single subscripted element is modified by a HEADING clause, ENFORM prints the
specified heading. For example:
MARCH
When an element including a subscript range is modified by a HEADING clause, ENFORM includes
the subscript in the specified heading. For example:
If a HEADING clause is not included, ENFORM includes the subscript with the default heading.
For example:
LIST month [ 3 ];
MONTH
[ 3 ]
Remember the default heading for a field name is either the heading declared in the dictionary or if
no heading is so declared, the field name. The default heading for a user variable is either the
heading defined in the DECLARE statement, or if no heading is defined, the user variable name.
5-39
Clauses
INTERN AL Clause
INTERNAL CLAUSE
'rhe INTERNAL clause allows you to specify the storage format for a user defined element. The
syntax of the INTERNAL clause is:
INTERNAL internal-format
where
internaL-format
is the format for storing the user-defined element. Internal-format can be:
The optional INTERNAL clause can appear in a PARAM or DECLARE statement. When the
INTERN AL clause is not used, EN FORM stores user-defined elements (variables, aggregates,
tables, and parameters) as 64-bit signed integers. The following INTERNAL clause specifies the
internal-format as fixed. The element has a total length of 8 digits with 2 digits following the
decimal point:
INTERNAL F8.2
5··40
Clauses
JULIAN-DATE CONVERSION Clause
The JULIAN-DATE Conversion clause allows you to specify translation of a date target-item into
internal format. The syntax for the JULIAN-DATE Conversion clause is:
where
year
month
day
Dates are a common part of data base records. From an information standpoint, dates need to be
printed on a report in a form recognizable as a date, such as 05/15/72, Apr 1, 1979 or 06-01-1970.
From an analytical standpoint, dates need to be stored in a form for use in calculations or expres-
sions, such as 80 11 27. Dates used in calculations or expressions must be in an internal format. If the
date is not in this internal format, it can be converted by using the JULIAN-DATE Conversion
clause. The internal format represents a date as the number of days which have elapsed from an ar-
bitrary date in the past.
To change a date to internal format, use the JULIAN-DATE Conversion clause. For example,
assume the data description entry of the day and year portion of a data base date is as follows:
05 date.
10 yy PIC "99".
10 mm PIC "99".
10 dd PIC "99".
The month (1-12), day (1-31), and year (4 digit number) can be passed to the JULIAN-DATE Conver-
sion clause as follows:
Notice the numeric literal 1900 was added to make a 4 digit year.
Gregorian dates must be converted to an internal date format when used for purposes other than
printing on a report. When the date only needs to be printed, convert it with the JULIAN -DA TE
clause and then use an AS DATE Conversion clause. For example:
5-41
Clauses
JULIAN-DATE CONVERSION Clause
Alternatively, convert the date to an integer that can be formatted with an AS cllause. For example~
date AS M<99-99-99>
To convert a date stored as a yearly Julian date, where the day of the year is relative to January 1
of that year, define each part of the date:
05 yearly-julian-date.
10 day-af-year PIC "999".
10 current-year PIC "99".
Then add day-of-year to the internal date for December 31 of the previous year:
Display Format
To print a date in internal format on a report, convert the date to a display format with an AS
DA TE clause. The AS DATE clause is discussed in this section.
5-42
Clauses
NOHEAD Clause
NOHEAD CLAUSE
The NOHEAD clause allows you to specify suppression of the printing of the column heading of a
target-item or by-item. The syntax of the NOHEAD clause is:
NOHEAD ALL
where
target-item
by-item
The NOHEAD clause following a LIST target-item suppresses the column heading for the target-
item.
Sometimes it is undesirable to print a column heading for an item such as when you want to print
more than one target-item under the same column heading. In the following example, the address,
city, and state are all printed in the same column:
LI ST suppnum,
address / TAB 10,
city NOHEAD / TAB 10,
state NOHEADi
SUPPNUM ADDRESS
The NOHEAD ALL clause suppresses column headings for all the target-items specified in a LIST
statement. It must follow the WHERE clause in the LIST statement. Refer to the syntax of the
LIST statement in Section 4 for the relative locations of the clauses within a LIST statement.
5-43
Clauses
NOPRINT Clause
NOPRINT CLAUSE
The NOPRINT clause allows you to specify suppression of the printing of a target-item or by-item
and its associated column heading. The syntax of the NOPRINT clause is:
NOPRINT ALL
where
target-item
is a record name, a field name, a numeric literal, a predefined aggregate, a user
aggregate, an arithmetic expression, an IF/THEN/ELSE expression, a user table name, a
user variable, a System Variable clause or a JULIAN-DATE clause.
by-item
is the name of a field grouped by a BY or BY DESC clause.
-----------------------------------_.
The NOPRINT clause following a LIST target-item or by-item suppresses the printing of the
target-item or by-item and its heading. The target-item or by-item can still be used for sorting?
grouping, or calculations elsewhere in the report.
You can use the NOPRINT clause to suppress printing of a target-item or by-item within the body
of a report. In the following example, the records are grouped by region, but the region number is
not printed as a by-item in the report. Instead the region number is printed at the end of the group
using a BEFORE CHANGE clause:
BRANCHNUM MANAGER
1 7S
2 129
Region
The NOPRINT ALL clause suppresses the printing of all column and column headings. It must
follow the WHERE clause in the LIST statement. Refer to the syntax of the LIST statement in Sec-
tion 4 for the relative locations of the clauses within a LIST statement.
Title and summary information, using AT END, AT START, FOOTING, SUBFOOTING, SUB-
TITLE, TITLE statements and clauses, and AFTER CHANGE and BEFORE CHANGE clauses still
appear in the report. This is useful for reports where only summary information is desired.
5-44
Clauses
OPTION VARIABLE Clauses
The Option Variable clauses allow you to redefine the default values for several operational
variables. Refer to the SET statement in Section 4. The Option Variables and their legal values are:
@BLANK-WHEN-ZERO
@BREAK-KEY
@CENTER-PAGE {ON }
@HEADING TO
@STATS OFF
@SUMMARY-ONLY
@WARN
@COPIES
@COST-TOLERANCE
@DISPLAY-COUNT
@LINES
@MARGIN
@PAGES
@PRIMARY-EXTENT-SIZE TO number
@SECONDARY-EXTENT-SIZE
@READS
@SPACE
@TARGET-RECORDS
@VSPACE
@WIDTH
@DECIMAL }
@NEWLINE TO "character"
@NONPRINT-REPLACE
{ @OVERFLOW
@UNDERLINE
@SUBTOTAL-LABEL TO string-LiteraL
J @DATE-FORMAT
l @TIME-FORMAT
I TO dispLay-format
where
number
is an integer.
"character"
string-LiteraL
is a string literal; remember string literals must be enclosed in quotation marks (" 99).
dispLay-format
specifies the default format for printing dates or times when AS DATE * and AS TIME *
clauses are used; must be enclosed in quotation marks.
5-45
Clauses
OPTION VARIABLE Clauses
@BLANK-WHEN-ZERO
When set to ON, ENFORM suppresses the printing of target-item or by-item values of
zero in reports. When set to OFF, zeros are printed. Default is OFF.
@BREAK-KEY
When set to ON, pressing the BREAK key while a query is executing, either terminates
output (if output is being produced) or terminates the current query and returns you to
the ENFORM prompt. Refer to Section 2 for more information. When set to OFF, press-
ing the BREAK key temporarily suspends output and returns you to the Command Inter-
preter prompt but it does not terminate processing. Output resumes when you enter the
Command Interpreter PAUSE command. If the file specified in the IN option of the
EN FORM command is not a terminal, ENFORM ignores the BREAK key regardless of
the setting of @BREAK-KEY. Default is ON.
@CENTER-PAGE
When set to ON, ENFORM centers the report body on the page according to the listing
device's maximum page width. If the @MARGIN Option Variable clause is also set, that
margin value is added to the left after centering.
This clause does not center the TITLE, SUBTITLE, AT START, AT END, FOOTING, or
SUBFOOTING information within the report body. In effect the entire report body is
moved enough spaces to the right to cause it to be centered on the page.
When not set or set to OFF the report begins in column one. Default is OFF.
@COPIES
@COST-TOLERANCE
This does not mean that an EN FORM session which meets critera for level 2 will always
take less time to run than another ENFORM session which requires level 7. The execu-
tion time also depends on the amount of data that must be processed.
When not set or set to 0 (zero), ENFORM proceeds with whatever strategy it chooses.
If the strategy specified is exceeded, an error message is received and the ENFORM pro-
gram stops. ---....
5-46
Clauses
OPTION VARIABLE Clauses
@DATE-FORMAT
specifies a default format for printing dates when AS DATE * is used. For date format
specifications, refer to the AS DATE clause in this section. The default is "M2/D2/Y2".
@DECIMAL
When set to a single ASCII character, ENFORM prints that character for a decimal
point. EN FORM also accepts the specified character in place of a decimal point in a
numeric literal. The default value is the period character (.).
@DISPLAY-COUNT
determines how many lines to display on output device at one time. When number lines
are displayed, ENFORM pauses. To continue the display, press the carriage return.
Execution of the ENFORM program, while at the pause, can be aborted by:
Control returns to ENFORM. To reset the display count so that the entire EN FORM pro-
gram is printed, enter 0 for number. Specifying @DISPLAY-COUNT when using an
ENFORM server (described in the ENFORM Users Guide) is inadvisable. The default
value is O.
@HEADING
When set to ON, EN FORM prints column headings in the report. When set to OFF,
EN FORM does not print headings. OFF is equivalent to NOHEAD ALL for every report.
The default is ON.
@LINES
specifies how many lines are to be printed per page. The default value is 60.
5-47
Clauses
OPTION VARIABLE Clauses
@MARGIN
specifies the left margin size in columns for reports. The default value is 0 (zero).
@NEWLINE
The new line character can appear within a heading string, inside the quotation marks. It
is used to specify multiple line column headings. The @NEWLINE Option Variable
clause can be reset to any single ASCII character except circumflex (") or hyphen (-). The
default NEWLINE character is / (slash).
@NONPRINT-REPLACE
EN FORM prints the replacement character for values which do not have a printable
character. When this clause is set to a character, that character is printed for values
which do not have a printable character. The default value is OFF.
@OVERFLOW
When a value does not fit within its formatted width, ENFORM replaces the value with
overflow characters. When this clause is set to a single ASCII character, ENFORM
prints that character when overflow occurs. The default overflow character is an asterisk
(*).
@PAGES
specifies a maximum number of pages to print per report. The default value is 32,767
pages.
@PRIMARY-EXTENT-SIZE
When this clause is not set, ENFORM calculates an estimate of the primary and sec-
ondary extent sizes needed for each output file. The estimate could be too large, creating
a file system error 43 unable to obtain disc space for file extent; or the estimate could be
too small, producing more data than the file can hold. Each time an output file is full,
ENFORM must create a new output file, with a larger extent size, and copy the data from
the full file into the new file. This results in very inefficient processing.
@READS
specifies the maximum number of records to be returned from the data base per
EN FORM program. This is a useful tool when debugging. For an idea of how many reads
are required by a given ENFORM program, see the @STATS Option Variable clause. To
remove a limit, set the @READS Option Variable to 0 (zero). The default value is
unlimited.
@SECONDARY-EXTENT-SIZE
specifies the extent size of the output files. When this clause is not set, ENFORM uses
the primary-extent size. ~
5-48
Clauses
OPTION VARIABLE Clauses
iilSPACE
specifies how many blanks appear between report columns. The default value is two
blanks.
iilSTATS
When set to ON, ENFORM prints the statistics regarding the records after the
ENFORM program is completed. ENFORM prints the following statistics:
LEVEL READ order this physical file was read in relation to all physical files
read. The first file read is indicated by the number 1.
RECORDS READ total number of logical records read from this physical file.
STRATEGY COST number, 1 through 8, used to represent the cost of the strategy
EN FORM developed to handle the ENFORM program. For a
definition of the cost numbers, refer to the @COST-
TOLERANCE option variable.
iilSUBTOTAL-LABEL
specifies a character string which is to appear on the same line as and to the left of the
subtotal. ENFORM prints the character string in the column of the group item over
which the subtotal is computed. If the item is defined with the NOPRINT clause,
EN FORM does not print the character string. If the character string does not fit in the
column, ENFORM truncates it on the right. The character string can be from 1 to 15
ASCII characters, enclosed within quotation marks. The default value is an asterisk (*).
iilSUMMARY-ONLY
causes a summary report to be produced. See the explanation of summary reports found
with the LIST and FIND statements in Section 4.
iilTARGET-RECORDS
specifies the maximum number of records to be selected per EN FORM program. The
default value is zero, meaning no limit. Setting @TARGET-RECORDS to number when
your query contains BY, BY DESC, ASCD, or DESC clauses returns the first target-
records produced by the query processor which are not necessarily the first records that
appear in a full report. ~
5-49
Clauses
OPTION VARIABLE Clauses
@TIME-FORMAT
specifies a default format enclosed within quotation marks for printing times when AS
TIME * is used. For time format specifications, refer to the AS TIME clause in this sec-
tion. The default value is "H2:M2:S2".
@UNDERLINE
specifies a single ASCII character used to underline headings and totals. To specify no
underlining, set the @UNDERLINE Option Variable clause to blank, " ". The default
character is "_".
@VSPACE
specifies how many lines are skipped before a report line when the SKIP clause is used.
The default number is one.
@WARN
specifies when warning messages are to appear on the terminal. When set to OFF, warn-
ing messages do not appear. The default is ON.
@WIDTH
specifies the maximum width of the output. The maximum value is 132 characters.
Verify the device's width before using this clause. This clause is conveni,ent for setting a
report page width smaller than the device's default width. The default wlidth is the width
of the output device being used. The default value for unstructured disc files is 132.
---_. __. _ - - - - - - - - - - - - - - - - - - - - _ .
15-50
Clauses
PCT Clause
PCT CLAUSE
The PCT clause prints the percentage of the grand total for a numeric target-item, based either on a
total figure for all instances of the target-item or a total for the instances of the target-item grouped
over a by-item. The syntax of the PCT clause is:
target-item
is a field name, a numeric literal, the predefined aggregates SUM and COUNT, an
arithmetic expression, an IF/THEN/ELSE expression, a user table name, a System
Variable clause. The data type of the target-item used in a PCT clause must be numeric.
by-item
When the PCT OVER ALL clause is used, ENFORM prints a percentage of the grand total for the
numeric target-item in place of each target-item value. When only PCT is specified, ENFORM
assumes PCT OVER ALL.
When the PCT OVER by-item clause is used, ENFORM prints the percentage of the instances of the
numeric target-item within the group in place of each target-item value. The group must have been
defined earlier by a BY or BY DESC clause. In the following example, ENFORM prints the percen-
tage value of the cost of one part over the total value of all the parts at each location. For example,
consider the following query and report:
LIST BY location,
partnum,
price,
price PCT OVER location;
Part PCT
LOCATION Number PRICE PRICE
-------- --------- ---------
H76 3102 4800.00 66.67
7301 2400.06 33.33
H57 2402 7500.00 41.67
3103 10500.00 58.33
5-51
Clauses
PCT Clause
The SUBTOTAL OVER clause can be combined with the PCT OVER clause, causing ENFORM to
print the percentage the subtotal is of the total value of the target-item. ENFORM does not print
the value of each target-item. The percentage values do not always exactly total 100 0/0 due to trunca-
tion during division. If you execute the following query for example, the total percentage values do
not equal 100 0/0:
OPEN employee;
LIST BY regnum, empname, salary peT, SUBTOTAL OVER regnum;
When a numeric target-item with a PCT clause is assigned to a user variable, ENFORM makes the
assignment to the user variable first, before the percentage is calculated. When the user variable is
referenced as a target-item in a LIST statement or as an element within a target-item, of a LIST
statement, ENFORM uses the value of the user variable. When the user variabh~ is referenced in a
print list, ENFORM uses the value of the percentage for the user variable.
Restrictions
Note that you cannot combine the PCT clause with the CUM clause.
5-52
Clauses
SKIP Clause
SKIP CLAUSE
The SKIP clause allows you to indicate the number of lines ENFORM should move forward before
continuing printing. The syntax of the SKIP clause is:
SKIP [ number ]
where
number
Sometimes it is desirable to print more than one target-item under the same column heading. If you
want to do this, you can specify a SKIP clause after the first target-item, then use the TAB clause to
position the printing of the second target-item under the first target-item. The second target-item
should be modified by a NOHEAD clause to prevent ENFORM from printing the unwanted column
heading. ENFORM prints the target-items under a a suppressed column heading, one target-item
per line.
The option variable @VSPACE affects the number of lines ENFORM advances when the SKIP
clause is specified. Refer to the Option Variable Clause in this section for more information.
The SKIP clause can precede or follow a target-item or by-item within a LIST statement. If number
is specified, ENFORM moves forward the specified number of lines before printing continues. If
number is not specified, EN FORM moves forward to the next line.
In the following example, address and city are printed in the same column on separate lines.
LIST address,SKIP,
city NOHEAD SKIP 2;
ADDRESS
UNIVERSITY WAY
PHILADELPHIA
The SKIP clause can be part of the print list of an AT END statement or clause, an AT START
statement or clause, a FOOTING statement or clause, a SUBFOOTING statement or clause, a SUB-
TITLE statement or clause, or an AFTER CHANGE or BEFORE CHANGE clause. When number
is specified, ENFORM moves forward the specified number of lines every time the SKIP clause is
processed. When number is not specified, EN FORM moves forward to the next line when the SKIP
clause is processed.
5-53
Clauses
SPACE Clause
SPACE CLAUSE
The SPACE clause allows you to specify horizontal spacing. The syntax of the SPACE clause is:
SPACE [ number]
where
number
is an integer.
The SPACE clause can precede either a target-item or a by-item within a LIST statement. When
number is specified, ENFORM inserts the specified number of spaces every time the SPACE clause
is processed. When number is not specified, one space is inserted.
The default spacing between columns on a report is initially set to two spaces. It can be temporarily
overriden by using the SPACE clause with the number parameter. To delete all spaces between
columns, use SPACE o.
The SPACE clause can be part of a print list for an AFTER CHANGE, BEFORE CHANGE, AT
START PRINT, AT END PRINT, FOOTING, SUBFOOTING, SUBTITLE, or TITLE clause or
statement. When number is specified, ENFORM inserts the specified number of spaces every time
the SPACE clause is processed. When number is not specified, one space is inserted.
5-54
Clauses
SUBFOOTING Clause
SUBFOOTING CLAUSE
The SUBFOOTING clause allows you to specify printing of information at the bottom of each page
preceding the footing for the current report. This clause is an optional part of the LIST statement.
The syntax of the SUBFOOTING clause is:
where
print-list
contains any combination of literals, FORM, SKIP, SPACE, or TAB clauses. A 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 described in this section. The other
elements are described in Section 3.
If you specify a field name within a print-list of a SUBFOOTING clause, ENFORM prints the same
field value as the last row of data on the current page. A field name appearing within the SUB-
FOOTING clause need not be explicitly included within the LIST statement. If the field name,
ENFORM effectively adds the field to the LIST statement with a NOPRINT clause.
Spacing Considerations
By default the footing begins in the same 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:
If you specify either a SKIP clause or the slash symbol (j) within a print-list, ENFORM advances one
or more lines before printing the rest of the SUBFOOTING 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 causes two lines to be printed:
Report 2-A
Total Sales
5-55
Clauses
SUBFOOTING Clause
Using the FORM clause within a SUBFOOTING statement forces a new page. ENFORM continues
printing the remainder of the SUBFOOTING print-list, starting at the top of the next physical page.
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 SUBFOOTING on the next. The
same page number applies to all physical pages in the logical page.
Using the CENTER clause centers the subfooting within the leftmost and rightmost columns of the
report.
The CENTER, Option Variables, SKIP, SPACE, and TAB clauses are described in this section.
A SUBFOOTING clause within a LIST statement prints a subfooting only for the current report. A
SUBFOOTING clause temporarily overrides a session-wide SUBFOOTING statement. A SUB-·
FOOTING statement prints a subfooting at the bottom of each page for all subsequent reports in
the current session.
5-56
Clauses
SUBTITLE Clause
SUBTITLE CLAUSE
The SUBTITLE clause allows you to specify printing of information at the top of each page imme-
diately following the title for the current report. This clause is an optional part of the LIST state-
ment. See also the TITLE clause in this section and the SUBTITLE statement in Section 4. The syn-
tax of the SUBTITLE clause is:
where
print-list
contains any combination of literals, FORM, SKIP, SPACE, or TAB clauses. A 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 described in this section. The other
elements are described in Section 3.
If you specify a field name within a print-list of a SUBTITLE clause, EN FORM prints the same field
value as in the first row of the report. A field name appearing within the SUBTITLE clause need
not be explicitly included within the associated LIST statement. If the field name is not included,
ENFORM in effect adds it with a NOPRINT clause.
Spacing Considerations
By default the subtitle begins in the same 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 literal to be separated by 15 spaces:
If you specify either a SKIP clause or the slash symbol (f) within a print-list, ENFORM advances one
or more lines before printing the rest of the SUBTITLE 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 causes two lines to be printed:
Report 2-A
Total Sales
5-57
Clauses
SUBTITLE Clause
Using the FORM clause within the print-list causes EN FORM to start a new page. ENFORM con-
tinues with the remainder of the print-list starting at the top of the next physi.cal page. The page
number remains the same.
Using the CENTER clause centers the subtitle within the leftmost and rightmost columns of the
report.
The CENTER, Option Variable, SKIP, SPACE, and TAB clauses are described in this section.
A SUBTITLE clause within a LIST statement prints a subtitle only for the current report. It tem-
porarily overrides the session-wide SUBTITLE statement. A SUBTITLE statement prints a sub-
title at the top of each page immediately following the title for all subsequent reports in the current
session.
5-58
Clauses
SUBTOTAL Clause
SUBTOTAL CLAUSE
The SUBTOTAL clause allows you to specify the printing of a subtotal for a numeric target-item.
This clause is an optional part of the LIST statement. The syntax for the SUBTOTAL clause is:
where
target-item
by-item
When the SUBTOTAL clause is specified, ENFORM prints prints the subtotals for each target-item
within a by-item value. EN FORM prints the subtotal in the column of the target-item being sub-
totaled and precedes the subtotal by a row of underline characters specified by the @UNDERLINE
option variable. ENFORM marks the subtotal with a subtotal string specified by the
@SUBTOTAL-LABEL option variable. Refer to the Option Variable clauses in this section.
When a SUBTOTAL OVER clause is used, ENFORM subtotals the target-item each time the value
of the specified by-item changes. When more than one SUBTOTAL OVER clause is specified,
EN FORM prints the subtotals in the order that the clauses are entered in the LIST statement.
When a SUBTOTAL clause is used without OVER, ENFORM prints a subtotal in the specified
target-item column each time the value of any by-item appearing to the left of the target-item
changes. ENFORM prints the subtotals using a minor to major order precedence; that is: ENFORM
prints the subtotal for the first by-item to the left of the targe t-item, followed by the subtotal for
the second by-item to the left of the target-item, and so on until the subtotal for the last by-item
appearing in the report is printed.
SUBTOTAL does not generate a grand total at the end of the report. If a grand total is desired, use
the TOTAL clause. The TOTAL clause is described in this section.
If the width of the value of a subtotal exceeds the width of the format specified for a target-item, an
overflow condition occurs causing asterisks to be printed in place of the value. To prevent this,
enlarge the target-item display format by adding an AS clause to the target-item being subtotaled.
The AS clause is described in this section.
5-59
Clauses
SUPPRESS Clause
SUPPRESS CLAUSE
The SUPPRESS clause allows you to eliminate certain records from being printed in the report. The
records still contribute to the report calculations. This clause is an optional part of the part of the
LIST statement. This clause cannot be used with the FIND statement. The syntax of the SUPPRESS
clause is:
where
logical-expression
is an expression returning a true or false value. See Section 3 for more information.
The SUPPRESS clause defines a condition or conditions that prevents specific records from print-
ing throughout a report. For example, in the following query, the SUPPRI~SS clause causes
!t~NFORM to print only the inventory, part number, and part name where the inventory is greater
than zero:
Part
INVENTORY Number PARTNAME
EN FORM still includes the suppressed records in AFTER CHANGE and BEGIN CHANGE clauses,
subtotals, totals, and other calculations specified for the report. Note that the value of the first
record of an AFTER CHANGE clause or the last record of a BEFORE CHANG]~ clause is used for
the print list whether or not that record is printed.
Aggregates cannot be used in a SUPPRESS WHERE clause; however, you can reference a user
variable that has been assigned the aggregate value.
5-60
Clauses
SYSTEM VARIABLE Clauses
The System Variable clauses allow you to obtain the current value for the current date, time, line
number, and page number. The syntax for the System Variable clauses is:
@DATE
@TIME
@LINENO
@PAGENO
The @DATE and @TIME System Variable clauses return the current date and time in internal
format. When used in an expression, ENFORM treats them as numeric literals.
When the @DATE or @TIME system variables are to be printed on a report, convert them to a
display format using the AS DATE or AS TIME clauses. Frequently the default format is satisfac-
tory and can be specified by:
@DATE AS DATE *
For more information on date and time display formats, refer to to AS DATE and AS TIME clauses
in this section.
The @LINENO System Variable clause prints the current line number within a page of the report.
@LINENO can be a target-item in a LIST statement, part of an AFTER CHANGE, BEFORE
CHANGE, AT START, AT END, FOOTING, TITLE, SUBFOOTING, and SUBTITLE clauses or
statements.
The @LINENO option variable specifies how many lines are printed on a page. It is initially set to
60 lines. To change the number of lines to be printed per page, reset the @LINENO Option Variable
clause. Refer to the SET statement in Section 4 and the Option Variable clauses in this section.
The @PAGENO System Variable prints the page number. The following example prints the page
number at the top of a page:
Page 10
5-61
Clauses
TAB Clause
TAB CLAUSE
The TAB clause allows you to specify in which column in the report a target-item or by-item is to
begin. This clause is an optional part of the LIST statement and must not be specified in the FIND
statement. The syntax of the TAB clause is:
TAB [ number
where
number
is an integer.
-----------------
The TAB clause specifies which column to tab to before printing an element on a report. Care must
be taken not to overlap elements. If overlap occurs, the last numbers or characters specified appear
on the printed report. Note that TAB never causes ENFORM to advance to the next line, so you can
tab backwards on the current line.
The TAB clause can precede a target-item or by-item within a LIST statement. If number is
specified, EN FORM tabs to that position before the next target-item or by-item is printed; if
number is not specified, ENFORM begins printing in column one.
'I'he TAB clause can be part of a print list for an AT END statement or clause, an AT START state-
ment or clause, a FOOTING statement or clause, a SUBFOOTING statement or clause, a SUB-
TITLE statement or clause, and the AFTER CHANGE and BEFORE CHANGE clauses. When
number is specified, EN FORM tabs to that position before the next element is printed on the cur-
rent line. If number is not specified, ENFORM assumes column one.
5-62
Clauses
TIMESTAMP-DATE Clause
TIMESTAMp·DATE CLAUSE
The TIMESTAMP-DATE clause extracts the date portion of a timestamp field that has been
created by the GUARDIAN procedure TIMESTAMP. The syntax of the TIMESTAMP-DATE
clause is:
TIMESTAMP-DATE ( field-name)
where
field-name
is the name of a field to which the TIMESTAMP-DATE clause returns a date value. The
field must be described in the dictionary.
You must define the field that receives the date value from the TIMESTAMP-DATE clause in your
data dictionary. You must define the field as a six-character alphanumeric field, such as:
Refer to the TIMESTAMP-TIME clause in this section for extracting the time portion of a
timestamp field.
5-63
Clauses
TIMESTAMP-TIME Clause
TIMESTAMp·TIME CLAUSE
The TIMESTAMP-TIME clause extracts the time portion of a timestamp Held that has been
created by the GUARDIAN procedure TIMESTAMP. The syntax of the TIMESTAMP-TIME
clause is:
TIMESTAMP-TIME ( field-name)
where
field-name
is the name of a field to which a time value is returned. The field must be described in
your data dictionary.
Your data dictionary must contain a definition of the field to which the TIMESTAMP-TIME clause
returns a time value. You must define the field as a six-character alphanumeric field, such as:
The value returned to this field is a quantity in one hundredths of a second in internal time format.
You can obtain this value in seconds by using the AS clause with an integer edit descriptor or by
using the AS TIME clause. If you need to obtain this value in one hundredths of :a second, you must
write your own conversion routine.
Refer to the TIMESTAMP-DATE clause in this section for extracting the date portion of a
timestamp field.
5-64
.-----,-------------------------------------------
Clauses
TITLE Clause
TITLE CLAUSE
The TITLE clause allows you to specify printing of information at the top of each page for the cur-
rent report. See also the SUBTITLE clause in this section and the TITLE statement in Section 4.
The syntax of the TITLE clause is:
where
print-List
contains any combination of literals, FORM, SKIP, SPACE, or TAB clauses. A 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 described in this section. The other
elements are described in Section 3.
If you specify a field name within a print-list of a TITLE clause, ENFORM prints the same field
value as in the first row of the page. A field name appearing within the TITLE clause need not be
explicitly included within the associated LIST statement. If field name is not included, ENFORM in
effect adds it with a NOPRINT clause.
Spacfng Considerations
By default the title begins in the same 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 clauses causes the two
literals to be separated by 15 spaces:
If you specify either a SKIP clause or the slash symbol (f) within a print-list, ENFORM advances one
or more lines before printing the rest of the AFTER CHANGE print-list. The number of lines ad-
vanced 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 SPACE clause causes two lines to be printed:
Report 2-A
TotaL SaLes
5-65
Clauses
TITLE Clause
Using the FORM clause within the print-list causes ENFORM to start a new page and continue with
the rest of the print-list. The page number remains the same. A single logical page can span multi-
ple physical pages such that a TITLE appears 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 centers the title within the leftmost and rightmost columns of the
report.
The CENTER, Option Variables, SKIP, SPACE, and TAB clauses are described in this section.
A TITLE clause within a LIST statement prints a title only for the current report. It temporarily
overrides the session-wide TITLE statement. A TITLE statement prints a title at the top of each
page for all subsequent reports in the current session.
Temporarily override a session-wide TITLE statement by using the TITLE clause with .. " for the
print-list parameter.
5-66
----------------------------,----------------
Clauses
TOTAL Clause
TOTAL CLAUSE
The TOTAL clause prints the grand total for a numeric target-item. This clause is an optional part
of the LIST statement and cannot be specified in a FIND statement. The syntax of the TOTAL
clause is:
where
target-item
by-item
When the TOTAL clause is specified, EN FORM prints the grand total for a target-item or by-item
after printing the last value of the target-item or by-item. ENFORM precedes the total by two rows
of underline characters, as specified by the @UNDERLINE option variable. The Option Variable
clauses are discussed in this section.
If the width of the value of a total exceeds the width of the target-item or by-item display format, an
overflow condition occurs causing asterisks to be printed in place of the total. To prevent this,
enlarge the display format by adding an AS clause to the target-item being totaled. The AS clause is
described in this section.
5-67
Clauses
WHERE Clause
WHERE CLAUSE
The WHERE clause allows you to qualify the records that contribute to the target-record. The syn-
tax of the WHERE clause is:
WHERE LogicaL-expression
where
LogicaL-expression
is a condition that returns a true or false value. See Section 3 for more information about
logical expressions.
The logical expression in a WHERE clause defines which records are restricted from eontributing'
to the target-record. For example:
Using the WHERE clause to specify a link causes only the records which satisfy the condition
specified in the logical expression to be included in the report. The link created by the WHERE
clause remains in effect only for the associated LIST or FIND statement. For a more complete
description of linking, refer to the LINK statement in Section 4. The following example shows how
the WHERE clause is used to specify a link:
5-68
SECTION 6
COMMANDS
This section contains a complete description of the syntax of the ENFORM commands. The com-
mands are arranged in alphabetical order.
EN FORM commands are compiler directives that instruct the ENFORM compiler/report writer to
perform a specific operation. The compiler/report writer recognizes a command by the presence of a
question mark in column 1. You can either enter commands at the level of the ENFORM prompt (> )
or place commands in an EDIT file. EN FORM executes commands in an EDIT file as if they were
entered interactively with one exception: ENFORM ignores a ?RUN command in an EDIT file.
The following commands are not saved in a compiled query file (created by the ?COMPILE com-
mand): ?ATTACH, ?COMPILE, ?EDIT, ?EXECUTE, ?EXIT, ?OUT, ?RUN, ?SECTION, ?SHOW,
?SOURCE. For this reason, these commands are not used:
• Through the host language interface (described in the ENFORM Users Guide). The host
language interface uses a compiled query file.
• When you specify the ?EXECUTE command. The ?EXECUTE command can only be used with a
compiled query file.
• If the filename specified in the IN option of the ENFORM command is a compiled query file.
6-1
Commands
Summary of Commands
?DICTIONARY names a subvolume which contains a dictionary. It also clears the internal
table and reclaims table space.
?HELP displays information about the syntax of the ENFORM language. This command
can also display user-defined information.
?SHOW displays information about the environment of the current ENFORM session.
6-2
Commands
?ASSIGN Command
?ASSIGN COMMAND
The ?ASSIGN command associates a physical file with a dictionary record description or a generic
file. This command is functionally equivalent to the Command Interpreter ASSIGN command. The
syntax of the ?ASSIGN command is:
?ASSIGN [I record-name
generic-file-name
I [TO ] physical-filename
]
[ , create-open-spec •.. ]
where
record-name
generic-filename
is the name of one of the ENFORM generic files described in Section 2. A generic file is
used to store some class of EN FORM output. The following names are allowed:
QUERY-COMPILER-LISTING
QUERY-REPORT-LISTING
QUERY-STATISTICS
QUERY-STA TUS-MESSA GES
QUERY-WORK-AREA
QUERY-SORT-AREA
QUERY-QPSTATISTICS
QUERY-QPSTATUS-MESSAGES.
physical-filename
For record-name, physical-filename is the name of a physical file being associated with
the record description. TO must be specified if the file name is TO. A partial file name is
expanded using the default system, volume, and subvolume names.
For generic-file-name, physical-filename is the name of the physical device to which you
want ENFORM to direct output. --..
6-3
Commands
?ASSIGN Command
create-open-spec
is one file creation or open attribute. Only exclusion spec is used by ENFORM. create-
open-spec is of the form:
extent-spec
CODE file-code
exclusion-spec
access-spec
REC record-size
BLOCK block-size
where
extent-spec
EXT [ ( ] pri-extent-si ze )] t
{ EXT ( [ pri-extent-size ] , sec-extent-size ) ~
exclusion-spec
EXCLUSIVE
SHARED
PROTECTED
access-spec
1-0
INPUT
OUTPUT
The ?ASSIGN command can be entered at any time prior to running a query. Each time an
?ASSIGN command is entered, an entry of the assignment is made in the internal table. The inter-
nal table holds up to 32 assignments. When the internal table is full, the? ASSIGN command can be
entered without any parameters to clear all of the assignments.
6-4
Commands
? ASSIGN Command
Each DDL dictionary RECORD statement describes records in a physical file, named by a DDL
FILE IS clause. ENFORM uses the physical file name in the DDL FILE IS clause to locate the
records and retrieve information. There might be times when the actual records desired are not in
the physical file named in the dictionary. An example would be when test records are used in place
of actual records. The ?ASSIGN command temporarily overrides the physical file named by the
DDL FILE IS clause. In the following example, the employee record description is assigned to the
physical file $data.database.sample:
The ?ASSIGN command can be used to assign the generic ENFORM files to a physical device. In
the following example, the generic file QUERY-COMPILER-LISTING is assigned to a printing
device named $ep:
The? ASSIGN command can be used to change the exclusion specification for a file; the default is
SHARED. If the DDL physical file name is not being overridden, only the record name and the
exclusion specification need be specified. For example:
?ASSIGN empLoyee"SHARED
6-5
Commands
?ASSIGN Command
?ATTACH COMMAND
'rhe ?ATTACH command allows you to specify a query processor to use during an ENFORM ses-
sion. The syntax of the ?ATTACH command is:
?ATTACH [ process-name ]
where
process-name
When one or more server query processors exist on a Tandem system, you can use the ?ATTACH
command to specify the query processor you want to use. If you do not specify the ?AT'TACH com-
mand, ENFORM defaults to a dedicated query processor. A dedicated query processor is an
ENFORM process that is created for and provides services to an individual compiler/report writer
process. The dedicated query processor runs for the duration of an ENFORM session until either an
error occurs or an ?ATTACH command is issued specifying a new query processor. When you enter
the ?ATTACH command without a process name, ENFORM starts a new dedicated query processor
for your use.
An ?ATTACH failure is not evident until the first FIND or LIST statement is executed. The possi··
ble ?ATTACH failures and the actions you can take are as follows:
• The server query processor already has the maximum number of users it can handle. In this
case, you can wait and then try again specifying the same query processor; name a different
server query processor; or select a dedicated query processor.
• The server query processor does not exist. In this case, you can start the server query pro··
cessor, name a server query processor that does exist, or select a dedicated query processor.
• The attached server query processor reached one of two limits set for that particular server
query processor. Either the query reached a data base read limit or the cost strategy specified
by ENFORM exceeded its limit. In this case, you can: name a server query processor with
greater limits or without built-in limits; change the query; or select a dedicated query processor.
The @READS and @COST-TOLERANCE Option Variable clauses are discussed in Section 5.
6··6
..._a: I
Commands
?COMPILE Command
?COMPILE COMMAND
The ?COMPILE command compiles a query and stores it in a physical file. The syntax of the
?COMPILE command is:
where
edit-filename
section-name, ... )
is the name of the section(s) within an EDIT file. The list must be enclosed within
parentheses.
compiled-physical-filename
The ?COMPILE command compiles a query. The ENFORM internal table becomes part of the com-
piled query file. If physical-filename existed before compilation, the old version is purged and a new
physical file is created. If errors are produced during a compilation attempt, the original compiled
query file is not affected at all.
The ?COMPILE command only compiles one LIST or FIND statement. If your EDIT file contains
more than one LIST or FIND statement, EN FORM compiles the first LIST or FIND statement to
the compiled query file. ENFORM does not compile any statements or commands following the first
LIST or FIND statement; instead ENFORM continues processing, executing the statements and
commands as they are encountered in the EDIT file.
When the LIST or FIND statement of the query is written to the compiled query file, most of the
commands, options, and other statements that provide environmental information are stored in the
internal table. The internal table is then saved in the compiled query file.
ENFORM assigns a file code of 888 to the compiled query file. ENFORM creates this code to iden-
tify the physical file as a stored query produced by ENFORM.
A query called by a host language program must be compiled first. Other queries do not need to be
compiled before run time; however, there are some advantages to creating a compiled query file.
The compiled query file protects the query from being inadvertently changed. Less processing time
is required when the compiled query file is saved and reused for runs.
6-7
Commands
?DICTIONARY Command
?DICTIONARY COMMAND
The ?DICTIONARY command names a subvolume that contains your dictionary. It also clears the
internal table and reclaims table space. The ?DICTION ARY command is the same as the
DICTIONARY statement.
?OICTIONARY [ dict-subvol-name ]
where
dict-subvol-name
is the name of the subvolume where the dictionary files reside. Refer to the GUARDIAN
Operating System Programming Manual, for information about specifying file names.
The dictionary identified in a ?DICTION ARY command must be created by the Data Definition
Language compiler. Release T9102CIO of ENFORM accepts only dictionaries produced by DDL ver-
sion T9100DOO or later. ENFORM issues an error message if an attempt is made to use a dictionary
compiled with an earlier version of DDL. These dictionaries must be recompiled with DDL version
T9100DOO or later before ENFORM is used. Refer to the Data Definition Language (DDL) Pro,-
gramming Manual, for complete instructions.
• The volume and subvolume where the dictionary resides can be specified as a part of the Com-
mand Interpreter ENFORM command. If none is specified, it is assumed that the dictionary
resides on the default volume and subvolume.
• The DICTIONARY statement or ?DICTIONARY command can specify where the dictionary
resides. Either overrides the dictionary identified at the time of the Command Interpreter
ENFORM command. When a new dictionary is specified, the old internal table is cleared.
Entering the ?DICTIONARY command without a volume and subvolume name is a simple means of
clearing the entire internal table, without changing the dictionary. To clear only lCertain items of thE~
internal table, refer to the CLOSE and DELINK statements in Section 4. The items cleared by the
?DICTION ARY command are:
6-8
Commands
?EDIT Command
?EDIT COMMAND
The ?EDIT command allows you to access the Editor without leaving ENFORM. The syntax of the
?EDIT command is:
?EDIT [ edit-filename]
where
edit-filename
A query can be stored in an EDIT file. The EDIT file can be created or changed without leaving
ENFORM. An ?EDIT command invokes the Editor and operates just as if the Command Interpreter
EDIT Command was used. If a new filename is specified while using the Editor, that name becomes
the default edit-filename for use in a subsequent ?EDIT or ?RUN command. To exit the Editor,
enter EXIT at the EDIT prompt (*) and control returns to ENFORM.
6-9
Commands
?EXECUTE Command
?EXECUTE COMMAND
The ?EXECUTE command executes a compiled query file. The syntax of the ?EXECUTE command
is:
--------"--------
?EXECUTE compiled-physical-filename
where
compiled-physical-filename
is the name of the physical file containing the stored compiled query.
---------
The ?EXECUTE command resets the internal table to the same state that existed at time of com-
pilation. The ?EXECUTE command changes the dictionary being used for the duration of the execu-
tion. Internal table information from the compiled query file is used until execution terminates,
then EN FORM uses the dictionary specified before you entered the ?EXECUTE command.
If the stored compiled query requires a parameter value passed to it during execution, the Com-
mand Interpreter PARAM command can be issued prior to executing the query" For information on
the PARAM command, refer to the GUARDIAN Operating System Command Language and
Utilities Manual.
The ?EXECUTE command only accepts a physical file with a file code of 888. ENFORM assigns a
file code of 888 when it creates a compiled query file.
6-10
Commands
?EXIT Command
?EXIT COMMAND
The ?EXIT command terminates the current ENFORM session. The syntax of the ?EXIT command
is:
[ ?EXIT
--------J
---------
The ?EXIT command returns control to the Command Interpreter. It is the same as the EXIT state-
ment. An alternate way of exiting ENFORM is to press the terminal CTRL and Y keys
simultaneously.
6-11
Commands
?HELP Command
·?HELP COMMAND
The ?HELP command displays information about the syntax of the ENFORM language. The ?HELP
command can also display information about user-defined topics if your system manager has provid··
ed this information. The syntax of the ?HELP command is:
?HELP [ help-element ]
where
help-element
is one of the topics for which help is available. Among these topics is the syntax of the
ENFORM statements, clauses, commands, and language elements. To obtain a current
list of the help-elements, enter the ?HELP command without help-ele·ment. I~NFORM
responds by displaying a list of all the topics for which help is available.
When specifying the ?HELP command, enter help-element in either upper or lower case characters.
ENFORM accepts unambiguous abbreviations for help-element. If you use an ambiguous abbrevia-
tion, ENFORM displays help text for all help-elements beginning with those characters .
>?HELP
Help is available for the following topics:
STATEMENTS:
AT END AT START CLOSE DECLARE DELINK
DICTIONARY EXIT FIND FOOTING LINK
LIST OPEN PARAM SET SUBFOOTING
SUBTITLE TITLE
CLAUSES:
global modifier modifier
positional control report format
target-item
OTHER:
aggregate arithmetic expression
logical expression option variable
print list system variable
COMMANDS:
?ASSIGN ?ATTACH ?COMPILE ?DICTIONARY ?EDIT
?EXECUTE ?HELP ?OUT ?RUN ?SECTION
?SHOW ?SOURCE
6-12
Commands
?HELP Command
In the following example, EN FORM displays information about a target item when ?HELP target
item is entered:
6-13
Commands
?OUT Command
?OUT COMMAND
The ?OUT command specifies the output device for a report. The syntax of the ?OUT command is:
?OUT [ physicaL-fiLename]
where
physicaL-fiLename
is the name of the output device to which any subsequent report is directed.
The ?OUT command is used to name the physical device on which a report is printed. The physical
device can be a printing device such as such as $mlp. The physical device can also he a file name. The
?OUT command remains in effect until a new ?OUT command is issued or the session is terminated.
Issuing the ?OUT command without specifying a physical-filename causes the report to be printed
on the listing file specified by EN FORM's run-time OUT option.
The ?OUT command only affects where the report is sent. The source listing goes either to the
default listing file specified by the OUT option of the EN FORM command or to the QUERY-
REPORT-LISTING file.
The ?OUT command can be part of the EDIT file or precede an ?EXECUTE or ?RUN command. The
?OUT command is not saved in a compiled query file.
6-14
Commands
?RUN Command
?RUN COMMAND
The ?RUN command executes a query or queries in an EDIT file. The syntax of the ?RUN com-
mand is:
where
edit-filename
is the name of the EDIT file containing the ENFORM source query.
( section-name, .•• )
is the name of one or more sections of the EDIT file. They must be enclosed within
parentheses.
If both edit-filename and section-name are specified, that specific collection of commands and
statements within the EDIT file identified by the section name is executed. Multiple sections of an
EDIT file can be combined to create complete queries.
If only edit-filename is specified, ENFORM compiles and executes the entire EDIT file. If neither
edit-filename nor section-name is specified, ENFORM compiles and executes the EDIT file specified
by the most recent ?EDIT or ?RUN command.
Note that ENFORM issues a warning message and ignores a ?RUN command if:
• The ?RUN command appears in the file specified as the IN option of the ENFORM command.
• The ?RUN command appears in an EDIT file compiled and executed by a ?SOURCE command.
• The ?RUN command appears in an EDIT file compiled and executed by another ?RUN command.
6-15
Commands
?SECTION Command
?SECTION COMMAND
The ?SECTION command names a collection of ENFORM commands and statements within an
EDIT file. The syntax of the ?SECTION command is:
?SECTION section-name
where
section-name
is the name to be used for a collection of ENFORM commands and/or statements within
an EDIT file.
1.'he ?SECTION command names a collection of ENFORM commands and/or statements within an
E~DIT file. The ?COMPILE, ?RUN, and ?SOURCE commands can be used to read a section or sec-
tions of an EDIT file.
• must be unique
• can contain from 1-31 characters (names longer than 31 characters are trunca.ted and a warning
message is issued.
6-16
Commands
?SHOW Command
?SHOW COMMAND
The ?SHOW command displays information about the environment of the current ENFORM ses-
sion. The syntax of the ?SHOW command is:
?SHOW OPEN
LINK
CONTROL
LIMITS
ASSIGN [ record-name
user-variable-name
record-name
param-name
where
user-variable-name
record-name
param-name
Table 6-2 shows the environmental information displayed by the ?SHOW command.
6-17
Commands
?SHOW Command
?SHOW Lists the various items that can be displayed with the ?SHOW
command.
?SHOW OPEN Lists the open record descriptions. If none have been opened,
nothing is displayed. An OPEN statement does not actually
open a physical file, but accesses the record description in
the dictionary.
?SHOW LINK Lists links that are in effect. If no record descriptions have
been linked, nothing is displayed. A LINK state!ment does not
actually link physical files, but accesses their record descrip·
tions from the internal table.
?SHOW CONTROL Displays the current values of all of the option variables.
Option variables can be changed by setting the Option
Variable clauses. Refer to the SET statement in Section 4 and
the Option Variable clauses in Section 5.
?SHOW LIMITS Displays the current space available for the symbol table,
literals and formats, LINK table, PRINT table, PARAM table,
and OVER clause table.
?SHOW ASSIGN Displays all of the opened record descriptions and physical
file name pairs specified by a ?ASSIGN command or Com-
mand Interpreter ASSIGN command. If none were assigned,
nothing is displayed.
?SHOW ASSIGN record-name Displays all ASSIGN table information related to the specified
record name.
?SHOW user-var-name Displays the current value(s) of the user variable or table.
?SHOW record-name Displays the following for the specified opened record
description.
6-18
Commands
?SOURCE Command
?SOURCE COMMAND
The ?SOURCE command reads an EDIT file or a collection of commands and statements within an
EDIT file. The syntax of the ?SOURCE command is:
where
edit-fiLename
the name of the sections of the EDIT file. section-name must be enclosed with
parentheses.
The ?SOURCE command can be used to read in an EDIT file or a collection of commands and/or
statements within an EDIT file. When a ?SOURCE command is entered, the specified commands
and/or statements are read in just as if they had been entered a line at a time. ?SOURCE commands
can be nested up to a depth of four.
If both the edit-filename and section-name are specified, that specific collection of commands and
statements of the EDIT file is read in. If only the edit-filename is specified, the entire EDIT file is
read in.
Issuing the ?SOURCE command does not set the default EDIT file name for subsequent ?RUN or
?EDIT commands.
6-19
APPENDIX A
SYNTAX SUMMARY
ENFORM syntax is summarized in this appendix. For specific details of syntax, refer to the
language elements, statement, clause and command sections.
LANGUAGE ELEMENTS
Aggregates:
AVG
COUNT fieLd-namel [OVER ALL ]
MAX ( expression OVER over-item
MIN
{ SUM [ WHERE LogicaL expression] >,
user-aggregate
AVG
COUNT [UNIQUE] fieLd-name [OVER ALL
MAX [ WHERE LogicaL expression] >,
MIN
SUM
user-aggregate
Arithmetic operators:
*
/
A-l
Syntax Summary
Language Elements
Logical Expression:
BEGINS
, ] , WITH }
string-l iteral
CONTAINS
{ I>'
conditionaL operator
field-name
[NOT] EQUAL
=
EQ
IS value-range
( "["pattern-match"]"
I
NE
<>
~~::~~~;me } [NOT]
{ expreSSlon
condi tiona L operator {~~::~~~:me }
expreSSlon
STATEMENTS
record-name }
user-variabLe-name
CLOSE user-aggregate-name , ... [
{ user-tabLe-name
param-name
A-2
Syntax Summary
Statements
user-variabLe-name
INTERNAL internaL-format
AS dispLay-format]
HEADING "heading-string" , ... [ ; ]
DICTIONARY [ dict-subvoL-name ] [
EXIT [
[ output-fieLd-name :=
] {BY
BY by-i
DESC tem
by-item }
target-item
ASCD target-item
DESC target-item , ... )
[ WHERE LogicaL-expression]
A-3
Syntax Summary
Statements
A-4
Syntax Summary
Statements
record-name }
OPEN
{ record-name2 [ AS ] COpy [ OF ] record-name1 , ..• [
user-variabLe-name } { string-LiteraL}
SET user-tabLe-name"["subscript"]" TO number , . .. [
{ param-name
option-variabLe-name TO ON
OFF
number
"character"
string-L iteraL
dispLay-format
CLAUSES
ASCO }
{ fieLd-name
OESC
repeatabLe-edit-descriptors II
( nonrepeatabLe-edit-descriptors
repeatabLe-edit-descriptors) II
A-5
Syntax Summary
Clauses
where
report-item
nonrepeatabLe-edit-descriptors
specify some general ways report-items are to be printed. Nonrepeatble-edit-descriptors
should not be specified without a repeatable-edit descriptor. Nonrepeatable-edit-
descriptors are:
repeatabLe-edit-descriptors
specify data conversion to the GUARDIAN Formatter for printing the report-item
values. Valid values for repeatable-edit-descriptors are:
where
"["decorations"]"
conditions
are one or more of the following:
A-6
Syntax Summary
Clauses
location
char-string
"["modifiers"]"
where:
char
pr-of-symbols
date-in-internal-format AS DATE I *
display-format
I
time-in-internal-format AS TIME I *
display-format
I
AT END PRINT print-list [ CENTER]
BY
\ BY DESC
I fie ld-name
A-7
Syntax Summary
{
Clauses
CENTER ALL
FORM [ number ]
INTERNAL internaL-format
l{ tar~et-;
bY-ltem,
tem} NOHEAD I
NOHEAD ALL
l{ tar~et-i
bY-ltem
tem} NOPRINT I
NOPRINT ALL
@BLANK-WHEN-ZERO
@BREAK-KEY
@CENTER-PAGE TO {ON }
@HEADING OFF
@STATS
@SUMMARY-ONLY
@WARN
@COPIES
@COST-TOLERANCE
@DISPLAY-COUNT
@LINES
@MARGIN
@PAGES
@PRIMARY-EXTENT-SIZE TO number
@SECONDARY-EXTENT-SIZE
@READS
@SPACE
@TARGET-RECORDS
@VSPACE
@WIDTH
A-8
Syntax Summary
Clauses
@DECIMAL }
@NEWLINE TO "character"
@NONPRINT-REPLACE
{ @OVERFLOW
@UNDERLINE
@SUBTOTAL-LABEL TO "char-string"
I @DATE-FORMAT
@TIME-FORMAT
I
TO display-format
SKIP [ number ]
SPACE [ number ]
System Variables:
@DATE
@TIME
@LINENO
@PAGENO
TAB [ number ]
TIMESTAMP-DATE ( field-name)
TIMESTAMP-TIME ( field-name)
A-9
Syntax Summary
Clauses
COMMANDS
?ATTACH [ process-name
?DICTIONARY [dict-subvol-name]
?EDIT [ edit-filename]
?EXECUTE compiled-physical-filename
?EXIT
?HELP [ help-element ]
?OUT [ physical-filename
?SECTION section-name
OPEN
LINK
CONTROL
?SHOW LIMITS
ASSIGN [ record-name
user-variable-name
record-name
param-name
A-IO
Syntax Summary
ENFORM Procedures
ENFORM PROCEDURES
COBOL:
FORTRAN:
A-tt
Syntax Summary
}l~NFORM Procedures
TAL:
A-12
APPENDIX B
ERROR MESSAGES
• !!! ERROR error-number types: mean a serious error has occurred. Statement execution ter-
minates. If this type of error occurs for a LIST or FIND statement, the query terminates.
• *** WARNING warning-number types: point out an error that could change the expected
results. The error does not abort the query although it could lead to more serious error condi-
tions.
• *** FILE ERROR ... types: mean a serious error has occurred within the file system. If there is a
file error with the run-time IN input file, the dictionary file, or the vocabulary file, the entire
ENFORM session is terminated.
• *** ... types: occur during ENFORM initialization. If this type of error occurs, ENFORM ter-
minates abnormally.
• ENFORM [QP] TRAP: means a that either a hardware failure or an unexpected software error
has occurred. Please save the information produced by this message and report the error to
Tandem.
• *** ERROR types: means an error has occurred during execution of the BUILDMK utility.
BUILDMK terminates abnormally. Correct the problem and rerun BUILDMK or you cannot use
the key-sequenced version of the message table with ENFORM.
Error messages are listed in the following order within this appendix.
2. !!! ERROR and *** WARNING type errors are listed together in numeric order with the error
message text and additional comments.
5. BUILDMK error messages are listed. These messages consist of the following types of
messages: !!!ERROR and FILE ERROR messages.
B-1
Error Messages
*** Current reserved word cannot be used to redefine another reserved word
A reserved word redefinition in the ?VOCABULARY section of the message table contains
an old reserved word where a new word is expected. (The key-sequenced message table file
was not built by the BUILDMK utility or the :file has been modified since it was built).
*** Message table does not contain a version number record. Rebuild key-sequenced file
Either the key-sequenced message table file was not built by the BUILDMK utility or the
file has been modified since it was built.
*** Message table must contain both ?MESSAGES and ?HELP sections
Self-explanatory. Use the BUILDMK utility to build the key-sequenced message table file.
*** Primary key for message table file must be offset at 0 and have length 34
Self-explanatory. Use the BUILDMK utility to build the key-sequenced message table file.
B-2
Error Messages
! !! ERROR [28] The boolean operators AND and OR cannot be used in a TITLE or
PRINT statement expression
Only a simple logical expression may be used in an IF/THEN/ELSE expression within an
AFTER CHANGE, AT END, AT START, BEFORE CHANGE, FOOTING, SUBFOOTING,
SUBTITLE, or TITLE, statement or clause.
!!! ERROR [29] Reference has been attempted to an undefined or illegal item
in PRINT statement
An item has been used in a Print List clause that does not appear in the LIST statement.
B-3
Error Messages
!!! ERROR [41] The maximum target length of 2000 bytes was exceeded. Unable to
process query
The maximum length of a LIST or FIND statement requiring sorting exceeded 2000 bytes,
or the maximum length of a LIST or FIND statement without sorting requirements exceeded
4095 bytes.
!!! ERROR [43] The specified relation is invalid in the above context
CONTAINS, BEGINS WITH, and pattern match conditions require string arguments. The
pattern match operation allows only EQ and NE operators.
!!! ERROR [49] User variable assignments are illegal in the scope 01: a FIND statement
User defined variable or table is not an acceptable output field name in a FIND statement.
!!! ERROR [50] Insufficient memory available for data buffer (SERVEH-related
failure on name)
An ENFORM server (process file) cannot be opened because there is no space for a message
buffer.
B-4
Error Messages
!!! ERROR [55] A user aggregate may not be used in a user aggregate end-expression
Self-explanatory.
! !! ERROR [56] An aggregate may not be used as the argument to another aggregate
Self-explanatory.
!!! ERROR [58] Illegal use of KEY item <SERVER-related failure on name)
Record-name.KEY or KEY OF record-name is not allowed when the data for record-name is
from an ENFORM server (process file).
!!! ERROR [60] A user aggregate declaration may not reference the value of
another user aggregate
Self-explanatory.
B-5
Error Messages
!!! ERROR [66] Only one OPTIONAL LINK request allowed per LIST or FIND statement
Only one link (whether it is OPTIONAL or not.) can be used when OPTIONAL is specified.
!!! ERROR [71] The table containing literals, AS formats and headings has overflowed
The literal table overflowed its maximum size of 5,915 words.
B-6
Error Messages
!!! ERROR [78J The attribute UNIQUE may not be used with an OVER clause
UNIQUE may not be used with aggregates computed OVER a grouped-item.
!!! ERROR [81J The preceding text contains a syntactically incorrect element
Check the preceding line. If ok, check the next few preceding lines.
!!! ERROR [83J The type of the argument in the SET cLause is invaLid
Assigning a string to a numeric or vice versa or assigning a non-integer numeric literal.
!!! ERROR [85J More than one PCT or CUM modifies List item
Only one PCT or CUM clause allowed per item.
B-7
Error Messages
!!! ERROR [90] All field names referenced in a qualification aggregatl~ must belong
to the same record
All fields in the expression being aggregated, the over-item, and the embedded WHERE
clause must belong to the same record.
*** WARNING [91] No report will be listed. The target list is composed of
literals only
An ENFORM report will not print alphanumeric and/or numeric literals only. Include at
least one field name from an opened file description.
!!! ERROR [92] At least one record has no LINK or a qualification relating it to any
other record
Missing LINK statement or WHERE clause to link file descriptions.
*** WARNING [101] The param table would overflow if updated to the SET value
Parameter table is full and the last value has not been added. Use the CLOSE statement to
clear parameter values not needed.
!!! ERROR [102] Field referenced in TITLE statement not found in target list
Usually an internal error with some unsupported item within an AFTER CHANGE, Arr
END, AT START, BEFORE CHANGE, FOOTING, SUBFOOTING, SUBTITL}t~, or TITLE
statement or clause.
B-8
Error Messages
!!! ERROR [105] SUBTOTAL, TOTAL, CUM, and PCT only modify numeric items.
Cannot use alphanumeric'string items. Numeric strings are allowed.
*** WARNING [111] The following LINKs were previously ignored; they are now
being used:
QUALIFIED-FIELD-NAME-1 is linked to QUALIFIED-FIELD-NAME-2 ...
ENFORM now uses all existing LINK statements. To obtain the results this query produced
prior to ENFORM release T9102C09, remove all the LINK statements listed in WARNING
[111]. Refer to the LINK statement discussion in Section 4.
!!! ERROR [113] An aggregate may not be used in this context with PCT
Only the aggregates SUM and COUNT can be used with PCT and they must be used alone
(not in an expression).
!!! ERROR [115] Dictionary is outdated. Recompile with 000 DOL or later
As of release T9102C10, ENFORM accepts only dictionaries compiled with DDL Version DOO
or later. Current dictionary has an old version number; recompile it with a new version of
DDL.
B-9
Error Messages
!!! ERROR [t66] String literal must be terminated with a quotation mark
Closing quotation mark is missing. Remember that a string literal cannot be continued from
one source line to the next.
!!! ERROR [167] String literal cannot contain more than 127 characters
Self-explanatory.
!!! ERROR [172] Item on left side of assign operator must be a field in the
FIND record
The output-field-name in a FIND statement cannot be a field from an input record or the
name of the FIND record itself.
!!! ERROR [173] Value must be a single ASCII character, not IIAII or "_"
This is a restriction on the value for the Option Variable @NEWLINE.
!!! ERROR [175] A subscript range cannot be used in a fieLd in a FIND statement
Specify each item in the range individually.
! !! ERROR [176] HeLp item phrase must be Less than 32 characters long.
The phrase following the ?HELP keyword must be less than 32 characters long, including
embedded blanks and the initial question mark (if present).
!!! ERROR [177] Parameter is treated Like a literal here. Its vaLue cannot be changed.
In certain cases, ENFORM treats a parameter exactly like a numeric literal. This means that
you cannot change the value of the parameter at execution time, either with a Command
Interpreter PARAM command or an ENFORM SET statement. Refer to the PARAM state-
ment in Section 4 for more details.
B-I0
Error Messages
File management errors are reported through ENFORM with *** FILE ERROR ... messages. In the
messages below, #/ile-error-number is a GUARDIAN file management error number. name is the
physical file name.
*** FILE ERROR (Process nonexistent, insufficient system resources or full queue)
#file-error-number on name
The server query processor named in the ?ATTACH command does not exist or cannot
accept more users.
B-ll
Error Messages
*** FILE ERROR (Specified ENFORM compile file exists as edit or TAL object file)
on name
The file must be a compiled query file created with an EN FORM ?COMPILE command.
*** FILE ERROR (Unable to open ENFORM message table) #file-error-numbE!r on name
Self-explanatory. EN FORM terminates abnormally. Correct the problem with the message
table and restart the session.
*** FILE ERROR (UnabLe to position ENFORM message table) #file-error-number on name
ENFORM is unable to use the message table file. The session continues but all messages con-
tain "???" instead of text.
*** FILE ERROR (Unable to read ENFORM message table) #file-error-number on name
EN FORM is unable to use the message table file. The session continues but all messages con-
tain "???" instead of text.
B-12
Error Messages
*** ERROR Second parameter in command line must be a key-sequenced file name
The second parameter of the BUILDMK command must be the name of a key-sequenced file.
*** ERROR Primary key for key-sequenced file must be at offset 0 and have length 34
Self-explanatory.
*** ERROR Edit file contains ?HELP section but no ?MESSAGES section
The Edit file version of the message table must contain a ?MESSAGE section if a ?HELP
section is included.
*** ERROR Edit file contains ?MESSAGES section but no ?HELP section
The Edit file version of the message table must contain a ?HELP section if a ?MESSAGES
section is included.
An identifier specified in the Edit file version of the message table must begin with either an
alphabetic character or a circumflex.
*** ERROR ?MESSAGES section must contain at least one line of text
Self-explanatory.
*** ERROR ?VOCABULARY section must redefine at least one reserved word
Self-explanatory.
B-13
Error Messages
*** ERROR A ? may only appear as the first char in the first word of a HELP phrase
A question mark can only appear as the first character in the first word of the phrase that
identifies a HELP section or subsection.
*** ERROR First parameter in command line must be an edit file name
The first parameter specified for the BUILDMK command must be the name of an Edit file
containing the Edit version of the message table.
*** ERROR ?VOCABULARY must appear in columns 1-11 and all other columns must be blank
The characters ?VOCABULARY must appear in columns 1 through 11 of the first line of the
?VOCABULARY section. All other columns on this line must contain blanks.
*** ERROR ?MESSAGES must appear in columns 1-9 a nd all other columns must be blank
The characters ?MESSAGES must appear in columns 1 through 9 of the first line of the
?MESSAGES section. All other columns on this line must contain blanks.
*** ERROR ?HELP must appear in columns 1 thru 5 and all other columns, must be blank
The characters ?HELP must appear in columns 1 through 5 of the first line of the ?HELP sec-
tion. All other columns on this line must contain blanks.
*** ERROR In a reserved word redefinition, the new reserved word is missing
Supply the new reserved word.
B-14
Error Messages
*** ERROR In a reserved word redefinition, the old reserved word is missing
Supply the old reserved word.
B-15
APPENDIX C
GLOSSARY
Aggregate - a cumulative operation on set(s) of numbers, producing a single value per set. See
Predefined Aggregate and User Aggregate.
By-item - the field name used to group and sort ENFORM output; always associated with a BY or
BY DESC clause. A by-item is a special kind of target-item.
Compiler/Report Writer - the ENFORM process that both compiles ENFORM queries and formats
and writes ENFORM reports.
Compiled Query File - the physical file containing a saved query that been compiled by the
?COMPILE command.
Current Output Listing File - the file to which ENFORM directs output; this file can change during
an ENFORM session.
Data Description Language (DDL) - the language used to describe the record and file structure of a
data base.
Dictionary - a data base of file descriptions and record types created by the Data Definition
Language (DDL); also called a data dictionary.
Default Output File - the file to which ENFORM directs output at the beginning of an ENFORM
session. See also Current Output Listing File.
Default Input File - the file from which the ENFORM source code is entered when the IN option of
the ENFORM command is omitted; usually the home terminal.
C-l
Glossary
File Type - identifies the organization of the physical file, such as key-sequenced. entry-sequenced,
or relative files.
Front End - the ENFORM process which compiles ENFORM programs, and prints reports. See
Compiler/Report Writer.
Group Field - a collection of one or more fields that can be accessed with a single name.
Group Name - name of one or more fields that can be accessed with a single name.
Home Terminal - the terminal from which the ENFORM command is entered.
Link - specifies a relationship between records in a relational data base to be used in an_ EN FORM
query.
Literal - one or more numeric or alphanumeric characters. See String Literal and Numeric Literal.
Normalized - data that has been described in such a manner that only one value exists for every
field position in a record.
Numeric Literal - composed of the digits 0 thru 9. Numeric literals cannot be larger than 32765 and
must be enclosed in parentheses unless they appear in a logical expression or a TAB, SPACE,
SKIP, or FORM clause.
Option Variable - An ENFORM supplied variable that defines certain operational values.
OUT File - the physical device specified in the OUT option of the EN FORM command.
Predefined Aggregate - one of the ENFORM aggregates: AVG, COUNT, MAX, MIN, or SUM.
Primary Key - the field or group of fields that uniquely identifies a record.
C-2
Glossary
Qualified Field Name - a name which uniquely identifies a field as a component of a record
description.
Query - a complete ENFORM LIST or FIND statement specifying which fields and records to
retrieve.
Query Processor (QP) - the ENFORM process which opens the files and retrieves the records from
a relational data base for a report or a new file.
Record Description - the dictionary description of a record, including the record name, record type,
field names, and data types, and key definitions.
Record Type - a record's structure including field names and data types.
Relational Data Base - a data base in which records are related through fields with common formats
and comparable values.
Report - the printed output of an ENFORM query using an ENFORM LIST statement.
Request-qualification - the condition or conditions that a data base element must satisfy to con-
tribute to the target-record; begins with a WHERE clause followed by a logical expression.
Server Query Processor - specific query processor specified by an ?ATTACH command, initiated
separately from the compiler.
Source Code - the ENFORM statements, clauses, and commands that comprise the query speci-
fications.
Source File - the Edit file that contains the source code. See also Source Code.
String Literal - one or more alphanumeric characters enclosed in quotation marks (").
System Variable - an ENFORM supplied variable that returns the current time, date, line number,
or page number.
Target-file - the file produced by the Query Processor that contains records with all the information
requested in the query specifications.
C-3
Glossary
Target-item - the record names, field names, expressions, variables, aggregates, and literals,
including by-items, whose values appear in a target-record.
Target-list - the record names, field names, expressions, variables, aggregates, and literals follow-
ing the keywords LIST or FIND that contribute to the target-record. Ta:rget-lists consist of
target-items some of which are by-items. See also By-items and Target-items.
Target-record - the records generated by the Query Processor from which your ENFOHM output is
produced.
Unnormalized - data that has been described such that more than one value exists for each field
position in a record.
User Variable - a user declared element that can be used to store numeric or string literals, field
values, and the results of arithmetic or aggregate calculations.
C-4
INDEX
Index-l
Index
Index-2
Index
Index-3
Index
Index-4
Index
Index-5
Index
Index-6
. - - - ----_._ ....__._--
Index
Index-7
Index
Index-8
Index
Index-9
Index
Index-10
Index
Index-11
Index
Index-12
Index
Index-13
Index
Index-14
,------------------------------------------.--------.-----------------------------------------,
Index
Index-15
Index
Index-16
Index
Index-17
---.....--..........
--------------------------------------------------------------------------------------.--------,---------- ,
YOUR COMMENTS PLEASE
Tandem welcomes your comments on the quality and usefulness of its publications. Does this publication serve
your needs? If not, how could we improve it? If you have specific comments, please give the page numbers with
your suggestions.
This comment sheet is not intended as an order form. Please order Tandem publications from your local
Sales office.
FROM:
Company _____________________________________________________
Address
City/State _ Zip
CF
111111 O POSTAGE
C
NECESSARY
IF MAILED
IN THE
UNITED STATES
TAPE TAPE