£EPA
United States
Environmental Protection
Agency
Environmental Research
Laboratory
Athens GA 30613
EPA/600/3-89/034
April1989
Research and Development
ANNIE-IDE, A System for
Developing Interactive
User Interfaces for
Environmental Models
(Programmers Guide)
-------
EPA/600/3-89/034
April 1989
ANNIE-IDE, A SYSTEM FOR
DEVELOPING INTERACTIVE USER INTERFACES
FOR ENVIRONMENTAL MODELS
(PROGRAMMERS GUIDE)
by
John L. Kittle, Jr.
Paul R. Hummel
John C. Imhoff
AQUA TERRA Consultants
Decatur, Georgia 30030
Contract Number 68-03-3513
Project Officer
Thomas O. Barnwell, Jr.
Assessment Branch
Environmental Research Laboratory
Athens, Georgia
ENVIRONMENTAL RESEARCH LABORATORY
OFFICE OF RESEARCH AND DEVELOPMENT
U.S. ENVIRONMENTAL PROTECTION AGENCY
ATHENS, GEORGIA 30613
-------
DISCLAIMER
The information in this document has been funded wholly or in part
by the United States Environmental Protection Agency under Contract
No. 68-03-3513 with AQUA TERRA Consultants. It has been subject
to the Agency's peer and administrative review, and it has been
approved for publication as an EPA document. Mention of trade
names or commercial products does not constitute endorsement or
recommendation for use by the U.S. Environmental Protection Agency.
11
-------
FOREWORD
As environmental controls become more costly to implement and
the penalties of judgement errors become more severe, environmental
quality management requires more efficient analytical tools based
on greater knowledge of the environmental phenomena to be managed.
As part of this Laboratory's research on the occurrence, movement,
transformation, impact, and control of environmental contaminants,
the Assessment Branch develops management or engineering tools to
help pollution control officials address environmental problems.
Recent progress in environmental science and engineering has
seen the increasing use of interactive interfaces for computer
models. Initial applications centered on the use of interactive
functions to assist the modeler in building complicated input
sequences required by batch programs. From these original
applications, interactive capabilities are rapidly being expanded
to provide "smarter" and more flexible communication between users
and the environmental models and databases they use. This manual
provides a straightforward, consistent methodology for programmers
who have the task of designing and implementing new interactive
interface systems.
Rosemarie C. Russo, Ph.D.
Director
Environmental Research Laboratory
Athens, Georgia
111
-------
ABSTRACT
This document is a guide to the newly developed computer software
called ANNIE-IDE - the ANNIE Interaction Development Environment.
ANNIE-IDE provides a consistent methodology for building
interactive interfaces for environmental software. ANNIE-IDE
combines a toolkit of utility subroutines for building individual
interactive screens with instructions for developing two parallel
products: a file containing all text, questions, and messages used
in interactive communication, and a Fortran program containing the
control strategy and sequencing instructions for interactions. The
system provides an efficient means for storing and updating screen
contents.
The ANNIE-IDE package is based on a re-evaluation of currently
available tools and ideas for constructing a user interface.
Accordingly, the manual draws on an expanding body of knowledge of
the "human factors" involved in effective design of man-machine
interfaces. By providing a straightforward, but powerful set of
"tools" and a detailed consideration of the best way to use these
tools, the ANNIE-IDE software and manual greatly reduce the
difficulty a programmer will encounter in developing an interactive
user interface.
This report was submitted in fulfillment of Work Assignment No.
2(B) of Contract No. 68-03-3513 by AQUA TERRA Consultants under
the sponsorship of the U.S. Environmental Protection Agency. This
report covers a period from November 1987 to September 1988, and
work was completed as of September 1988.
IV
-------
CONTENTS
Disclaimer ii
Foreword iii
Abstract iv
Figures viii
Tables x
Acknowledgments xi
1. Introduction 1
1.1 Who Should Use ANNIE-IDE? 2
1.2 Why Use ANNIE-IDE? 3
1. 3 Manual Contents 3
2. Overview 4
2.1 Background 4
2.1.1 WDM and ANNIE 4
2.1.2 EMIFE 4
2.1.3 ANNIE-IDE 6
2.2 Overview of Toolkit and Methodology 6
2.2.1 Screen Content Construction 7
2.2.2 Screen Interaction Control 8
2.2.3 Housekeeping 8
2.2.4 Sample Screens 8
2.3 System Requirements and Goals 12
2.4 Limitations 13
2.5 Toolkit Demonstration Examples 14
3. Theoretical Considerations of ANNIE-IDE Development ... 16
3.1 General Theory of Interactive Interfaces 16
3.1.1 Human Factors Goals 17
3.1.2 Why Interactive Systems Fail 17
3.1.3 Rules of System Design 18
3.1.4 Styles for Interactive Systems 18
3.1.5 Menu Selection Interactions 19
3.1.6 Rules for Grouping Items in Menus and Tree
Structures 19
3.1.7 Menu Item Presentation Sequence 19
3.1.8 General Considerations 20
3.1.9 Form Fill-in Interactions 20
3.2 Application of Human Factors Theory to ANNIE-IDE . 21
3.3 Screen Layout 22
3.4 Data Window 24
3.5 Assistance Window 24
-------
3.6 Instruction Window 28
3.7 Command Line 28
3.8 User Control Within Screens 30
3.8.1 User Interaction Modes 30
3.8.2 Keystrokes and Communication Features ... 31
3.8.3 Movement Between Interaction Modes 33
3.9 Screen Definition Directives 33
3.10 Screen Sequencing 35
4. Instructions for Using ANNIE-IDE 36
4.1 Building and Storing Screen Definition Files ... 36
4.1.1 Text Screen Directives 40
4.1.2 Menu Screen Directives 41
4.1.3 1-D Array (PRM1) Screen Directives 42
4.1.4 2-D Array (PRM2) Screen Directives 43
4.1.5 File Screen Directives 44
4.1.6 Using MESSIE 45
4.1.7 Directives to Provide Assistance to User . . 47
4.2 Designing and Developing the Interactive Program . 48
4.2.1 Initialize ANNIE-IDE 48
4.2.2 Initialize Parameters 48
4.2.3 Read Existing Parameter Values From a File . 49
4.2.4 Update Parameter Values 50
4.2.5 Write Revised Parameter Values To File ... 50
4.2.6 Shut Down ANNIE-IDE 50
4.2.7 Using Toolkit Subroutines for Screen
Interaction Control 50
4.2.8 Closing Comments on the Development
Process 57
4.3 Advanced Topics 58
4.3.1 User System Specifications File (TERM.DAT) . 58
4.3.2 Interscreen Movement Commands 59
4.3.3 Control of Assistance Window Containing
System Status 59
5. Example Applications 60
5.1 Initialize System 60
5.2 Initialize Model Parameters 61
5.3 Read File Input For a Model 61
5.4 Display Text 62
5.5 Display Text With Numeric Information 64
5.6 Select an Item From a Menu 65
5.7 Open a File 67
5.8 Edit One-dimensional Array of Data 68
5.9 Edit Two-dimensional Array of Data 70
5.10 Enter Two-dimensional Array of Data with Buffer Use 72
5.11 Set Limits and Defaults for One or Two-dimensional
Data 74
VI
-------
5.12 Display System Status Information 75
5.13 Set Command Availability 76
5.14 Save Current Menu Text 77
5.15 Determine User Screen Exit Command 78
5.16 Write File Containing Model Parameters 78
5.17 Shut Down System 79
6. Recommendations for ANNIE-IDE Enhancements 80
References 82
Appendices
A. Glossary of Terms 83
B. Reference Manual 85
B.I Frequently Called Routines 86
B.2 Summary of All Toolkit Routines 138
B.3 Data Structures 144
B.4 Screen Definition Directives 155
B.5 File Formats 158
B.6 TERM.DAT Parameters 159
B.7 ANNIE-IDE Commands 161
B.8 Color Codes for PC Color Implementation 162
B.9 Distribution Disk Contents 163
VII
-------
FIGURES
2.1 ANNIE functions and capabilities 5
2.2 ANNIE-IDE toolkit 7
2.3 Sample text screen 9
2.4 Sample menu screen 10
2.5 Sample 1-D array screen. 10
2.6 Sample 2-D array menu screen 11
2.7 Sample file screen 11
3.1 Screen format utilized by ANNIE-IDE 23
3.2 Example error message in instruct window 28
3.3 Screen layout in assist mode 30
3.4 Screen directive functions 34
4.1 Building an interactive application 37
4.2 Building and storing a screen definition file 38
4.3 Template screen definition file 39
4.4 Structure of interactive program providing user
interface to an environmental model 49
4.5 Structure chart for text display subroutines 52
4.6 Text display subroutines 53
4.7 Structure chart for menu subroutines 53
4.8 Structure chart for 1-D array subroutines 54
4.9 One-dimensional array input subroutines 55
4.10 Structure chart for 2-D array edit subroutines 56
4.11 Two-dimensional data edit subroutines 56
4.12 Structure chart for file subroutines 57
4.13 File management subroutines 57
4.14 Sample TERM.DAT file 58
5.1 Fortran code to initialize ANNIE-IDE 60
5.2 Fortran code to initialize model parameters 61
5.3 Fortran code to read model parameters from a file. . . 62
5.4 Fortran code to display text 62
5.5 Screen definition directives to display text 63
5.6 Resulting text screen 63
5.7 Fortran code to display text with numeric
information 64
5.8 Screen definition directives to display text with
numeric information 64
5.9 Resulting text screen with numeric information. .... 65
5.10 Fortran code to select from menu 65
5.11 Screen definition directives to select from menu. ... 66
5.12 Resulting menu screen 66
5.13 Fortran code to specify a file 67
5.14 Screen definition directives to specify a file 67
5.15 Resulting file specification screen 68
viii
-------
5.16 Fortran code to enter 1-D data 68
5.17 Screen definition directives to enter 1-D data 69
5.18 Resulting 1-D data screen 70
5.19 Fortran code to enter 2-D data 70
5.20 Screen definition directives to enter 2-D data 71
5.21 Resulting 2-D data screen 72
5.22 Fortran code to enter 2-D data using buffer 72
5.23 Screen definition directives to enter 2-D data with
use of buffer 73
5.24 Resulting 2-D data screen with use of buffer 74
5.25 Fortran code to set limits for data fields 74
5.26 Fortran code to add status information 75
5.27 Resulting status display 75
5.28 Fortran code to set command availability 76
5.29 Resulting command line display 76
5.30 Fortran code to save menu text 77
5.31 Resulting screen with additional text information. . . 77
5.32 Fortran code to determine user screen exit command. . . 78
5.33 Fortran code to write model parameters to a file. ... 79
5.34 Fortran code to shut down ANNIE-IDE 79
IX
-------
TABLES
3.1 Advantages and Disadvantages of Candidate Interaction
Styles 18
3.2 Assistance Window Types 26
3.3 Commands for Basic Application of ANNIE-IDE 29
3.4 Keystrokes and Their Results 32
3.5 Optional Commands for Interscreen Movement 35
4.1 TEXT Screen Definition Directives 40
4.2 MENU Screen Definition Directives 41
4.3 PRM1 Screen Definition Directives 42
4.4 PRM2 Screen Definition Directives 43
4.5 FILE Screen Definition Directives 44
4.6 Screen Directives for Specifying Assistance 47
-------
ACKNOWLEDGMENTS
Development of the ANNIE-IDE package was made possible by the
efforts and support of a number of individuals and organizations.
Thomas Barnwell was the EPA Project Monitor during the course of
this work. His guidance and support contributed to the successful
completion of this project and is gratefully acknowledged. Others
from the Environmental Research Laboratory, Athens, GA, who
contributed ideas include Robert Carsel and Dr. Lawrence Burns of
the EPA and Patrick Cannon, Ronnie Moon and David Disney of
Computer Sciences Corporation.
The United States Geological Survey is acknowledged for providing
assistance in developing many of the software components utilized
by ANNIE-IDE. Dr. Alan Lumb and Kathleen Flynn have had key
involvement in developing ANNIE/WDM, from which many of the "tools"
in the ANNIE-IDE toolkit have been extracted. During the course
of this project, their comments and those of their co-worker Lewis
DeLong have allowed us to produce a better product.
Guidance for developing effective strategies for human-computer
interaction in ANNIE-IDE was provided by Dr. Albert Badre of the
Georgia Institute of Technology who served as a technical
consultant for the duration of this project. Dr. Ben Shneiderman's
book Designing the User Interface was also a key reference for
resolving "human factors" issues. Their ideas and comments have
been invaluable.
James Pilotte of General Software Corporation provided the EPA and
AQUA TERRA with the computer code and documentation for the
Environmental Model Input File Editor (EMIFE). Some of the user
interaction screens developed for ANNIE-IDE were based on
prototypes contained in EMIFE.
For AQUA TERRA Consultants, Jack Kittle was the Project Manager
and was responsible for designing ANNIE-IDE. Paul Hummel had
primary responsibility for coding and testing the toolkit
subroutines. John Imhoff developed the system documentation.
Anthony Donigian and Brian Bicknell provided reviews and comments.
XI
-------
SECTION 1
INTRODUCTION
Over the past three to four years, the implementation and use of
interactive interfaces for computer models of all types have become
increasingly popular. In the fields of environmental science and
engineering the first attraction to interactive functions centered
on their ability to assist the modeler in the effort of building
complicated, format-dependent input sequences for batch programs.
Hence early interactive interfaces often focused on prompting the
model user for all the input instructions and model parameter
values needed to produce a complete machine-generated batch input
sequence. This was a limited application of interactive
capability, but nonetheless was an effective means of reducing user
error related to formatting and/or omission of necessary input
information. The primary benefit of this application was reduced
run failure. A natural next step to the extension of interactive
capabilities was to provide checking for input model parameter
values to assure they fell within a reasonable range. While the
concept of checking the reasonableness of input values is valid,
the effective implementation of this capability for environmental
models has been hindered by the lack of sound scientific
information on some model parameters and the very broad range of
possible values for others. Value checking, however, can provide
a safeguard against the entry of mistaken values for many
parameters, and consequently has become an expected function of
many interactive systems.
From these original functions, interactive capabilities are rapidly
expanding to provide "smarter" and more flexible communication
between users and environmental models and/or data bases.
Desirable interactive capabilities, which are currently in various
stages of implementation, include: (1) "help screens" that offer
the user guidance in executing the interactive system or supplying
input data, (2) enhanced system logic that allows the user better
control of command and operation sequencing, (3) enhanced system
checks that assure that the instructions provided by the user are
logically consistent, and (4) system capability to adjust the
nature of user interaction to accommodate the level of expertise
of individual users.
As is often the case with rapidly developing technologies, the
approaches and methods that have been used to produce the array of
-------
currently available interactive systems vary widely and reflect
the knowledge, philosophies, and personal biases of their
developers. The diversity in systems capabilities and approaches
has resulted in user confusion and frustration and has somewhat
limited the effectiveness of the available systems. At the same
time, the lack of any sort of guidance or standardized methods for
interactive system development has placed an unnecessary burden on
programmers given the task of designing and implementing new
systems.
The impetus for developing this manual, and the programmer's
toolkit (ANNIE-IDE) it describes, is recognition that a need exists
for an straightforward, consistent methodology for building
interactive interfaces for available and developing environmental
models and data bases. An immediate goal is to begin a
standardization process for implementing interactive interfaces for
environmental models commonly used by the EPA and its contractors.
The ANNIE-IDE system is a product of re-evaluation of currently
available tools and ideas for constructing a user interface. The
system combines a "toolkit" of subroutines for interaction
construction that can be called from Fortran programs with an
efficient procedure for storing screen contents. The manual
provides instructions for using the toolkit to build an effective
interface to models or data bases. In doing so, the manual draws
on an expanding body of knowledge of the "human factors" involved
in effective design of man-machine interfaces. By providing a
powerful set of "tools" and a detailed consideration of the best
way to use these tools, the ANNIE-IDE software and manual are
intended to greatly reduce the difficulty a programmer will
encounter in developing an interactive user interface.
1.1 WHO SHOULD USE ANNIE-IDE?
The ANNIE-IDE package can be utilized to build a user interface for
virtually any type of computer program or computer-stored data
base. Potential applications range from generating user-supplied
input for already existing scientific or environmental models to
allowing user access to data bases for the purpose of searching,
analyzing, or displaying data values. ANNIE-IDE provides
application programmers with the tools needed to build and store
a convenient user interface whenever and wherever there is a need
to perform one or more of the following operations.
o display text
o prompt the user to select a menu option
o prompt the user to input or edit values in a one- or two-
dimensional array
o open a file to store or retrieve text and other information
-------
1.2 WHY USE ANNIE-IDE?
The advantages gained by using ANNIE-IDE for interface development
center on four concepts: modularity, consistency, portability, and
ease of application. The system utilizes a library of subroutines
to perform the basic communication functions between the user and
the program. Repeated use of these subroutines allows the
application programmer to focus attention on designing an effective
sequence for interactions while minimizing the effort needed to
program the more mechanical aspects of the interface. At the same
time the repeated use of modular subroutines decreases the
likelihood of introducing programming errors. By approaching the
interface development effort as a repetitive application of a
limited number of tools, a higher degree of programming consistency
is maintained both within and between resulting interactive
programs; both the programmer and the user benefit from program
consistency. Because the ANNIE-IDE software utilizes strict coding
conventions, the machine dependency of interactive programs
generated by its use is kept to a minimum, resulting in a high
degree of portability to various hardware. The residual machine
dependencies are identified in Section 2.4. Finally, the ANNIE-
IDE system can make the task of developing a user interface much
easier for an application programmer. The expediency of using
ANNIE-IDE will become more evident in the remainder of this manual,
particularly Sections 4 and 5.
1.3 MANUAL CONTENTS
Section 2 of this manual provides background on the development of
the ANNIE-IDE system; an overview of the toolkit contents and
application procedures; and a description of the system's scope,
design requirements, goals, and limitations. Section 3 describes
the theoretical considerations of interactive system design in
general terms and then relates these considerations to the ANNIE-
IDE package. In Section 4, general instructions are given for
building and storing screen definition files, using the individual
toolkit subroutines, and implementing a Fortran program that calls
the subroutines and sequences user interactions. In Section 5,
detailed examples of the application of the toolkit are provided.
In Section 6, ideas for additional development activities are
presented. In addition to the instructional materials in the main
body of this manual, two appendices are provided. Appendix A is
a glossary of technical terms used in the manual, and Appendix B
is a programmer's reference manual that provides details related
to toolkit subroutines, data structures, screen definition files,
the formats for the screen definition file used to build an
interactive program, specification of system parameters, and
contents of the ANNIE-IDE distribution disks. Appendix B is
designed for easy reference during the actual interface building
activities. The ANNIE-IDE distribution disks include additional
documentation for the toolkit subroutines.
-------
SECTION 2
OVERVIEW
2.1 BACKGROUND
2.1.1 WDM and ANNIE
Over the last several years, the U.S. Environmental Protection
Agency (USEPA) and the U.S. Geological Survey (USGS) have been
developing an integrated framework for environmental models called
the Watershed Data Management (WDM) System (Lumb and Kittle, 1986).
This framework has been developed to facilitate the joint,
integrated use of environmental models and relevant databases
required for model application. The framework has been oriented
towards computer models with intensive data requirements and
contains a user interface named ANNIE (Lumb et al., 1988). ANNIE
is organized as a toolkit of Fortran subroutines that allow
manipulation of databases and screen information, and perform many
of the functions required to support model operation. ANNIE helps
users interactively store, retrieve, list, check, update, and
analyze spatial, parametric, and time-series data for hydrologic
models. A binary, direct-access file is used to store the data in
a logical, well-defined structure called the WDM file. Many
hydrologic and water-quality models and analysis tools developed
by the USGS and the USEPA currently use the WDM file, ANNIE, or
both.
ANNIE/WDM provides the user with a common data base for many
applications, hence eliminating the need to reformat data from one
application to another. Furthermore, the ANNIE/WDM system offers
its users an expanding library of subroutines for graphics, user
queries, graphic and data storage, and retrievals to enable a
programmer to efficiently create software for highly specialized
applications. Figure 2.1 provides a summary of ANNIE capabilities.
2.1.2 EMIFE
A second user interface toolkit, the Environmental Model Input File
Editor (EMIFE) (General Sciences Corporation, 1987) , has been
developed recently as a result of a joint project between EPA's
Office of Research and Development and Office of Toxic Substances.
EMIFE is based on user interaction capabilities developed for the
Graphical Exposure Modeling System (GEMS) and the microcomputer
-------
Data Management
oCreate space on a disk for a WDM file
oDefine attributes for each data set that will be stored in the WDM file
oAdd, modify, or delete time-series data from data sets
oCopy all or part of the data in one data set to another data set within the same WDM file
oUpdate the WDM file by deleting or renumbering data sets
oExport data sets from a WDM file to a flat file
oImport data sets from a flat file to a WDM file
oLoad U.S. Geological Survey (USGS) and Hydrological Simulation Program-Fortran (HSPF) sequential
files into WDM files
oPerform selected numerical transformations on one or two time series to produce a new time
series
Data Display
oDisplay data-set attributes in list or tabular format
oList time-series data in a data set that are within a specified time span and value range
oList data in a data set that are within a specified time span but outside of a value range
oDisplay a summary of data sets for a WDM file
oDisplay a list of data sets that exhibit user-specified attributes
oTable a year of time-series data by month and day
oPlot one or more time series over a specified time span
oProduce x-y plots for time-matched values from two data sets in a WDM file
oProduce x-y plots for time-matched values of two data types input by a terminal session
oProduce x-y plots of attribute pairs for all data sets or a selected subset of the data sets
in a WDM file
oProduce a graphical representation of "the percent of time data values in a time series exceed
specified levels" as determined by ANNIE statistical analysis
oPerform flow-duration analysis (use all data in a time series)
oCompute error analysis statistics (use all data in two time series as a basis for computing
absolute errors, standard errors, error matrix)
oGenerate event statistics for a user-specified subset of a time series ("event" may be defined
by value threshold or time span)
oPerform event frequency analysis according to generalized procedures or Water Resources Council
(WRC) guidelines for determining flood flow frequency (USGS program J407, Bulletin 17B)
Model Input Preparation
oPrompt user for parameter values and options
oCheck user entries against acceptable range of values
oAssemble input sequences
oModify input sequence files
Figure 2.1. ANNIE functions and capabilities.
-------
version PCGEMS (General Services Corporation, 1988), which were
designed primarily to deal with models and data needed to evaluate
fate and exposure of chemicals covered by the Toxic Substances
Control Act. As part of the re-design effort accomplished in the
EMIFE system, computer dependencies of the code were removed, and
standard Fortran 77 was implemented. EMIFE is intended for use by
applications programmers to develop easy-to-use interfaces to the
environmental databases and models being developed by both the EPA
and its contractors. This toolkit complements the original ANNIE
user interface by adding additional input screen formats, but uses
a less sophisticated scheme for management of the potentially large
number of input screens required in a data intensive model. EMIFE
capabilities allow full screen editing of three classes of input
menu screens: a menu of input options, a menu of single value
items, and a menu of one-dimensional arrays of variable sizes.
2.1.3 ANNIE-IDE
During the first half of 1988, the ANNIE and EMIFE capabilities
were integrated into a consistent user interaction framework called
the ANNIE Interaction Development Environment (ANNIE-IDE). ANNIE-
IDE includes (1) a toolkit of subroutines that may be used by the
programmer to build a standardized user interaction, (2) a means
for storing and updating screen contents, and (3) a methodology for
interactive software development. This manual will guide
programmers, through explanation and example, in effective use of
ANNIE-IDE.
2.2 OVERVIEW OF TOOLKIT AND METHODOLOGY
The ANNIE Interaction Development Environment (ANNIE-IDE) was
created to provide a consistent methodology for building
interactive interfaces for environmental computer programs and data
bases. The ANNIE-IDE software combines a toolkit of subroutines
for interface construction that can be called from Fortran programs
with a convenient means for storing and updating screen contents.
This manual provides instructions for using the toolkit to build
an effective interface to both models and data bases. By providing
a powerful set of tools and a detailed consideration of the best
way to use these tools, the ANNIE-IDE software and manual can
greatly reduce the difficulty an application programmer will
encounter in developing an interactive interface.
The ANNIE-IDE toolkit consists of software that allows construction
of screens, control of screen display, and performance of related
housekeeping. Figure 2.2 illustrates the tasks that can be
accomplished using the toolkit.
6
-------
SCREEN CONTENT
CONSTRUCTION
Build Screen Definition
Files With Text Editor
Convert Screen Definition
Files to WDM Message
File and Vice Versa
ANNIE-IDE TOOLKIT
SCREEN INTERACTION
CONTROL
Present Text Options
and Data Along With
Assistance to User
Supply User-Specified
Options and Data to
Application Program
HOUSEKEEPING
System Initialization
System Cleanup
Display System Status
Set Availability of
Advanced Movement
Between Screens
Get Text From WDM
Message File
Figure 2.2. ANNIE-IDE toolkit.
2.2.1 Screen Content Construction
The content of screens is defined by using screen definition
directives. The concept of "directives" was developed in ANNIE-
IDE to (1) eliminate the code required to construct screens from
the main body of the interactive program and (2) enable the
application programmer to use consistent methods for screen
construction. The directives provide the necessary information to
the toolkit subroutines to control text and data display on the
screens.
The contents of an individual screen are defined by a series of
directives called a screen group. Screen groups for all screens
needed by the interactive program are constructed in a sequential
file by using a text editor. After this file has been developed,
ANNIE-IDE provides a stand-alone interactive program called MESSIE
that is used to convert the sequential file to a WDM message file.
The WDM file is direct access and hence allows much-improved
application program communication with large amounts of screen
information. A single WDM message file can contain the contents
of many individual screen definition files. In fact, more than
three million unique screens could conceivably be stored in one WDM
file. Use of the ANNIE-IDE software enables efficient modification
of existing screens and addition of new screens. To accomplish
these tasks, the MESSIE program is used to export the existing WDM
message file contents back to a sequential file, which can be
-------
modified using a text editor and then re-imported to the WDM
message file.
2.2.2 Screen Interaction Control
Tools for screen interaction control enable the presentation of
text options and data along with associated assistance to the user.
These tools are subroutines that are called from the application
program. They handle all interaction with the user within the
specified screen. When the user indicates completion of the
screen, these tools supply the application program with the user-
specified option or data.
2.2.3 Housekeeping
In addition to the subroutines needed to perform the above-
mentioned operations, the ANNIE-IDE toolkit also contains
housekeeping subroutines to initialize ANNIE-IDE within an
application, display system status, set the availability of
advanced screen movement within an application, retrieve text from
the WDM message file and shut down ANNIE-IDE upon completion of its
use. Full instructions and examples for using the system for these
purposes are provided in Section 5.
2.2.4 Sample Screens
The subroutines for screen display control are divided into five
groups by function:
o display text
o select an option from a menu
o evaluate a one-dimensional (1-D) array of related values
o evaluate a two-dimensional (2-D) array of related values
o open a file to store or retrieve text and other information
The overall function of the toolkit subroutines can best be
illustrated by providing sample screens (Figures 2.3 - 2.7) for
each of these five functions which have been generated by using the
ANNIE-IDE software.
The TEXT screen (Figure 2.3) is used to display information to the
user. It may contain up to 50 lines of text, with 10 or 16
available for viewing at any time. The user may use the cursor
movement keys to view other portions of the text. The 'NEXT1
command is used to move on to the next screen.
The MENU screen (Figure 2.4) is used to select an option. The
selection may be made using the first letter of the option(more
letters if a conflict exists) or the cursor movement keys and the
"NEXT" command.
-------
-WELCOME-
******
******
******
******
******
**********************************************
****** WELCOME TO "ANNIE/DBAPE"
DATED JANUARY 12, 1988
REVISION OF AUGUST 10, 1988
*************************************************
if you are not familiar with this program
press 'F11 for instructions
,-HELP-
DBAPE is used to ANALYZE soil property data along with the geographic
distribution of soils and to ESTIMATE parameters for the RUSTIC model.
^INSTRUCT-
'Next' command to go to next screen
Help:Fl Next:F2 Quiet:F8 Xpad:f$ Cmnds
Figure 2.3. Sample text screen.
The 1-D ARRAY screen (Figure 2.5) is used to enter numeric values
or text. Up to 24 fields of information may be entered. The user
may use the cursor keys to move between fields. Details about each
field may be requested with the "HELP" and "LIMITS" commands. User
input is checked against valid values and errors are reported if
incorrect input is detected. The user may adjust the value for the
currently highlighted field by specifying an arithmetic expression
(e.g., "*3".) The "NEXT" command is used to go to the next screen.
The 2-D ARRAY screen (Figure 2.6) is used to enter arrays of
numeric values or text. Up to 24 fields and 49 rows of information
may be entered. Movement within this screen is similar to that in
the 1-D ARRAY screen with the additional feature of "WINDOW." This
allows manipulation of large blocks of data simultaneously.
The FILE screen (Figure 2.7) is used to enter the name of a file
that is needed by an application. If the named file does not meet
programmer-specified criteria, then additional information is
automatically requested from the user.
It should be emphasized that, although the ANNIE-IDE toolkit can
minimize the effort needed to program the more mechanical aspects
of an interactive program, the application programmer remains
responsible for designing an effective sequence for user
-------
,-MAIN OPTION SELECT-
Which DBAPE option?
ANALYSIS - analyze soil property or geographic data base
ESTIMATE - estimate parameter values for RUSTIC
r-INSTRUCT-
Select an option using arrow keys or first letter of option.
Confirm selection with 'Next1 command.
Help:tt Next:F2 Xpad:F9 Cmnds
Figure 2.4. Sample menu screen.
1
REAL PARH SPEC
for parameter: DP1
What is the minimum value for this parameter? > 0-; . -. .-;:?l
What is the maximum value for this parameter? >
INCLUDE or EXCLUDE soils within specified range? > INCLUDE
. 1 TMTT*;
Default: O.OOOOE+00 Minimum: O.OOOOE+00 Maximum: none
__TUCTPI ifT
Enter data in highlighted field.
1elp:Ft Next:f2 Prev:f4 Limits:^ Xpad:f$! Cmnds Status Oops Quiet
Figure 2.5. Sample 1-D array screen.
10
-------
— Muuncn i
Enter data type 3: Flow
Order Hum of
of
Reach
1.
2.
3.
4.
5.
Avail
Sources
0
0
0
0
0
augmentation data.
Target Order of Available Augmentation
DO Level
(mg/l)
5.
5.
5.
5.
5.
Sources
1st
0.
0.
0.
0.
0.
2nd
0.
0.
0.
0.
0.
3rd
0.
0.
0.
0.
0.
4th
0.
0.
0.
0.
0.
5th
0.
0.
0.
0.
0.
6th
0.
0.
0.
0.
0.
i-INSTRUCT-
Enter data in highlighted field.
Help:M Next:F2 Limits:F5 Xpad:F9 Cmnds Oops Window
Figure 2.6. Sample 2-D array menu screen.
-OUTPUT FILE-
Name of file for output?
-HELP-
Enter the name of a file which your system understands.
,-INSTRUCT-
Enter data in highlighted field.
Help:F1 Next:?2 LimitstfS Quiet:F8 Xpad:?9 Cmnds Oops
Figure 2.7. Sample file screen.
11
-------
interactions. The dual goals of this manual are to instruct the
programmer on using the ANNIE-IDE toolkit subroutines and to
provide ample guidance related to designing, implementing, and
storing the necessary components of an interactive program. To
accomplish this latter goal, detailed instructions are provided for
producing the two necessary products of the interface building
effort: (1) a WDM message file containing text, questions, and
messages (Section 4.2) and (2) an application program responsible
for calling and sequencing the toolkit subroutines (Section 4.3).
2.3 SYSTEM REQUIREMENTS AND GOALS
Seven system requirements have been established for development
and application of ANNIE-IDE. These requirements emphasize
consistency within and between interactive interfaces for
environmental models.
(1) The system framework for user interactions must be applicable
for use within a broad range of both batch and interactive
environmental models.
(2) The operational aspects of the system must be developed
following a consistent approach and guidelines.
(3) User interactions and procedures must be consistent
irrespective of the model/database to which the toolkit is
applied. For example, the same key should always be used for
'HELP1 information.
(4) Both model and system parameter values and options specified
by the user must be checked for correct ranges, and the
ranges displayed whenever available.
(5) The use of a "mouse1 will be allowed on the PC, but not
required. Microsoft Mouse Menu routines will be used to
process information from the mouse.
(6) Color is optional for screens on the PC, and users are
allowed to change colors to suit individual tastes.
(7) The software must be portable at a minimum to the IBM PC, DEC
VAX, and PRIME 850 systems. An ANSI standard terminal is
required.
In addition to satisfying the system requirements listed above, the
developers of the ANNIE-IDE system and this manual have attempted
to achieve a number of related, supporting goals:
(1) Integrate the best features of ANNIE and EMIFE into a
consistent user interaction framework.
12
-------
(2) Enable a system for storing and updating user interaction
text and parameter ranges.
(3) Incorporate effective error handling methods.
(4) Reduce memory requirements for interactive systems.
(5) Improve user control over interaction sequencing.
(6) Provide system design guidance based on "human factors"
research.
2.4 LIMITATIONS
ANNIE-IDE and its manual are designed to aid the application
programmer in several critical components of interactive program
development. However, the limit of their scope and utility should
be kept in mind from the onset of a planned application.
Consequently, several key functional limitations of the ANNIE-IDE
software and manual are outlined below:
(1) The current ANNIE-IDE is limited to a large extent to input
functions. Data management and output functions (e.g.,
plotting) are beyond the scope of the current project and
hence the programmer must develop such functions parallel to,
but without the assistance of, ANNIE-IDE. (Provision has
been left for plotting within the two-dimensional array
screen, but has not been implemented.)
(2) The programmer is responsible for all file formats and data
structures required by the specific model for which an
interactive interface is being developed.
(3) The toolkit subroutines and manual instructions emphasize
"intrascreen functions." Although some aid is provided for
implementing "interscreen" communication, these functions are
outside the scope of work of the ANNIE-IDE development
project and hence have not been fully developed.
In addition to these functional limitations, ANNIE-IDE also is
subject to a small number of hardware portability limitations that
result from the use of extensions to Fortran as listed below. All
these extensions are supported on the IBM PC, the Dec VAX, and the
Prime 850. If the planned interactive code is to be used on other
hardware, it is the programmer's responsibility to assure that the
following extensions are allowable on the target hardware:
(1) Reading single characters without a carriage return
(2) Writing a string of characters without a carriage return
13
-------
(3) Using ANSI standard terminal cursor movement for the
following functions: "home cursor," "cursor position,"
"cursor relative move," and "clear screen."
2.5 TOOLKIT DEMONSTRATION EXAMPLES
As a component of the ANNIE-IDE development project, the toolkit
has been used to develop an enhanced user interaction for an
already-existing environmental model, QUAL2E-UNCAS (Brown and
Barnwell, 1987) , and for a recently developed soils properties
analysis program, DBAPE (unpublished). Because the examples
provided in this manual are all excerpted from the development of
the user interaction for QUAL2E-UNCAS and DBAPE, a brief
description of each is provided for programmers who are unfamiliar
with them.
QUAL2E-UNCAS and its predecessors QUAL-II and QUAL-2E are probably
the most widely used computer models for predicting the effects of
conventional pollutants in streams. The model simulates the
following water quality constituents: dissolved oxygen,
biochemical oxygen demand, temperature, algae, nitrogen and
phosphorus species, coliforms, an arbitrary nonconservative
constituent, and three conservative constituents. QUAL2E-UNCAS is
a steady-state hydraulics model with both steady-state and quasi-
dynamic water quality capabilities. Many model parameter values
required by this program are variable by reach, and certain
meteorologic parameters are variable with time. QUAL2E-UNCAS also
allows the modeler to perform uncertainty analyses for specified
model parameters by utilizing Monte Carlo simulation techniques.
QUAL2E-UNCAS was selected for demonstration of the ANNIE-IDE
capabilities for several reasons. First, the model has evolved from
predecessor models that have been effectively used for analysis of
numerous environmental problems by a wide user audience. Second,
the model already had an interactive interface developed through
the use of ANNIE. This fact allowed the development of enhanced
interactive capabilities for a rather complex model with a lesser
level of effort than would have otherwise been required. Because
the model requires considerable input, and input of many different
kinds, application of ANNIE-IDE to QUAL2E-UNCAS was a good test of
the toolkit's ability to provide the programmer with the
capabilities needed to build an interactive interface for any
environmental model.
The Data Base Analyzer and Parameter Estimator (DBAPE) is an
interactive program currently under development at the
Environmental Research Laboratory, Athens, Georgia. At present
DBAPE interacts with two data bases: the first contains a
compilation of the acreage of individual agricultural soils types
(by USDA soil classification) across the United States on a county
basis; the second is a compilation of soils characteristics for
14
-------
each USDA soil classification such as crop suitability, average
depth of soil horizons, percent sand, silt, and clay, SCS runoff
classification (hydrologic group), and other pertinent physical
data. The current version of DBAPE allows the user to locate and
rank the acreage of a particular soil type by county, find all the
soil types which exhibit one or more of the characteristics
compiled in the data base (e.g., soils classified as belonging to
SCS hydrologic group B and also suitable for growing corn), and
export the results of any interactive operation to a file or the
line printer.
Examples from both QUAL2E-UNCAS and DBAPE are used in Section 5 to
illustrate general procedures involved in an ANNIE-IDE application.
The source code and file definition directives for these two
applications are found on the distribution disks for ANNIE-IDE.
15
-------
SECTION 3
THEORETICAL CONSIDERATIONS OF ANNIE-IDE DEVELOPMENT
Whereas subsequent sections of the manual emphasize the mechanical
aspects of utilizing ANNIE-IDE to facilitate the development of
interactive programs, this section describes the theoretical
considerations of interactive system design and relates these
considerations to the design and anticipated programmer
applications of the ANNIE-IDE package. The discussion presented
in this section relies heavily on the results of current "human
factors" research which is providing a much better understanding
of the requirements for effective man-machine interfaces.
3.1 GENERAL THEORY OF INTERACTIVE INTERFACES
The purpose of this section is to expose programmers who are
undertaking an ANNIE-IDE application to the general principles that
should govern the development of an interactive program interface.
The ideas and guidelines presented here are products of the
expanding field of human factors research. Recently, a number of
books and numerous research efforts have been devoted to defining
improved strategies for effective human-computer interaction.
Although a comprehensive consideration of human factors principles
is beyond the scope of this manual, a basic understanding of these
principles is necessary to appreciate the motivation for ANNIE-IDE
design and application instructions.
The material presented here originates from two sources: the notes
and comments of Professor Albert Badre who served as a technical
consultant to the ANNIE-IDE development effort and a book entitled
Designing the User Interface by Professor Ben Shneiderman (1987).
Topics addressed include:
o human factors goals
o why interactive systems fail
o rules of system design
o interactive system styles
o menus
o form fill-in
The intent of presenting this material is twofold: first, to
explain the foundation on which the ANNIE-IDE toolkit and
application instructions are based, and second, to provide
16
-------
guidelines for developing those components of the interactive
program that are not direct products of applying ANNIE-IDE. Hence,
although all the material contained in this section will prove
useful in developing an interactive program, only a portion, as
identified in later portions of this section, is embodied in the
current ANNIE-IDE system. Without question, application of the
general guidelines outlined below will improve the quality of all
aspects of an interactive program; consequently, the application
programmer is encouraged to review this section of the manual on
an regular basis during the program development effort.
3.1.1 Human Factors Goals
It is generally accepted that the ultimate goal of software is
"usability." Usability is achieved by: (1) creating an environment
in which the user feels in control; that is, the user "drives" the
system in the same sense that a driver controls a car; and (2)
reducing the level of effort needed by the end-user to complete
tasks. Hence, the overall goals of interface development should
be to:
o minimize time required to learn, search for information,
acquire knowledge, or understand the computer task to be
performed
o maximize speed of performance of tasks
o reduce user errors
o provide the user with protection from danger of system
failure, thereby encouraging exploration of system
capabilities
o maximize satisfaction of users
Human factors researchers recognize that there are necessary
tradeoffs between these goals; consequently, priorities must be
identified and ranked at the onset of each interface development
project. Shneiderman (1987) notes that success in achieving all
the above listed goals can be quantified; hence, usability of
interactive software need not be a subjective term.
3.1.2 Why Interactive Systems Fail
Interactive systems that are deemed "failures" by the user
community are often hindered by the following inadequacies:
o inconsistent internal style and methods
o inadequate on-line user assistance
o rigid sequencing that does not allow the user to efficiently
perform frequent tasks
o program operations that cause the user to feel a loss of
control
17
-------
3.1.3 Rules of System Design
Shneiderman presents the following list of underlying principles
for design of interactive systems.
o strive for consistency
o provide shortcuts for frequent users
o offer informative feedback
o design dialogues that indicate the completion of operations
o offer simple error handling
o permit easy reversal of actions
o allow users to initiate actions rather than to solely respond
to program queries
o minimize the user's short-term memory load
3.1.4 Styles for Interactive Systems
In constructing an interactive program, the application programmer
may utilize a variety of interaction styles. The scope of work for
development of the ANNIE-IDE system was restricted to functions
related to menu selection and form fill-in; hence, the remainder
of this section is devoted to outlining general guidance related
only to these two styles of interaction. For many applications,
a combination of the two interaction styles is appropriate. The
advantages and disadvantages of using these styles are summarized
in Table 3.1.
TABLE 3.1. ADVANTAGES AND DISADVANTAGES OF CANDIDATE INTERACTION
STYLES (ADAPTED FROM SHNEIDERMAN (1987))
Interaction Style
Advantages
Disadvantages
Menu selection
Form fill-in (screens)
shortens learning
reduces keystrokes
structures decision-making
permits use of dialogue management tools
easy to support error handling
simplifies data entry
requires modest training
assistance is convenient
permits use of form management tools
danger of many menus
may slow frequent users
consumes screen space
requires rapid display rate
consumes screen space
18
-------
3.1.5 Menu Selection Interactions
Effective menu selection systems are the result of careful
consideration and testing of numerous design issues such as menu
organization and structure, the number and sequence of menu items,
titling, prompting format, graphic layout and design, phrasing of
menu items, display rates, response time, shortcuts through the
menus for knowledgeable frequent users, availability of help, and
the selection mechanism (keyboard, pointing devices, etc.).
Guidance that will be particularly useful for developing an
interface using ANNIE-IDE is summarized below. Included are rules
for grouping in menus and menu tree structures, rules for
sequencing the selections in a menu, and general considerations for
menu construction. If the programmer desires more detailed
guidance on any of the items presented, reference to Shneiderman
(1987) or other currently available human factors texts is
recommended.
3.1.6 Rules for Grouping Items in Menus and Tree Structures
Adhering to the following rules will result in an effective
grouping of menu items for user interaction:
o limit menus to seven items or less
o create groups of logically similar items
o form groups that cover all possibilities
o make sure items are nonoverlapping
o use familiar terminology, but ensure items are distinctive
from each other
3.1.7 Menu Item Presentation Sequence
If items have a natural sequence, ordering should reflect it;
examples are:
o time
o number
o physical properties
For items with no apparent natural sequence, ordering may be
according to:
o alphabetic sequence of terms
o grouping of related items
o most frequently used items first
o most important items first
19
-------
3.1.8 General Considerations (adapted from Shneiderman (1987))
o describe menu items briefly and in a consistent grammatical
style
o use consistent layout and terminology
o give position in organization by graphic layout, numbering
and titles
o use menu items as menu titles for menus of next lower level
o permit type-ahead, jump-ahead, and other short-cuts
o permit jumps to previous and main menu
o offer "help" facilities
3.1.9 Form Fill-in Interactions
If data entry of names and numeric values is needed, and especially
when many fields of data are necessary, the appropriate interaction
style is form fill-in. General guidelines for developing
interactive screens for form fill-in, as suggested by Shneiderman
(1987), are:
o give the form a meaningful title
o use comprehensible instructions
o use logical grouping and sequencing of fields
o develop a visually appealing layout
o use familiar field labels
o use consistent terminology and abbreviations
o provide error correction for characters and fields
o utilize visual templates for common fields
o implement "help" facilities
A final general comment concerning interface development should be
of considerable interest to application programmers planning to use
ANNIE-IDE to build an interactive interface. In his book Designing
the User Interface, Shneiderman singles out computer use in
exploratory environments, such as environmental modeling, as the
most difficult in which to develop successful interfaces. He
attributes this difficulty to three problems:
o user tasks tend to be less repetitive and require more system
flexibility
o system usage tends to be less frequent, increasing the need
for on-line assistance and good retention characteristics
o users tend to have high expectations of the systems they
apply
Using the ANNIE-IDE toolkit during interactive program development
cannot free the programmer from dealing with any of these inherent
problems. It can, however, allow the programmer to minimize the
effort needed to develop the mechanical aspects of the interface
and hence focus attention on the more challenging components of
20
-------
interface development intrinsic to the domain of environmental
science and engineering.
3.2 APPLICATION OF HUMAN FACTORS THEORY TO ANNIE-IDE
To better understand how the theoretical considerations of human
factors research are embodied in ANNIE-IDE, it is useful to
differentiate between "intrascreen" and "interscreen" functions in
an interactive program. The focus of the ANNIE-IDE toolkit is to
provide assistance in developing intrascreen functions; that is to
say, the tools allow the programmer to build individual screens.
Hence, in the strictest sense, a discussion of the theoretical
basis for ANNIE-IDS could be restricted to the realm of screen
building. It has been a goal of this project, however, to provide
sufficient instructions and examples in the manual to guide
application programmers in the construction of a complete
interactive program. Thus, guidance also has been given on
interscreen functions such as control logic and screen sequencing.
ANNIE-IDE is a toolkit of utility subroutines and instructions for
developing and storing two parallel products: a file containing
text, questions, and messages used in interactive communication,
and a Fortran program containing the control strategy and
sequencing instructions for interactions. Consequently, the
discussion of theoretical considerations for ANNIE-IDE will not
only consider the basis of the ANNIE-IDE software, but its current
and recommended application procedures as well.
Goals for enhancing human factors focus on program control,
reliability, functionality, and consistency. Concern for all these
goals is reflected in the design of the ANNIE-IDE toolkit and in
its first two applications to the programs QUAL2E-UNCAS and DBAPE.
The toolkit itself is designed to allow the application programmer
to utilize the capabilities of over 200 utility subroutines while
dealing directly with approximately 40 lead subroutines. Program
functions can thus be performed reliably and consistently by
repeated use of the necessary toolkit components. By using ANNIE-
IDE, the programmer is encouraged to recognize and isolate data
management functions, thereby avoiding unnecessary clutter and
complexity in the interactive program code.
Additional manifestations of human factors theory are evident in
the sample screens developed during the first two toolkit
applications and used as illustrations throughout this manual.
Features of ANNIE-IDE that embody human factors theory include:
o screen layout
o data window
o assist window
o instruction window
o command line
21
-------
o user control within screens
o screen definition directives
o screen sequencing
The following sections provide details on the use of human factors
concepts in the implementation of ANNIE-IDE.
3.3 SCREEN LAYOUT
The impetus for developing ANNIE-IDE is recognition that a need
exists for an straightforward, consistent methodology for building
interactive interfaces. Although the focal point in developing
ANNIE-IDE is to provide tools and guidance that will make the
program development effort of the application programmer easier and
more productive, we recognize that the ultimate success or failure
of the effort depends on the user satisfaction with the final
product. One of the most important determinants of user
satisfaction is screen layout. If the "look and feel" of
communication screens can be made consistent, user comfort and
confidence in using the system is greatly increased.
To this end, we have made the general screen format resulting from
applying ANNIE-IDE an intrinsic feature. That is to say, while the
application programmer has a large degree of control over what
information appears on the screen, and the user has control over
when the information appears, the ANNIE-IDE software determines
where the information appears on the screen. By making screen
layout an intrinsic feature of ANNIE-IDE, the user always knows
where to look for specific kinds of information on the screen, and
the location remains the same for every screen in every interactive
program produced using ANNIE-IDE.
Figure 3.1 defines the basic layout of an ANNIE-IDE screen. Screen
information is divided into four components: three windows (data
window, assistance window, instruction window) and the command
line. For convenience, the dimensions, content, and important
features of the four screen components are summarized along the
periphery of the screen area in the figure. .Additional details on
types of content and features for each of these four screen
components are provided in sections 3.4-3.7. General construction
details for screen content are provided in Section 4 and
illustrated in Section 5.
22
-------
CO
1—
LU ^N LU
^ -J CO t—
g-— O Q Z CO
u- «t Z O Q
O *-* Q. < O LU
Z 2 Z X Z LU
.— O z O ztoz o
300-- o; o i— uj x
O Z •— h- Z O O CJ •— UJ tO LU
z O — I---IDZ vx Z Of 0
--. U. 3 < Z Z -- * -- 0 Z Z
o; z CJ •-••-• _i co z — i to «C O
,>- ~ O — • u. x — t Z> UJ * Z — •
CO U- _1 LU < O 1— h-O- Of Z I—
UJ Z O_ Q Z Of < 00 -J O O <
0 CJ •-• O. U 1— >- UJ u_ O tO Z
UJ Z - LU ^ » >- ^^ O — 1 — 1 •-! Of U.
•— CO Z CO O£ UJ )— CO CO Of O Z CO < t— LU Z
CJ^-v— •< CJ _l — • 1- LU<< ca u_ LU O
< 3 < O O < x * o O LU <; t— •-• zto
o^o^O afofo to ct a; co u- a. o •— z
uu < i :n a_ 3: oo o O-O_Z>O;OLUCOZ-JLU
Zit-t— t-tot^ z LU UID<_JZ
Z O — — ' Z LU < ZZQiCOCOUt- O-—
< H H O Ct 1— CO Z OOO^Z<- a. u. o u z
zzjoocozoccjt— 3
<^N-r^>— a. - 1— i>-
t- z z < t/
H- £ rO CJ U. (/
0 -3
LU
_J
•J—
•— •
3
z
3
t—
f
1
—J LL.CL<»— U-ZCOLU-JOf IE
ILUCOZQ-t— LU LU < >- CO _l LU O
i Z
E CO CO
z a z
JO Z CO CO C/> O
) _. i>_ — O_ 1— ID
? i— z z zcj_icox< a;
^ •-•'-' O LU I—
> t— Q CJ U. CO
) Z
c ~
LU
^
1-
3
o
z
3
LU
CJ
z
t—
CO
CO
to
a
irt
V)
'i
J
rvj
*^
4-*
X UJ
to
LU tO D
h- O LU
CJ Z CO
Z3 hO Z >-
Of LU Of CJ
1— X h- O LU
CO tO Of Of
Z 00 >- Ot ~
•— S- tO LU O
.,
CO
z
O CO
CO Z Of
LU Z UJ Z)
_j UJ t— h-
1— Z Z <
•— — • O LU
t— Q CJ Uu
O
CO 1— CJ
0 CJ — •
Z UJ CO
< 0. <
Z X CO O
5 of *~*. u ****
cj >- O ro z %±
m u. • < •
LU Ki > ro
— 1 O UJ Q
CO UJ — t UJ < LU
< Of CO -J _l
—I LU < CO Of CO
— • O — I < O <
> o < *"" "~ "~
< > LU CO LU
>• ^ LU O LU
Of —1 (O Z tO
O — 1 CO -^ < •*-*
li_ < Q Z
U Z tO Z tO
to —, < z o z
Z I- Z < CJ <
o < z a: of
•— Z LU O O O tD
1- O to U O 0 O
< t— 13 or < of
— • ^ U. O. Q_
> < u- O 5-
uj o a: < z
Of LU t- O Z O
CO Of >- UJ —• —
co < o to h- or i—
< z — 1—
z z <
— O UJ
O O LU
H
•
n
a>
M
3
23
-------
3.4 DATA WINDOW
The top portion of the screen is the data window. The data window
contents consist of one or more of the following.
(1) programmer-supplied prompts for user-supplied decisions by
means of menu selection (see data window entitled "MAIN
OPTION SELECT" in Figure 2.4 for example)
(2) programmer-supplied prompts for user-supplied data by means
of form fill-in (see data window entitled "AUGMENT" in Figure
2.6 for example)
(3) echoes for current state of data (see data window entitled
"WELCOME" in Figure 2.3 for example)
(4) analysis results
The title for each data window is specified by the programmer
during the screen definition process and can be up to 48 characters
long. Program structure can be emphasized by using the menu
options from the data window of a menu screen as the titles for the
data windows of the subordinate screens.
ANNIE-IDE allows for two user-controlled "sizes" for the data
window. The default dimensions are 78 X 16 characters; in this
scenario the assistance window is not displayed, resulting in a two
window, one command line screen (see Figure 2.3 for example). If
the user desires any of the forms of assistance described in
Section 3.5, then the data window is reduced to 78 X 10 characters
to accommodate the assistance window (Figure 3.1). ANNIE-IDE
currently accommodates data of dimensions up to 78 X 50 and enables
scrolling in the data window when the data size exceeds the window
size. If necessary, the programmer can expand the height dimension
(50) by increasing the size of the variables ZMNTXT and ZMNTX1 in
common block ZCNTL2 (see Appendix B.3 for details.)
3.5 ASSISTANCE WINDOW
Within an ANNIE-IDE application program, several types of user
assistance can be implemented. Some assistance is automatically
generated by ANNIE-IDE, some must be supplied by the application
programmer, and a limited amount may be provided by the program
user. For the sake of organization, the forms of assistance can
be classified into two groups: screen-dependent and screen-
independent. Screen-dependent assistance is specific to the
contents of a particular screen; screen-independent assistance is
more global in nature and can be called upon from all screens.
24
-------
Conceptually, three layers, or levels, of assistance can be
provided for screen-dependent information:
Level 1- Use of descriptive and unique words or abbreviations for
field or menu option names in the data window provides
"first-cut" definitions.
Level 2- When space allows, additional information in the data
window near the data field or menu option can clarify the
desired information.
Level 3- If additional parameter- or screen-specific assistance
is needed, it can be supplied in the assistance window.
The two types of screen-dependent assistance allowable
in the assistance window are HELP and LIMITS.
The rationale for providing a means for "layered" help should be
explained. Perhaps the most important goal in designing user
assistance for an interactive program is to provide the proper
amount of assistance at the proper time. The layered interaction
strategy of ANNIE-IDE is designed so that the user must
specifically request the higher levels of assistance; consequently,
experienced users are not subjected to unnecessary information.
Screen-independent, or global, assistance provides a fourth level
of help in the ANNIE-IDE software. There are four distinctive
types of screen-independent assistance. Two types (XPAD and CMNDS)
are implicit to ANNIE-IDE, and the other two types (STATUS and
TUTOR) must be implemented by the application programmer.
The assistance window is used to display level 3 screen-dependent
assistance (HELP and LIMITS) and all types of screen-independent
assistance (CMNDS, XPAD, TUTOR, and STATUS).
The function, source, and size limitations for each type of
assistance are summarized in Table 3.2. The user selects one
assistance type at a time and the available assistance of that type
is displayed in a 78 X 4 window directly below the data window.
The title of the window corresponds to the type of assistance which
has been requested by the user. The types of assistance which are
available for a screen are indicated by the options listed in the
command line (Section 3.7). When the application programmer adds
a new type of assistance for a screen (Section 3.10), ANNIE-IDE
automatically adds a corresponding command to invoke the new type
of assistance to the command line. However, the command line is
limited to 80 characters. If the size of the available assistance
exceeds the window size, ANNIE-IDE automatically enables scrolling
in the window.
25
-------
TABLE 3.2. ASSISTANCE WINDOW TYPES
ASSISTANCE
TYPE
FUNCTION
SOURCE OF
ASSISTANCE
ALLOWABLE
SIZE
PROGRAMMER NO LIMIT
PROGRAMMER NO LIMIT
ANNIE-IDE NO LIMIT
PROGRAMMER NO LIMIT
PROGRAMMER 10 LINES
HELP PROVIDES INFORMATION WHICH CLARIFIES PARAMETER
DEFINITIONS AND PROGRAM QUERIES
LIMITS DISPLAYS ALLOWABLE VALUES FOR AN ENTRY
CMNDS DISPLAYS AND DEFINES AVAILABLE COMMANDS
TUTOR PROVIDES DETAILED PROGRAM TUTORIAL
STATUS DISPLAYS PROGRAMMER-DESIGNED SYSTEM STATUS
MESSAGES WHICH SUMMARIZE PREVIOUS ACTIONS AND
INDICATES RELATIVE LOCATION OF USER WITHIN
PROGRAM STRUCTURE
XPAD ALLOWS USER TO WRITE NOTES AND REMINDERS DURING USER 10 LINES
INTERACTIVE SECTION
Details on each of the assistance types follow.
HELP
HELP assistance provides further information on model and system
parameters and menu options. As noted above, HELP text must be
provided by the application programmer and is specific to a
particular screen. There are no size limitations on the HELP text,
and it can be scrolled in the assistance window.
LIMITS
LIMITS displays, in the assistance window, the allowable values for
a specific field in the data window. LIMITS information may be
maximum and minimum acceptable numeric values or a list of
acceptable alphanumeric values. LIMITS text must be provided by
the application programmer and is specific to the identified field
in the data window.
There are no size limitations on LIMITS text and it can be scrolled
in the assistance window.
CMNDS
CMNDS displays the names and definitions of all active commands at
the current location within the interactive program. The command
definitions are intrinsic to ANNIE-IDE; hence, the definitions
26
-------
never change. It should be noted, however, that the list of
available commands varies according to location within the program.
For example, the programmer may elect to use the STATUS command
only at certain program "levels." The availability of commands
also may be influenced by the contents of the data window of the
current screen. For example, the WINDOW command (Section 3.7) is
only available when two-dimensional data are present in the data
window, and the scrolling commands (UPPG, DNPG) are only available
when data for the current data window exceed the window dimensions.
There are no size limitations on CMNDS text, and it can be scrolled
in the assistance window.
TUTOR
TUTOR provides a general tutorial for all aspects of the
interactive program. A single body of text, which must be provided
by the application programmer, is available at all times during the
interactive session. Whenever TUTOR assistance is requested by the
user, the entire tutorial text is called up, and the user must
scroll through the text within the assistance window to search for
the desired information. There are no size limitations on the
TUTOR text.
STATUS
STATUS assistance displays programmer-designed system status
messages that summarize previous actions and indicate the relative
location of the user within the program structure. Incorporating
comprehensive STATUS assistance into the interactive program can
be the programmer's most effective means of assuring that the user
does not become lost or confused during a complex sequence of
operations.
A maximum of 10 lines of STATUS assistance may be viewed by the
user at any point within an application. Because the application
programmer may change the STATUS messages, however, there is no
practical limit to the amount of STATUS assistance that may be
available in an application.
XPAD
Scratch pad (XPAD) assistance allows the user to write notes and
reminders during an interactive session. The current capabilities
in ANNIE-IDE for providing this type of assistance are of a basic
nature. At this time the user may record information in a single
XPAD with a maximum width of 80 characters and length of 10 lines.
Regardless of where the user is located within the interactive
session, a request for XPAD assistance will call up the same XPAD
with the same information. ANNIE-IDE enables scrolling of XPAD
27
-------
information in the assistance window. New notes can be added to
existing notes, and existing notes can be overwritten.
3.6 INSTRUCTION WINDOW
The instruction window is always present on every screen produced
using ANNIE-IDE. In the screen layout, it is located below the
data and assistance windows and directly above the command line
(see Figure 3.1). The contents of this window are entirely
controlled by the ANNIE-IDE software; the application programmer
cannot modify the window contents. Two types of information are
provided in the window: instructions for the user's next keystroke
or error messages reporting incorrect keystrokes with instructions
for corrective actions. Depending on which type of information is
displayed by the system, the window title on the screen will be
either "INSTRUCT" or "ERROR." Figure 2.3 gives an example of the
type of information commonly provided in an INSTRUCT-type
instruction window, and Figure 3.2 illustrates an ERROR-type
instruction window.
rpnp cci err
for parameter: CROP
What crop to find?
INCLUDE or EXCLUDE soils
UCI p
01- CORN 23-
02- COTTON 24-
03- GRASS/PAS/HAY 25-
04- OATS 26-
FPPOP
> 9999
within specified range? > INCLUDE
PECANS 45- CAULIFLOWER
GRAPES 46- CELERY
PEACHES 47- APRICOTS
PEAS 48- ALMONDS/WALNUT
Invalid data input in highlighted field.
Use Limits command to see acceptable range,
Help command to see field definition.
Figure 3.2. Example error message in instruct window.
3.7 COMMAND LINE
The final component of the standard screen produced by ANNIE-IDE
is the command line (Figure 3.1). The command line is restricted
to one line having a maximum length of 80 characters. It contains
a menu of abbreviations for the available commands at the user's
28
-------
current location within the program structure. The commands are
automatically ordered by expected frequency of use, with the most
commonly used commands located toward the beginning of the line.
Definitions of the abbreviated commands are made available to the
user by invoking the CMNDS assistance in the assist window (Section
3.6) .
Table 3.3 lists the basic commands available for ANNIE-IDE
applications. Included are definitions and command order numbers
for eleven basic commands and three planned command extensions.
The command order numbers indicate the relative order in which the
commands will appear on the command line when they are available.
Inspection of the command line in Figure 3.1 shows that some of the
commands are associated with the PC functions keys and some are
not. Instructions on the alternate methods for invoking the
various commands are provided in Section 3.8.
TABLE 3.3. COMMANDS FOR BASIC APPLICATION OF ANNIE-IDE
COMMAND COMMAND
NAME ORDER # COMMAND DEFINITION
CMNDS 2 DISPLAY DEFINITIONS OF VALID COMMANDS IN ASSISTANCE INFORMATION WINDOW
DNPG H DISPLAY NEXT PAGE IN DATA WINDOW
HELP 1 DISPLAY HELP INFORMATION IN ASSISTANCE INFORMATION WINDOW
LIMITS 6 DISPLAY LIMITS OF CURRENT FIELD IN ASSISTANCE INFORMATION WINDOW
NEXT 3 GO TO NEXT SCREEN (SETS SCREEN EXIT STATUS CODE TO 1)
OOPS 8 RESET VALUES IN DATA WINDOW TO VALUES WHEN SCREEN FIRST DISPLAYED
QUIET 20 TURN OFF ASSISTANCE INFORMATION WINDOW TO ALLOW MORE ROOM FOR DATA
STATUS 7 DISPLAY SYSTEM STATUS IN ASSISTANCE INFORMATION WINDOW
UPPG 15 DISPLAY PREVIOUS PAGE IN DATA WINDOW
WINDOW 9 DEFINE CORNER OF DATA OPERATION WINDOW
XPAD 21 DISPLAY USERS SCRATCH PAD, ALLOW CHANGES
planned command extensions
MOVE 10 COPY ROWS/COLUMNS OF TWO-DIMENSIONAL DATA
TUTOR 5 PROVIDE TUTORIAL
VIEW 11 DISPLAY GRAPHIC DATA
It should be noted that the eleven basic commands are "fixed"
within ANNIE-IDE, and cannot be removed by the programmer. As
explained in the previous section not all eleven commands are
available at any given location within the program, but their
availability is determined by the system, not the application
programmer. The programmer may, however, enable a number of
additional commands related to movement between screens; these
commands are introduced in Section 3.10.
A final feature of the command line is mentioned here to avoid
confusion. As will be explained in the following section, three
29
-------
interaction modes are utilized by programs developed using ANNIE-
IDE: data mode, command mode, and assist mode. The command line
appears on the screen when the user is utilizing either the data
mode or the command mode. When the user has invoked the assist
mode, the command line is removed from the screen to avoid
confusion, and command instructions are displayed in the
instruction window. Figure 3.3 illustrates the layout for a screen
when the user is in "assist mode" and the command line is not
displayed. When the user leaves the assist mode to return to
either of the other two modes, the command line reappears.
ppnp ccp cry
for parameter: CROP
What crop to find? > 0.
INCLUDE or EXCLUDE soils within specified range? > INCLUDE
HhU
01- CORN 23- PECANS 45- CAULIFLOWER
02- COTTON 24- GRAPES 46- CELERY
03- GRASS/PAS/HAY 25- PEACHES 47- APRICOTS
04- OATS 26- PEAS 48- ALMONDS/WALNUT
INSTRUCT
Page Down or Down Arrow for more text
ESC to return to Data
Figure 3.3. Screen layout in assist mode.
3.8 USER CONTROL WITHIN SCREENS
3.8.1 User Interaction Modes
User interaction is organized into three "modes," each with a
specific function:
o data mode - enter data or select from menu options in data
window
o command mode - invoke commands or functions listed in command
line; basic commands perform three functions:
(1) allow exit from screens (NEXT)
(2) manage assistance window (HELP, LIMITS, XPAD, STATUS,
CMNDS, TUTOR, QUIET)
30
-------
(3) manipulate data window (UPPG, DNPG, OOPS, WINDOW, MOVE,
VIEW)
o assist mode - provide user with supplemental information in
the assistance information window on which to base subsequent
actions.
3.8.2 Keystrokes and Communication Features
ANNIE-IDE applications allow the user the flexibility of using both
keyboard and mouse communication. From the keyboard mode, commands
may be invoked either by pressing designated function keys or by
typing the first letter of a command name. Likewise, menu options
may be selected either by moving the cursor (either by use of
cursor keys or a mouse) to the selection field and confirming, or
by typing the first letter (or letters, if needed) of the menu
item. For each of the three interaction modes, individual keys and
key groups are used in a consistent manner as summarized in Table
3.4.
Several features of user communication using these keystrokes
within the framework of ANNIE-IDE should be noted:
o there are no restrictions to upper- or lower-case mode
o the system does not use the same key or command to invoke two
different functions
o cursor keys are always used to invoke movement within a
screen
o cursor or mouse movement in command mode results in the
sequential highlighting of command options; pressing the
ENTER key, or clicking the mouse, invokes the currently
highlighted command
o character keys can be used to select commands when in command
mode
o character and number keys are used to enter data in a field
or select a menu item when in data mode
o function keys are only used to invoke commands
o the TAB and F3 keys are left undefined to avoid system-
related conflicts
o in data mode, arithmetic operands (+,-,*,/,**) can be used to
modify values in 1- or 2-D arrays. For 1-D screens, cursor
movement highlights fields for individual data values. An
arithmetic operation can implemented by typing it into the
appropriate field and then pressing the "ENTER" or "RETURN"
key. For 2-D screens, the "WINDOW" command allows the user
to perform global manipulations by establishing a highlighted
field, and then typing the operation into this field. All
values within the specified field are modified accordingly.
31
-------
TABLE 3.4. KEYSTROKES AND THEIR RESULTS
MODE KEY GROUP
KEY CODE
RESULT
DATA PRINTABLE
CHARACTER
UNPRINTABLE
CURSOR
MOVEMENT
FUNCTION
ENTER
OR
RETURN
ESC
F3
TEXT SCREEN - NOTHING
MENU SCREEN - SELECT OPTION(S) ASSOCIATED WITH CHARACTER
NO CONFIRMATION NEEDED
DATA SCREEN - CHARACTER INSERTED AT CURSOR POSITION
TEXT SCREEN - NOTHING
MENU SCREEN - NOTHING
DATA SCREEN - END FIELD, MOVE TO NEXT FIELD
SWITCH TO COMMAND MODE
NOTHING
MOVE WITHIN DATA WINDOW AS APPROPRIATE
ESC
EXECUTE ASSOCIATED COMMAND (FI-'Help1, etc.)
COMMAND
PRINTABLE
CHARACTER
UNPRINTABLE
CHARACTER
CURSOR
MOVEMENT
FUNCTION
ENTER
OR
RETURN
ESC
LEFT
RIGHT
F3
EXECUTE COMMAND WITH CORRESPONDING FIRST LETTER IF
AVAILABLE
SELECT HIGHLIGHTED COMMAND
SWITCH TO DATA MODE
NOTHING
HIGHLIGHT COMMAND TO THE LEFT
HIGHLIGHT COMMAND TO THE RIGHT
NOTHING
ESC
NOTHING
ASSIST
PRINTABLE
CHARACTER
UNPRINTABLE
CHARACTER
CURSOR
ESC
ENTER
OR
RETURN
XPAD - CHARACTER INSERTED AT CURSOR POSITION
OTHER - NOTHING
SWITCH TO DATA MODE
XPAD - MOVE TO START OF NEXT LINE
OTHER - NOTHING
NOTHING
MOVE WITHIN ASSISTANCE WINDOW AS POSSIBLE
32
-------
3.8.3 Movement Between Interaction Modes
User movement from each of the interaction modes to the other modes
can be summarized as follows.
data mode to command mode - press ESC key
data mode to assist mode - press function key associated with
appropriate type of assistance or go through command mode
command mode to data mode - press ESC key
command mode to assist mode - select appropriate type of
assistance from options in command line
assist mode to data mode - press ESC key
assist mode to command mode - press ESC key twice (goes
through data mode)
3.9 SCREEN DEFINITION DIRECTIVES
The content of screens is defined by using screen definition
directives. The concept of directives is used in ANNIE-IDE to (1)
eliminate the code required to construct screens from the main body
of the interactive program and (2) enable the application
programmer to use consistent methods for screen construction. The
directives provide necessary screen definition information to the
toolkit subroutines that control text and data display on the
screens.
ANNIE-IDE allows the construction of five different screen types.
The screen types and their functions are:
TEXT display text
MENU select an option from a menu of options
1-D ARRAY edit a one-dimensional (1-D) array of related values
2-D ARRAY edit a two-dimensional (2-D) array of related values
FILE open a file to store or retrieve text and other
information
Each of these screen types has its own list of directives and
subdirectives (i.e., directives that are subordinate to the primary
directives). The functions that are determined by the directives
for each screen type are summarized in Figure 3.4. The
instructions for their use are presented in Section 4.2 and their
application is illustrated in Section 5.
The collection of directives and subdirective designations for a
particular screen is called a screen group. Screen groups for all
screens needed by the interactive program are constructed in a
sequential file called a screen definition file by using a text
editor. After this file has been developed, ANNIE-IDE provides a
stand-alone interactive program called MESSIE, which is used to
33
-------
TEXT SCREEN
(1) provide text for display
(2) define help-type assistance
(3) define screen name
MENU SCREEN
(1) provide menu title
(2) assign default menu option selection
(3) define length of menu options
(4) specify whether menu options are to be numbered
(5) define screen column width and length
(6) provide identification string for menu items
(7) provide description text for options
(8) define help-type assistance for each option
(9) define general help-type assistance for menu
(10) define screen name
FILE SCREEN
either
(1) define prompt asking for name of file
and/or
(2) define name of file (no number 1) or provide name for file name input field
(3) define file status
(4) specify file access method, format, and length of record
(5) define help-type assistance for screen
(6) define screen name
1-D and 2-D ARRAY SCREENS
(1) provide text explaining screen contents
(2) provide names for input parameter fields
(3) specify data types (e.g., INTEGER or REAL)
(4) assign default values for parameters
(5) define valid range for numeric parameters
(6) define valid parameter values for any type
(7) define invalid parameter values for any type
(8) specify storage instructions for screen group
(9) define help-type assistance for parameters
(10) define name of storage file for parameters
(11) provide text header and trailer for storage file
(12) define prompt for screen fill-in
(13) define help-type assistance for entire screen
(14) define screen name
ADDITIONAL 2-D ARRAY SCREEN FEATURES
(15) specify sorting requirements
(16) specify field protection
Figure 3.4. Screen directive functions.
34
-------
convert the sequential file to a WDM-message file. The WDM-message
file is direct access and hence enables more efficient retrieval
of screen information. Further instructions on building and
storing screen definition files are provided in Section 4.2.
3.10 SCREEN SEQUENCING
One of the most important functions of a good interactive program
is providing the user with the ability to move from one screen to
others in an expedient manner. The necessary types of interscreen
movement vary from one program to another and hence need to be
defined by the application programmer. The capabilities for
interscreen commands have not been fully developed in ANNIE-IDE at
this time. A list of useful interscreen commands has been
developed, however, and a methodology for their development by the
application programmer has been devised and will be explained as
an "advanced" application of ANNIE-IDE in Section 4.4
Table 3.5 presents our list of optional commands for interscreen
movement. The commands are defined, and the relative order in
which ANNIE-IDE will sequence the commands on the screen command
line (with respect to each other and the basic commands in Table
3.2) is indicated. The significance of the "screen exit status
code" will be explained in Section 4.4.
TABLE 3.5. OPTIONAL COMMANDS FOR INTERSCREEN MOVEMENT
COMMAND COMMAND SCREEN EXIT
NAME ID # STATUS CODE COMMAND DEFINITION
ABORT
BEGIN
EXIT
GOTO
NEXT
PREV
18
12
17
13
INTRPT 16
STOP EVERYTHING QUICKLY
GO TO FIRST SCREEN
CLEAN UP AND RETURN TO OPERATING SYSTEM
GO TO SCREEN TO BE SPECIFIED
STOP CURRENT ACTIVITY
GO TO NEXT SCREEN (ALWAYS AVAILABLE)
GO TO PREVIOUS SCREEN
35
-------
SECTION 4
INSTRUCTIONS FOR USING ANNIE-IDE
The emphasis of the material presented in the previous section
centered on the scope and features of ANNIE-IDE. In Section 4 the
focus shifts to the mechanics of using the ANNIE-IDE software to
build interactive applications. The goal of this section is to
provide the procedural "how-to"s needed to implement the software's
capabilities. To a large extent, the topics contained in the
latter portions of Section 3 are reintroduced and discussed with
much greater instructional detail.
The first two subsections present instructions for producing the
two major components of an ANNIE-IDE application as depicted in
Figure 4.1: the MESSAGE.WDM file and the application program.
Section 4.1 provides instructions for producing and storing the
user interaction text and allowable field value ranges by using
screen directives, groups, and clusters; screen definition files;
and WDM-message files. In Section 4.2, general guidance is given
for implementing the application program. Further details are
provided on the toolkit subroutines that are available to implement
screen interaction control. Finally, Section 4.3 contains
guidelines for using ANNIE-IDE to develop more complex application
programs by implementing advanced capabilities related to
interscreen movement and system status reporting. Throughout
Section 4, frequent references are made to Section 5 which provides
a full range of code, directives, and screen examples to support
the development instructions.
4.1 BUILDING AND STORING SCREEN DEFINITION FILES
The content of each ANNIE-IDE screen is defined and processed as
shown in Figure 4.2. The application programmer starts with ideas
about the number and content of each screen required by the
application. The content of each screen should be sketched out on
paper. Information from the sketches is then translated into a
series of screen definition directives. Screen definition
directives consist of a keyword and an associated value. The
associated value may be a text string, a number, or a series of
numbers.
36
-------
screen
sequencing cede
screen definition
file for application
general screen
definition directives
********************
* FORTRAN compiler *
* and linker *
********************
MESSIE I
1 i
I
I application program j
j programmer supplied (
ANN IE-IDE supplied
INTERACTIVE APPLICATION
***************************
* available to programmer *
***************************
Figure 4.1. Building an interactive application.
The series of directives that define a single screen is called a
screen group. A set of related screen groups is called a screen
cluster. Related screen groups are aggregated into screen clusters
in order to make efficient use of the long length of WDM-message
file records. Each group and cluster has a unique identification
number (ID) associated with it. These IDs are used within the
application program to identify a particular screen. A screen
cluster corresponds to a WDM dataset. One or more screen clusters
are stored together in a screen definition file.
The screen definition file is a formatted, ASCII, sequential file
in ANNIE-WDM import/export format containing directives that
describe all the particulars of one or more clusters. The file may
be created or edited using any text editor that does not add
special characters or reformat the text. (If the editor works with
source code, it will work with this file.)
A template screen definition file is shown in Figure 4.3. The
template file is found in file 'SDEF.TEM1 on the distribution
37
-------
(paper sketches of screens I
: . 1
template screen
definition file
screen definition
directives
!j
screen group and cluster |
numbers used in screen j
I sequencing software j
* editor of choice *
screen
definition file
(ASCII format)
I programmer supplied |
ANN IE-IDE supplied
I
MESSIE
***************************
* available to programmer *
***************************
MESSAGE.WDM
binary, direct
access file used
by application
Figure 4.2. Building and storing a screen definition file.
disks. Complete screen definition files for DBAPE and ANNIE-QUAL2
are found on the ANNIE-IDE distribution disks.
Note that four-character abbreviations are used to identify the
type of a screen group (fields "d,1 "f and 'j1 in Figure 4.3:
TEXT - text
MENU - menu
PRM1 - 1-dimensional parameter
PRM2 - 2-dimensional parameter
FILE - file specifications
All screens included in a particular application are stored in a
WDM-message file. One or more screen definition files are
converted into an application's WDM-message file using the stand
alone program "MESSIE." The WDM-message file is an unformatted
38
-------
DATE
UDMSFL
SYSTEM
COMMENT
* : :
END COMMENT
CLU a TYPE MESS NDN 1 NUP 1 NSA 5 NSP 20 NDP 400
LABEL
GRPNAM b :
END LABEL
DATA CLU a :
#GROUP ..c TYPE d
< screen definition directives for group c of cluster a >
#GROUP e TYPE f
< screen definition directives for group e of cluster a >
END DATA
END CLU
CLU 9 TYPE MESS NDN 1 NUP 1 NSA 5 NSP 20 NDP 400
LABEL
GRPNAM h i
END LABEL
DATA CLU 9
#GROUP i TYPE j
< screen definition directives for group i of cluster g >
END DATA
END CLU
notes:
application programmer fills in highlighted fields of template as follows:
a - cluster number of first cluster in file
b - cluster name
c - group number of first screen in cluster
d - type of first screen
e - group number of second screen in cluster
f - type of second screen
g - cluster number of second cluster in file
h - cluster name
i - group number of first screen in second cluster
j - type of first screen in second cluster
s - optional comment which describes this screen definition file
Figure 4.3. Template screen definition file.
direct-access file with a record length of 2048 bytes. WDM utility
routines keep a buffer of records from the file in memory in order
to reduce the number of read requests made to the file. This
allows for quicker loading of screen information from the WDM-
message file. The WDM-message file is always named "MESSAGE.WDM."
39
-------
Cluster numbers one through five are reserved for internal use by
ANNIE-IDE and are contained in a file named "MESSAGE.SEQ" provided
on the distribution disk.
Screen directives are organized hierarchically - the "$" keyword
prefix indicates a primary directive associated with an entire
screen; the "_" keyword prefix indicates a subdirective associated
with a field or option. The following sections describe the
individual directives associated with each screen type.
4.1.1 Text Screen Directives
A TEXT screen is defined using the directives shown in Table 4.1.
Note that "&" is used to define where optional numeric information
is to be written within the text. The optional numberic
information is provided as subroutine arguments. Example TEXT
screens with associated directives are shown in Sections 5.4 and
5.5.
TABLE 4.1. TEXT SCREEN DEFINITION DIRECTIVES
KEYWORD POS NOTES
JWINDOU aft name of screen (up to 48 characters)
$TEXT nxt text to display is data window of screen, total number of lines must be 50 or
less, max length of line to display in data window is 78, use "&" to indicate
spot where toolkit text screen display routine is to fill in a value
$HELP nxt general help for screen
NOTES:
POS indicates where to specify value for directive as follows:
1) nxt - text on following records
2) aft - text after keyword
40
-------
4.1.2 Menu Screen Directives
Screen definition directives to define a MENU screen are shown in
Table 4.2. An example MENU screen with accompanying directives is
shown in Section 5.6.
TABLE 4.2. MENU SCREEN DEFINITION DIRECTIVES
KEYWORD POS NOTES
SW1NDOW aft window name (up to 48 characters)
$TITLE aft title of menu, maximum length 78 characters, appears on first line of data window
$DEFAULT afi default option; if omitted, no default
SLENGTH afi length of longest option identification string; required, must be between 1 and
63
SWIDTH afi column width, default 78
$COLENGTH afi length of each column, must be between 1 and 8; default 8
SOPTION aft option identification string,length must be less than or equal to SLENGTH
_DESC aft description of option, length must be less than ($WIDTH - SLENGTH - 3)
_HELP nxt help for option, use as many records as required, up to 78 characters per record
$HELP nxt general help related to all options, as many records as required, up to 78
characters per record
NOTES:
POS indicates where to specify value for directive as follows:
1) nxt - text on following records
2) aft - text after keyword
3) afi - integer after keyword
4) fig - flag, no value needed
41
-------
4.1.3 1-D Array (PRM1) Screen Directives
A one-dimensional array (PRM1) screen is defined using the
directives shown in Table 4.3. Example PRM1 screens with
accompanying directives are found in Sections 5.8 and 5.14.
TABLE 4.3. PRM1 SCREEN DEFINITION DIRECTIVES
KEYWORD POS NOTES
SWINDOU aft window name (up to 48 characters)
SSCREEN nxt up to 10 records of text which represent the screen menu. field names are
preceded by '3' and may be extended by one or more '.' in order to make field
wide enough for expected values, up to 30 fields may be indicated
$HELP nxt general help for screen
SFIELD aft name of field, must match name in SSCREEN (including '3', excluding '.')
_TYPE aft data type - INTEGER, REAL, DOUBLE PRECISION, or CHARACTER (type must be specified
before any other subdirectives under SFIELD)
_PROTECT aft field protection - NONE (default), CORRECT (must be in valid range), PROTECTED
(cannot change value)
_RANGE aft minimum and maximum value allowed for numeric fields, separated by a colon,
-999 if unknown
_VALID aft valid values for any type of field, separated by commas
_DEFAULT aft default value for parameter (must appear after _RANGE and _TYPE)
_INVALID aft invalid values for any type of field
_HELP nxt help information about field
•warning, the following optional directives have not been tested within the 1-D screen routines
_RECORD afi record number in output data file where value will be stored
_SLOT afi start column in output data file record where value will be stored
_PCODE afi parameter code for field
JJCODE afi units code for field
"FORMAT aft format for field output to file
SOUTPUT aft name of file to store field values on
_HEADER aft character string written at beginning of output file
_TRAILER aft character string written at end of output file
NOTES:
POS indicates where to specify value for directive as follows:
1) nxt - text on following records
2) aft - text after keyword
3) afi - integer after keyword
42
-------
4.1.4 2-D Array (PRM2) Screen Directives
A two-dimensional array (PRM2) screen is defined using the
directives shown in Table 4.4. An example PRM2 screen with
accompanying directives is found in Section 5.9
TABLE 4.4. PRM2 SCREEN DEFINITION DIRECTIVES
POS NOTES
SUINDOW aft window name (up to 48 characters)
SHEADER nxt header for screen (may be multiple lines)
$HELP nxt general help for screen
SFIELD aft name of input array field (no '3' required as in 1-D)
*next 5 directives required before other remaining directives
_TYPE aft data type - INTEGER, REAL, DOUBLE PRECISION, or CHARACTER
"WIDTH afi field width in characters
~ORDER aft sort requirement - RANDOM (default), ASCENDING, DESCENDING
_PROTECT aft field protection - NONE (default), CORRECT (must be in valid range), PROTECTED
(cannot change value)
_COLUMN afi starting column of field
_HELP nxt help information for field
_RANGE aft valid range for numeric field
_VALID aft valid values for any type field
_DEFAULT aft default value for field
_INVALID aft invalid values for any type field
•warning, the following optional keywords have not been tested within the 2-D screen routines
_PACK afi number of values to pack on a data record
_FORMAT afi format of values on data record
_PCOOE afi parameter code for field
JJCODE afi units code for field
_FORMAT aft format for field output to file
SOUTPUT aft name of file to store field values on
_HEADER aft character string written at beginning of output file
_TRAILER aft character string written at end of output file
NOTES:
POS indicates where to specify value for directive as follows:
1) nxt - text on following records
2) aft - text after keyword
3) afi - integer after keyword
43
-------
4.1.5 File Screen Directives
A FILE screen is defined using the directives shown in Table 4.5.
An example FILE screen with accompanying directives is found in
Section 5.7.
TABLE 4.5. PILE SCREEN DEFINITION DIRECTIVES
SWINDOW aft window name (up to 48 characters)
SSCREEN aft screen menu text when asking for name of file, up to 10 records, field name
preceded by '3' and may be extended by one or more '.', this keyword used only
if file name is to be provided by user
5NAME aft name of file (SSCREEN keyword not allowed) provided by application or field name
in screen text directive which will be provided by user
SSTATUS aft file status, OLD (default), NEW, UNKNOWN, or SCRATCH
SACCESS aft file access method, SEQUENTIAL (default) or DIRECT
$FORM aft file format, FORMATTED (default) or UNFORMATTED
SRECL aft length of record in direct access file (bytes if formatted, half words if
unformatted)
SHELP nxt help information for screen
NOTES:
POS indicates where to specify value for directive as follows:
1) nxt - text on following records
2) aft - text after keyword
3) afi - integer after keyword
44
-------
4.1.6 Using MESSIE
MESSIE is a stand-alone interactive program that is used by the
application programmer to import and export screen definition data
between the screen definition file format used during development
and the direct-access format used during interactive program
execution. MESSIE's role comes into play after the application
programmer has constructed screen groups and clusters for the
screens needed by the interactive program. The screen groups are
entered in a screen definition file by using a text editor. When
the programmer is ready to test the interactive program, it is
necessary to use MESSIE to convert the screen definition file to
a WDM-message file.
It will most likely be necessary during the development effort for
the application programmer to modify existing screens and add new
ones. To accomplish these tasks efficiently, MESSIE also can be
used to export the WDM-message file contents back to a screen
definition file, which can be modified by a text editor, and then
re-imported to MESSAGE.WDM.
Instructions for using MESSIE to create the WDM-message file,
import screen definition data to it from a sequential file, and
export screen groups out of the message file back to a sequential
file are provided below.
Create WDM-message File
A prerequisite to using MESSIE to create a WDM-message file is that
the file named "MESSAGE.SEQ" be copied to the directory in which
MESSAGE.WDM is to be created. The MESSAGE.SEQ file is provided as
part of the distributed software for ANNIE-IDE. This screen
definition file contains standard messages and information needed
for all applications of ANNIE-IDE. When the file is available to
MESSIE, the following steps should be taken (on a PC):
(1) Type "MESSIE" to execute the MESSIE.EXE file. MESSIE will
try to open the MESSAGE.WDM file. Unable to find it, MESSIE
automatically opens a new file by that name and reports a
successful open. Next, MESSIE automatically imports the
MESSAGE.SEQ file into MESSAGE.WDM. The message file is now
ready for import of screen clusters constructed by the
application programmer.
(2) If no programmer-generated screen clusters are to be imported
at this time, instruct MESSIE to return to the operating
system by typing "R."
45
-------
Import a Screen Definition File
Prerequisite: Successful creation of WDM-message file and import
of MESSAGE.SEQ file
Instructions:
(1) Execute program MESSIE. On a PC type "MESSIE" to execute the
MESSIE.EXE file. Program will report successful open of
MESSAGE.WDM file or an attempt will be made to create the
MESSAGE.WDM file as described above.
(2) Following prompt, select import option by entering "I".
(3) Following prompt, enter file name for screen definition file.
MESSIE will automatically begin to import the individual
screen clusters contained in the specified screen definition
file; the successful import of each screen cluster will be
reported on the screen.
If MESSIE encounters screen clusters in the screen definition
file that are already contained in MESSAGE.WDM (as identified
by comparing screen cluster numbers), the program asks
whether to skip the screen cluster (i.e., don't import it),
overwrite the screen cluster already in the WDM-message file,
or abort the entire import process. Appropriate responses
are "S," "O," and "A," respectively.
When MESSIE has completed the import of screen clusters in
the screen definition file, the end of the importing process
is reported on the screen.
(4) If no other import tasks are needed, enter "R" following
prompt to return to the operating system.
Export WDM-message File to Sequential File
Prerequisite: WDM-message file must contain something to export
(i.e., screen clusters)
Instructions:
(1) Execute "MESSIE." Program will report successful open of
MESSAGE.WDM.
(2) When prompted, select export option by entering "E".
(3) When prompted, enter a name for the output file. The name
must not already exist in the current directory.
46
-------
(4) MESSIE prompts for comment lines that will be used to label
the output file. Type in comment lines - use "ENTER" with no
text to end the comment lines.
(5) MESSIE asks whether all or selected screen groups are to be
exported from the MESSAGE.WDM file. If all screen clusters
are to be exported, enter "A." MESSIE will automatically
export all clusters contained in the WDM-message file to the
output file.
If only selected screen clusters are to be exported, enter
the screen cluster identification numbers for these clusters
one-at-a-time as they are prompted. Successful completion of
export for each screen cluster will be reported by MESSIE.
(6) When exports have been completed, enter "0" (zero). Instruct
program to return to the operating system by typing "R."
4.1.7 Directives to Provide Assistance to User
The concept of layered assistance to the user was introduced in
Section 3.5. Screen directives used to supply user assistance at
the three assistance levels for each screen type are shown in Table
4.6.
TABLE 4.6. SCREEN DIRECTIVES FOR SPECIFYING ASSISTANCE
SCREEN TYPE
TEXT MENU PRH1 PRH2 FILE
ASSISTANCE LEVEL
1 -
2 -
field or option name
additional information
none
none
SOPTION
DESC
SSCREEN
SSCREEN
SHEADER
SHEADER
none
$TEXT
in DATA window
3 - additional information SHELP _HELP _HELP _HELP $HELP
in ASSISTANCE window _VALID _VALIO J/ALID
_IN VALID JNVALID
_RANGE _RANGE
$HELP SHELP
47
-------
4.2 DESIGNING AND DEVELOPING THE INTERACTIVE PROGRAM
The ANNIE-IDE package can be utilized to build a user interface for
virtually any type of computer program or computer-stored data
base. Potential applications range from generating user-supplied
input for already existing environmental or scientific models to
allowing user access to a variety of data bases.
The structure of an application program designed to provide a user
interface for a computer program is shown in Figure 4.4.
Double-lined box borders are used to show functions that are the
responsibility of the application programmer. Single-lined box
borders are used to show ANNIE-IDE toolkit functions. Sections
4.2.1 through 4.2.7 describe the application program functions
introduced in Figure 4.4. Example Fortran codes to perform the
functions are found in Section 5.
A major portion of the programmer's effort in developing an
interactive program will be devoted to specifying the details of
screen interaction control. Section 4.2.8 gives further
instruction on using toolkit routines for this purpose. Closing
comments on the interactive program development process are
provided in Section 4.2.9.
4.2.1 Initialize ANNIE-IDE
Before any screens are displayed the application program must
initialize ANNIE-IDE. Initialization tasks include opening the
WDM-message file named "MESSAGE.WDM," reading default system
parameter information from the WDM-message file, determining user-
specified system parameters by reading the TERM.DAT file, and
reading the old scratch pad file XPAD.DAT into the applications
scratch pad. Example code demonstrating this function is shown in
section 5.1.
4.2.2 Initialize Parameters
Most environmental models have data structures that contain
parameters required to execute the model. The purpose of this
function is to initialize these parameter values. If no default
value is appropriate, then the value should be set to an arbitrary
value indicating that it is undefined. In ANNIE-QUAL2 the
undefined value is -999. This function is required because the
user may choose not to enter data for each of the data entry
screens defined for the model. When that situation occurs, the
parameters for the model must either be reasonable or cause a fatal
error. This function is demonstrated with Fortran code found in
Section 5.2.
48
-------
I READ EXISTING
^ PARAMETER VALUES
FROM FILE
UPDATE
PARAMETER
VALUES )
I WRITE REVISED
-I PARAMETER VALUES
TO FILE
SHUT DOWN
ANNIE-IDE
APPLICATION PROGRAM FUNCTION
ANNIE-IDE TOOLKIT FUNCTION
FILE SCREEN AND OTHER UTILITIES
MENU SCREEN -
SPECIFY PARAMETER GROUP
1- AND 2-D DATA SCREENS-
REVISE PARAMETER VALUES
FILE SCREEN
Figure 4.4. Structure of interactive program providing user
interface to an environmental model.
4.2.3 Read Existing Parameter Values From a File
The user may be executing a series of model runs as part of model
calibration or an examination of alternatives. In this case,
current model parameters must be retrieved from an existing file.
The interactive program must not fail due to a read error caused
by an error in the file. Further description of the FILE screen
49
-------
routines used to retrieve files is provided in Section 4.2.8. Code
illustrating this function is found in Sections 5.3 and 5.7.
4.2.4 Update Parameter Values
In this function, the application programmer must define the
sequence of user interactions required to indicate what parameters
to change and to specify new parameter values. This is done by
using a series of menu screens to define the parameter group of
interest and then a one- or two-dimensional data screen to allow
revision of the parameter value. Further description of these
screen types is provided in Section 4.2.8. Fortran code
illustrating these functions is found in Sections 5.6, 5.9-12 and
5.14.
4.2.5 Write Revised Parameter Values To File
After the user has specified values for all revised parameters, the
model parameter file must be written. This involves opening a file
with a user specified name and writing all parameter values into
it. Further description of the FILE screen routines used to write
files is provided in Section 4.2.8. Sections 5.7 and 5.16 contain
code that illustrate these functions.
4.2.6 Shut Down ANNIE-IDE
This routine writes out the user's scratch pad to file XPAD.DAT.
This file is read next time the application is run. The routine
also closes the WDM-message file. An example is found in Section
5.17.
4.2.7 Using Toolkit Subroutines for Screen Interaction Control
ANNIE-IDE toolkit subroutines are used by the application
programmer to control the display of screens, locate the screen's
general content on the WDM-message file, and transfer the data
values displayed on the screens between the user and the
application program (and vice versa). A call from the application
program to any of the toolkit screen interaction routines described
in this section results in the display of a screen. The general
content of the screen is defined by the specification of the screen
group and cluster (Section 4.1) on the WDM-message file in the
toolkit argument list. Data values displayed on the screen and
edited by the user are transferred between the screen and the
application through additional arguments in the toolkit routines.
50
-------
The ANNIE-IDE toolkit subroutines are organized into five groups,
each of which allows interaction with one of the five screen types
defined in Section 3.9. Descriptions of the function of each group
follow, showing the relationship between the toolkit routines with
a structure chart, and providing general instructions for use of
the routines. The structure charts represent the heirarchy of the
various routines within a group. Their purpose is to enable the
programmer to locate a routine within its program context so that
its relationship to the rest of the group can be better understood.
Each box within the structure chart represents a single subroutine.
Subroutines call other subroutines that are directly below and
connected by a line. The higher level routines perform the more
general functions, and the lower level routines perform specific
functions. Routines shown on the same level perform functions of
similar detail.
All the subroutines shown in this section's structure charts are
"lead" subroutines. These subroutines call additional subordinate
subroutines contained within the ANNIE-IDE software. The
subordinate subroutines accomplish specific tasks required for the
performance of the more general functions of the lead routines.
Default values for the arguments of the subordinate routines are
provided by code in the lead routines and hence they are able to
perform their tasks for basic applications in a transparent
fashion. If the experienced application programmer wishes to "fine
tune" the screens produced by a group, however, it may become
necessary to understand the optional capabilities allowed by the
subordinate routines. To this end, Appendix B.2 lists all
available routines and their functions, and the file SYSDOC.OUT
contained on the distribution disk provides details on their use.
Example applications of routines from each group are found in
Section 5. Details of the subroutine arguments are provided in
Appendix B.I.
51
-------
TEXT Display Subroutines
TEXT screens are used to display information to the user. A screen
may contain up to 50 lines of text, with 10 or 16 lines available
for viewing in the data window at any time. The user may use the
cursor movement keys to view portions of text not displayed in the
data window. The text may contain character or numeric data values
supplied by the application program through the subroutine's
argument list. Generally the text displayed on the screen is
retrieved from the MESSAGE.WDM file. However, if the text varies
significantly within a screen (as with model results), then the
application programmer may specify the entire contents of the
screen within the application program.
Figure 4.5 contains a structure chart showing the relationships
among the various text display routines. Three general classes of
text display routines are identified in the structure chart by the
number that follows the routine name. Routines within each class
are differentiated by the descriptions in Figure 4.6.
text
text & integers text & reals text & doub.pr text & strings
| PRNTXT(I) |
I I
PRNTXK2)
PRNTXRC2)
PMXTXTd)
PMXTXK2)
PMXTXR(2)
PRNTXAC2)
PMXTXA(2)
PMXCNTd)
PMXTMXC2)
PMXCNW(1)
ZBLDURC3)
text display classes:
(1) display text from WDM-message file
(2) display text from WDM-message file and application program supplied data
(3) display application program supplied text and data
Figure 4.5. Structure chart for text display subroutines.
52
-------
SUBROUTINE PRIMARY ACTIONS
(TEXT FROM WDM-MESSAGE FILE ONLY)
PRNTXT DISPLAY TEXT FROM WDM-MESSAGE FILE, WRITE AND WAIT, INITIALIZE SCREEN
PMXTXT SAME AS PRNTXT, OPTIONALLY INITIALIZE SCREEN, ALSO COUNTS LINES WRITTEN
FOR RETURN TO APPLICATION PROGRAM
PMXCNT SAME AS PMXTXT, COUNTS LINES WRITTEN FOR RETURN TO APPLICATION PROGRAM
PMXCNW SAME AS PMXCNT, OPTIONALLY WRITE AND GO, WRITE AND WAIT FOR USER TO
RESPOND, DON'T WRITE
(TEXT FROM WDM MESSAGE FILE AND DATA FROM APPLICATION PROGRAM)
PRNTXI DISPLAY TEXT FROM WDM-MESSAGE FILE, INTEGER VALUE FROM APPLICATION PROGRAM,
WRITE AND WAIT, INITIALIZE SCREEN
PMXTXI SAME AS PRNTXI, MAY WRITE MANY INTEGERS
PRNTXR SAME AS PRNTXI EXCEPT WRITES REAL
PMXTXR SAME AS PRNTXR, MAY WRITE MANY REALS
PRNTXD SAME AS PRNTXI EXCEPT WRITES DOUBLE PRECISION
PMXTXD SAME AS PRNTXD, MAY WRITE MANY DOUBLE PRECISIONS
PRNTXA SAME AS PRNTXI EXCEPT WRITES CHARACTER STRINGS
PMXTXA SAME AS PRNTXA, MAY WRITE MANY CHARACTER STRINGS
PMXTXM DISPLAY TEXT FROM WDM-MESSAGE FILE WITH A COMBINATION OF INTEGERS, REALS,
DOUBLE PRECISIONS, AND STRINGS
(TEXT AND DATA FROM APPLICATION PROGRAM)
ZBLDWR DISPLAY PROGRAMMER SPECIFIED TEXT AND DATA, OPTIONALLY WRITE AND GO, WRITE AND
WAIT FOR USER TO RESPOND, DON'T WRITE; RETURNS USER SCREEN EXIT COMMAND CODE
Figure 4.6. Text display subroutines.
Details of the arguments required in order for these routines to
be called from an application program are found in Appendix B.I.
MENU Selection Subroutines
MENU screens are used to display a series of options and prompt
the user to request one. No more than seven options should be
displayed on a particular screen. The application programmer is
allowed to display up to 64 options if needed, however.
53
-------
QRESP
returns order of response
returns order and text
Two toolkit routines are used
for menu selection. They are
shown in Figure 4.7. Both
return the order number of the
user's response (option one
returns 1, etc.); QRESPS also
returns the text of the selected
option.
Details of the arguments
required in order for these two
routines to be called from an Figure 4.7. Structure chart for
application program are found in menu subroutines.
Appendix B.I.
ONE-DIMENSIONAL Array Edit Subroutines
The one-dimensional data edit subroutines are used to prompt the
user to select options, enter numeric values, and/or enter text.
Up to 30 field entries may be used. User input is checked against
valid values and errors are reported for incorrect input. Figure
4.8 contains a structure chart showing the relationships among the
various data editing subroutines.
integer
I QRSPUI(I) I
real
QRESPId)
I QRSPUR(I) I
QRESPRd)
double prec
I QRSPUDd)
QRESPDd)
string
d) request a single value from user
(2) request an array of values
QRESCD(2)
multiple
:N(2) |
i
QRESCXC2) |
i
QRESCRC2)
| QRESCZC2) |
Figure 4.8. Structure chart for 1-D array subroutines,
54
-------
There are two general classes of 1-D data edit routines identified
on the structure chart by the number that follows the routine name.
Routines within each class are differentiated by descriptions in
Figure 4.9.
SUBROUTINE PRIMARY ACTIONS
(SINGLE VALUE INPUT)
QRSPUI RETURN A SINGLE INTEGER VALUE, ALLOWABLE RANGES FROM APPLICAITON PROGRAM
QRESPI RETURN A SINGLE INTEGER VALUE, ALLOWABLE RANGES FROM WDM-MESSAGE FILE
QRSPUR RETURN A SINGLE REAL VALUE, ALLOWABLE RANGES FROM APPLICATION PROGRAM
QRESPR RETURN A SINGLE REAL VALUE, ALLOWABLE RANGES FROM WDM-MESSAGE FILE
QRSPUD RETURN A SINGLE DOUBLE PRECISION VALUE, ALLOWABLE RANGES FROM APPLICATION PROGRAM
QRESPD RETURN A SINGLE DOUBLE PRECISION VALUE, ALLOWABLE RANGES FROM WDM-MESSAGE FILE
QTSTR RETURN A TEXT STRING
(MULTIPLE VALUE INPUT)
ORESPM RETURN AN ARRAY OF RESPONSES IN TEXT AND NUMERIC FORM, MAY INCLUDE INTEGER AND
REAL VALUES
QRESPX SAME AS QRESPM, INITIAL VALUES FROM TEXT STRING
QRESCN SAME AS QRESPM BUT MAY HAVE MULTIPLE ROWS FOR 2-D
QRESCX SAME AS QRESPX BUT MAY HAVE MULTIPLE ROWS FOR 2-D
QRESCD SAME AS QRESCN BUT DOUBLE PRECISION ALLOWED
QRESCR SAME AS QRESCX BUT DOUBLE PRECISION ALLOWED
QRESCZ SAME AS QRESCR BUT WITH VARIABLE BUFFER LENGTH
Figure 4.9. One-dimensional array input subroutines.
Details of the arguments required in order for these routines to
be called from an application program are found in Appendix B.I.
55
-------
TWO-DIMENSIONAL Array Edit Subroutines
QRESCN
QRESCD
_L
QRESCX
The 2-D data edit subroutines are used
to prompt the user to enter numeric
and/or text values in up to 30 fields
and 49 rows of data. User input is
checked against valid values and errors
are reported if incorrect input is
detected. Figure 4.10 contains a
structure chart showing the
relationships among the various two-
dimensional data input subroutines.
Note that these routines also may be
used to prompt the user to enter one-
dimensional data if the parameter
"NROW" is set to 1. Figure 4.11 Figure 4.10. Structure
differentiates between the capabilities chart for 2-D array edit
of the subroutines resident in this subroutines.
group.
SUBROUTINE PRIMARY ACTIONS
(ALL REQUIRE SPECIFICATION OF NUMBER OF ROWS OF DATA)
QRESCN RETURN TEXT STRING OF RESPONSES ALONG WITH INTEGER AND REAL VALUES
QRESCX SAME AS QRESCN BUT GETS INITIAL VALUES FROM TEXT STRING
QRESCD SAME AS QRESCN BUT DOUBLE PRECISION ALLOWED
QRESCR SAME AS QRESCX BUT DOUBLE PRECISION ALLOWED
QRESCZ SAME AS QRESCR BUT WITH VARIABLE BUFFER LENGTH
Figure 4.11. Two-dimensional data edit subroutines.
Details of the arguments required in order for these routines to
be called from an application program are found in Appendix B.I.
56
-------
FILE Management Subroutines
FILE screens are used to enter
names of files that are needed by
an application. Figure 4.12
contains a structure chart showing
the two file management
subroutines. In Figure 4.13 the
capabilities of the two routines
are differentiated. Details of
the arguments required in order
for these two routines to be
called from an application program
are found in Appendix B.I.
QFOPEN
I
QFOPFM
Figure 4.12. Structure
for file subroutines.
chart
SUBROUTINE PRIMARY ACTIONS
QFOPEN OPEN A FILE AND RETURN FORTRAN UNIT NUMBER, ASK USER TO CORRECT NAME
IF ERROR OCCURS
QFOPFN OPEN A FILE AND RETURN UNIT NUMBER, OPEN A FILE WITH SPECIFIED NAME,
ASK USER TO CORRECT NAME IF ERROR OCCURS
Figure 4.13. File management subroutines.
4.2.8 Closing Comments on the Development Process
The most difficult part of the development process is developing
the series of menu and data screens that allow the user to complete
the input sequence in an efficient fashion. The user will be
pleased with an interactive program if it allows entry of
information in a familiar and logical manner while providing
assistance where needed. It is most beneficial to sketch the
planned sequence and detail of screens for end-user interactions
at the beginning of the development effort.
Interactive program development is an iterative process. Users
should test a prototype program at an early stage in the
development process in order to identify additional needs with
regards to screen sequence and content. Within the ANNIE-IDE
framework the screen content can be changed quickly by editing the
screen definition file and using the import function of MESSIE.
57
-------
4.3 ADVANCED TOPICS
4.3.1 User System Specifications File (TERM.DAT)
The ANNIE-IDE system contains a number of parameters that may be
system dependent. All of these parameters have a default value.
The defaults are in the main message file, MESSAGE.WDM. Any number
of these defaults can be overridden by adding a TERM.DAT file to
the directory where the application is being executed. At
initialization, default values for all parameters are read from the
message file. Then the TERM.DAT file is read, if it exists, and
the parameter values found replace those from the message file.
All of the parameter values are saved in a common block.
Application programmers can determine the value of a parameter in
the common block by calling subroutine ANPRGT. Appendix B.6 lists
the parameter code number (used only by the application
programmer), parameter code name (needed for the users TERM.DAT
file), default value, allowable values, and the definition for
each parameter.
TRMINP 5
TRMOUT 6
FILUNI 40
CMPTYP PC
TRMTYP PC
CLRBKS 1
CLRFRE 15
CLRBKE 4
PFKEY4 C
PFKEY5 L
Figure 4.14 contains a sample user's TERM.DAT
file. The first two parameters are the
terminal input file (TRMINP) and terminal
output file (TRMOUT) . For a PC version of
Fortran, the standard values for these
parameters are five and six. The next
parameter is the starting Fortran unit number
to be available to the program. It is
suggested this number be assigned a value of
at least 40, as many unit numbers below that
are used by ANNIE-IDE (e.g. WDM-message
file). The fourth and fifth parameters are
the computer type (CMPTYP) and terminal type
(TRMTYP) . For this example, the user is
working on a PC, so the values of these Figure 4.14. sample
parameters are set accordingly. The next TERM.DAT file.
three parameters are color specifications.
The first color is the standard background
color which has been set to one (blue) . The next color is the
foreground error color. This has been set to 15, which is bright
white (as opposed to the standard foreground color default of light
grey). The final color is the background error color. This has
been set to 4, which is red. The error colors should be set to
values that will draw attention to the error messages. Appendix
B.8 contains descriptions of all allowable color codes. The final
two parameters are function key definitions. Valid values for
these parameters are the first letter of screen commands. Thus,
the first parameter, function key 4 (PFKEY4) , has been set to
execute the 'CMNDS' command. The second parameter, function key
5 (PFKEY5), has been set to execute the 'LIMITS' command.
58
-------
4.3.2 Interscreen Movement Commands
The application programmer may make the interscreen movement
commands described in Section 3.10 available through calls to
toolkit routine ZSTCMA. The user's screen exit code is determined
by the application program by a call to routine ZGTRET. Sections
5.13 and 5.15 show how this capability may be used in an
application program.
4.3.3 Control of Assistance Window Containing System Status
The assistance window used to display system status information is
controlled by the application programmer with calls to toolkit
routine ZSTADD. This routine updates a record within the 10 record
status buffer. An example of how this function is used may be
found in Section 5.12.
59
-------
SECTION 5
EXAMPLE APPLICATIONS
This section provides examples and supporting text illustrating the
use of ANNIE-IDE software to build the components of an interactive
program. As appropriate, each example consists of one or more of
the following: the Fortran code needed to perform the function,
the screen directive needed to define screen display, and the
resulting screen.
It should be noted that the examples utilize certain subordinate
subroutines that are discussed in Section 4.2. Details for these
subroutines can be found in Appendix B.I. Screen directives used
in the examples are explained in Section 4.2 and summarized in
Appendix B.4.
The examples in this section appear in the general order in which
they might occur within an interactive program. That is to say,
the examples begin with initializing the system and end with
closing the system. Further details on seguencing the functions
of an interactive program are available in Section 4.2.
5.1 INITIALIZE SYSTEM
initialize ANNIE-IDE
MESSFL= 30
CALL ANINIT (MESSFL)
The toolkit housekeeping routine ANINIT is
responsible for initializing ANNIE-IDE for
each session. It opens the WDM-message
file and sets system parameters (either by
default or by user specifications in
TERM.DAT). The Fortran unit number of the
WDM-message file (MESSFL) is reguired as
an input argument. This call must be made
before any other ANNIE-IDS routines are Figure 5.1. Fortran
called. Figure 5.1 shows sample code to co<*e to initialize
perform this task. This code was taken ANNIE-IDE.
from the DBAPE main program. The
application programmer must select a Fortran unit number for the
WDM-message file that does not conflict with others assigned by
ANNIE-IDE through the TERM.DAT parameter FILUNI.
60
-------
1= 11
J= 0
CALL ZIPI (I.J.NSOPT)
BOOOPT= 1
form 2
1= 7
J= 10
CALL ZIPI (I.J.PCIVL)
1= 13
R= 7.3
CALL ZIPR (I,R,PCRVL)
Figure 5.2. Fortran
code to initialize
model parameters.
5.2 INITIALIZE MODEL PARAMETERS
The code in Figure 5.2 shows examples of
data initialization required to set
default values for an environmental
model. The main initialization routines
are ZIPC (character) , ZIPI (integer) ,
ZIPR (real) , and ZIPD (double
precision). These routines are
particularly helpful in initializing
data arrays. The first argument (I) is
the number of elements in the array
being initialized. The second argument
(J or R) is the initial value desired.
The third argument is the array being
initialized. This code comes from
ANNIE-QUAL2 code group ANNSQ2M, routine
AQ2INI. This form of initialization
(setting default values for parameters
in the individual data entry screens) is
required because the user may choose not to enter data in each of
the individual data screens, thus failing to initialize some
parameter values.
5.3 READ FILE INPUT FOR A MODEL
The code in Figure 5.3 shows a method for reading input for a model
from a file. In this example, the program reads a formatted
sequential file containing the input sequence for a model; reading
continues until a keyword is reached (or until a boundary is
reached). Thus, for each set of parameters, reading continues
until the temporary string, TCHR, matches the keyword, ENDA. This
is checked by the function STRFND, which searches the first string
(TCHR) looking for the second string (ENDA). ENDA is defined with
a Fortran DATA statement. The argument LEN is the length of each
string. Often the lengths are two different arguments with the
first larger than the second. Each loop is completed when either
STRFND has a value greater than 1 or the limit of the array sizes
for the parameters is reached. If a read error occurs on a read
from the file, then control is passed to label 900 where a message
is printed to the screen indicating the nature of the error. The
code comes from ANNIE-QUAL2 code group ANNSQ2M, subroutine AQ2REA.
61
-------
C read form 5
RETCOO= 5
I = 0
50 CONTINUE
1= 1+ 1
READ (SUCIFL,1050,ERR=900) TCHR,DAT2(1,I),(RCHNAM(J,I),J=1,16),
1 DAT2(2,I),DAT2(3,I)
J= STRFND(LEN,TCHR,LEN,ENDA)
IF (I.LT.MXRCH.AND.J.EQ.O) GO TO 50
IF (J.EQ.O) READ (SUCIFL,1000,ERR=900)
Figure 5.3.
file.
Fortran code to read model parameters from a
5.4 DISPLAY TEXT
Figure 5.4 is an example of code
required to display on the screen
the text stored in the WDM-message
file. The programmer supplies the
WDM-message file unit number
(MESSFL), the screen cluster number
(SCLU), and the screen group number
(SGRP) within the cluster. The
subroutine PRNTXT is the simplest
text-displaying routine. It
initializes the data screen to
blanks, displays the text and
instructions, and waits for the
user to continue to the next screen.
main program.
initialize screen cluster number
SCLU= 36
welcome message
SGRP= 1
CALL PRNTXT (MESSFL,SCLU,SGRP)
Figure 5.4. Fortran code to
display text.
This code is from the DBAPE
The screen definition directives in Figure 5.5 contain instructions
to display text ($TEXT), provide associated help information
($HELP) and define the name that labels the data window ($WINDOW).
Both the text and help are automatically centered within their
respective windows when they are displayed.
Figure 5.6 shows the text screen that is displayed based on the
code and screen definition directives shown (after the user has
asked for the display of help information).
62
-------
#GROUP 1 TYPE TEXT
STEXT
********************************************************
****** WELCOME TO "ANNIE/DBAPE" ******
DATED JANUARY 12, 1988
REVISION OF AUGUST 10, 1988
******
******
******
******
******
if you are not familiar with this program
type 'FT for instructions
SHELP
DBAPE is used to ANALYZE soil property data along with the geographic
distribution of soils and to ESTIMATE parameters for the RUSTIC model.
JUINDOW WELCOME
Figure 5.5. Screen definition directives to display text.
t
. WELCOME
****** WELCOME TO "ANNIE/DBAPE" ******
****** DATED JANUARY 12, 1988 ******
****** REVISION OF AUGUST 10, 1988 ******
if you are not familiar with this program
type 'F11 for instructions
HFI P
DBAPE is used to ANALYZE soil property data along with the geographic
distribution of soils and to ESTIMATE parameters for the RUSTIC model.
IWITPIirT
'Next1 command to go to next screen
(elp:Fl Next:F2 Quiet:p$ Xpad:f$ Cmnds
Figure 5.6. Resulting text screen.
63
-------
5.5 DISPLAY TEXT WITH NUMERIC INFORMATION
conflicting number of headwaters
IVAL(1)= J
IVAL(2)= NUMHUD
SCNINI = 1
MXLIN = 50
I = 2
10 =0
SGRP = 5
CALL PMXTXI (MESSFL.SCLU,SGRP,MXLIN,SCNINI,10,I,IVAL)
Figure 5.7 shows code
to display text with
numeric information
included. The
programmer supplies
the WDM-message file
unit number (MESSFL),
cluster (SCLU), and
group (SGRP) as in the
basic display text
example in the
previous section(5.4).
The maximum number of Figure 5.7. Fortran code to display text
text lines allowed with numeric information.
(MXLIN), a screen
initialization flag (SCNINI), a write flag (10), the number of
parameters (I), and the value of the parameters (IVAL) also must
be specified. In this example, the maximum number of lines has
been set to the size of the screen text (50 lines) . The
initialization flag is set to one to initialize the screen. The
write flag is set to zero indicating that the message will be
displayed and the user must respond to continue to the next screen.
There are two integer values to be put in the text. This code is
from ANNIE-QUAL2 code group ANNSQ2S, subroutine AQUAL2.
The screen definition directives
in Figure 5.8 show the text to
display in the data window
($TEXT). The text includes two
"&" signs. These indicate where
the integer parameters will be
put in the text. Note that there
is no need to specify the length
of the integer values; the amount
of space required to display them
will be used. The name of the
data window is specified with the
directive $WINDOW. There is no
help available for this screen.
#GROUP 5 TYPE TEXT
$TEXT
Conflicting number of headwaters.
REACH SCREEN: &
CONTRL SCREEN: & (or old INPUT sequence)
SWINDOW Headwater Conflicts
Figure 5.8. Screen definition
directives to display text with
numeric information.
Figure 5.9 shows the text screen that results from the code and
screen directives just shown.
64
-------
f
Conflicting number of headwaters.
REACH SCREEN: 1
CONTRL SCREEN: 3 (or old INPUT sequence)
i MCTPI IPT
'Next1 command to go to next screen
Iext:f2 Xpad:£9 Cmnds
Figure 5.9. Resulting text screen with numeric information.
5.6 SELECT AN ITEM FROM A MENU
Shown in Figure 5.10 is the code
required to prompt the user to
select an item from a menu. The
programmer supplies the
WDM-message file unit number
(MESSFL), the screen cluster
number (SCLU), and the screen
group number (SGRP) within the
cluster to subroutine QRESP. The
order number of the selected
response (RESP) is returned. The
program then branches based on the response.
the DBAPE main program.
c
main loop for DBAPE, which
SGRP= 6
opt i on
CALL QRESP (MESSFL.SCLU, SGRP, RESP)
GO TO (10,20,30), RESP
Figure 5.10. Fortran code to
select from menu.
This example is from
65
-------
The screen definition file
for this menu (Figure 5.11)
shows that the default
response ($DEFAULT) is 1,
that the maximum length of
the responses ($LENGTH) is
8, and that there are 3
$OPTION directives (one for
each valid response). Each
option is described. If
additional help was
available for an option,
then a _HELP directive
would be used. If help was
available for the whole
screen, then the $HELP
directive would be used.
ffGROUP 6 TYPE MENU
(TITLE Which DBAPE option?
(DEFAULT 1
(LENGTH 8
(OPTION RETURN
_DESC - back to operating system
(OPTION ANALYSIS
DESC - analyze soil property or geographic data base
WPTION ESTIMATE
_DESC - estimate parameter values for RUSTIC
(WINDOW MAIN OPTION SELECT
Figure 5.11. Screen definition
directives to select from menu.
The menu screen that results from these directives and the Fortran
code is shown in Figure 5.12.
t
MAIN OPTION SELECT
Which DBAPE option?
RETURN * back to operating; system
ANALYSIS - analyze soil property or geographic data base
ESTIMATE - estimate parameter values for RUSTIC
i UCTUI in
Select an option using arrow keys or first letter of option.
Confirm selection with 'Next1 command.
Jext:f2 Xpad:F? Cmnds
Figure 5.12. Resulting menu screen.
66
-------
export soil properties to a file
SGRP= 31
CALL QFOPEN (MESSFL,FSCLU,SGRP,EXPFL,ERRFLG)
IF (ERRFLG.EQ.O) THEN
file open successfully, continue
5.7 OPEN A FILE
Figure 5.13 contains code to
display a screen that asks
the user for a file name and
opens the file. The message
file (MESSFL) , cluster
(FSCLU), and group (SGRP)
are supplied by the
programmer. The routine
returns the unit number of
the file that was just
opened (EXPFL). The final
argument (ERRFLG) indicates whether the opening of the file was
successful. Any non-zero value for this argument indicates an
error occurred. If no error has occurred, then the program
proceeds to write to the file (not shown here). This example is
from DBAPE code group SOIMAK, subroutine SOIMAK.
Figure 5.13.
specify a file.
Fortran code to
#GROUP 31 TYPE FILE
SSCREEN
Name of file for output?
3FILE
SNAME 3FILE
SSTATUS UNKNOWN
SACCESS SEQUENTIAL
SFORM FORMATTED
$HELP
Enter the name of a file which your system understands.
The screen definition
in Figure 5.14
demonstrates that the
$SCREEN directive is
used here in the same
manner as in the PRM1
type screen. The
field in which the
user enters the file
name is set using the
11 ©FILE" text with a
string of "."s
following it. A
length of 64 is
suggested for this
field, so that the
user may enter long
file names if
necessary. The $NAME directive is similar here to the $FIELD
directive in the PRM1 type screen and is thus followed with the
field name "@FILE," which appears in the screen text. The
directives $STATUS, $ACCESS, and $FORM specify the file as being
sequential, formatted, and of unknown status. Help to the user is
provided through the $HELP directive.
The file specification screen that results from these directives
and code (after the user has requested help information) is shown
in Figure 5.15.
Figure 5.14. Screen definition
directives to specify a file.
67
-------
[-OUTPUT FILE-
Name of file for output?
-HELP-
Enter the name of a file which your system understands.
-INSTRUCT-
Enter data in highlighted field.
Help:Ft Next:£2 Limits:F5 Quiet^S Xpad:*.? Cmnds Oops
Figure 5.15. Resulting file specification screen,
5.8 EDIT ONE-DIMENSIONAL ARRAY OF DATA
The Fortran code required
to prompt the user to
edit data is shown in
Figure 5.16. The
programmer supplies the
message file (MESSFL),
cluster (SCLU), group
(SGRP), number of integer
values (II) , number of
values (FNUM),
of character
(II), number of
data (set to 1
get min, max, and include info
11 = 1
SGRP= 26
FNUM= 2
RVAL(1)= 10
RVAL(2)= 10
CVAL(1,1)= 10
CALL QRESCN (MESSFL,SCLU.SGRP,11.FNUM,11,11,11,
IVAL,RVAL,CVAL,TBUFF)
SOFRMN(SOFCNT)= RVAL(1)
SOFRMX(SOFCNT)= RVAL(2)
SOFCND(SOFCNT)= CVAL(1,1)- 1
Figure 5.16.
1-D data.
Fortran code to enter
real
number
values
rows of
for one-dimensional
data) , and a flag, which
is set to 1 for this
application. The routine
QRESCN modifies the integer, real, and character arrays
(IVAL,RVAL,CVAL) as well as the character*! buffer containing the
data (TBUFF, dimensioned (80)). The arrays all must be dimensioned
by a value of at least one, even if there are no data values for
the respective array. In this case, the real array is dimensioned
68
-------
by two (FNUM) and both the integer and character arrays are
dimensioned by one. The character array has three elements for
each character field and thus must be dimensioned (number of
character fields,3). The first element is the response sequence
number in the user-selected response from the list following the
directive _VALID. The second element is the starting position of
the character response in the character*! buffer (TBUFF). The
third element is the length of the character response. The buffer
will contain the modified array values based on their starting
position and length. Although the integer array is set to 1, it
is not used because the screen definition file contains no _TYPE
integer specification. This code is from DBAPE code group SOIMAK,
subroutine SOIFSP.
The screen definition shown in Figure 5.17 specifies the format of
the screen ($SCREEN) and provides first and second level help
information. Two real fields with ranges and defaults and one
character field with valid responses and a default value are
defined. For the defined screen, help information is available
only for the character field for PRM3.
#GROUP 26 TYPE PRM1
SSCREEN
What is the minimum value for this parameter? > 3PRM1
What is the maximum value for this parameter? > 3PRM2
INCLUDE or EXCLUDE soils within specified range? > 3PRM3..
SFIELO 3PRM1
TYPE REAL
IRANGE o.ooo.- -999.000
_DEFAULT 0.000
SFIELD 3PRM2
_TYPE REAL
_RANGE 0.000: -999.000
"DEFAULT o.ooo
SFIELD 3PRM3
_TYPE CHARACTER
_VALID INCLUDE, EXCLUDE
"DEFAULT INCLUDE
_HELP
If you want to find soils within the specified numeric range, enter INCLUDE.
If soils not in the specified range are desired, enter EXCLUDE.
SWINDOW REAL PARM SPEC
Figure 5.17. screen definition directives to enter 1-D data.
The one-dimensional data entry screen resulting from these
directives and the Fortran code (after the user has requested
limits information for the first field) is shown in Figure 5.18.
69
-------
I
. PFAI PAPM 1PFP
What is the minimum value for this parameter? > D.
What is the maximum value for this parameter? >
INCLUDE or EXCLUDE soils within specified range? > INCLUDE
1 TUT Tf.
Default: O.OOOOE+00 Minimum: O.OOOOE+00 Maximum: none
... T UITPIIPT
Enter data in highlighted field.
1elp:Fl Next:?? Prev:F4 Limits:F$ Xpad:f$ Cmnds Status Oops Quiet
Figure 5.18. Resulting 1-D data screen.
5.9 EDIT TWO-DIMENSIONAL ARRAY OF DATA
65
group data3, form 6
11= 1
DO 65 J= 1, NUMRCH
DAT3R(1,J)= DAT2(1,J)
CONTINUE
SGRP= 13
RNUM = 8
CALL QRESCN (MESSFL.SGRP,11,11,RNUM,11 .NUMRCH, 11,
DAT3I,DAT3R,CVAL,SCHRBF)
The arguments for this
example are identical
to those in the example
in Section 5.8. The
main difference between
the two is that the
arrays now have two
dimensions. The second
dimension is the number
of rows of data, here
defined by the variable
NUMRCH (which was
defined earlier by the
program). Thus, all
the arrays must now be
dimensioned by the number of integer, real, or character fields and
by the maximum number of data rows possible. The character array
must now be dimensioned (number of character fields,3,number of
data rows). In this example, the integer (DAT3I) and real (DAT3R)
values being modified are already arrays dimensioned to (1,NUMRCH)
and (RNUM,NUMRCH) . This code is from ANNIE-QUAL2 code group
ANNSQ2S, subroutine AQUAL2.
Figure 5.19. Fortran code to enter 2-D
data.
70
-------
The screen definition in Figure 5.20 designates field 1 to be a
protected field, as it is only there to show the user the data row
(a stream reach in this example) for which data is being entered.
The field definitions are similar to those of the one-dimensional
data screen, with the addition of starting column (_COLUMN) and
field length (_WIDTH). Figure 5.21 is the resulting screen.
#GROUP 1 TYPE PRM2
(HEADER
Enter data type 3: Flow augmentation data.
Order Nutn of Target Order of Available Augmentation
of Avail DO Level Sources
Reach Sources (mg/l) 1st 2nd 3rd 4th 5th 6th
SFIELD FIELD1
_UIDTH 6
"COLUMN 10
PROTECT PROTECTED
"TYPE REAL
"RANGE o.: so.
"DEFAULT -999.
JtELP
Reach number (don't change)
$FIELD FIELD2
_WIDTH 9
_COLUMN 16
"TYPE INTEGER
RANGE 0: 100
"DEFAULT o
_HELP
Number of headwaters available for flow augmentation.
$FIELD FIELD3
WIDTH 9
"COLUMN 25
_TYPE REAL
RANGE 0.: 15.
"DEFAULT 5.
"HELP
Target minimum allowable dissolved oxygen level for reach
SFIELD FIELD4
_WIDTH 6
"COLUMN 39
_TYPE REAL
_RANGE 0.: 100.
_DEFAULT 0.
"HELP
Order of Sources (available headwaters, start upstream)
SFIELD FIELDS
_UIDTH 6
"COLUMN 45
TYPE REAL
"RANGE o.: 100.
^DEFAULT 0.
"HELP
Order of Sources (available headwaters, start upstream)
**** repeat for next 4 fields *****
Figure 5.20. Screen definition directives to enter 2-D data.
71
-------
Al IfiMFMT
Enter data type 3: Flow
Order Num of
of Avail
Reach Sources
1. Q
2. 0
3. 0
4. 0
5. 0
INSTRUCT
augmentation
Target
00 Level
(mg/l)
5.
5.
5.
5.
5.
Enter data in
1elp:Fi Next:f2 Limits
:F5 Xpad:F?
data.
Order
1st
0.
0.
0.
0.
0.
of Available Augmentation
2nd
0.
0.
0.
0.
0.
highlighted
Cmnds
Oops
Sources
3rd 4th 5th 6th
0. 0. 0. 0.
0. 0. 0. 0.
0. 0. 0. 0.
0. 0. 0. 0.
0. 0. 0. 0.
field.
Window
Figure 5.21. Resulting 2-D data screen.
5.10 ENTER TWO-DIMENSIONAL ARRAY OF DATA WITH BUFFER USE
Figure 5.22 shows the
Fortran code to prompt
the user to enter a
two-dimensional array
of data with use of a
buffer by the
programmer to set
character fields. The
arguments for
subroutine QRESCX are
the same as QRESCN (see
previous two examples).
This routine differs in
that it does not
initialize the screen
buffer (SCHRBF) to
blank characters.
Thus, the programmer
may pass the current
values into QRESCX
through the buffer.
This is necessary
because field two is an
C group data2, form 5
11= 1
C initialize screen
DO 52 1= 1, NUMRCH
LEN = 6
C reach order number
CALL DECCHR (DAT2(1,I),LEN,JUST,K,SCHRBF(1,I))
LEN = 16
C reach name
CALL CHRCHR(LEN,RCHNAM(1.I),SCHRBF<7,I))
LEN = 10
CALL DECCHR (DAT2(2,I),LEN,JUST,K,SCHRBF(23,I))
CALL DECCHR (DAT2(3,I),LEN,JUST,K,SCHRBF(33,I»
52 CONTINUE
SCLU= 12
SGRP= 1
RNUM= 3
CALL QRESCX (MESSFL.SCLU.SGRP,11,RNUM,11.NUMRCH,11,
M IVAL,DAT2,CVAL,SCHRBF)
LEN= 16
DO 53 1= 1, NUMRCH
CALL CHRCHR(LEN,SCHRBF(7,I),RCHNAM(1,I))
53 CONTINUE
Figure 5.22. Fortran code to enter 2-D
data using buffer.
72
-------
alphanumeric name and thus has no set of valid responses as is
needed by CVAL arrays. Although the programmer has put all of the
data array values in the buffer before the call, he does not need
to retrieve them all from the buffer after the call. The data
array values returned from QRESCX can be used. The only data field
that needs to be retrieved from the buffer is field two as it is
not returned in any of the argument arrays.
Figure 5.23 contains the corresponding screen definition for this
example. The screen definition for field two shows that although
it is a character field, it does not have any valid or default
responses. The resulting screen is shown in Figure 5.24.
#GROUP 1 TYPE PRM2
SNEADER
Enter data type 2
Reach Alphanumeric Headutr End
Order Name Locn (mi) Locn (mi)
SUINDOW REACH Identification
SFIELD FIELD1
WIDTH 6
"COLUMN 10
_PROTECT PROTECTED
"TYPE REAL
"RANGE o. : so.
_DEFAULT -999.
_HELP
Reach number
SFIELD FIELD2
_WIDTH 16
^COLUMN 16
_TYPE CHARACTER
_HELP
Name of reach
(FIELD FIELDS
WIDTH 10
"COLUMN 32
_TYPE REAL
RANGE 0. : -999.
"DEFAULT -999.
_HELP
River mile at head of reach
SFIELD FIELD4
_WIDTH 10
_COLUMN 42
"TYPE REAL
"RANGE o. : -999.
"DEFAULT o.
"HELP
River mile at end of reach
JHELP
See instructions for form 5 for more information.
Figure 5.23. Screen definition directives to enter 2-D data
with use of buffer.
73
-------
Enter data type 2
Reach Alphanumeric
Order Name
1.
2.
3.
4.
5.
tUCTpllPT
Enter
HelpifK Next:f2 Limits:F$
Headwtr End
Locn (mi ) Locn (mi )
; none none
none none
none none
none none
none none
data in highlighted field.
Xpad:p9 Cmnds Oops Window
Figure 5.24. Resulting 2-D data screen with use of buffer.
5.11 SET LIMITS AND DEFAULTS FOR ONE OR TWO-DIMENSIONAL DATA
Figure 5.25 shows
code used to set up a
call to QSCSET. This
routine allows the
programmer to set
limits and defaults
for one- or
two-dimensional data
that will override
the limits and
default on the screen
definition file. The
first four arguments
supply the number of
fields for each type
of data (integer,
real, double
precision ,
character). The
fifth argument is the
total number of
fields for the
current screen. For
set up ranges for full screen from base data set values
11 = 1
NFLDS= 4
IDUM = 0
DDUM = 0.0
CALL ZIPI (NFLDS.IDUM.VLINFG)
CALL ZIPI (NFLDS.IDUM.UCCNT)
CALL ZIPI (NFLDS,I1,USTRLN)
UCDEF= 0
RNUM = 4
RN = 0.0
CALL ZIPR (RNUM.RN.URMIN)
CALL ZIPR (RNUM.RN.URDEF)
URMIN(1)= DAT2(3,NUMRCH)
RN = 25.0
CALL ZIPR (RNUM,RN,URMAX(2))
URHAX(1)= DAT2(2,1)
CALL QSCSET (11,RNUM,11.11,NFLDS,IDUM,IDUM,IDUM,
URHIN,URHAX,URDE F,DDUM,DDUM,DDUM,
VLINFG,UCCNT,UCDEF,USTRLN,BLNIC)
Figure 5.25. Fortran code to set limits
for data fields.
74
-------
each type of numeric data, the minimum, maximum, and default values
must be specified (arguments 6 through 14). The argument VLINFG
is an array which specifies whether there are valid (set to 1) or
invalid (set to 2) values for each field. If the value for a field
is set to zero, there are no valid or invalid values for this
field. The argument UCCNT is an array of the number of valid or
invalid values specified for each field (set to zero if previous
argument is zero). The argument UCDEF is the default response for
each character field. The argument USTRLN specifies the length of
valid or invalid responses (if they exist) for each field. The
final argument is a buffer containing the valid or invalid
responses. In this example, the data fields are all real fields.
Thus, for all other data types, dummy values are used.
5.12 DISPLAY SYSTEM STATUS INFORMATION
Figure 5.26 contains code to
place information in the first
two lines of the status
display. The programmer
supplies the line number in the
status text (1-10) and the text
to display (TXTSTR). The text
is any length up to 78. The
status box is automatically
displayed in the assistance box
of the next screen that
appears.
put current data base in status
TXTSTR= 'Current data base is '//CDBTYP
CALL ZSTADDC11,TXTSTR)
TXTSTR= ' '
1= 2
CALL ZSTADDCI,TXTSTR)
Figure 5.26. Fortran code to add
status information.
Figure 5.27 shows the assistance box that results from the code
just discussed.
CTATIIfr
Current data base is ML
Figure 5.27. Resulting status display.
75
-------
5.13 SET COMMAND AVAILABILITY
Figure 5.28 contains Fortran code
to make commands appear and/or
disappear on the command line.
The programmer supplies the
command number (J) to be made
available or unavailable. The
second argument is a flag to make
the command available (set to 1)
or unavailable (set to 0) . A
list of the command numbers is
found in Appendix B.7. In this
example, a series of listings are
being displayed. When the first
listing is displayed (I equals 1
conditional), the user is allowed
to interrupt the listing, thus
the interrupt command is made
available (see Figure 5.29).
When the user progresses to the
second listing (I equals 2
conditional), the user is allowed
to back through the listings,
thus the previous command is made
available (see Figure 5.29). If
the user backs up to the first listing, the previous command would
be made unavailable again. Once the user has finished viewing the
listings, the interrupt and previous commands are made unavailable
(see Figure 5.29). This code is from DBAPE code group SOIMAK,
subroutine SOIPRT.
in loop of listing soils
IF (I.EQ.2) THEN
allow user to previous screen
J= 4
CALL ZSTCMA(J,I1)
ELSE IF (I.EQ.1) THEN
dont allow previous
J= 4
CALL ZSTCMA(J.IO)
allow interrupt
J= 16
CALL ZSTCMA(J,I1)
END IF
all done listing soils
turn of interrupt and prev
J= 4
CALL ZSTCMA(J.IO)
J= 16
CALL ZSTCHA(J.IO)
Figure 5.28. Fortran code to
set command availability.
command line display after interrupt allowed:
Next:F2 Xpad:F9 Cmnds Status Intrpt Quiet
command line display after previous allowed
Next:F2 Prev:F4 Xpad:f$ Cmnds Status Intrpt Quiet
command line display after listing complete
Next:F2 Xpad:F9 Cmnds Status Intrpt Quiet
Figure 5.29. Resulting command line display.
76
-------
5.14 SAVE CURRENT MENU TEXT
put name of parameter at top of menu (after blank line)
LEN= 1
CALL ZBLDUR (LEN.BK,11,IM1.DONBLD)
WRITE (TBUFX.2000) STR
LEN= 78
CALL ZBLDWR (LEN.TBUFF,10,IM1.DONBLD)
set dont initialize menu
CALL ZHNSST
Figure 5.30. Fortran code to save menu text.
Figure 5.30 shows
Fortran code to
control clearing
of the data
window. This
allows the
programmer to add
text from the
program to a menu
or data editing
screen. Figure
5.8 showed a
screen where a minimum value, maximum value, and include/exclude
option were entered. This screen is designed to define search
criteria for the parameter that has just been selected from a list
of parameters. This example shows how the programmer can display
the parameter which was selected. Two calls to ZBLDWR are made
with the write flag (fourth argument) set to a value of "-1." The
result is that text is not displayed. The first call is for a blank
line, with the initialization flag set to 1 (third argument), and
the second call is for the parameter name. Then a call to ZMNSST
sets the system to save the current text so it will be displayed
on the next screen. If this code is put before the code in example
5.8, the resulting screen is Figure 5.31.
\
.. PFAI PAPM *IPFr
for parameter: DP1
What is the minimum value for this parameter? > Q.
What is the maximum value for this parameter? >
INCLUDE or EXCLUDE soils within specified range? > INCLUDE
- 1 IMTT°
Default: O.OOOOE+00 Minimum: O.OOOOE+00 Maximum: none
—.. TWITDIirT
Enter data in highlighted field.
4elp:?t Next:f2 Prev:f4 Limits:?? Xpad:f9 Cmnds Status Oops Quiet
Figure 5.31.
information.
Resulting screen with additional text
77
-------
5.15 DETERMINE USER SCREEN EXIT COMMAND
Figure 5.32 shows how the programmer
returns the user's exit command value
using a call to ZGTRET. This is CALL ZGTRET
useful when the programmer has made
screen exits other than "NEXT"
available. Screen exit codes which
can be used are listed in Appendix ELSE 1F <'"T.E0.7) THEN
get the return code
IF (IRET.EQ.2) THEN
back up to review
1= I- 2
interrupt listing
1= NSOI
END IF
B.7. In this example, the programmer
has made the "INTRPT" and "PREV"
commands available. The value of the
screen exit command is checked, using
conditionals, to determine whether Figure 5.32. Fortran code
either the "INTRPT" (value of 7) or to_ determine user screen
"PREV" (value of 2) command has been exit command.
selected by the user. The programmer
then acts accordingly, depending on the value of the screen exit
command.
5.16 WRITE FILE CONTAINING MODEL PARAMETERS
Figure 5.33 illustrates the code needed to write an output file
containing a set of model parameters. The output file (OFL) has
already been successfully opened. In this example, there are
character strings to be output with the model parameters. The
strings are retrieved from the WDM-message file using the GETTXT
routine and placed in a character buffer TBUFF. The message file,
screen cluster number, group number, and maximum length of the
buffer are supplied by the programmer. The modified buffer is
returned as well as its new length. The current model parameters
are then put into the buffer using the routine INTCHR (integer to
character), DECCHR (real to character), or CHRCHR (character to
character). The inputs for either INTCHR or DECCHR are the data
value, the available length for the value, and the justification
of the value (0 for right, 1 for left) in the buffer. The modified
buffer and the actual length of the value in the buffer are
returned. The inputs for CHRCHR are the length of the character
string arrays and the character string array to be put in the
output character buffer. Once the data values for the current form
have been put in the output buffer, the buffer is written to the
output file. Notice that only the actual length of the buffer is
output, as determined by the length returned from the function
LENSTR. The buffer's maximum length and contents are supplied to
the function, and the actual length is returned as the function
value. The purpose of building a text string in this manner is to
assure that the parameter values required by a model fit in the
field width and are in an easily readable form.
78
-------
c
C form 5 - rch id
SGRP= 49
C get template text buffer from file
LEW = 80
CALL GETTXT (MESSFL,SCLU,SGRP,LEN,TBUFF)
DO 50 1= 1.NUMRCH
C put reach number in text buffer
L= 5
CALL DECCHR (DAT2C1,I),L,JUST,K,TBUFF(16))
C put reach name in buffer
L= 16
CALL CHRCHR (L,RCHNAM(1,I),TBUFF(25))
C put reach location in text buffer
L= 10
CALL DECCHR (DAT2C2,1 ),L, JUST,K,TBUFF(5D)
CALL DECCHR (DAT2C3,I),L,JUST,K,TBUFF(70))
C write text buffer to file
WRITE (OFL.2000) (TBUFF(K),K=1 ,LENSTR( I80,TBUFF»
50 CONTINUE
SGRP= 50
LEN = 80
CALL GETTXT (MESSFL,SCLU,SGRP,LEN,TBUFF)
WRITE (OFL.2000) (TBUFF(K),K=1,LENSTR(I80.TBUFF))
Figure 5.33. Fortran code to write model parameters to a
file.
5.17 SHUT DOWN SYSTEM
The code in Figure 5.34 shows a call
to routine ANGLOS. This routine
performs necessary functions for
close message, shut down system
, . n . . . , CALL ANCLOS (MESSFL)
ending an application program's use
of ANNIE-IDE. It closes the
WDM-message file and writes out the
scratch pad file. This call must Figure 5.34. Fortran code
follow all use of ANNIE-IDE and to shut down ANNIE-IDE.
should generally be the final
executable statement before the program stops.
79
-------
SECTION 6
RECOMMENDATIONS FOR ANNIE-IDE ENHANCEMENTS
During the course of the ANNIE-IDE development effort, a number of
ideas have surfaced that exceed the capabilities of the ANNIE and
EMIFE systems which were prototypes for ANNIE-IDE. Some (for
example, the scratch pad) have been implemented. Action on other
ideas has been deferred in order to get feedback from system users.
Ideas for additional ANNIE-IDE features fall into seven categories.
First, screen definition and movement within screens can be
enhanced. Additional data could be edited within a single screen
by allowing horizontal scrolling and improvements to vertical
scrolling. Basic data plotting capabilities would allow better
review of data values. Within 2-D data screens the ability to
generate data through functional transformations of other data
could assist in data editing tasks. Applications have been
identified which could make use of a dynamic screen definition
capability. This would allow the fields and related information
for the various types of data screens to be built in a manner
similar to the advanced screen building capabilities currently
supported. An option to allow users to view 2-D screens as a
series of 1-D screens would allow new users of an application to
view more levels of assistance with each field.
Enhancements to movement between screens would benefit more
advanced applications. Storage of screen movement command
availability with screen definition directives would simplify use
of advanced screen movement capabilities. The addition of screen
directives for specifying the names of other screens that are
accessible from a given screen would simplify interscreen movement.
Improvements to the scratch pad (XPAD) would allow users more
control in their use of an application. Recommended improvements
include allowing the user to read and write the contents of the
scratch pad to a file. Also recommended is the ability to copy the
contents of the data or status window to the scratch pad.
Management of user files is another area where enhancements to
ANNIE-IDE could be made. Application users are sometimes asked to
specify the name of a file where information was previously stored.
If the file name has been forgotten, then the user must exit the
application to determine the name. This inconvenience could be
80
-------
eliminated by making the names of files available within the
application.
Another series of possible enhancements relate to "cleaner"
recovery from user mistakes. Multiple levels of "OOPS" commands
would allow the user to backtrack through a number of individual
fields and screens. A command to interrupt an operation that was
started in error without breaking out of the application entirely
would allow users to continue within the application and not lose
completed work.
Finally, user training could be improved by implementing an
advanced tutorial facility that requires the user to enter expected
keystrokes and allows for display of additional information if the
user has not responded within a programmer-specified amount of
time.
In addition to the specific suggestions for ANNIE-IDE enhancements
found in this section, a review should be made of proposed
windowing standards like X-windows with the view of incorporating
ANNIE-IDE into a windowing environment.
81
-------
REFERENCES
1. Badre, A.N. 1988. Usability Critique and Recommendations
for the ANNIE-QUAL2E and EMIFE/123d Software. Report
prepared for AQUA TERRA Consultants, Mountain View, CA.
2. Brown, L.C. and T.O. Barnwell. 1987. The Enhanced Stream
Water Quality Models QUAL2E and QUAL2E-UNCAS: Documentation
and User Manual. U.S. Environmental Protection Agency,
Athens, GA. EPA report 600/3-87-007.
3. General Sciences Corporation. 1987. EMIFE- Environmental
Model Input File Editor Fortran Utilities-Preliminary
Documentation. U.S. Environmental Protection Agency, Office
of Toxic Substances, Washington, DC.
4. General Sciences Corporation. 1988. PCGEMS User's Guide.
Draft report prepared for U.S. Environmental Protection
Agency, Office of Pesticides and Toxic Substances,
Washington, DC.
5. Lumb, A.M. and J.L. Kittle, Jr. 1986. Preliminary Design of
a Data Storage and Retrieval System for Hydrologic and
Hydraulic Models (Watershed Data Management System, WDMS).
U.S. Geological Survey, Reston, VA.
6. Lumb, A.M., K.M. Flynn and J.L. Kittle, Jr. 1988. ANNIE
User's Manual. U.S. Geological Survey draft open-file report,
Reston, VA.
7. Shneiderman, B. 1987. Designing the User Interface:
Strategies for Effective Human-Computer Interaction.
Addison-Wesley, Inc., Reading, MA.
82
-------
APPENDIX A. GLOSSARY OF TERMS
The following terms have specific meanings within this manual and
hence require precise definition.
assistance window - four-line, middle window of standard ANNIE-IDE
screen; may display help, limits, status, command definitions,
scratch pad, or tutorial
command line - line at bottom of screen that displays the currently
available commands
data window - top window of standard ANNIE-IDE screen displaying
up to 10 or 14 lines of data (# of lines available depends on
whether or not assistance window is present)
human factors - interactive program characteristics that affect
user performance and satisfaction; factors include control,
consistency, functionality, and response time
information type - computer-specific abbreviation for the type of
ANNIE-IDE screen (valid types are: PRM1,PRM2,TEXT,MENU,FILE)
instruct window - bottom window of standard ANNIE-IDE screen
containing either instructive or corrective messages; contents of
window are controlled by ANNIE-IDE.
interscreen functions - program tasks related to movement between
screens and other screen-independent functions
intrascreen functions - program tasks related to construction of
individual screens
keyword - a character string which the ANNIE-IDE software
recognizes as the beginning of a screen directive; keywords with
a "$" prefix connote primary directives associated with an entire
screen, and those with a "_" prefix connote subdirectives
associated with a field or option
MESSAGE.SEQ file - sequential file containing screen directives for
screen clusters required by all ANNIE-IDE application programs
MESSAGE.WDM file - unformatted, direct-access file used for
efficient storage of user interaction text and parameter value
information
83
-------
MESSIE - interactive program used to import and export screen
definition files into and out of the WDM-message file
routine - Fortran SUBROUTINE or FUNCTION
screen - all the information displayed on a user's monitor at one
time; for ANNIE-IDE applications, the screen layout is standardized
and consists of three windows and a command line
screen cluster number - identification number for a series of
screen groups that are related in such a manner that they may be
expected to be modified at the same time (for example, a series of
screen groups related to a particular process or model subroutine;)
organization as clusters saves time and space when importing and
exporting and is useful for development of large programs with
multiple programmers
screen definition file - formatted sequential file containing one
or more screen clusters
screen directive - character strings in the screen definition file
which are used to define the type and content of an ANNIE-IDE
interactive screen; a screen directive consists of a keyword and
associated options or information
screen group number - identification number for a series of screen
directives that fully define one screen
screen type - one of five basic screen formats used by ANNIE-IDE
for enabling user interaction; the five screen types are TEXT,
MENU, 1-D ARRAY, 2-D ARRAY and FILE.
TERM.DAT file - formatted sequential file containing user
interaction parameter values
toolkit - total ANNIE-IDE software package, including subroutines
used for screen content construction, screen display control, and
housekeeping tasks; also included is an interactive program to
convert screen definition files to WDM-message files and vice versa
window - separate, delineated area of the screen devoted to a
specific task or category of tasks; ANNIE-IDE uses a data window,
an assistance window, and an instruction window
84
-------
APPENDIX B. REFERENCE MANUAL
Appendix B contains detailed information about the ANNIE-IDE
package. Included are:
Appendix B.I. Frequently Called Routines. Detailed
information about each toolkit routine mentioned in the main
body of this document. These are the routines most likely to
be used by the application programmer.
Appendix B.2. Summary of all Toolkit Routines. An
alphabetized list of all ANNIE-IDE toolkit routine names, the
code group where they are located, and a short description of
their function.
Appendix B.3. Data Structures. A description of the common
blocks used internally by ANNIE-IDE which includes the
definitions of the variables and where they are used.
Appendix B.4. Screen Definition Directives. A summary of
all screen definition directives organized by screen type.
Appendix B.5. File Formats. Details of the XPAD.DAT,
TERM.DAT and MESSAGE.WDM file formats.
Appendix B.6. TERM.DAT Parameters. A description of the
TERM.DAT file parameters used by ANNIE-IDE.
Appendix B.7. ANNIE-IDE Commands. A summary of available
and planned commands for ANNIE-IDE applications.
Appendix B.8. Color Codes. A table of color codes used to
specify colors on PCs.
Appendix B.9. Distribution Disk Contents. A description of
the ANNIE-IDE distribution disks.
85
-------
APPENDIX B.I FREQUENTLY CALLED ROUTINES
The ANNIE-IDE toolkit is designed to allow the application
programmer to utilize the capabilites of over 200 utilities while
dealing directly with approximatly 50 "lead" subroutines. In
Section 4.1 the lead subroutines are identified and their functions
are explained. This appendix provides additional programmer-
oriented information including: the purpose of each module,
arguments and their definitions, use of common blocks, routines
called by the module, and routines that call the module.
In addition to the lead subroutines, subordinate subroutines
contained in ANNIE-IDE which have been used in the programmer
application examples in Section 5 are also documented in this
appendix to allow better understanding of how ANNIE-IDE can
implement the screens and functions which have been illustrated.
Parallel documentation for all of the approximately 200 subordinate
routines contained in ANNIE-IDE is available in a file called
SYSDOC.OUT which is included with the ANNIE-IDE distribution disks.
86
-------
ANGLOS ANGLOS
This SUBROUTINE is number 2 in file AN1NIT.
Close message file and scratch pad file, write out scratch pad file.
ARGUMENTS:
declaration
order name type size status explanation
1 MESSFL 1*4 I Fortran unit number for message file
COMMON USAGE:
none
CALLS:
routine
QFCLOS ZEMSTP
CALLED BY:
unknown
87
-------
ANINIT ANINIT
This SUBROUTINE is number 1 in file ANINIT.
Initialize environment for ANNIE application.
ARGUMENTS:
declaration
order name type size status explanation
1 WDMSFL 1*4 I Fortran unit number for WDM message file
COMMON USAGE:
block name status
CFBUFF MAXREC 0
CALLS:
routine
ANPRGT COLINI GETFUN TRMINL UDBOPN UDFLCK ZEMIFE
CALLED BY:
group rout i ne
ANNSQ2M ANNIE
DBAPE DBAPE
88
-------
CHRCHR
CHRCHR
This SUBROUTINE is number 5 in file UTCHAR.
This routine moves LEN characters from string STR1 to string STR2.
ARGUMENTS:
declaration
order name type size status explanation
1 LEN
2 STR1
3 STR2
COMMON USAGE:
none
CALLS:
none
CALLED BY:
1*4
C*1 (V)
C*1 (V)
length of character strings
input character string
output character string
routine
ANNSQ2M
ANNSQ2S
ANOTHR
QTCHAR
QTFILE
QTPRIN
OTSCN1
SOIMAK
UTCHAR
UTMISC
UTSORT
UTWDMF
ZTSCN1
AQ2WRT
AQUAL2
ANUNCA
GEOMAK
CHKANS
QFOPFN
PMXTXM
QRESCZ
SOIFSM
DATLST
QTSTRY
ASRTC
UMSGTM
ZFLOUT
MTIT
OBSWRT
GSTF1N
PRTANS
CHRCHK
QRESPS
CHRSRT
QRSPIN
UNCREA
QTSTR
UNCURT
VRCOHP
QSCSET
SOIFSP
DECCHX
QUESET
SOIMAK
SOIPRT
GTCRNM
89
-------
DECCHR
OECCHR
This SUBROUTINE is number 20 in file UTCHAR.
This routine converts a real number to a character string. The number is right justified in
the string if the flag JUST is zero or if the number requires an exponent, otherwise it is left
justified.
ARGUMENTS:
declaration
order name type size status explanation
1 REAIN
2 LEW
3 JUST
JLEN
STR
R*4 I real value to be converted to a character string
1*4 I available length for output character string
1*4 M output justification
0 - right justified
1 - left justified
will be forced to 0 if an exponent is required
1*4 0 actual length of output character string
C*1 (V) 0 output character string
COMMON USAGE:
ANNS02M
ANNSQ2S
ANOTHR
GEOMAK
QTPRIN
SOIMAK
UTCHAR
ZTSCN1
AQ2URT
AQUAL2
ANUNCA
PRRLIS
PMXTXM
SOIFSM
PRTLIN
ZFLOUT
CHRINS FLOAT
IABS
IFIX
INTCHR
ZIPC
LCLWRT OBSWRT
PRTLNO
UNCWRT
90
-------
GETTXT
GETTXT
This SUBROUTINE is number 1 in file QTCHAR.
Reads text from the message file into a buffer.
ARGUMENTS:
order name
declaration
type size status explanation
UMESFL 1*4
SCLU
SGRP
OLEN
OBUFF
1*4
1*4
1*4
C*1 (V)
I message file containing string to read
I screen cluster number on WDM-message file
I screen group number in cluster
M length of string read from message file
0 string read from message file
COMMON USAGE:
none
CALLS:
routine
UMSGTT
CALLED BY:
ANNSQ2M
ANNSQ2S
ANOTHR
GEOMAK
QTCHAR
SOIMAK
UTUPRM
ZUTIL
ZUTILX
routine
AQ2WRT
AQUAL2
LCLWRT
ALLPRT
QRESPS
FNDCRP
ANPRRD
ZEMIFE
ZURTCM
OBSURT
GEOFND
SOIFSM
ZLIMIT
UNCINI
GEOMAK
SOIMAK
UNCWRT
GSTFIN
GTCRNM
GSTNFI
PRRLIS
91
-------
1NTCHR
INTCHR
This SUBROUTINE is number 24 in file UTCHAR.
This routine converts the integer number INTIN to a character string. The number will be right
justified in the string if the flag JUST is zero, otherwise is will be left justified.
ARGUMENTS:
declaration
order name type size status explanation
1 INTIN
2 LEN
3 JUST
JLEN
STR
COMMON USAGE:
none
CALLS:
1*4 I integer value to be converted to a character string
1*4 I available length for output character string
1*4 I output justification
0 - right justified in the field
1 - left justified in the field
1*4 0 actual length of output character string
C*1 (V) 0 output character string
routine
ALOG10
DIGCHR
INT
MOO
REAL
ZIPC
CALLED BY:
ANNSQ2M
ANOTHR
GEOMAK
QTPRIN
SOIMAK
USCNVT
UTCHAR
ZTSCN1
rout i ne
AQ2URT
LCLWRT
PRRL1S
PMXTXM
SOIFSM
SCCUMV
DATCHR
ZFLOUT
OBSURT
SOIPRT
SCCURM
DATLST
UNCURT
DECCHR
DECCHX
DPRCHR
92
-------
LENSTR
LENSTR
This INTEGER FUNCTION is number 25 in file UTCHAR.
This routine returns the actual length of the character string, excluding trailing blanks.
ARGUMENTS:
order name
declaration
type size status explanation
LEN
STR
C*1 (V)
available length of character string
character string
COMMON USAGE:
none
CALLS:
none
CALLED BY:
group routine
ANNSQ2M AQ2WRT
ANOTHR LCLWRT
CHKANS
QFOPFN
QRESPD
PMXTXM
QRESCZ
SOIFSP
QTSTRY
ANPRRD
QTCHAR
QTFILE
OTNUMB
QTPRIN
QTSCN1
SOIMAK
UTMISC
UTUPRM
UTUDMF
ZTSCN1
WMSADI
ZFILVL
OBSWRT
PRTANS
QRESPI
PRTSTR
ZFLOUT
CHRCHK
QRESPS
QRESPR
UNCURT
93
-------
PMXCNT
This SUBROUTINE is number 4 in file QTPRIN.
PMXCNT
This routine prints text from a message file to a terminal. It prompts the user every MAXLIN
lines to be sure its ok to continue. It also returns the number of lines printed.
ARGUMENTS:
name
declaration
type size
status explanation
1 UMESFL 1*4
2 SCLU 1*4
3 SGRP 1*4
4 MAXLIN 1*4
5 SCNINI 1*4
6 LINCNT 1*4
COMMON USAGE:
message file containing text to print
screen cluster number on WDM-message file
screen group number in cluster
maximum number of lines to print before more prompt
screen initialization flag (-1 - dont clear anything,
0 - clear in EMIFE mode only
1 - always clear)
count of lines printed
PRTXLC
94
-------
PMXCNU
This SUBROUTINE is number 5 in file QTPRIN.
PMXCNU
This routine prints text from a message file to a terminal. It prompts the user every MAXLIN
lines to be sure its ok to continue. It also returns the number of lines printed.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
UHESFL
SCLU
SGRP
MAXLIN
SCNINI
1*4
1*4
1*4
1*4
6 IURT 1*4
7 LINCNT 1*4
COMMON USAGE:
none
CALLS:
routine
ANPRGT PPRMPT
CALLED BY:
group routine
ANNSQ2S AQUAL2
QTPRIN PMXCNT
I message file containing text to print
I screen cluster number on WDM-message file
I screen group number in cluster
I maximum number of lines to print before more prompt
I screen initialization flag (-1 - dont clear anything,
0 - clear in EMIFE mode o
1 - always clear)
I 1 - write and go, 0 - write and wait for user a
-1 - dont write yet (EMIFE only)
0 count of lines printed
SCCLR
WMSGTT
ZBLDUR
ZTXINI
95
-------
PMXTXA
PMXTXA
This SUBROUTINE is number 13 in file QTPRIN.
This routine prints text from a message file to a terminal. It fills in values from CVAL
whenever a delimeter is found. It prompts the user every MAXLIN lines to be sure its ok to
continue.
ARGUMENTS:
declaration
order name type size status explanation
UHESFL
SCLU
SGRP
MAXLIN
SCNINI
6 IURT
7 CNUM
8 CLEN
9 CVAL
COMMON USAGE:
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4 (V)
C*1 (*)
message file containing text to print
screen cluster number on WDM-message file
screen group number in cluster
maximum number of lines to print before more prompt
screen initialization flag (-1 - dont clear anything,
0 - clear in EMIFE mode only
1 - always clear)
1 - write and go, 0 - write and wait for user acknowledge
-1 - dont write yet (EMIFE only)
number of character strings to include in message
array of lengths of character strings
array containing character strings to include
96
-------
PMXTXD
PMXTXD
This SUBROUTINE is number 11 in file QTPRIN.
This routine prints text from a message file to a terminal. It fills in values from OVAL
whenever delimeter is found. It prompts the user every MAXLIN lines to be sure its ok to
continue.
ARGUMENTS:
declaration
order name type size status explanation
UHESFL
SCLU
SGRP
MAXLIN
SCNINI
IURT
DNUM
DVAL
COMMON USAGE:
none
CALLS:
1*4
1*4
1*4
1*4
1*4
1*4
1*4
R*8 (V)
message file containing text to print
screen cluster number on WDM-message file
screen group number in cluster
maximum number of lines to print before more prompt
screen initialization flag (-1 - dont clear anything,
0 - clear in EMIFE mode only
1 - always clear)
1 - write and go, 0 - write and wait for user acknowledge
-1 - dont write yet (EMIFE only)
number of double precision numbers to include in message
array containing numbers to include
QTNUMB
QTPRIN
QRESPD
PRNTXD
97
-------
PMXTXI
This SUBROUTINE is number 7 in file QTPRIN.
PMXTXI
This routine prints text from a message file to a terminal. It fills in values from
whenever delimeter is found. It prompts the user every MAXLIN lines to be sure its ok
to continue.
IVAL
ARGUMENTS:
declaration
order name type size status explanation
UMESFL
SCLU
SGRP
MAXLIN
SCNINI
IWRT
1NUM
IVAL
COMMON USAGE:
none
CALLS:
routine
PMXTXM
CALLED BY:
1*4 I message file containing text to print
1*4 I screen cluster number on WDM-message file
1*4 I screen group number in cluster
1*4 I maximum number of lines to print before more prompt
1*4 I screen initialization flag (-1 - dont clear anything,
0 - clear in EMIFE mode o
1 - always clear)
1*4 I 1 - write and go, 0 - write and wait for user a
-1 - dont write yet (EMIFE only)
1*4 I number of integers to include in message
1*4 (V) I array containing integers to include
ANNSQ2S AQUAL2
QTNUMB QRESPI
QTPRIN PRNTXI
SOIMAK S01MAK
UTDATE CKTSTU
SOIPRT
98
-------
PMXTXM
This SUBROUTINE is number 14 in file QTPRIN.
PMXTXM
This routine prints text from a message file to a terminal. It fills in values from the IVAL,
RVAL, DVAL and CVAL arrays whenever a delimeter is found. It prompts the user every MAXLIN lines
to be sure its ok to continue.
ARGUMENTS:
declaration
order _ name type size status explanation
I Fortran unit number for WDM file
I screen cluster number on WDM-message file
I screen group number in cluster
I maximum number of lines to print before more prompt
I screen initialization flag (-1 - dont clear anything,
0 - clear in EMIFE mode only
1 - always clear)
I number of variables to be added to the text
I array of types for variables to be added to the text
I 1 - write and go, 0 - write and wait for user acknowledge
-1 - dont write yet (EMIFE only)
I array containing integers to include
I array containing reals to include
I array containing double precisions to include
I array of lengths of character strings
I array containing character strings to include
1
2
3
A
5
6
7
8
9
10
11
12
13
COMMON
none
CALLS:
UMESFL
SCLU
SGRP
MAXLIN
SCNINI
ONUM
OTYP
IURT
IVAL
RVAL
DVAL
CLEN
CVAL
USAGE :
1*4
1*4
1*4
1*4
1*4
1*4
1*4 (V)
1*4
1*4 (*)
R*4 (*)
R*8 (*)
1*4 (*)
C*1 (*)
routine
ABS
LENSTR
CALLED
group
ANPRGT CH
PPRMPT SC
BY:
routine
CHRDEL
STRFND
CHRINS
WMSGTT
DECCHR
ZBLDWR
DPRCHR
ZIPC
INTCHR
PMXTXR
PMXTXA
PMXTXD
99
-------
PMXTXR
PMXTXR
This SUBROUTINE is number 9 in file QTPRIN.
This routine prints text from a message file to a terminal. It fills in values from RVAL
whenever delimeter is found. It prompts the user every MAXLIN lines to be sure its ok
to continue.
ARGUMENTS:
declaration
order name type size status explanation
UMESFL
SCLU
SGRP
MAXLIN
SCNINI
IURT
RNUM
RVAL
1*4
1*4
1*4
1*4
1*4
1*4
1*4
R*4 (V)
I message file containing text to print
I screen cluster number on WDM-message file
I screen group number in cluster
I maximum number of lines to print before more prompt
I screen initialization flag (-1 * dont clear anything,
0 - clear in EMIFE mode o
1 - always clear)
I 1 - write and go, 0 • write and wait for user a
-1 - dont write yet (EMIFE only)
I number of decimal numbers to include in message
I array containing numbers to include
COMMON USAGE:
none
CALLS:
rout i ne
PMXTXM
CALLED BY:
group routine
ANNSQ2S AQUAL2
QTNUMB QRESPR
QTPRIN PRNTXR
100
-------
PMXTXT
This SUBROUTINE is number 2 in file QTPRIN.
PMXTXT
This routine prints text from a message file to a terminal. It prompts the user every MAXLIN
lines to be sure its ok to continue.
ARGUMENTS:
declaration
order name type size status explanation
1 UMESFL 1*4
2 SCLU 1*4
3 SGRP 1*4
4 MAXLIN 1*4
5 SCNINI 1*4
COMMON USAGE:
none
CALLS:
rout i ne
PMXCNT
CALLED BY:
group rout i ne
QTPRIN PRNTXT
I message file containing text to print
I screen cluster number on WDM-message file
I screen group number in cluster
I maximum number of lines to print before more prompt
I screen initialization flag (-1 - dont clear anything,
0 - clear in EMIFE mode only
1 - always clear)
101
-------
PRNTXD
This SUBROUTINE is number 10 in file QTPRIN.
PRNTXD
This routine prints text from a message file to a terminal with a double precision value appended
to the end of the first line.
ARGUMENTS:
order name
1 UMESFL
2 SCLU
3 SGRP
4 DVAL
COMMON USAGE:
none
CALLS:
rout i ne
PMXTXD
CALLED BY:
unknown
declaration
type size
1*4
1*4
1*4
R*8
status explanation
I message file containing text to print
I screen cluster number on WDM-message file
I screen group number in cluster
I array containing decimals to include
102
-------
PRNTXI
This SUBROUTINE is number 6 in file QTPRIN.
PRNTXI
This routine prints text from a message file to a terminal with an integer value appended to
the end of the first line.
ARGUMENTS:
order name
1 UMESFL
2 SCLU
3 SGRP
4 IVAL
declaration
type size status explanation
1*4
1*4
1*4
1*4
COMMON USAGE:
none
CALLS:
rout i ne
PMXTXI
CALLED BY:
group routine
ANNS02M A02REA
ANMS02S AQUAL2
ANOTHR ANOBDO
GEOMAK GEOMAK
QTFILE OFOPFN
SOIMAK SOIMAK
ANUNCA
GEOPRT
SOIPRT
I message file containing text to print
I screen cluster number on WDM-message file
I screen group number in cluster
I integer value to append at end of first line
OBSREA
UNCREA
103
-------
PRNTXR PRNTXR
This SUBROUTINE is number 8 in file QTPRIN.
This routine prints text from a message file to a terminal with an decimal value appended to the
end of the first line.
ARGUMENTS:
declaration
order name type size status explanation
1 UHESFL 1*4 I message file containing text to print
2 SCLU 1*4 I screen cluster number on WDM-message file
3 SGRP 1*4 I screen group number in cluster
4 RVAL R*4 I array containing decimals to include
COMMON USAGE:
none
CALLS:
routine
PMXTXR
CALLED BY:
unknown
104
-------
PRNTXT
This SUBROUTINE is number 1 in file QTPRIN.
This routine prints text from a message file to a terminal.
ARGUMENTS:
declaration
order name type size status explanation
PRNTXT
1 UMESFL
2 SCLU
3 SGRP
COMMON USAGE:
1*4
1*4
1*4
I message file containing text to print
I screen cluster number on WDM-message file
I screen group number in cluster
CALLS:
rout i ne
PMXTXT
CALLED BY:
ANNSQ2M
ANNS02S
ANOTHR
DBAPE
GEOMAK
QTCHAR
QTFILE
QTNUMB
OTSCN1
SOIMAK
UTMISC
ANNIE
AQUAL2
ANOBOO
DBANAL
GEOMAK
CHKANS
OFOPFN
QRESPD
QRESCZ
SOIFSP
ARRINP
TABI NO
MPCD
ANUNCA
OBAPE
QTSTR
QRESPI
SOIMAK
QTSTRY
DBWRIT
QRESPR
SOIPRT
SAFPAR
VADPAR
105
-------
QFOPEN
This SUBROUTINE is number 1 in file QTFILE.
This routine reads file specifications from the ANNIE message file
and opens the files.
ARGUMENTS:
declaration
order name type size status explanation
OFOPEN
1 MFILE
2 SCLU
3 SGRP
4 DAFL
5 RETCOD
COMMON USAGE:
1*4
1*4
1*4
1*4
1*4
I Fortran unit number of message file
I screen cluster number on WDM-message file
I screen group number in cluster
0 Fortran unit number for the file opened
0 return code, 0 if file opened, else non-zero
none
CALLS:
routine
QFOPFN ZIPC
CALLED BY:
group routine
ANNSQ2S AQUAL2
ANOTHR ANLOCL
GEOMAK GEOMAK
SOIMAK SOIMAK
ANOBDO
ANOTHR
ANUNCA
106
-------
QFOPFN QFOPFN
This SUBROUTINE is number 2 in file QTFILE.
This routine reads file specifications from the ANNIE message file and opens the files.
ARGUMENTS:
declaration
order name type size status explanation
1 MFILE
2 SCLU
3 SGRP
4 FLNEXT
6 DAFL
7 RETCOO
COMMON USAGE:
1*4
1*4
1*4
C*1 (64)
PRTFLG 1*4
1*4
1*4
I Fortran unit number of message file
I screen cluster number on WDM-message file
I screen group number in cluster
I name of file to open (original QFOPEN initializes this
to blank, user may supply a name from an external routine
I print flag, 0 - calling routine prints message,
1 - print message, dont try to fix error,
2 - print message and try to fix error
0 Fortran unit number for the file opened
0 return code, 0 if file opened, else non-zero
CARVAR
QRESP
CHRCHR
QTSTR
CVARAR
RECSET
GETFUN
WMSGTF
IOESET
LENSTR
PRNTXI
PRNTXT
CALLED BY:
group rout i ne
QTFILE
UTMISC
QFOPEN
QTSTRY
107
-------
QRESCD
QRESCD
This SUBROUTINE is number 5 in file QTSCN1.
This routine prompts a user for a response that contains any combination of integer, decimal,
double precision, and character strings. May be called with many rows of data and used in screen
mode.
ARGUMENTS:
declaration
order name type size status explanation
MESSFL
SCLU
SGRP
INUM
RNUM
DNUM
CNUM
NROW
SCNFG
14
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4
I
10 IVAL
1 1 RVAL
12 DVAL
13 CVAL
1*4 (V,V)
R*4 (V,V)
R*8 (V,V)
1*4 (V,3,V)
M
M
M
M
TBUFF C*1 (80,V)
COMMON USAGE:
none
CALLS:
rout i ne
QRESCR ZIPC
CALLED BY:
unknown
Fortran unit number of users message file
screen cluster number on WDM-message file
screen group number in cluster
number or integer responses
number of real responses
number of double precision responses
number of character responses
number or rows of responses
indicator flag for type of input processing
0 - process one line at a time
1 - process a screen at a time
array containing integer responses, calling routine
may pass initial values
array containing real responses, calling routine may
pass initial values
array containing double precision responses, calling
routine may pass initial values
array containing information about character responses
(_,1) - response sequence number
(_,2) - starting position of character response in TBUFF
(_,3) - length of character response
array of character strings containing integer, real, and
character responses in the order described by the
message file
108
-------
ORESCN
QRESCN
This SUBROUTINE is number 3 in file QTSCN1.
This routine prompts a user for a response that contains any combination of integer, decimal
and character strings. Hay be called with many rows of data and used in screen mode.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
8
UMESFL
SCLU
SGRP
INUM
RNUN
CNUH
NROU
SCNFG
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4
9 IVAL 1*4 (V,V) H
10 RVAL R*4 - length of character response
array of character strings containing integer, real, a
character responses in the order described by the
message file
QRESCX
ZIPC
ANNS02S AQUAL2
ANOTHR ANLOCL
QTSCN1 QRESPX
SOIMAK SOIFSP
MCELFG
ANOBDO
MPLOT
ANUNCA
109
-------
QRESCR
QRESCR
This SUBROUTINE is number 6 in file QTSCN1.
This routine prompts a user for a response that contains any combination of integer, decimal,
double precision, and character strings. Uses existing TBUFF for initial values. May be called
with many rows of data and used in screen mode.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
8
9
10
11
12
13
UMESFL
SCLU
SGRP
INUM
RNUM
DNUM
CNUM
NROW
SCNFG
IVAL
RVAL
DVAL
CVAL
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4 (V,V)
R*4 (V,V)
R*8 (V,V)
1*4 (V,3,V)
14
TBUFF C*1 (80,V)
Fortran unit number of users message file
screen cluster number on WDM-message file
screen group number in cluster
number or integer responses
number of real responses
number of double precision responses
number of character responses
number or rows of responses
indicator flag for type of input processing
0 - process one line at a time
1 - process a screen at a time
array containing integer responses, calling routine
may pass initial values
array containing real responses, calling routine may
pass initial values
array containing double precision responses, calling
routine may pass initial values
array containing information about character responses
(_,1) - response sequence number
(_,2) - starting position of character response in TBUFF
(_,3) - length of character response
array of character strings containing integer, real, and
character responses in the order described by the
message file
COMMON USAGE:
QRESCX
110
-------
QRESCX
This SUBROUTINE is number 4 in file QTSCN1.
QRESCX
This routine prompts a user for a response that contains any combination of integer, decimal
and character strings. Uses existing TBUFF for initial values. May be called with many
rows of data and used in screen mode.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
8
UMESFL
SCLU
SGRP
INUM
RNUM
CNUM
NROW
SCNFG
1*4
1*4
1*4
1*4
1*4
1*4
1*4
1*4
9 IVAL 1*4 (V,V)
10 RVAL R*4 (V,V)
11 CVAL 1*4 (V,3,V)
12 TBUFF C*1 (80,V)
COMMON USAGE:
Fortran unit number of users message file
screen cluster number on WDM-message file
screen group number in cluster
number or integer responses
number of real responses
number of character responses
number or rows of responses
indicator flag for type of input processing
0 - process one line at a time
1 - process a screen at a time
array containing integer responses, calling routine
may pass initial values
array containing real responses, calling routine may
pass initial values
array containing information about character responses
(_,1) - response sequence number
(_,2) - starting position of character response in TBUFF
(_,3) - length of character response
array of character strings containing integer, real, a
character responses in the order described by the
message file
ANNSQ2S AQUAL2
ANOTHR ANUNCA
QTSCN1 QRESCN
111
-------
QRESCZ
QRESCZ
This SUBROUTINE is number 7 in file QTSCN1.
This routine prompts a user for a response that contains any combination of integer, decimal,
double precision, and character strings. Uses existing TBUFF for initial values. May be called
with many rows of data and used in screen mode.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
UMESFL
SCLU
SGRP
INUM
RNUM
DNUM
CNUM
NROU
SCNFG
TLEN
IVAL
RVAL
OVAL
CVAL
*4
*4
*4
*4
*4
*4
*4
*4
1*4
1*4
1*4
**4
R*8
[*4
(V,V)
(V,V)
(V,V)
-------
CHRCHR
ZCNTL1
COLOR
ZCNTL3
CQRSPC
ZEDIT1
CQRSPI
ZEDTOM
LENSTR
ZFILVL
MOD
ZFLOUT
PRNTXT
ZIPI
UMSGTP
ZSCDEF
CALLED BY:
group rout i ne
ANNSQ2S MGLP
QTSCN1 QRESCR
MPCD
MTHETA
MTIT
113
-------
QRESP
QRESP
This SUBROUTINE is number 4 in file QTCHAR.
This routine prompts the user for a response with a question from the message file. Valid
responses in the message file are used to check the response. The user is prompted until an
acceptable answer is recieved. The responses for this routine are specific
character strings.
ARGUMENTS:
declaration
order name type size status explanation
1 UMESFL 1*4
2 SCLU 1*4
3 SGRP 1*4
4 RESP 1*4
COMMON USAGE
none
CALLS:
rout i ne
CFBUFF
CALLED BY:
:
QRESPS WD
I message file containing question
I screen cluster number on WDM-message file
I screen group number in cluster
M number of users response
WMSIDP
UMSMNS
ZIPC
group
ANNSQ2M
ANNS02S
ANOTHR
DBAPE
GEOMAK
QTFILE
SOIMAK
ANNIE
AQUAL2
ANLOCL
CORDAN
SCPAN
PRZSOI
ALLPRT
QFOPFN
SOIFSP
ANOBDO
DBANAL
SOI LAN
VADPAR
GEOFND
SOIMAK
ANOTHR
DBAPE
DBPARM
GEOMAK
ANUNCA
DSTAN
DBURIT
GSAN
PRZCHM
MDBSAN
PRZMET
METAN
PRZPAR
114
-------
ORESPD
This SUBROUTINE is number 6 in file QTNUMB.
QRESPD
This routine prompts the user for a response with a question from the message file. Valid
responses in the message file are used to check the response. The user is prompted until an
acceptable answer is received. The responses for this routine are double precision numbers and
the valid responses are checked against a minimum and maximum that are on the message file.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
UMESFL
SCLU
SGRP
DVAL
1*4
1*4
1*4
R*8
I message file containing question
I screen cluster number on WDM-message file
I screen group number in cluster
M value of users response
COMMON USAGE:
block
name status
CSCREC HELP
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
ZCNTL1
ZCNTL1
ZCNTL2
CALLS:
rout i ne
ABS
WMSGTP
CFLD
DDEF
DMAX
DMIN
FLEN
FLIN
SCOL
GPTR
HPTR
ZMNTXT
ANPRGT
ZCNTL3
I
A
A
A
I
I
I
A
A
A
CALLED BY:
group routine
QTNUMB ORSPUD
CHKDPR
ZEDTOM
CHRDPR
ZLJUST
LENSTR
PMXTXD
PRNTXT
QTSTRX
115
-------
ORESPI
QRESPI
This SUBROUTINE is number 2 in file OTNUMB.
This routine prompts the user for a response with a question from the message file. Valid
responses in the message file are used to check the response. The user is prompted until an
acceptable answer is received. The responses for this routine are integer numbers and the valid
responses are checked against a minimum and maximum that are on the message file.
ARGUMENTS:
declaration
order name type size status explanation
1 UMESFL 1*4
2 SCLU 1*4
3 SGRP 1*4
4 IVAL 1*4
COMMON USAGE:
block name status
CSCREC HELP 0
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CFLD
FLEN
FLIN
IDEF
I MAX
IMIN
SCOL
ZCNTL1 GPTR
ZCNTL1 HPTR
ZCNTL2 ZMNTXT
CALLS:
routine
ANPRGT
ZCNTL3
CALLED BY:
CHKINT
ZEDTOM
group rout i ne
I Fortran unit number for UDM file
I screen cluster number on WDM-message file
I screen group number in cluster
M users response
ANNSQ2S
ANOTHR
GEOMAK
OTNUMB
SOIMAK
AQUAL2
ANLOCL
GEOMAK
QRSPUI
SOIMAK
CRINTX
ZLJUST
LENSTR
PMXTXI
PRNTXT
OTSTRX
UMSGTP
MPLOT
ANOBDO
ANUNCA
116
-------
QRESPM
This SUBROUTINE is number 1 in file QTSCN1.
QRESPM
This routine prompts a user for a response that contains any combination of integer, decimal and
character strings.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
8
9
UMESFL
SCLU
SGRP
I HUM
RNUM
CNUM
IVAL
RVAL
CVAL
1*4
1*4
1*4
1*4
1*4
1*4
1*4 (V)
R*4 (V)
1*4 (V.3)
10 TBUFF C*1 (80)
COMMON USAGE:
Fortran unit number of users message file
screen cluster number on WDM-message file
screen group number in cluster
number or integer responses
number of real responses
number of character responses
M array containing integer responses, calling routine
may pass initial values
M array containing real responses, calling routine may
pass initial values
M array containing information about character responses
(_,1) - response sequence number
(_,2) - starting position of character response in TBUFF
(_,3) - length of character response
0 character string containing integer, real, and character
responses in the order described by the message file
none
CALLS:
routine
QRESPX
CALLED BY:
unknown
2IPC
117
-------
QRESPR
QRESPR
This SUBROUTINE is number 4 in file QTNUMB.
This routine prompts the user for a response with a question from the message file. Valid
responses in the message file are used to check the response. The user is prompted until an
acceptable answer is received. The responses for this routine are decimal numbers and the valid
responses are checked against a minimum and maximum that are on the message file.
ARGUMENTS:
declaration
order name type size status explanation
UMESFL 1*4
SCLU 1*4
SGRP 1*4
RVAL R*4
COMMON USAGE:
block name status
CSCREC HELP
I message file containing question
I screen cluster number on WDM-message file
I screen group number in cluster
M value of users response
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CSCREN
CFLD
FLEN
FLIN
RDEF
RMAX
RMIN
SCOL
ZCNTL1 GPTR
ZCNTL1 HPTR
ZCNTL2 ZMNTXT
CALLS:
rout i ne
ABS
WMSGTP
CALLED BY:
ANPRGT
ZCNTL3
CHKREA
ZEDTOM
CHRDEC
ZLJUST
LENSTR
PMXTXR
PRNTXT
QTSTRX
group routine
ANNSQ2M
ANNSQ2S
ANOTHR
QTNUMB
TABIND
AQUAL2
ANUNCA
ORSPUR
118
-------
QRESPS
QRESPS
This SUBROUTINE is number 5 in file QTCHAR.
This routine prompts the user for a response with a question from the message file. Valid
responses in the message file are used to check the response. The user is prompted until an
acceptable answer is received. The responses for this routine are specific character strings.
ARGUMENTS:
declaration
order name type size
status explanation
1
2
3
4
5
6
7
UMESFL
SCLU
SGRP
STRLEN
JUST
STR
STRNUM
1*4
1*4
1*4
1*4
1*4
C*1 (V)
1*4
message file containing question
screen cluster number on WDM-message file
screen group number in cluster
length of string response
justification of string (0-right, 1-left)
users response string
number of users response
COMMON USAGE:
block
name status
CQRSPC OBUFF
CQRSPC TANS
CQRSPC UANS
CORSPI DANS
CQRSPI LANS
ANPRGT
SCCLAL
CHKANS
STRFND
CHRCHR
WMSGTM
CHRDEL
ZCNTL1
CHRINS
2CNTL2
GETTXT
ZCNTL3
LENSTR
ZIPC
QTSTRX
ZSLMNN
CALLED BY:
group rout i ne
GEOMAK GEOMAK
QTCHAR QRESP
SOIMAK SOIFSP
SOIMAK
119
-------
QRESPX
This SUBROUTINE is number 2 in file QTSCN1.
QRESPX
This routine prompts a user for a response that contains any combination of integer, decimal and
character strings. Uses existing TBUFF for initial values.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
UMESFL
SCLU
SGRP
INUM
RNUM
CNUM
IVAL
1*4
1*4
1*4
1*4
1*4
1*4
1*4 (V)
8 RVAL
9 CVAL
10
COMMON USAGE:
R*4 (V)
1*4 (V,3)
TBUFF C*1 (80)
I Fortran unit number of users message file
I screen cluster number on WDM-message file
I screen group number in cluster
I number or integer responses
I number of real responses
I number of character responses
M array containing integer responses, calling routine
may pass initial values
M array containing real responses, calling routine may
pass initial values
M array containing information about character responses
(_,1) - response sequence number
(_,2) - starting position of character response in TBUFF
(_,3) - length of character response
M character string containing integer, real, and character
responses in the order described by the message file,
calling program may pass initial values
120
-------
QRSPUD
QRSPUD
This SUBROUTINE is number 5 in file QTNUMB.
This routine prompts the user for a response with a question from the message file. Valid
responses are supplied by the user to check the response. The user is prompted until an
acceptable answer is recieved. The responses for this routine are integer numbers and the valid
responses are checked against a minimum and maximum that are supplied by the user.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
UMESFL
SCLU
SGRP
DMIN
DMAX
DDEF
DVAL
1*4
1*4
1*4
R*8
R*8
R*8
R*8
Fortran unit number for WDM file
screen cluster number on WDM-message file
screen group number in cluster
user defined minimum value
user defined maximum value
user defined default value
users response
COMMON USAGE:
121
-------
QRSPUI
This SUBROUTINE is number 1 in file QTNUMB.
QRSPUI
This routine prompts the user for a response with a question from the message file. Valid
responses are supplied by the user to check the response. The user is prompted until an
acceptable answer is recieved. The responses for this routine are integer numbers and the valid
responses are checked against a minimum and maximum that are supplied by the user.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
UMESFL
SCLU
SGRP
IHIN
I MAX
IDEF
IVAL
1*4
1*4
1*4
1*4
1*4
1*4
1*4
I Fortran unit number for WDM file
I screen cluster number on WDM-message file
I screen group number in cluster
I user defined minimum value
I user defined maximum value
I user defined default value
M users response
COMMON USAGE:
none
CALLS:
routine
QRESPI QSCSET
CALLED BY:
group routine
ANNSQ2S MPLOT
ANOTHR ANUNCA
122
-------
QRSPUR
This SUBROUTINE is number 3 in file QTNUMB.
QRSPUR
This routine prompts the user for a response with a question from the message file. Valid
responses are supplied by the user to check the response. The user is prompted until an
acceptable answer is recieved. The responses for this routine are integer numbers and the valid
responses are checked against a minimum and maximum that are supplied by the user.
ARGUMENTS:
declaration
order _name type size status explanation
1
2
3
4
5
6
7
UMESFL
SCLU
SGRP
RMIN
RMAX
RDEF
RVAL
1*4
1*4
1*4
R*4
R*4
R*4
R*4
Fortran unit number for WDM file
screen cluster number on WDM-message file
screen group number in cluster
user defined minimum value
user defined maximum value
user defined default value
users response
COMMON USAGE:
none
CALLS:
routine
QRESPR
CALLED BY:
unknown
QSCSET
123
-------
QSCSET
QSCSET
This SUBROUTINE is number 9 in file QTSCN1.
Routine to set common block values for full screen limits as definied by user (bypassing
assignment from message file)
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
I HUM
RNUM
DNUM
CNUM
NMFLDS
UIMIN
UIMAX
UIDEF
URMIN
URMAX
UROEF
UDMIN
UDMAX
UODEF
VLINFG
UCCNT
UCDEF
USTRLN
URSPST
1*4
1*4
1*4
1*4
1*4
1*4 (V)
1*4 (V)
1*4 (V)
R*4 (V)
R*4 (V)
R*4 (V)
R*8 (V)
R*8 (V)
R*8 (V)
1*4 (V)
1*4 (V)
1*4 (V) I
1*4 (V)
C*1 (960)
COMMON USAGE:
number of integer fields
number of real fields
number of double precision fields
number of character fields
number of fields for this screen
array of user-defined integer minimum values
array of user-defined integer maximum values
array of user-defined integer default values
array of user-defined real minimum values
array of user-defined real maximum values
array of user-defined real default values
array of user-defined double precision minimum values
array of user-defined double precision maximum values
array of user-defined double precision default values
valid/invalid flag, 1- valid, 2- invalid, (0- none)
array of user-defined valid responses for each field
array of user-defined default responses for character fie
array of user-defined lengths of responses
user-defined string of valid responses
none
CALLS:
routine
CHRCHR CSCREC CSCREN WMSPIV
CALLED BY:
group routine
ANNSQ2S AQUAL2
ANOTHR ANOBDO
QTNUMB QRSPUD QRSPUI QRSPUR
ZCNTL1
ZCNTL2
ZCNTL3
124
-------
QTSTR
This SUBROUTINE is number 2 in file QTCHAR.
This routine, after prompting the user, reads text from the terminal into the buffer.
ARGUMENTS:
declaration
order name type size status explanation
QTSTR
1 UMESFL
2 SCLU
3 SGRP
4 LEN
5 STR
COMMON USAGE:
block name
CSCREN FLIN
CSCREN SCOL
1*4
1*4
1*4
1*4
C*1 (V)
status
I
I
1 Fortran unit number for WDM file
I screen cluster number on WDM-message file
I screen group number in cluster
I length of string to read
0 string containing users response
ANPRGT
ZEDTOM
CHRCHR
ZLJUST
CALLED BY:
group routine
ANOTHR ANOBDO
QTFILE QFOPFN
SOIMAK SOIFSP
CSCREC
ANUNCA
PRNTXT
QTSTRX
WMSGTP
ZCNTL2
ZCNTL3
125
-------
STRFND
STRFND
This INTEGER FUNCTION is number 29 in file UTCHAR.
This routine returns the position in the string STR of length LEN that the string FSTR of length
FLEN occurs. If FSTR is not found, a zero is returned.
ARGUMENTS:
declaration
order name type size status explanation
1
2
3
4
LEN
STR
FLEN
FSTR
1*4
C*1 (V)
1*4
C*1 (V)
COMMON USAGE:
none
CALLS:
none
CALLED BY:
I length of character string being searched
I character string to be searched
I length of character string to search for
I character string to be searched for
ANNSQ2M
ANOTHR
QTCHAR
QTPRIN
UTMISC
UTUPRM
routine
AQ2REA
LCLREA
QRESPS
PMXTXM
QTSTRY
ANPRRD
OBSREA
126
-------
ZBLDWR
This SUBROUTINE is number 11 in file ZUTIL.
build a screen in the menu box, options are write and wait
ARGUMENTS:
order name
ZBLDWR
declaration
type size status explanation
1 OLEN 1*4 I length of string to write
2 STRING C*1 (V) I string to write
3 INIT 1*4 I initialize screen, 0 - save old stuff,
1 - initialize,
-1 - overwrite last record
4 IWRT 1*4 I write flag, -1 - dont write, 0 - write and wait,
1 - write and dont wait
5 DONFG 1*4 0 user screen exit command
COMMON USAGE:
block name status
ZCNTL1 ZCLEN
ZCNTL1 ZCRCOL
ZCNTL1 ZCRLIN
ZCNTL1 ZCWID
ZCNTL1 ZHLCOL
ZCNTL1 ZHLLEN
ZCNTL1 ZHLLIN
ZCNTL1 ZMNLEN
ZCNTL2 ZMNTXT
ZCNTL3 ZB1N
ZCNTL3 ZMNCSL
ZCNTL3 ZMNNLI
A
A
A
A
A
A
A
A
ZCNTER
routine
GEOMAK ALLPRT
OTPRIN PMXCNW
SOIMAK FNDCRP
ZDRWSC
GEOFND
PMXTXM
SOIFSM
ZGTKYD
ZSCINI
ZSTCMA
ZUNCNT
ZWRTMN
GEOMAK
SOIFSP
GEOPRT
SOIMAK
PRRLIS
SOIPRT
127
-------
ZEMSTP ZEMSTP
This SUBROUTINE is number 9 in file ZUTILX.
Save xpad to a file.
ARGUMENTS:
none
COMMON USAGE:
none
CALLS:
routine
GETFUN QFCLOS ZCNTL1 ZCNTL2 ZCNTL3
CALLED BY:
group rout i ne
DBAPE DBAPE
128
-------
2GTRET
This SUBROUTINE is number 11 in file ZUTILX.
get return code from last screen
ARGUMENTS:
declaration
order name type size status explanation
ZGTRET
return code from last screen
ZCNTL3
ANNSQ2S AQUAL2
GEOHAK PRRLIS
SOIMAK SOIFSP
SOIMAK
129
-------
ZIPC
This SUBROUTINE is number 31 in file UTCHAR.
This routine fills the character array X of length LEN with the given value ZIP.
ARGUMENTS:
declaration
order name type size status explanation
ZIPC
1 LEN
2 ZIP
3 X
COMMON USAGE:
none
CALLS:
none
CALLED BY:
group routine
1*4
C*1
C*1 (V)
ANNSQ2M
ANNSQ2S
ANOTHR
QTCHAR
QTFILE
QTPRIN
QTSCN1
SOIMAK
UTCHAR
UTMISC
UTUPRM
UTUDMF
AQ2INI
AQUAL2
ANOBDO
UNCWRT
CHKANS
QFOPEN
PMXTXM
QRESCD
SOIFSM
DATLST
QTSTRY
ANPRRD
WMSGTM
AQ2URT
MGLP
ANUNCA
VRCDHP
PRTANS
QRESCN
SOIFSP
DECCHR
UMSGTP
length of character string
character to fill string
character string to be filled
MPCD
LCLWRT
QRESP
QRESPM
SOIPRT
DPRCHR
WMSGTE
MTHETA
OBSURT
QRESPS
GTCRNM
INTCHR
MTIT
UNCINI
ORSPIN
PRTLNO
CHRSRT
UNCREA
130
-------
ZIPD ZIPD
This SUBROUTINE is number 9 in file UTNUMB.
This routine fills the double precision array X of length LEN with the given value ZIP.
ARGUMENTS:
declaration
order name type size status explanation
I length of array
I value to fill array
0 output array
131
-------
ZIPI
This SUBROUTINE is number 10 in file UTNUMB.
This routine fills the integer array X of length LEN with the given value ZIP.
ARGUMENTS:
declaration
order name type size status explanation
ZIPI
1 LEN
2 ZIP
3 X
1*4
1*4
1*4 (V)
I
I
0
length of array
value to fill array
output array
COMMON USAGE:
none
CALLS:
none
CALLED BY:
group routine
ANNSQ2M AQ2INI
ANNS02S AQUAL2
AHOTHR ANLOCL
GEOMAK ALLPRT
QTSCN1 ORESCZ
SOIMAK SOICLR
UTDATE DATCHK
UTNUMB INITMD
Z4UTIL ZSLMNN
ZUTIL ZEMIFE
ANOBOO
GEOCLR
SOIFSP
ANUNCA
GEOIO
SOIMAK
UMCIHI
UNCREA
132
-------
ZIPR
This SUBROUTINE is number 11 in file UTNUMB.
This routine fills the real array X of length LEN with the given value ZIP.
ARGUMENTS:
declaration
order name type size status explanation
ZIPR
length of array
value to fill array
output array
ANNS02M AQ2INI AQ2REA
ANNSQ2S AQUAL2 MTHETA
ANOTHR ANLOCL ANOBDO
GEOMAK ALLPRT
SOIMAK SOICLA SOICLR
UTNUMB INITMD
ANUNCA
UNCINI
133
-------
ZMNSST ZHNSST
This SUBROUTINE is number 15 in file ZUTILX.
Set menu save flag.
ARGUMENTS:
none
ZCNTL2 ZCNTL3
SOIMAK
134
-------
ZPRTHN ZPRTMN
This SUBROUTINE is number 10 in file ZUTIL.
Write menu text to file.
ARGUMENTS:
declaration
order name type size status explanation
1 EXPFL 1*4 I Fortran unit number of file to write to
COMMON USAGE:
none
CALLS:
routine
ZCNTL1 ZCNTL2 2CNTL3
CALLED BY:
group routine
SOIMAK SOIPRT
135
-------
ZSTADD ZSTADD
This SUBROUTINE is number 17 in file ZUTILX.
Add to system status buffer.
ARGUMENTS:
declaration
order name type size status explanation
1
2
COMMON
block
ZCNTL1
ZCNTL1
ZCNTL1
STPOS
STTXT
USAGE:
name
ZSTCSL
ZSTLEN
ZSTNLN
1*4 I position in status buffer to add
C*78 I text to put in status buffer
status
0
M
M
CALLS:
routine
ZCNTL2 ZCNTL3 ZLNTXT ZSTCMA ZSTWRT
CALLED BY:
group routine
GEOMAK GEOMAK
SOIMAK SOIMAK
136
-------
ZSTCMA
This SUBROUTINE is number 18 in file ZUTILX.
Set command availability.
ARGUMENTS:
declaration
order name type size status explanation
ZSTCMA
ICMD
IAV
1*4
1*4
ANNSQ2S
GEOMAK
SOIMAK
UTWDMF
Z1UTIL
Z4UTIL
ZUTIL
ZUTILX
AOUAL2
PRRLIS
SOIFSP
UMSGTM
ZLOCAR
ZSLMNN
ZCMOEX
ZB20N
command id number
availability code =0 - NO, 1 - YES
ZCNTL3
SOIMAK
WMSGTP
ZEMIFE
ZDRUSC
UMSGTT
ZBLDWR
ZSTADD
ZQUIET
ZTXINI
137
-------
APPENDIX B.2 SUMMARY OF ALL TOOLKIT ROUTINES
The following is a complete list of the names of all subroutines
contained in the ANNIE-IDE software. A short definition of the
function of each subroutine also is included. The purposes of this
list are two-fold: first, to prevent the application programmer
from duplicating already-used routine names when naming new
subroutines developed for the specific application program; and
second, to alert the programmer to the capabilities of lower-level
subroutines included in the ANNIE-IDE software. The programmer may
obtain further details on these subroutines in the SYSDOC.OUT file
contained on the system distribution disk. For each subroutine,
the appendix provides information on the subroutine type, the file
in which it resides on the distribution disk, the order number
indicating where the subroutine occurs within the file, and a
functional description. The subroutine types are:
E - main program
S - subroutine
I - integer function
R - real function
D - double precision function
type file # description
Close message file and scratch pad file, write out scratch pad file.
Initialize environment for ANNIE application.
Routine to create local climatology data file.
Process input for annie/qual2 interactively.
Routine to plot observed DO data.
For seperate files of QUAL2E, (observed DO, UNCAS and local climate data).
Get user parameter value, reads TERM.DAT on first entry if overlay is used.
Reads user specific parameters from TERM.DAT file, otherwise defaults.
Interaction for uncertainty analysis specifications file.
Initialize aqua 12 common to default values.
Read in existing QUAL2E input sequence.
Write out a QUAL2E input sequence.
Main subroutine for ANNIE/QUAL2.
This routine gets a set of real numbers from the user from the terminal.
Sorts character strings.
Sorts integers.
Sorts integers in their array.
Sorts decimal numbers.
Sorts decimal numbers in their array.
Converts a character*! array of size LENA to a character*LEN string.
Converts a character string to its real equivalent.
Converts a character string to its integer equivalent.
ANCLOS
ANINIT
ANLOCL
ANNIE
ANOBDO
ANOTHR
ANPRGT
ANPRRD
ANUNCA
AQ2INI
AQ2REA
AQ2URT
AQUAL2
ARRINP
ASRTC
ASRTI
ASRTIP
ASRTR
ASRTRP
CARVAR
CHDECE
CHINTE
S
S
S
E
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
R
t
ANINIT
ANINIT
ANOTHR
ANNSQ2M
ANOTHR
ANOTHR
UTUPRM
UTUPRM
ANOTHR
ANNSQ2M
ANNS02M
ANNS02M
ANNSQ2S
UTMISC
UTSORT
UTSORT
UTSORT
UTSORT
UTSORT
UTCHAR
UTCHAR
UTCHAR
2
1
5
1
2
1
1
2
8
3
2
4
1
6
1
2
3
4
5
1
2
3
138
-------
name type group
description
CHKANQ
CHKANS
CHKDPR
CHKINT
CHKREA
CHKSTR
CHRCHK
CHRCHR
CHRDEC
CHRDEL
CHRDIG
CHRDPR
CHRINS
CHRINT
CHRSRT
CKDATE
CKNBLK
CKTSTU
CMPTIM
COLGET
COLIN!
COLSET
COPYC
COPYD
COPY!
COPYR
CORDAN
CRINTE
CRINTX
CTRSTR
CVARAR
DATCHK
DATCHR
DATLST
DATNXT
DAYMON
DBANAL
DBAPE
DBPARM
DBURIT
DECCHR
DECCHX
DIGCHR
DLIMIT
DPRCHR
DSTAN
EXRLIS
FNDCRP
GBFLIS
GEOCLR
GEOFND
GEOIO
GEOMAK
GEOPRT
GEOTBF
GETFUN
GETTXT
GSAN
GSTFIN
GSTNFI
GTCRNM
INITM
S
S
S
S
S
I
S
S
R
S
I
D
S
I
S
S
I
S
S
S
S
S
S
S
S
S
S
I
I
S
S
S
S
S
S
I
S
E
S
S
S
S
c
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
QTCHAR
QTCHAR
UTNUMB
UTNUMB
UTNUMB
UTCHAR
ANOTHR
UTCHAR
UTCHAR
UTCHAR
UTCHAR
UTCHAR
UTCHAR
UTCHAR
ANOTHR
UTDATE
UTCHAR
UTDATE
UTDATE
UTMISC
OTSCN1
UTMISC
UTCHAR
UTNUMB
UTNUMB
UTNUMB
DBAPE
UTCHAR
UTCHAR
UTCHAR
UTCHAR
UTDATE
UTCHAR
UTCHAR
UTDATE
UTDATE
DBAPE
DBAPE
DBAPE
DBAPE
UTCHAR
UTCHAR
UTCHAR
UTDATE
UTCHAR
DBAPE
GEOMAK
SOIMAK
SOIMAK
GEOMAK
GEOMAK
GEOMAK
GEOMAK
GEOMAK
SOIMAK
QTFILE
QTCHAR
DBAPE
GEOMAK
GEOMAK
SOIMAK
UTNUMB
7
6
3
1
2
4
14
5
6
8
9
7
10
11
12
1
12
2
3
12
8
11
13
4
5
6
6
14
15
16
17
4
18
19
5
6
2
1
10
17
20
22
23
7
21
8
10
6
13
5
4
6
1
7
12
5
1
4
9
8
10
7
Checks character answers supplied by the user. Returns any conflicting answer.
Checks character answers supplied by the user.
Checks the double precision OVAL against the minimum and maximum values.
Checks the integer IVAL against the minimum and maximum values.
Checks the real RVAL against the minimum and maximum values.
Searches the array of character strings STR2 for the character string STR1.
Searches through INVRNM array for a user input variable code.
Moves LEN characters from string STRt to string STR2.
Converts a character string to its real equivalent.
Deletes the character in position POS, shifts rest of string left one position.
Converts a single character to an integer if the character is 0 thru 9.
Converts a character string to its double precision equivalent.
Inserts the character CHAR into position COL in the string of characters STRING.
Converts a character string to its integer equivalent.
Sorts variable codes from INVAR.DAT file for UNCAS section of ANNIE/QUAL2E.
Determines the calendar order of two dates.
Checks string for all blanks. Returns a 0 if all blanks, else it returns a 1.
Checks time step and units for compatiIity.
Compares one time code and time step to a second time code and time step.
Returns the current values of the fore- and background.
Initializes the colors to be used in the program.
Sets the foreground and background colors.
Copies one character array to another cfiaracter array, both of length LEN.
Copies one double precision array to another the double precision array.
Copies one integer array to another integer array.
Copies one real array to another real array .
Selects coordinate analysis options.
Converts a character string to its integer equivalent.
Converts a character string to its integer equivalent.
Centers the characters within the string TITLE.
Converts a character*LENV variable to a character*! array of size LENA.
Checks a date (year, month, day, hour, minute, second) for valid entries.
Puts a date string into a character string.
Puts a date/time into a character string.
Adds or subtracts a time interval from the current date and time.
Returns the number of days in a given month for a given year.
Analyzes PRZM-LMS data base.
PRZM-LMS Interactive Data Base Analyzer and Parameter Estimator (DBAPE).
Estimates parameter values using PRZM-LMS data base (DBAPE).
Handles file writing capabilities.
Converts a real number to a character string.
Right justifies a real number into a character string of a given length.
Converts a single digit to a character.
Finds the earliest or latest date in an array of dates.
Converts a double precision number to a character string.
Analyzes descriptive statistics data base.
Export geographic ranked list of soils.
Finds use of a given crop in soils database.
Output geographic locations and acreages.
Clears geographic specifications array.
Find soils in given geographic area and summarize acres.
Do input/output on the geographic soil data base.
Interact with geographic soils database.
Output a geographic soil summary to standard output device.
Look through geographic buffer to find unique soil numbers.
Gets an unused Fortran unit number or frees up a unit number for a closed file.
Reads text from the message file into a buffer.
Analyzes geographic soils data base.
Get the state name from the input state FIPS code.
Get the state FIPS code from the input state number.
Determines name of crop from its number off the message file.
Initializes the arguments for full screen calls.
139
-------
name type group
# description
INITMD
INTCHR
IOESET
JDMODY
LCLREA
LCLWRT
LENSTR
LFTSTR
MCELFG
MDBSAN
METAN
MGLP
MPCD
MPLOT
MTHETA
MTIT
NUMPTS
OBSREA
OBSWRT
PCGRGT
PCGRST
PMXCNT
PMXCNW
PMXTXA
PMXTXD
PMXTXI
PMXTXM
PMXTXR
PMXTXT
PPRMPT
PRNTXA
PRNTXD
PRNTXI
PRNTXR
PRNTXT
PRRLIS
PRTANS
PRTLIN
PRTLNO
PRTSTR
PRTXLC
PRZCHM
PRZMET
PRZPAR
PRZSOI
Q2BSRT
QCHR
QFCLOS
QFOPEN
QFOPFN
QFSTAT
QRESCD
QRESCN
QRESCR
QRESCX
QRESCZ
QRESP
QRESPD
QRESPI
QRESPM
QRESPR
QRESPS
S
S
S
S
S
S
I
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
UTNUMB
UTCHAR
QTFILE
UTDATE
ANOTHR
ANOTHR
UTCHAR
UTCHAR
ANNSQ2S
DBAPE
DBAPE
ANNSQ2S
ANNSQ2S
ANNSQ2S
ANNSQ2S
ANNSQ2S
UTDATE
ANOTHR
ANOTHR
USCNVT
USCNVT
QTPRIN
QTPRIN
QTPRIN
QTPRIN
QTPRIN
QTPRIN
QTPRIN
QTPRIN
UTMISC
QTPRIN
QTPRIN
QTPRIN
QTPRIN
QTPRIN
GEOMAK
QTCHAR
UTCHAR
UTCHAR
UTMISC
QTPRIN
DBAPE
DBAPE
DBAPE
DBAPE
ANOTHR
UTMISC
QTFILE
QTFILE
QTFILE
QTFILE
QTSCN1
QTSCN1
QTSCN1
QTSCN1
QTSCN1
QTCHAR
QTNUMB
QTNUMB
QTSCN1
QTNUMB
QTCHAR
8
24
6
8
6
7
25
26
2
9
3
3
4
5
6
7
9
3
4
5
6
4
5
13
11
7
14
9
2
5
12
10
6
8
1
3
8
27
28
14
3
14
12
11
13
13
1
3
1
2
4
5
3
6
4
7
4
6
2
1
4
5
Initializes the arguments for full screen calls (with double precision).
This routine converts an integer number to a character string.
Set I/O error values for type of machine being used.
Converts a Julian day to month and day.
Reads in old local climatological data.
Writes out local climatological file.
Returns the actual length of the character string, excluding trailing blanks.
Left justifies a string of characters within the buffer TITLE.
Processes input for form 7 in ANNIE/QUAL2E.
Analyzes multiple data bases.
Analyzes metrologic data base.
Processes input for form 3 in ANNIE/QUAL2E.
Processes input for form 2 in ANNIE/QUAL2E.
Processes input for form 24 in ANNIE/QUAL2E.
Processes input for form 4 in ANNIE/QUAL2E.
Processes input for form 1 in ANNIE/QUAL2E.
Calculates the number of time steps between a start and end date.
Read in observed DO data.
Write out observed DO data.
Gets the graphics mode on the PC.
Sets the graphics mode on the PC.
PRNTXT variation, counts lines, opt to init screen.
PMXCNT variation, opt to: init screen, wait for user, display text.
Display text from message file with supplied character strings added.
Display text from message file with supplied double precision values added.
Display text from message file with supplied integer values added.
Display text from message file with any type(s) of supplied values added.
Display text from message file with supplied real values added.
PRNTXT variation, opt to initialize screen.
Asks user if more text, with more lines than screen buffer, should be printed.
Display text from message file with a character value added to text.
Display text from message file with a double precisioin value added to text.
Display text from message file with an integer value added to text.
Display text from message file with an decimal value added to text.
Display text from message file to terminal.
Print ranked list of soils by acreage.
Prints the valid character responses for a particular question.
This routine converts an array of real numbers into a string of characters.
This routine converts an array of real numbers into a string of characters.
This routine writes a character string to the given file unit.
PRNTXT variation, counts the lines displayed.
Estimates PRZM chemical data.
Estimates PRZM meteorologic data.
Estimates data base-related PRZM parameters.
Estimates PRZM soil parameters.
Sorts the input variable names (in UNCAS) in alphabetical order.
Gets a single character from a terminal.
Closes a file and makes the Fortran unit number available.
Reads file specifications from the message file and opens the file.
Variation of OFOPEN, file name to be opened is specified.
Returns a file name if the file is open or blanks if it is not open.
Variation of ORESCN with double precision data allowed.
Prompts user for any combination of data types (I,R,C) with multiple data rows.
Variation of QRESCD, buffer may supply initial data values.
Variation of QRESCN, buffer may supply initial data values.
Variation of QRESCR, length of buffer may be increased (>80).
Prompts user for a menu response from valid responses on the message file.
Prompts user for a double precision response, min, max, def from message file.
Prompts user for an integer response, min, max, def from message file.
Prompts user for any combination of data types (I,R,C) with one data row.
Prompts user for a real response, min, max, def from message file.
Variation of QRESP, with the menu response returned to the calling program.
140
-------
name type group
# description
QRESPX
QRSPIN
QRSPUD
QRSPUI
QRSPUR
QSCSET
QTSTR
QTSTRC
OTSTRX
OTSTRY
OUESET
QUPCAS
RECSET
SAFPAR
SCCLAL
SCCLR
SCCUHM
SCCUMV
SCCURM
SCPAN
SCPRBF
SCPRBN
SCPRST
SOICLA
SOICLR
SOICSP
SOIFSM
SOIFSP
SO I LAN
SOIMAK
SOIPRT
SOIREA
STRFND
STRLNX
TABIND
TIMADD
TIMBAK
TIMCHK
TIMCNV
TIMCVT
TIMDIF
TRMINL
UNCINI
UNCREA
UNCWRT
VADPAR
VRCDHP
WBCWCL
WBCWSP
UBCWSQ
WDATCL
WDATSP
WDBFIN
WDBOPN
WDCKDS
WDCKDT
WDDRRC
UDFLCK
UDINIT
WDNXDV
WDNXPS
WDPRPS
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
I
I
I
S
S
I
S
S
S
S
S
S
S
S
S
I
S
S
I
S
S
S
I
I
I
I
S
S
S
S
QTSCN1
QTCHAR
QTNUMB
QTNUMB
QTNUMB
QTSCN1
OTCHAR
UTMISC
UTMISC
UTMISC
QTSCN1
UTMISC
QTFILE
DBAPE
USCNVT
USCNVT
UTMISC
USCNVT
USCNVT
DBAPE
UTMISC
USYSPR
UTMISC
SOIMAK
SOIMAK
SOIMAK
SOIMAK
SOIMAK
DBAPE
SOIMAK
SOIMAK
SOIMAK
UTCHAR
UTCHAR
ANNS02M
UTDATE
UTDATE
UTDATE
UTDATE
UTDATE
UTDATE
UTMISC
ANOTHR
ANOTHR
ANOTHR
DBAPE
ANOTHR
UTWDT1
UTWDT1
UTWDT1
UTWDT1
UTWDT1
UTWDMD
UTWDMD
UTWDMD
UTWDMD
UTWDMD
UTWDMD
UTWDMD
UTWDMF
UTWDMF
UTWDMF
2
3
5
1
3
9
2
2
3
4
10
13
7
16
1
2
8
3
4
7
10
1
9
3
2
9
8
7
5
1
5
4
29
30
5
10
11
12
13
14
15
7
9
10
11
15
15
1
3
2
4
5
12
13
10
9
7
2
11
9
8
10
Variation of QRESPM, buffer may supply initial data values.
Routine to set responses for QRESP (menu) type question.
Variation of ORESPD, user supplies minimum, maximum, and default values.
Variation of QRESPl, user supplies minimum, maximum, and default values.
Variation of QRESPR, user supplies minimum, maximum, and default values.
Sets limits and defaults for 1 and 2-d data (bypassing message file).
Prompts user for character value with no valid responses.
Reads a character from the terminal.
Reads text from terminal into buffer.
Reads text from terminal into buffer, may read single character, or string.
Sets question for data response screens (bypassing message file).
Converts a character string from lower case to upper case.
Determine record length for an OPEN statement depending on the computer type.
Routine to data base-related SAFTMOD parameters.
Homes the cursor and clears the screen.
Clears the screen.
Moves the cursor home (1,1).
Moves cursor to the absolute row and column specified.
Moves the cursor to the relative row and column specified.
Routine to analyze soils properties and cropping practice data base.
Builds an output string buffer and writes it out.
Prints a string to the terminal with no cr/lf *** PRIME/PC SPECIFIC ***.
Prints a string to the terminal with no cr/lf.
Clear out the soil area storage buffer.
Clear out the soil storage buffer.
Does a soil meet our parameter specifications?
Summarize the search being performed.
Specify search parameters for soil/crop search.
Select soil analysis options under the GSAN level.
Interacts with soils database.
Routine to output a soil summary to standard output device.
Routine to input a soil properties record.
Return position in string being searched that string being searched for occurs.
Return the length of the input string. Leading/trailing blanks not included.
Determine the index of a table member specified by user (ANNIE/QUAL2).
Calculates a new time from an old time and increment.
This routine subtracts one time interval at the given units TUNIT.
Compares two time strings, returns 1 if SDAT < EDAT.
Converts a date/time that uses midnight convention of 00:00 to convention 24:00.
Converts a date/time that uses midnight convention of 00:00 to convention 24:00.
Calculates the number of timesteps between 2 dates.
Sets Fortran unit numbers for the log file and the terminal.
Initialize common for UNCAS.
Read old UNCAS file into UNCAS common block.
Write out UNCAS file.
Estimate data base-related VADOFT parameters.
Write out all valid variable codes in alphabetical order.
Calculates a WDMS block control word.
Breaks up a WDMS block control word.
Breaks up a WDMS block control word, adjusts TSTEP and NOV if possible.
Calculates a WDMS date (year- hour) for use at beginning of a group.
Breaks up a WDMS date word.
Initializes in memory file buffer.
Used by batch programs to open a wdmsfl and initialize common blocks.
Checks existence of dataset, returns 0 - dataset doesnt exist.
Checks existance and type of dataset, returns 0 - dataset doesnt exist.
Determines WDMSFL directory record number.
Function checks directory of WDMSFL for major errors.
Initializes MAXREC and buffer.
Move to the next data position on WDM file and return the data value.
Routine to get the next data position on a WDM file.
Routine to get the previous data position on a WDM file.
141
-------
name type group
# description
WDPTCL
WDPTSP
WDRCAD
WDRCGN
WDRCGO
WDRCGX
WDRCUP
WDSCHK
WMSADI
WMSANG
WMSATS
WMSATV
WMSBCS
WMSBCV
WMSBCX
WMSBTR
WMSFBC
WMSGTE
WMSGTF
WMSGTM
WMSGTO
WMSGTP
WMSGTT
WMSIDP
WMSMNS
WMSMNV
WMSP2S
WMSP2V
WMSPIS
WMSPIV
WMSPTE
WMSQCK
WMSSKB
WTBDCL
WTBDSP
WTBICL
WTBISP
XCHECK
Z4POS
ZARCMP
ZB20N
ZBEEP
ZBLDWR
ZCKINT
ZCMDEX
ZCMDIS
ZCNTER
ZCOLOR
ZCURMV
ZDELET
ZDRWDW
ZDRWSC
ZEDIT1
ZEDTOM
ZEMIFE
ZEMSTP
ZFILVL
ZFLOUT
ZFMTWR
ZGTKEY
ZGTKYD
ZGTRET
I
S
S
S
S
S
I
S
I
S
S
S
S
S
S
S
S
S
S
S
I
S
I
S
I
S
S
S
I
S
I
S
I
S
S
S
S
S
L
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
UTWDT1
UTWDT1
UTWDMD
UTWDMD
UTWDMD
UTWDMD
UTWDMD
UTWDMD
UTWDMF
UTWDMF
UTWDT1
UTWDT1
UTWDT1
UTWDT1
UTWDMF
UTWDMF
UTWDMF
UTWDMF
UTWDMF
UTWDMF
UTWDMF
UTWDMF
UTWDMF
UTWDMF
UTWDT1
UTWDT1
UTWDT1
UTWDT1
UTWDT1
UTWDT1
UTWDMF
UTWDMF
UTWDMF
UTWDT1
UTWDT1
UTWDT1
UTWDT1
SOIMAK
Z4UTIL
ZOUTIL
ZUTILX
ZUTILX
ZUTIL
ZUTILX
ZUTIL
ZUTIL
ZUTILX
ZUTILX
ZUTIL
ZUTILX
ZUTILX
ZUTILX
Z1UTIL
ZOUTIL
ZUTIL
ZUTILX
ZTSCN1
ZTSCN1
ZUTILX
ZSYSPR
ZUTIL
ZUTILX
6
7
6
4
1
5
3
8
3
2
17
16
13
12
15
13
16
12
7
6
14
4
5
17
15
14
21
20
19
18
11
1
18
10
11
8
9
11
2
2
2
1
11
4
3
5
5
3
14
6
7
8
1
1
1
9
3
2
10
1
2
11
Calculates a WDMS pointer value from record number and offset within record.
Split up a WDMS pointer into record and offset within record.
Function adds number of records specified to WOMSFL.
Function gets a new record from free record stack.
Function returns the index within the in memory file buffer.
Gets new record from free record stack, makes new records if required.
Writes a record to the UDMSFL.
Check WDM dataset existence and type, return number of groups.
Put message file information on WDM file.
Add new message file group to WDM file.
Split up message file attribute type integer parameters word.
Calculate a word for storing attribute type message file group paramters.
Split up a WDM message dataset block control word.
Calculate a WDM message dataset block control word.
Return the record and offset as well as the information stored there.
Back up NREC text records in a text group.
Get first block control word in a message dataset question and its position.
Get one record of text off WDM file for message datasets.
Get message file dataset file info from WDM file.
Get message file dataset menu info from WDM file.
Starting at DREC and DPOS, get and write text until end.
Get message file dataset parameter info from WDM file.
Get message file dataset text from WDM file.
Given the id of a piece of group info, return the position on the WDM file.
Split up a message file menu type integer parameters value.
Calculate a message file menu type integer parameters value.
Split up a message file PRM2 type integer parameters value.
Calculate an integer word from the 5 integer parms for PRM2 class questions.
Split a word from WDM file and return the values stored in the word.
Calculates a word for storage on WDM files given two integer words.
Put one record of text on WDM file for message datasets.
Checks to see if a question already exist on WDM file.
Skip to end of data block on WDM file.
Calculates a WDMS table dimension variable.
Split up WDM table dimension variable.
Calculates a WDMS table identifier from message file id, cluster and group.
Split up WDM table identifier.
Determines if current data base type matches type of XX soil in this record.
Calculate menu position for current option.
Arithmetic compiler.
Turn on the middle box, move upper text to make it fill whats available.
Ring terminal bell.
Build a screen in the menu box, options are write and wait.
Validate an integer character string.
Handle command input and execution.
Display current active commands and highlight default (if exists).
Center menu text.
Control screen colors in normal and reverse video.
Move cursor position based on keyboard input.
Delete a file using FORTRAN OPEN statement.
Draw window on the screen, given upper left corner coordinates and window size.
Draw screen for user interaction, (data window, message window, command list).
To perform menu selection for given template file.
Perform menu selections for multiple responses.
Retrieve control parameters from users TERM.DAT file.
Save xpad to a file.
This routine fills in QRESPM arrays with the user or default value.
Fills menu text for use in EMIFE routines.
Write string using a language-dependent format statement.
Wait for keyboad interrupt by performing queue I/O.
Get a key stroke for the data screen.
Get return code from last screen.
142
-------
name type group
# description
ZIPC
ZIPD
ZIPI
ZIPR
ZLIMIT
ZUUST
ZLNSTR
ZLNTXT
ZLOCAR
ZLOCFD
ZMNSST
ZPRTMN
ZQUIET
ZSCDEF
ZSCINI
ZSLMNN
ZSTADD
ZSTCHA
ZSTORE
ZSTRPR
ZSTWRT
ZTRIM
ZTXINI
ZUNCNT
ZVERIF
ZWINDO
ZWRHLP
ZWRMN1
ZWRSCR
ZWRTB2
ZWRTB3
ZWRTCM
ZWRTMN
ZWRVDR
ZWTREA
ZXPAD
S
S
S
S
S
S
1
I
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
S
UTCHAR
UTNUMB
UTNUMB
UTNUMB
ZUTIL
ZUTILX
ZUTILX
ZUTILX
Z1UTIL
ZOUTIL
ZUTILX
ZUTIL
ZUTIL
ZTSCN1
ZUTILX
Z4UTIL
ZUTILX
ZUTILX
ZUTILX
ZUTIL
ZUTILX
ZUTILX
ZUTIL
ZUTILX
ZUTIL
ZUTIL
ZUTIL
Z1UTIL
ZUTILX
ZUTIL
ZUTIL
ZUTILX
ZUTILX
ZSYSPR
ZUTILX
ZUTIL
31
9
10
11
12
14
12
13
2
3
15
10
16
1
16
1
17
18
19
13
20
21
15
22
6
17
9
3
25
7
8
23
24
2
26
4
Fills character array with the input value.
Fills double precision array with the given value.
Fills integer array with the given value.
Fills real array with the given value.
Display limits for current field.
Remove leading blanks from a character string.
Determine length of first word in a character string.
Determine length of text in a string, (the index of last non-blank character).
Locate neighbor field according to direction of cursor movement with arrow keys.
Locate neighbor field according to direction of cursor movement.
Set menu save flag.
Write menu text to file.
Turn on quiet mode.
Set default values for full screen arrays.
Initialize screen for a new menu.
To perform menu selection for given template file.
Add to system status buffer.
Set command availability.
Store data in a buffer in specific format.
Parse string of responses into string with commas separating the responses.
Display system status.
Remove embeded blanks between substrings in a character string.
Initialize parameters for start of a text screen.
Uncenter menu text.
Validate a data value field.
Turn on window.
Display help information.
Rewrite 2-d data screen.
Write a string to specific screen position.
Write a message to middle box from specified text.
Write a message to bottom box from WDM file.
Display a list of command descriptions.
Write menu to menu window.
Write a string to a given screen position in the video reverse mode.
Convert floating point number to numeric string.
Display and modify scratch pad.
143
-------
APPENDIX B.3 DATA STRUCTURES
This appendix provides detailed information on the common blocks
used internally by ANNIE-IDE. Included are a general description
of the common block's function, a list of parameters used to
dimension arrays within the common block, and the attributes of
variables and equivalences defined in the common block. Attributes
defined are: type (integer, real, etc.), array dimensions, and a
list of subroutines where the variable is used. For each
subroutine where a common variable is used, the usage is classified
as follows.
set - variable value is set
ref - variable is referenced
s/r - variable is both set and referenced
arg - variable is used as an argument to a subroutine
a/r - variable is used as an argument and referenced
asr - variable is used as an argument, referenced and set
144
-------
CFBUFF
This common block contains buffers for in memory storage of records from the WDM-message file. It is found
in the include file named CFBUFF.INC.
Parameters
CONREC value = 10 number of records used by in memory buffer
Variables
WIBUFF integer array (512.CONREC) in memory buffer for WDM-message file
set: WDRCGO WMSADI WMSPTE
ref: PRWMEX WDRCUP WDSCHK WDCKDT WDCKDS WMSQCK WMSANG WMSGTP WMSGTT WMSGTM WMSGTF WDNXPS WDNXOV
WDPRPS WMSGTE WMSBTR
s/r: WDFLCK WDRCGN WDRCAD UDDRRC
arg: WMSBCX
a/r: WMSFBC
asr: WDBSAC
EXUSE integer reserved for future use
set: WDBFIN
RECNO integer array (CONREC) array of record numbers in WDM-message file buffer
set: WDBFIN
ref: WDRCUP WDDRRC WMSANG WDNXPS
s/r: WDRCGO
NXTPOS integer array (CONREC) next position in buffer to use
set: WDBFIN
s/r: WDRCGO
PREPOS integer array (CONREC) previous position used in buffer
set: WDBFIN
s/r: WDRCGO
FREPOS integer next free data position on current record in WDM-message file
set: UDBFIN
s/r: WDRCGO
MAXREC integer maximum number of records on the WDM-message file
set: WDBFIN
ref: WDRCGO
S/r: ANINIT WDRCAD WDINIT
COLOR
This common block is used to set and retrieve screen colors. It is found in the include file named COLOR.INC.
Variables
FRE integer foreground color for error messages
ref: ZWRTB3
FRS integer standard foreground color
ref: ZCMDIS ZWRTB3
arg: COLINI
BKE integer background color for error messages
ref: ZWRTB3
BKS integer standard background color
ref: ZCMDIS ZWRTB3
arg: COLINI
FORE integer current foreground color
set: COLSET
ref: COLGET
BACK integer current background color
set: COLSET
ref: COLGET
Equivalences
COLARR integer array (15) array equivalenced to colors for retrieval from parameter definitions
arg: COLINI
145
-------
CORSPC
This common block contains character variables used by various user response subroutines. It is found in the
include file named CQRSPC.
Variables
QUEST character*! array (78) text for question in a menu type screen
s/r: WMSGTM
arg: QUESET
TANS character*! array (480) buffer containing valid responses for menu type screen
ref: ZSLHNN
s/r: WMSGTM
arg: ORSPIN QRESPS CHKANS
UANS character*! array (20) buffer containing users response in menu type screen
s/r: ZSLMNN
arg: QRESPS
OBUFF character*! array (80) buffer containing conflicting valid responses (from old ANNIE method)
a/s: QRESPS CHKANS
CQRSPI
This common block contains integer variables used by various user response subroutines. It is found in the
include file named CQRSPI.INC.
Variables
NANS integer number of valid responses for menu type screen
set: QRSPIN
ref: QRESPS ZSLMNN
s/r: UMSGTM
a/r: CHKANS
LANS integer length of valid responses for menu type screen
set: ORSPIN
ref: ZSLMNN
s/r: UMSGTM
a/r: QRESPS CHKANS
DANS integer default response for menu type screen
QUINIT integer flag indicating question already set for menu type screen
set: QUESET
s/r: UMSGTM
RSINIT integer flag indicating valid responses already set for menu type screen
set: QRSPIN
s/r: UMSGTM
146
-------
This common block contains character variables used by routines which do screen i/o. It is found in the
include file named CSCREC.INC.
Variables
FTC character*! constant indicating character data field
ref: ORESCZ ZEDTOM ZEDIT1 ZSCDEF ZFLOUT
S/r: UHSGTP
FTI character*! constant indicating integer data field
ref: ZEDIT1 ZSCOEF ZFLOUT ZLIMIT
s/r: WMSGTP
FTR character*! constant indicating real data field
ref: ZEDIT1 ZSCDEF ZFLOUT ZLIMIT
S/r: WMSGTP
FTD character*! constant indicating double precision data field
ref: ZEDIT! ZSCDEF ZFLOUT ZLIMIT
s/r: WMSGTP
BLNK character*! constant indicating blank character
S/r: WMSGTP
arg: ZWRMN!
a/s: QRESCN
HELP character*! constant indicating question mark
set: WMSGTP
s/r: QRESPI QRESPR QRESPD
FTYP character*! array (30) array indicating data field type (I.R.D.C)
ref: QRESCZ
s/r: WMSGTP ZSCDEF ZFLOUT ZLIMIT
a/r: ZEDTOM ZEDIT1
ASDSFG character*! array (30) array indicating field ordering (random,ascending,descending)
set: WMSGTP
ref: ZEDIT1
FDNAM character*8 array (30) array containing names for data fields
s/r: WMSGTP
FDFMT character*8 array (30) array containing formats for data fields
set: WMSGTP
147
-------
This common block contains numeric variables used by routines which do screen i/o. It is found in the include
file named CSCREN.INC.
Variables
NFLDS integer total number of data fields
ref: ZEDTOM
s/r: UMSGTP
a/r: QRESCZ
CROW integer current data row
ref: UMSGTP ZUINDO
set: ZGTKYD
r/s: QRESCZ ZEDIT1 ZLOCAR
CFLD integer current data field
ref: ORESPI ORESPR QRSPD ZIIMIT ZUINDO
s/r: UMSGTP ZLOCFD ZLOCAR
a/r: ZEDTOM ZEDIT1
FPROT integer array (30) array indicating data fields' protection (NONE.CORRECT,PROTECTED)
ref: ZLOCAR
asr: UMSGTP
SCOL integer array (30) array of data field starting columns
ref: QTSTR ORESPI QRESPR QRESPD ZEDTOM ZLOCFD ZEDIT1 ZLOCAR ZFLOUT
a/r: QRESCZ
asr: UMSGTP
FLEN integer array (30) array of data field lengths
ref: OTSTR QRESPI QRESPR ORESPD ZLOCFD ZLOCAR ZFLOUT
arg: ZLIMIT
a/r: QRESCZ ZEDTOM ZEDIT1 ZFLOUT
asr: UMSGTP
NMHDRU integer number of header rows for 2-dimensional data
ref: QRESCZ ZEDIT1 ZLOCAR ZURMN1 ZFLOUT ZGTKYD
s/r: UMSGTP
DTRUF integer first data row displayed in data window
s/r: ZEDIT1 ZLOCAR ZURMN1
DTRUL integer last data row displayed in data window
S/r: ZLOCAR ZURMN1
IMIN integer array (30) array of minimum values for integer data fields
set: QSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZLIMIT
a/r: QRESPI
IMAX integer array (30) array of maximum values for integer data fields
set: QSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZLIMIT
a/r: QRESPI
IDEF integer array (30)
set: QSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZSCDEF ZLIMIT
a/r: QRESPI
CCNT integer array (30)
set: QSCSET
s/r: UMSGTP
arg: ORESCZ ZLIMIT
CDEF integer array (30)
set: QSCSET UMSGTP
ref: ZSCDEF
RMIM real array (30)
set: OSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZLIMIT
a/r: QRESPI
RMAX real array (30)
set: OSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZLIMIT
a/r: ORESPI
array of default values for integer data fields
array of number of valid responses for character data fields
array of default responses for character data fields
array of minimum values for real data fields
array of minimum values for real data fields
148
-------
RDEF real array (30) array of minimum values for real data fields
set: QSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZSCOEF ZLIMIT
a/r: QRESPI
APOS integer array (30) array of pointers to data type count for each data field
set: UMSGTP
ref: ZEDTOM ZSCDEF ZFLOUT ZLIMIT
a/r: QRESCZ
SP1NIT integer flag indicating min, max, and default values have already been set for data fields
set: QRESCZ QSCSET
ref: UMSGTP
FUN integer array (30) array of line numbers in data screen text for each data field
ref: OTSTR QRESPI QRESPR ORESPD ZEDTOM ZLOCFD ZFLOUT
s/r: UMSGTP
a/r: ORESCZ
DMIN double precision array (30) array of minimum values for double precision data fields
set: OSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZLIMIT
a/r: QRESPI
DMAX double precision array (30) array of minimum values for double precision data fields
set: QSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZLIMIT
a/r: QRESPI
DDEF double precision array (30) array of minimum values for double precision data fields
set: OSCSET UMSGTP
ref: ZEDTOM ZEDIT1 ZSCDEF ZLIMIT
a/r: QRESPI
FREC integer array (30) array of record numbers to write data fields to on a file
a/s: UMSGTP
FSLOT integer array (30) array of column numbers to write data fields to on a file
a/s: UMSGTP
FDVAL integer array (30) array of pointers to start and length of valid responses for each field
set: OSCSET
ref: ZFLOUT ZLIMIT
arg: QRESCZ ZEDTOM ZEDIT1
asr: UMSGTP
FDINV integer array (30) array of pointers to start and length of invalid responses for each field
set: OSCSET UMSGTP
ref: ZLIMIT
arg: ZEDTOM ZEDIT1
UINFLG integer flag indicating user is specifying a data window in 2-dimensional data screen
set: ZUINDO
ref: ZLOCAR
s/r: ZEDIT1
URDU integer starting data row of window being defined
set: ZWINDO
ref: ZLOCAR
s/r: ZEDIT1
UFLD integer starting data field of window being defined
set: ZUINDO
ref: ZLOCAR
s/r: ZEDIT1
149
-------
CUSRPH
This common block contains variables to store users parameters. It is found in the include file named
CUSRPM.INC.
Variables
UPRMCT integer count of user parameters
ars: ANPRGT
UPARMS integer array of user parameter values
ars: ANPRGT
PMESFL
This parameter group contains the variable for the Fortran unit number of the WDM-message file. It is found
in the include file named PMESFL.INC.
Parameters
MESSFL value = 9 Fortran unit number of WDM-message file
TERI
This common block contains variables which control the input file to run the program. It is found in the
include file named TERI.INC.
Variables
TERIFL integer Fortran unit number for terminal or log file
set: TRMINL
ref: PPRMPT ARRINP
s/r: QTSTRY
TEMPFL integer Fortran unit number for terminal file if log file in use
set: TRMINL
ref: QTSTRY
LOGFL integer Fortran unit number for log input file
set: TRMINL
ref: QTSTRY ARRINP
ZCNTL1
This common block contains integer variables involved in screen control. It is found in the include file
named ZCNTL1.INC.
Variables
ZERR integer general error indication flag
set: ZCMDEX ZXPAD ZWRHLP ZDRWSC ZSCINI ZSTWRT ZWRTCM
ref: ZEDTOM ZEDIT1
S/r: ZGTKYD ZURTB3
ZRET integer user screen exit command
set: ZCMDEX ZSCINI
ref: ZBLDWR
s/r: ZEDTOM ZEDIT1 ZSLMNN
ZMESFL integer Fortran unit number for screen commands and information
set: ZEMIFE
arg: ZLOCFD ZLOCAR ZSLMNN ZCMDEX ZLIMIT ZWRTCM
a/r: ZWRTB3 ZDRWSC
ZDSN integer cluster on WDM-message file of screen messages
arg: ZWRTB3 ZLIMIT ZWRTCM
a/s: ZEMIFE
ZCMDAV integer array (26) array of screen command availability
set: ZEMIFE ZSTCMA
ref: ZLOCAR ZGTKYD ZCMDEX ZCMDIS ZWRTCM
150
-------
ZFKEY integer array (12) array of function key command assignments
set: ZEMIFE
ref: ZGTKYD
ZCMDMX integer total number of commands currently displayed
ref: ZCMDEX
s/r: ZCMDIS
ZESCST integer escape status, indicates what affect Escape key will have on screen
set: ZEMIFE ZXPAD ZWRTB3 ZWRHLP ZSCINI ZSTWRT ZWRTCM
s/r: ZGTKYD
ZTUTPS integer array (2) position in tutorial, cluster and group on WOM-message file
s/r: ZEMIFE
ZOTYP integer current type of data screen (i.e. text, menu, 1-d, 2-d)
set: ZEDTOM ZEDIT1 ZSLMNN ZBLDWR
ref: ZGTKYD ZCMDEX ZQUIET ZB20N ZDRWSC
ZQUFG integer flag indicating 'quiet1 command is available
set: ZEMIFE ZQUIET ZB20N ZDRUSC
ref: ZXPAD ZWRHLP ZLIMIT ZSTWRT ZWRTCM
ZB2LEN integer array (4) array of lengths of assistance window text
set: ZSCINI
s/r: ZXPAD
asr: ZWRTB2
ZCLEN integer number of lines which data screen information has been centered
arg: ZSLMNN ZBLDWR ZB20N
a/s: WMSGTM
ZCUID integer number of characters which data screen information has been centered
arg: ZSLMNN ZBLDWR ZB20N
a/s: WMSGTM
ZMNLEN integer array (50) array of lengths of data window text
set: WMSGTP ZFLOUT ZSCINI
arg: ZSLMNN ZQUIT ZB20N
a/s: WMSGTM ZEDTOM ZEDIT1
asr: ZCMDEX ZBLDWR
ZMSLEN integer array (3) array of lengths of instruction window text
set: ZSCINI
asr: ZWRTB3
ZWN2ID integer indentifier for type of information in the assistance window
set: ZEMIFE ZQUIET
ref: ZLOCFD ZLOCAR ZSLMNN ZSCINI
s/r: ZXPAD ZWRHLP ZLIMIT ZDRWSC ZSTWRT ZWRTCM
ZWN3ID integer indentifier for type of information in the instruction window
set: ZEDTOM ZED1T1 ZSLMNN ZDRWSC
s/r: ZWRTB3
ZGP3 integer identifier for current message in instruction window
set: ZEDTOM ZEDIT1 ZSLMNN ZDRWSC
s/r: ZWRTB3
ZHLPLN integer array (4) array of lengths of help text displayed
S/r: ZLIMIT ZWRTCM
asr: ZWRHLP
ZMNSAV integer flag indicating to save current data screen text
set: ZEDTOM ZSLMNN ZEMIFE ZMNSST
ref: ZSCINI
ZSTLEN integer array (10) array of lengths of current status text
ref: ZSTWRT
s/r: ZSTADD
ZSTNLN integer current number of lines in status text
set: ZEMIFE
ref: ZDRWSC ZSTWRT
s/r: ZSTADD
ZSTCSL integer current starting line of status text being displayed
set: ZEMIFE
s/r: ZSTADD ZSTWRT
ZCMDST integer flag indicating command line has been modified
set: ZEMIFE ZDRWSC ZSTCMA
s/r: ZCMDIS
151
-------
ZXPLEN integer array (10) array of lengths of current scratch pad text
s/r: ZEMIFE
asr: ZXPAD
ZXPNLN integer current number of lines in scratch pad text
ref: ZXPAD
s/r: ZEMIFE
ZXPCSL integer current starting line of scratch pad text being displayed
s/r: ZEMIFE ZXPAD
ZXPLIN integer current cursor line in scratch pad text
s/r: ZEMIFE ZXPAD
ZXPCOL integer current cursor column in scratch pad text
s/r: ZEMIFE ZXPAD
ZHLLIN integer current line being highlighted in data window
set: ZSCINI
ref: ZGTKYD ZWRHLP ZWRTMN
s/r: WMSGTP ZEDTOM ZLOCFD ZEDIT1 ZLOCAR ZWRMN1
arg: WMSGTM ZBLDUR ZB20N
asr: ZSLMNN
ZHLCOL integer current column being highlighted in data window
set: ZSCINI
ref: ZGTKYD ZWRHLP ZWRTMN
s/r: WMSGTP ZLOCFD ZLOCAR
arg: WMSGTM ZB20N ZBLDUR
a/r: ZEDTOM ZEDIT1 ZSLMNN
ZHLLEN integer current length of highlight in data window
set: WMSGTP ZLOCAR ZSCINI
ref: ZGTKYD ZWRHLP ZWRTMN
s/r: ZLOCFD
arg: WMSGTM ZBLDWR ZB20N
a/r: ZEDTOM ZEDIT1 ZSLMNN
ZCRLIN integer current cursor line on screen
set: WMSGTP ZWRMN1
arg: ZEDTOM ZEDIT1 ZSLMNN ZXPAD ZCMDIS ZWRTB3 ZWRHLP ZSTWRT ZWRTCM ZWRTMN
a/s: ZLOCFD ZLOCAR ZBLDWR
ZCRCOL integer current cursor column on screen
set: WMSGTP
arg: ZSLMNN ZXPAD ZCMDIS ZWRTB3 ZWRHLP ZSTWRT ZWRTCM ZWRTMN
a/s: ZLOCFD ZLOCAR ZBLDWR
asr: ZEDTOM ZEDIT1
GPTR integer pointer to start of general help on WDM-message file
set: WMSGTP WMSGTT WMSGTM WMSGTF ZTXINI
ref: ZDRWSC
arg: QRESPS ZLOCFD ZLOCAR ZSLMNN ZCMDEX
a/r: QTSTR QRESPI QRESPR QRESPD
HPTR integer array of pointers to start of help for data fields on WDM-message file
set: WMSGTP WMSGTM
ref: ZDRWSC
arg: QRESPS ZLOCFD ZLOCAR ZSLMNN ZCMDEX
a/r: QRESPI QRESPR QRESPD
152
-------
ZCNTL2
This common block contains character variables which are used to output screens. It is found in the include
file named ZCNTL2.INC.
Variables
ZMNTXT character*78 array (50) array containing the data screen text
set: ZSCINI
ref: ZPRTMN
s/r: WHSGTP
arg: QTSTR QRESCZ ZLOCFO ZLOCAR ZURMN1 ZSLMNN ZGTKYD ZCMDEX ZURHLP ZQUIET ZB20N ZWRTMN
a/s: QRESPI QRESPR QRESPD WMSGTM ZBLDWR
asr: ZEDTOM ZEDIT1 ZFLOUT
ZCMDNA character*6 array (26) array containing the screen command names
ref: ZCMDEX
arg: ZCMDIS
a/s: ZEMIFE
ZHLTXT character*78 array (4) array containing the help text
a/s: ZWRHLP ZLIMIT ZWRTCM
ZMSTXT character*78 array (3) array containing the instruction box text
a/s: ZWRTB3
ZSTTXT character*78 array (10) array containing the status text
set: ZEMIFE
arg: ZSTADD ZSTWRT
ZXPTXT character*78 array (10) array containing the scratch pad text
ref: ZEMSTP
a/s: ZEMIFE
asr: ZXPAD
ZFNAME character*80 name of to which screen data will be output
set: WMSGTP
ZFHEAD character*80 header to go at top of screen data output file
set: WMSGTP
ZFTRLR character*80 trailer to go at top of screen data output file
set: WMSGTP
RSPSTR character*! array (960) buffer containing valid and invalid responses for all data fields
ref: ZFLOUT ZVERIF
s/r: WMSGTP
arg: QRESCZ ZLIMIT
a/s: QSCSET
ZWNNAM character*8 array (13) array containing the various window names appearing on screens
arg: ZXPAO ZWRTB3 ZURHLP ZLIMIT
a/s: ZEMIFE
a/r: ZSTWRT ZWRTCM
ZSCNAM character*48 buffer for data window names specified by screen directive SW1NDOW
set: WMSGTP WMSGTT WMSGTM
a/r: ZDRWSC
Equivalences
The following equivalences are needed for use in ANNIE utilities which require character*! variables.
ZMNTX1 character*! array (78,50) equivalenced to ZMNTXT
arg: QTSTR QRESPI QRESPR QRESPO QRESCZ
asr: ZFLOUT
ZCMDN1 character*! array (6,26) equivalenced to ZCMDNA
ref: ZCMDEX
a/s: ZEMIFE
ZHLTX1 character*! array (78,4) equivalenced to ZHLTXT
set: ZWRHLP
arg: ZLIMIT ZWRTCM
ZXPTX1 character*! array (78,10) equivalenced to ZXPTXT
a/s: ZXPAD
ZWNAM1 character*! array (8,13) equivalenced to ZWNNAM
a/s: ZEMIFE
153
-------
ZCNTL3
This common block contains integer variables invlolved in screen control, primarily in window definition.
It is found in the include file named ZCNTL3.INC.
Variables
ZITYPE integer indicates which type of line graphics will draw the window
set: ZCOLOR
ref: ZDRUSC ZSTWRT ZURICH
arg: ZXPAD ZURTB3 ZWRHLP ZLIMIT
ZB1F integer screen line number of the first row of text in the data window
set: ZEMIFE
ref: ZDRWSC
arg: ZEDTOM ZEDIT1 ZSLMNN ZCMDEX ZBLDUR ZQUIET ZB20N
ZB2F integer screen line number of the first row of text in the assistance window
set: ZEMIFE
ref: ZXPAD ZURHLP ZLIMIT ZSTURT ZWRTCM
arg: ZWRTB2
ZB3F integer screen line number of the first row of text in the instruction window
set: ZEMIFE
a/r: ZWRTB3
ZB1N integer number of text rows able to be displayed in data window
set: ZEMIFE
ref: ZLOCAR ZURMN1 ZGTKYD
s/r: ZDRWSC
arg: WMSGTM ZEDTOM ZSLMNN
a/s: ZB20N
a/r: ZEDIT1 ZCMDEX ZBLDUR
asr: ZQUIET
ZB2N integer number of text rows able to be displayed in assistance window
set: ZEMIFE ZB20N
ref: ZXPAD ZLIMIT ZSCINI ZSTURT ZWRTCM
s/r: ZQUIET ZDRUSC
a/r: ZWRTB2 ZURHLP
ZB3N integer number of text rows able to be displayed in instruction window
set: ZEMIFE
ref: ZSCINI
a/r: ZURTB3
ZMNNLI integer current number of text rows in data window buffer (ZMNTXT)
set: ZFLOUT ZEMIFE
ref: QRESCZ ZEDIT1 ZURMN1 ZGTKYD ZCMDEX ZPRTMN ZDRUSC
s/r: UMSGTP ZSCINI
arg: ZB20N
asr: WMSGTM ZBLDWR
ZMNCSL integer current starting row of text displayed in data window
set: ZSCINI
ref: ZGTKYD ZQUIET ZB20N
s/r: ZCMDEX ZBLDWR ZDRWSC
154
-------
APPENDIX B.4 SCREEN DEFINITION DIRECTIVES
This appendix provides details for all screen definition directives
and subdirectives used for developing the five ANNIE-IDE screen
types. Note that the keywords for directives are preceded by a
"$," and those for subdirectives are preceded by a "_."
Instructions for sequencing and evaluating the directives for each
screen group are provided. The reader is referred to Section 5 for
examples of completed screen groups.
POS indicates where to specify value for directive as follows:
1) nxt - on following records
2) aft - after directive (text)
3) afi - after directive (integer)
4) fig - flag, no value needed
ID is calculated by MESSIE and is not specified by the application programmer.
KEYWORD POS .ID NOTES
TEXT screen type
STEXT
nxt 1
SHELP nxt 2
SUINDOW aft 19
MENU screen type
STITLE aft 1
text to display is data window of screen, total number of lines must be 50 or less,
max length of line to display in data window is 78, use "&" to indicate spot where
toolkit text screen display routine is to fill in a value
general help for screen
name of screen (up to 48 characters)
title of menu, maximum length 78 characters, appears on first line of data window
$DEFAULT afi 2a default option; if omitted, no default
SLENGTH afi 2b length of longest option identification string; required, must be between 1 and 63
$WIDTH afi 2d column width, default 78
SCOLENGTH afi 2e length of each column, must be between 1 and 8; default 8
SOPTION aft 3 option identification string,length must be less than or equal to SLENGTH
_DESC aft 4 description of option, length must be less than ($WIDTH - SLENGTH - 3)
_HELP nxt 5 help for option, use as many records as required, up to 78 characters per record
SHELP nxt 6 general help related to all options, as many records as required, up to 78 characters
per record
SWINDOU aft 19 window name (up to 48 characters)
155
-------
KEYWORD POS ID
PRM1 screen type
(WINDOW aft 19
(SCREEN nxt 1
NOTES
window name (up to 48 characters)
up to 10 records of text which represent the screen menu, field names are preceded
by '&' and may be extended by one or more '.' in order to make field wide enough for
expected values, up to 30 fields may be indicated
(HELP
nxt 16 general help for screen
(FIELD aft 2
TYPE aft 3
RANGE
VALID
aft 5
aft 6
DEFAULT aft 4
JNVALID
"HELP
•warning,
_RECORD
"SLOT
"PCODE
"UCODE
"FORMAT
ioUTPUT
HEADER
"TRAILER
aft 7
nxt 9
name of field, must match name in (SCREEN (including '3', excluding '.')
data type-INTEGER, REAL, DOUBLE PRECISION, or CHARACTER (type must be specified before
any other subdirectives under SFIELD)
minimum and maximum value allowed for numeric fields, separated by a colon, -999 if
unknown
valid values for any type of field, separated by commas
default value for parameter (must appear after _RANGE and _TYPE)
invalid values for any type of field
help information about field
the following optional keywords have not been tested within the 1-D screen routines
afi 8a record number in output data file where value will be stored
afi 8b start column in output data file record where value will be stored
afi 10a parameter code for field
afi 10b units code for field
aft 11 format for field output to file
aft 12 name of file to store parameter values
aft 13 character string written at beginning of output file
aft 14 character string written at end of output file
PRN2 screen type
(WINDOW aft 19 window name (up to 48 characters)
(HEADER nxt 16 header for screen (may be multiple lines)
(HELP
(FIELD
nxt
aft
15
2
•next 5 directives
TYPE
"WIDTH
ORDER
^PROTECT
COLUMN
"HELP
"RANGE
"VALID
"DEFAULT
"INVALID
•warning,
PACK
"FORMAT
"PCCOE
"UCODE
^FORMAT
(OUTPUT
HEADER
"TRAILER
aft
aft
aft
aft
afi
nxt
aft
aft
aft
aft
the
afi
afi
afi
afi
aft
aft
aft
aft
3a
3b
3c
3d
3e
9
5
6
4
7
general help for screen
name of input array field (no '3' required as in 1-D)
required before other directives
data type- INTEGER, REAL, DOUBLE PRECISION, or CHARACTER
field width, in characters
sort requirement - RANDOM (default), ASCENDING, DESCENDING
field protection - NONE (default), CORRECT (must be in valid range), PROTECTED (cannot
change value)
starting column of field
help information for field
valid range for numeric field
valid values for any type field
default value for field
invalid parameter values for any type
following optional keywords have not been tested within the 1-D screen routines
8a
8b
10a
106
11
12
13
14
number of values to pack on a data record
format of values on data record
parameter code for field
units code for field
format for field output to file
name of file to store parameter values on
character string written at beginning of output file
character string written at end of output file
156
-------
KEYWORD POS ID
FILE type screen
(WINDOW aft 19
(SCREEN aft 1
$NAME
aft 2
(STATUS aft 3
(ACCESS aft U
(FORM aft 5
(RECL aft 7
$HELP nxt 6
NOTES
window name (up to 48 characters)
screen menu text when asking for name of file, up to 10 records, field name preceded
by '&' and may be extended by '.', this keyword used only if file name is to be
provided by user
name of file ((SCREEN keyword not allowed) provided by application or field name in
screen text directive which will be provided by user
file status, OLD (default), NEW, UNKNOWN, or SCRATCH
file access method, SEQUENTIAL (default) or DIRECT
file format, FORMATTED (default) or UNFORMATTED
length of record in direct access file (bytes if formatted, half words if unformatted)
help related to file
157
-------
APPENDIX B.5 FILE FORMATS
This appendix provides format details for files that must be
utilized by an application programmer who intends to use the ANNIE-
IDE software. The files are introduced and their purpose and
contents are discussed in Section 4.3. Additional details for the
TERM.DAT file are provided in Appendix B.6.
TERM.DAT
The TERM.DAT file is a formatted, sequential file that may be
constructed and manipulated with a text editor. One parameter name
and its value are to be specified per line. The parameter name
should be followed by one blank and then the desired value. Blank
lines at the top or bottom of the file may cause problems on
certain systems. The number of lines in the file is limited only
by the number of available parameters for which the user wishes to
specify values.
XPAD.DAT
The scratch pad file is a formatted, sequential file that may be
constructed and manipulated with a text editor. The maximum number
of lines is ten, and the length of these lines must not be greater
than 78.
Screen Definition
The screen definition file is a formatted, sequential file that
may be constructed and manipulated with a text editor. The length
of lines may not be greater than 120. However, the length is most
often limited by the maximum length of the variable being defined
(e.g. maximum length of 78 for any data to be displayed in any of
the windows). There is no column dependency for the values being
defined, although spacing between keywords and their values is
suggested for readablility. Careful attention should be paid to
correct spelling of keywords for directives and sub-directives as
the whole word is searched for.
WDM-message
The WDM-message file is an unformatted direct access file with
record lengths of 2048 bytes. This file must not be manipulated
in any way with a text editor or Fortran READ or WRITES. It must
only be created or modified using MESSIE.
158
-------
APPENDIX B.6 TERM.DAT PARAMETERS
This appendix describes the parameters of the user system
specifications file (TERM.DAT), which is introduced in Section 4.3.
Information provided includes: parameter code numbers (used by
programmer) , code names (required by program user) , default values,
allowable values, and definitions. Additional TERM.DAT parameters
are found in the ANNIE users manual (Lumb et al., 1988.)
PARAMETER
CODE NUMB
AND NAME
1 CMPTYP
2 TRMTYP
3 TRMINP
4 TRHOUT
DEFAULT
VALUE
PC
PC
1
1
ALLOWABLE
VALUES
PC
PRIME
VAX
PC
VT100
0 to 10
0 to 10
5 TRMPAU
6 TRMF1L
11 SCRUID
12 SCRLEN
13 FILMAX
14 F1LUNI
15 RECTYP
124
64
80
24
15
30
WORD
33 to 127
33 to 127
40 to 256
10 to 100
10 to 99
7 to 99
BYTE
WORD
color definitions (see Appendix B.7 for values for PC)
22 CLRFRK 15 0 to 15
26 CLRFRE
28 CLRFRD
30 CLRFRS
32 CLRBKE
33 CLRBKS
4
15
7
2
0
0 to 15
0 to 15
0 to 15
0 to 15
0 to 15
DEFINITION
type of computer, use PC for IBM
clones
type of terminal
Fortran unit number for reading
from the terminal
Fortran unit number for writing
to the terminal:
1 for PRIME,
6 for DEC VAX,
6 for PC,
0 for Data General.
pause character, sequence
number in character set
fill character, sequence number
in character set
number of columns on the
terminal screen
number of lines shown on the
terminal screen
maximum number of file units
open at any one time
first unit number to assign to
files needed by ANNIE-IDE
units for specifying record
lengths on OPEN statements for
unformatted direct access files.
foreground color for modified data (currently
as CLRFRS)
foreground color for error messages
foreground color for data window (currently same
as CLRFRS)
standard foreground color
background color for error messages
standard background color
159
-------
PARAMETER
CODE NUMB DEFAULT
AND NAME VALUE
35 BUGFLG NONE
45 USRLEV
function key definitions
ALLOWABLE
VALUES
NONE,SOME
LOTS
0 or 2
DEFINITION
91 PFKEY1
92 PFKEY2
93 PFKEY3
94 PFKEY4
95 PFKEY5
96 PFKEY6
97 PFKEY7
98 PFKEY8
99 PFKEY9
amount of debug printout
User experience level
0-lots, 2=none
Allowable values are the first letters of system
commands supported. The PFKEY3 is defaulted to
no value as it is needed to emulate ESC when
using a mouse.
160
-------
APPENDIX B.7 ANNIE-IDE COMMANDS
This appendix describes the commands which are currently available
in, or are planned extensions of, the ANNIE-IDE development system.
First, the eleven basic commands are described, followed by three
planned extensions. See Section 3.7 for additional discussion of
these fourteen commands. Finally, the seven optional commands
which can be used to implement movement between screens are
described. See Section 3.10 for additional discussion of these
commands.
BASIC APPLICATION COMMANDS
COMMAND COMMAND
NAME ORDER # COMMAND DEFINITION
CMND 2 DISPLAY DEFINITIONS OF VALID COMMANDS IN ASSISTANCE INFORMATION WINDOW
DNPG 14 DISPLAY NEXT PAGE IN DATA WINDOW
HELP 1 DISPLAY HELP INFORMATION IN ASSISTANCE INFORMATION WINDOW
LIMITS 6 DISPLAY LIMITS OF CURRENT FIELD IN ASSISTANCE INFORMATION WINDOW
NEXT 3 GO TO NEXT SCREEN (SETS SCREEN EXIT STATUS CODE TO 1)
OOPS 8 RESET VALUES IN DATA WINDOW TO VALUES WHEN SCREEN FIRST DISPLAYED
QUIET 20 TURN OFF ASSISTANCE INFORMATION WINDOW TO ALLOW MORE ROOM FOR DATA
STATUS 7 DISPLAY SYSTEM STATUS IN ASSISTANCE INFORMATION WINDOW
UPPG 15 DISPLAY PREVIOUS PAGE IN DATA WINDOW
WINDOW 9 DEFINE CORNER OF DATA OPERATION WINDOW
XPAD 21 DISPLAY USERS SCRATCH PAD, ALLOW CHANGES
planned command extensions
MOVE 10 COPY ROWS/COLUMNS OF TWO-DIMENSIONAL DATA
TUTOR 5 PROVIDE TUTORIAL
VIEW 11 DISPLAY GRAPHIC DATA
OPTIONAL COMMANDS FOR MOVEMENT BETWEEN SCREENS
COMMAND COMMAND SCREEN EXIT
NAME ID # STATUS CODE COMMAND DEFINITION
ABORT 18 6 STOP EVERYTHING QUICKLY
BEGIN 12 3 GO TO FIRST SCREEN
EXIT 17 5 CLEAN UP AND RETURN TO OPERATING SYSTEM
GOTO 13 4 GO TO SCREEN TO BE SPECIFIED
INTRPT 16 7 STOP CURRENT ACTIVITY
NEXT 3 1 GO TO NEXT SCREEN (ALWAYS AVAILABLE)
PREV 4 2 GO TO PREVIOUS SCREEN
161
-------
APPENDIX B.8 COLOR CODES FOR PC COLOR IMPLEMENTATION
The following color code numbers are acceptable values for the
color specifications parameters in the TERM.DAT file (i.e.,
parameters CLRFRM, CLRFRE, CLRFRD, CLRFRS, CLRBKB, CLRBKS) in
Appendix B.6. Note that color specification is only meaningful for
program applications using PCs with color monitors.
NUMBER DESCRIPTION
0 BLACK
1 BLUE
2 GREEN
3 CYAN
4 RED
5 MAGENTA
6 BROWN
7 LIGHT GRAY
8 DARK GRAY
9 BRIGHT BLUE
10 BRIGHT GREEN
11 BRIGHT CYAN
12 BRIGHT RED
13 BRIGHT MAGENTA
14 YELLOW
15 WHITE
162
-------
APPENDIX B.9 DISTRIBUTION DISK CONTENTS
The distribution diskettes for ANNIE-IDE are organized into four
groups. These are: utilities, MESSIE, DBAPE and QUAL2E, and
documentation. Each diskette, and any directory on it, contains
a READ.ME file describing each file in more detail.
The utilities diskette contains all of the source code for ANNIE-
IDE. It also contains an object library of routines (ANNIEIDE.LIB)
which was compiled using Ryan-McFarland Fortran. This library
allows PC application programmers to skip the step of compiling
the utility routines. The utility diskette also contains a number
of directories which contain system-specific code. When setting
up ANNIE-IDE on a machine, follow the appropriate directory paths
to use the correct system-specific code groups.
The MESSIE diskette contains the source code for MESSIE and the
executable version of the program. This diskette also contains the
general screen definition file (MESSAGE.SEQ) required for all
ANNIE-IDE applications and a template screen definition file
(SDEF.TEM).
The DBAPE and QUAL2E diskettes contain the source code for the two
applications as well as the executables for a PC. Each application
has its own screen definition file. The DBAPE diskettes also
contain databases which are used by the program. Three of the
databases (SOIML.DAT,SOIXX.DAT,GEOML.DAT) are provided in both
sequential and direct access formats; the direct access files can
be used directly by the program. The remaining databases (*.INF)
are all in sequential format, and they must be converted to direct
access by using the CREATE program (also supplied on these
diskettes) before they can be used by the DBAPE program. The
contents of these databases are described in more detail in the
READ.ME files on the DBAPE diskettes. If DBAPE is to be run on a
machine other than a PC, the sequential versions of all the
databases must be transferred to the machine and then made direct
access by using the CREATE program.
The documentation diskette contains a copy of the ANNIE-IDE manual.
It also contains a complete listing of SYSDOC.OUT as referenced at
the beginning of Appendix B.I.
163
-------
INDEX
$ACCESS 44,67,157
$COLENGTH 41,155
$DEFAULT 41,66,155
$FIELD 42,43,67,69,71,73,156
$FORM 44,67,157
$HEADER 43,47,71,73,156
$HELP 40-44,47,62,63,66,67,73,155-157
$LENGTH 41,66,155
$NAME 44,67,157
$OPTION 41,47,66,155
$OUTPUT 42,43,156
$RECL 44,157
$SCREEN 42,44,47,67,69,156,157
$STATUS 44,67,157
$TEXT 40,47,62-64,155
$TITLE 41,66,155
$WIDTH 41,155
$WINDOW 40-44,62-64,66,69,73,153,155-157
ABORT 35,46,161
ANGLOS 79,87,138
ANINIT 60,87,88,138,145
assistance window 22,24-28,30,32,47,59,83,84,151,154
BEGIN 2,35,46,60,161
CHRCHR 72,78,79,89,99,107,113,119,124,125,139
cluster 37-40,46,47,50,62,64,65,67,68,78,84,91,94-112,
114-123,125,142,150,151
CMND 161
command line 21,22,24,25,28-30,33,35,76,83,84,151
data operation window 29,161
data window 21,22,24-27,29-32,40,41,47,52,62,64,77,
83,84,142,148,149,151,152,153-155,159,161
dataset 37,141,142
DECCHR 72,78,79,90,92,99,130,139
DNPG 27,29,31,161
EXIT 29,30,35,53,59,78,80,127,150,161
FILE 2-5,7-9,11,12,13,15,21,33-40,42-53,55,57,58,60,61,
62,64-69,74,78-80,82-112,114,115-143,145-154,
156-159,162,163
GETTXT 78,79,91,119,139
GOTO 35,161
group 7,15,32-34,37-39,49-51,56,61-73,76,78,84,85,88-137,
164
-------
141,142,150,151,155
HELP 1,9-12,19,20,25,26,28-30,32,34,40,41,42-44,47,62-64,
66-74,77,83,115,116,118,143,147,151-153,155-157,
161
information type 83
initialize 8,48,49,53,60-62,64,72,77,88,127,138,140,141,143
instruct window 28,83
INTCHR 78,90,92,99,130,140
interscreen functions 21,83
intrascreen functions 13,21,83
INTRPT 35,76,78,161
LENSTR 78,79,93,99,107,113,115,116,118,119,140
LIMITS 9-11,25,26,28-30,58,68-70,72,74,77,83,124,141,143,
161
MENU 2,6,8,10-12,18,19,20,24-26,28,30-34,38,41,42,44,47,49,
50,53,54,57,65,66,77,83,84,127,134,135,140-143,
146,151,155,156,157
MESSAGE.SEQ 38,40,45,46,83,163
MESSAGE.WDM 36-39,45-48,52,58,83,85
MESSIE 7,33,37,38,45-47,57,84,155,158,163
MOVE 8,9,14,29,31,32,35,141,142,161
NEXT 1,8-11,20,28-30,32,35,43,45,50,58,62-66,68,70-72,
74-78,141,145,156,161
OOPS 10,11,29,31,68,70,72,74,77,81,161
PMXCNT 52,53,94,95,101,140
PMXCNW 52,53,94,95,127,140
PMXTXA 52,53,96,99,140
PMXTXD 52,53,97,99,102,115,140
PMXTXI 52,53,64,98,99,103,116,140
PMXTXM 52,53,89,90,92,93,96-100,126,127,130,140
PMXTXR 52,53,99,100,104,118,140
PMXTXT 52,53,94,101,105,140
PREV 10,35,70,76-78,161
PRM1 38,42,47,67,69,83,156
PRM2 38,43,47,69,71,73,83,142,156
PRNTXD 52,53,97,102,140
PRNTXI 52,53,98,103,107,140
PRNTXR 52,53,100,104,140
PRNTXT 52,53,62,101,105,107,113,115,116,118,125,140
QFOPEN 57,67,106,107,130,140
QFOPFN 57,89,93,103,105-107,114,125,140
QRESCD 54-56,108,110,130,140
QRESCN 54-56,68,70,72,109,111,120,130,140,147
QRESCR 54-56,108,110,111,113,140
QRESCX 54-56,72,73,109-111,140
QRESCZ 54-56,89,93,105,110,112,132,140,147-149,153,154
QRESP 54,65,107,114,119,130,140,141
QRESPD 54,55,93,97,105,115,121,140,141,147,148,149,152,153
QRESPI 54,55,93,98,105,116,122,140,141,147,148,149,152,153
QRESPM 54,55,117,120,130,140-142
QRESPR 54,55,93,100,105,118,123,140,141,147,148,149,152,153
165
-------
QRESPS 54,89,91,93,114,119,126,130,140,146,152
QRESPX 54,55,109,117,120,141
QRSPUD 54,55,115,121,124,141
QRSPUI 54,55,116,122,124,141
QRSPUR 54,55,118,123,124,141
QSCSET 74,89,121-124,141,148,149,153
QUIET 9-11,29,30,63,68,70,76,77,143,151,161
screen definition file 3,33,37-39,45,46,57,66,69,74,84,
158,163
screen directive 34,60,67,83,84,153
STATUS 7,8,10,25-27,29,30,34-36,44,59,67,70,75-77,80,83,
87-112,114,115,116-127,129-133,135-137,143,151,
153,157,161
STRFND 61,62,99,119,126,141
structure chart 51,52,54-57
system status 8,26,27,29,36,59,75,136,143,161
TERM.DAT 48,58,60,84,85,138,142,158,159,162
TEXT 2,7-9,12,13,21,26,27,30,32-34,36-38,40-45,47,52,53,
54-56,60,62-65,67,75,77-79,83,84,91,94-105,125,
135,136,139-143,146,149,151-158
toolkit 2-4,6-9,12-14,16,20,21,33,36,37,40,48-51,54,59,60,
84-86,138,155
TUTOR 25-27,29,30,161
UPPG 27,29,31,161
VIEW 8,29,31,52,80-82,161
window 9,11,21,22,24-32,40-44,47,52,59,62-64,66,69,72-74,
77,80,83,84,142,143,148,149,151-157,159,161
XPAD 9-11,25-27,29,30,32,48,50,63,65,66,68,70,72,74,76,77,
80,85,128,142,158,161
ZBLDWR 52,53,77,95,99,127,137,142,150-154
ZEMSTP 87,128,142,153
ZGTRET 59,78,129,142
ZIPC 61,90,92,99,106,108,109,114,117,119,130,143
ZIPD 61,131,143
ZIPI 61,74,113,132,143
ZIPR 61,74,133,143
ZMNSST 77,134,143,151
ZPRTMN 135,143,153,154
ZSTADD 59,75,136,137,143,151,153
ZSTCMA 59,76,127,136,137,143,150,151
fcU.S. GOVERNMENT PRINTING OFFICE: 1989 648-163/87104
166
------- |