A Data Analysis and Graphical Plotting Program for

¾
»
A Data Analysis and Graphical Plotting Program
for Scientists and Engineers
GGGGGGG
GG
GG
GG
GG GGGGG
GG
GG
GG
GG
GGGGGGG
EEEEEEE
EE
EE
EEEEE
EE
EE
EEEEEEE
NN
NN
N N
NN
NN N
NN
NN N NN
NN
N NN
NN
N N
NN
NN
PPPPPPPP
PP
PP
PP
PP
PPPPPPPP
PP
PP
PP
LL
LL
LL
LL
LL
LL
LLLLLLLL
OOOOOOO TTTTTTTT
OO
OO
TT
OO
OO
TT
OO
OO
TT
OO
OO
TT
OO
OO
TT
OOOOOOO
TT
Computer Graphic Service, Ltd.
www.genplot.com
9504 Roanoke Dr.
El Paso, Texas 79924
[Copyright 1987-2007 Computer Graphic Service, Ltd.]
All rights reserved
½
¾
¼
»
1.5
0.4
Al75Re21Si4
Al76Mn17Ru4Si3 quasicrystal
Al79Ru21
Al78Cr17Ru5
}
-1
0.2
Pd80Si20
o-Al6Mn
Q
internal friction Q-1 (10-3)
-3
(10 )
0.3
0.1
1.0
0.0
0
1
2
3
4
5
T(K)
0.5
0.0
0
20
40
60
80
100
T(K)
½
c
-Computer Graphic Service, Ltd. °1988-2007
¼
June 5, 2007-
Disclaimer
Although the material contained in the manual has been carefully reviewed, Computer Graphic
Service, CGS, does not warrant it to be free of errors or omissions. CGS reserves the right to make
corrections, updates, revisions or changes to the information contained herein.
The software and accompanying written materials including instructions for use, are provided “as
is” without warranty of any kind. Further, Computer Graphic Service (CGS) does not warrant,
guarantee, or make any representations regarding the use, the fitness for a particular purpose, or the
results of the use, of the software or written materials in terms of correctness, accuracy, reliability,
currentness, or otherwise. The entire risk as to the results and performance of the software is assumed
by you, the user. If the software or written materials are defective you and not Computer Graphic
Service or its dealers, distributors, agents, or employees, assume the entire cost of all necessary
servicing, repair or correction.
Notwithstanding the legalese, CGS will work diligently to resolve any problems and fix all reported
bugs. The quality depends on feedback from users like you.
Trademarks
References are made to the following companies and products within this manual and the online
help:
IBM, IBM PC, PC DOS, DW3 are registered trademarks of the International Business Machine
Corporation.
Hercules is a trademark of Hercules Computer Technology.
MS DOS is a registered trademark of Microsoft Corporation.
WordPerfect is a trademark of WordPerfect.
HP, LaserJet and HP-GL are trademarks of Hewlett-Packard Corp.
Postscript is a trademark of Adobe.
LaserWriter is a trademark of Apple Computer.
Okidata is a trademark of Okidata America Co.
Epson is a registered trademark of Epson America, Inc.
QuadEGA is a trademark of Quadram.
VEGA is a trademark of Video7.
3GPlus is a trademark of AST Research, Inc.
AT&T 6300 is a trademark of AT&T.
Acknowledgements
The cover plot was adapted from a publication figure by Jon Custer in the Materials Science department at Cornell University. The title page includes an example plot by Neil Gershenfeld, from
the Physics department at Cornell University.
-2c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
GENPLOT LICENSE AGREEMENT
This legal document is an agreement between you, the end user, and Computer Graphic Service,
Ltd. (CGS). As end users of software, we understand that license agreements cannot be totally
inflexible. But we also recognize that without incentives and support (financial or otherwise), much
good software would not be available and other software would not be supported. We try to charge
a price that both reflects the value of the product and provides sufficient income to continue the
distribution, support and improvement of this software.
1. License
By purchasing this software you are granted a non-exclusive right to use this copy of GENPLOT
and/or RUMP on a single computer. If you routinely use both a fixed (desktop) computer and a
portable (laptop) computer, you may install the software on both provided that only a single copy
of the program will be run at any time. If the computer on which this software is installed is a
multiuser system, the license covers all users on that system.
2. Ownership
As the licensee, you own only the media on which the software is recorded, but CGS retains title
and ownership of the software and all subsequent copies of the software. This license is not a sale of
the original software.
3. Copy Restrictions
GENPLOT software and any documentation are copyrighted. Unauthorized duplication of the
software (including software that has been modified, merged or included with other software) or
written materials is expressly forbidden. You may make copies for backup purposes only or as
described under “Use Restrictions”.
4. Use Restrictions
You may transfer the software from one computer to another provided that the software is available
for use on only one computer at a time. You may not distribute copies of the software or documentation to any other person for any reason other than as provided under transfer restrictions. You may
not create for sale any derivative works based directly on this software without explicit permission
of CGS (which will normally be freely given).
You are free to incorporate GENPLOT into your own programs or to write subroutines for use from
within GENPLOT as long as all other restrictions are observed. Such user written software remains
your property and may be sold or distributed freely. However, no component of the GENPLOT
software may be included in such distribution without express permission from CGS.
5. Transfer restrictions
GENPLOT is licensed only to you, the licensee. Ownership may be transferred to another person
by giving any and all copies of this software to the other person and erasing any copies which cannot
be physically transferred. In no event may you assign, rent, lease, sell or otherwise dispose of the
software except as provided herein.
6. Update policy
CGS may from time to time create updated versions of this software. At our discretion, we may make
such updates available for either free or for a nominal fee to licensees. Versions of the software may
be made freely available for specific or indeterminate times at our discretion. Such modifications of
the distribution models do not modify these terms for existing licensed copies.
-3c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
DISCLAIMER OF WARRANTY
The software and accompanying written materials including instructions for use, are provided “as
is” without warranty of any kind. Further, CGS does not warrant, guarantee, or make any representations regarding the use, or the results of the use, of the software or written materials in terms
of correctness, accuracy, reliability, currentness, or otherwise. The entire risk as to the results and
performance of the software is assumed by YOU. If the software or written materials are defective,
you and not CGS or its dealers, distributors, agents, or employees, assume the entire cost of all
necessary servicing, repair or correction.
LIMITED WARRANTY
CGS warrants the original licensee that the disk(s) on which the software is recorded is free from
defects in materials and workmanship under normal use and service for a period of ninety (90) days
from the date of delivery as evidenced by a copy of the receipt.
CGS’s entire liability and your exclusive remedy shall be return of the purchase price or replacement
of the disk(s) returned to CGS with a copy of the sales receipt. Any replacement disk will be
warranted for the remainder of the original warranty period or thirty (30) days whichever is longer.
The above are the only warranties of any kind, either expressed or implied. There are no warranties
concerning the fitness of this product for a particular purpose or application.
Neither CGS nor anyone else who has been involved in the creation, production or delivery of
this product shall be liable for any direct, indirect, consequential, or incidental damages, including
damages for loss of business profits, business interruption, loss of business information and the like,
arising from the use of or inability to use this product even if CGS has been advised of the possibility
of such damages.
-4c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
INTRODUCTION TO VERSION 2.1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Introduction to Version 2.1
HISTORY
It took 5 years to make the first revision to the manual, and it now seems to have taken another 10
years to start the second major revision. Indeed, the manual is seriously out of date in almost every
command. Part of the delay reflects the challenges of a wife and family for a single programmer.
Fortunately, GENPLOT development has not been at all static over that time.
Over this past decade, Windows has finally become a serious operating system, mostly by the power
of Moore’s Law, but also finally by a recognition at Microsoft that software should be robust (too
bad the Office group can’t learn the same lesson). As a serious surprise to some, the move to the
Macintosh may not be so far off in the future. The cutesy stuff still turns me off, but the Unix
underpinning has some serious advantages. Linux has similarly many draws, but the lack of good
applications limits it to the server environment (in my opinion – please don’t spam me to death over
that comment).
While Windows is acceptable as an OS, I continue to find the mouse a serious impediment to work.
Those who know how to type can get far more done than someone wiggling around the screen with
a click here and a click there. Indeed, the power of typing, and especially macros, has been proven
again and again. It is most heartening to see colleagues adopt GENPLOT after finding how easily a
week of Excel based analysis work can be dispatched in a matter of minutes with a simple macro file.
While many other programs have become commercial successes and now make “reasonable” graphs,
I believe GENPLOT remains one of the most powerful for those willing to learn the commands. Its
learning curve remains extremely stiff and steep, but the payback is enormous for those willing to
put in the effort. However, the absence of an up to date manual makes it difficult even for power
users – I have the advantage of going to the code to remember what exists and how it works while
others just get frustrated. This is perhaps the strongest motivator for working on an updated manual
again.
From a data perspective, the greatest change in the last decade has been the growth of the amount
of data collected and a decrease in the amount analyzed (on an absolute basis, not just fractional
basis). Students and scientists are overwhelmed with data, be it in image form or as instrument
monitored traces with thousands to millions of points. But most remain in the Excel mindset where
only an occasional set is analyzed for trends and then summarized as a pie or bar graph (and no,
you can’t do a pie graph easily in GENPLOT even today). Even at a prestigious university like
Cornell, only a tiny fraction of the students would even consider writing their own code to extract
serious detail from data (including Matlab and GENPLOT as programming languages). Perhaps
this manual will encourage a few to explore their data more fully.
Development has been driven by my own research and consulting activities, and by a number of
seriously power-hungry users. I must acknowledge especially Roger de Reus (now at IMEC) and
Patrick Smith for seriously pushing the limits. Pat Smith is/was notorious for finding every hardcoded limitation in the package. If a command line were limited to 1024 characters (15 normally
typed lines), he would come up with the need for 1200 characters. Somewhere in the past five years,
I learned my lesson and the code now abhors all limits. For example, data sets and lines can grow
without bounds (usually system limited). Similarly, their complex macros have used commands and
features in ways I had never envisioned, at times showing the brilliant foresight of a well written
subroutine, and at other times exposing the programmer for the hack he really is.
1-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Introduction to Version 2.1
History
Finally, let me comment on what seems to be an unfortunately shift in the very nature of manuals and
online help. In the old days, every application came with a thick manual explaining each command
and usually including some theory and complex examples. Today, manuals either don’t exist or are
included as a PDF on the install CD. They certainly are not worth wasting the paper to print (even
after getting past the 30 pages of legal disclosures and warnings that power cords contain chemicals
known to the State of California to cause cancer). Perhaps it is the click-and-learn mentality, or the
fact that off-shore employees write manuals, or just the lack of time by programmers. But manuals
today seldom give any more detail than the dialog box itself. As an example, I tried to help a novice
set the BIOS options for the suspend mode. The pull down entry on the dialog box itself contained
“S1 (POS) only”, “Auto” and “S3 only”. Checking the manual, this was explained as: “To choose
S1 (POS) only, click the first radio button. For Auto, click the second, and for S3 only, click the
third.” Anyone have any idea what S1 (POS) means? Why should you choose one of the other?
GENPLOT’s manual will hopefully never be as bad, but details take considerable time to write and
will always fall out of date. So I’ll make the effort this summer and see if the next version takes
another 15 years!
HISTORY - INTRODUCTION TO VERSION 2
It has been nearly 5 years since the last major modification to this manual, during which time
development on GENPLOT has certainly not ceased. Version 2.0 has been in “beta” test for nearly
the same period of time serving a number of research groups very efficiently. As I’ve told many users,
development will never be finished as long as I remain active in research because I will always need
the program to do something new – indeed the major driving force behind continued development
have been my own requirements. Most of the beta users are well aware that the fastest way to get
a new feature enabled is to either (1) get me involved in their problem or (2) challenge my abilities
as a programmer.
So why, after 5 years, should I undertake now to finally edit an update the manual for version 2.0.
Well, it is in fact for the very same reasons that the first manual was written. First, I find that I can
no longer myself remember all of the features and commands and I find myself going back to the code
itself too many times to ascertain exactly how a particular feature or command worked. Second,
I’m beginning to answer the same questions over and over from other users; do it once right and the
number of questions drop rapidly. And finally, there are enough new features in the program that
a large number of users do not know about – and cannot know about unless I document them. So
with these thoughts in mind, I finally made the effort to again tackle the daunting effort of revising
and updating the manual.
The beginnings of GENPLOT in its current form can be traced to at least 1982 in the days of
the PC-AT when 640 kB of RAM memory was as much as anyone could possibly imagine using,
much less affording, hard disks were still measured in 10’s of MB, and processor speeds had not yet
exceeded even the 10 MHz speed limits. But it was an exciting time from the scientific computing
world – finally a chance to have a computer for working with data in the lab with relatively high
speed graphics and ones own control of the machine.
Much has changed since those days. Processors now approach 300 MHz clock speeds with pipelined
architectures and embedded coprocessors, RAM memory of 16 MB is the minimum with 1 GB not
unheard of in scientific circles, and any hard disk not measured in gigabytes is no disk at all. These
hardware changes have brought about paradigm shifts striking at the very core of our interaction with
computers. The raw computational power of today’s desktop machines makes the GUI (graphical
user interface) responsive enough even for those of us with absolutely no patience. No longer is the
computer the reserved privilege of the computer geeks. Even a computer phobe and neophytes can
sit down today to a GUI word processor and very effectively compose letters, draw figures, even
1-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Introduction to Version 2.1
History
make movies. For the creative arts, the age of the GUI has allowed artists to be artists, just on
computers.
Reading the old manual, I note with humor my comments concerning the Macintosh. In some
sense, I regret my comments because I have always admired the vision of Apple especially in user
aesthetics such as their interface and the uniformity of applications. But for serious scientific work,
the computation power simply did not exist to support the complexity of the GUI and handle our
needs. Today, with the computation power now here, the Mac faces a serious challenges from the
markedly inferior imitation of Microsoft Windows (be it 3.1 or 95,96,. . . ). (Unfortunately, the Mac
still harbors its own grudges toward me and is sure to hang at my briefest of attempts at serious
use.)
However, while the paradigm for computer interfaces has markedly changed over the past decade, the
task facing scientists and engineers has not (though some may argue the current emphasis on relevent
research is as much a revolutionary paradigm shift as the command line interface to a GUI). We
are still faced primarily with trying to discern nature around us – trying to identify trends in data,
extracting features from data, fitting data to models, critically testing models, building intuition on
behavior of mathematical functions, and only then generating pretty pictures for inclusion in papers.
Unfortunately, the advent of the GUI has, in many cases, actively reduced the quality of the work we
do. Watching students in my own university, I see them spend enormous amounts of time generating
viewgraphs to show data that was collected in less than 10 minutes. At the next scientific meeting,
note the inverse correlation between the actual scientific content of a talk and the quality of the
viewgraphs. Why? Because it looks really neat to have a blue background with yellow bulleted
letters and a 3D border. Manuscripts are the same way – I’ve gone so far now as to give extra credit
for simple typed reports.
So what does this tirade about the failing qualities of modern students have to do with the revisions
to GENPLOT? Well, nothing with the changes, but much to do with what remains the same.
GENPLOT began as a simple command line driven program, albeit very flexible, and it will probably
end its life in the same way (possibly in proof that I am wrong). As a scientist, I am still very much
a linear thinker – consider one model and if it fails, try another. Change parameters to see how they
change, smooth the data and look again, compare the data to a previous experiment. Understanding
and fore-knowledge of what is being done is a critical requirement to quality research.
The GUI in modern programs has also eliminated power and flexibility for the ease of learning.
This is not always such a great tradeoff – and putting back in the complexity bloats programs in a
way that only Microsoft can love (aka Word 6.0). The GUI learning curve is rapid, but levels out
quickly with no further productivity enhancements in time. A powerful command driven program,
like UNIX, on the other hand has a long learning curve but the curve never saturates – as one gains
experience with the commands the productivity continues to increase seemingly without end. It is
toward this latter model that GENPLOT continues to evolve.
There are other problems I have with GUI based programs that try to dumb down the effort of data
analysis. There is an advertisement in my “competition” folder for a commercial program that touts
its ability to fit your data to 1200 different functional forms, returning a list of those that match
most closely. What absolute crap – the old paradigm that if you give me enough parameters I can
fit an elephant immediately comes to mind. If you don’t have any idea what form the data should
take, stop and do a little thinking first. Similarly almost every graphing will do a linear fit and
return that horrid correlation coefficient that less than 5% of the scientific population can properly
interpret. Computers have brought us fortunately and unfortunately to the point that data can be
too easily analyzed – and many critical steps in the scientific process have been lost. Much more
careful thought must have been required in the past when comparing a model to experimental data
1-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Introduction to Version 2.1
History
meant several hours of painful calculations with a slide rule (no I never did it and no I don’t really
wish to return to such days).
I believe GENPLOT 2.0 remains the premiere program for testing and critically evaluating models
against data. The expression evaluator has been extensively upgraded and is now almost unlimited
in the complexity which can be handled, including complex number expressions. The non-linear
least squares fitting has similarly been extended to handle arbitrary expressions and can even call
external programs to run complex simulations. Limitations posed by the old DOS architecture have
disappeared and curves with millions of points can be routinely handled. But it remains impossible
to mold intuitive investigations and scientific examination of data into point and click sets of dialog
boxes – I cannot possibly forsee all the twists and convolutions that will be necessary for you to
perform to analyze your data. And so GENPLOT remains a command driven environment at version
2.0, flying in the face of modern wisdom.
But there is value in the GUI – if not for more than helping remind one of the proper command
syntax. The FFT command has so many options and parameters that there is no feasible way to
remember them. A simple dialog box however puts all them in place (albeit very busy and considered
anathema to modern GUI design – design rules that specify no more than 3 or 4 topics per dialog
box and require one to dig down 4 or 5 levels to get to the single parameter that is to be changed)
and when executed, gives the command line version for future reference. Or the dialog box to set all
the strange parameters of the axis control. The GUI can complement the command line interface,
but it can never replace it.
But what about the graphics. Well, here I have to admit that there is great value in the GUI
and I’ve tried to begin incorporating more control based on the GUI. The absence of a unified
graphical environment (covering UNIX, OS/2, Mac, and perhaps even Windoze) has slowed me
considerably since the effort is large and the payback only marginal (in terms of the science that can
be done). Users of OS/2 will notice much better integration than UNIX, but both will see substantial
improvements in the presentation of graphics on postscript printers. But certainly GENPLOT
remains behind, in ease of use, programs which emphasis the presentation of data over the analysis.
However, though not as easy to use, I still claim that the final graphics produced by GENPLOT are
equivalent or superior to almost every other drawing application.
The change from version 1.0 to 2.0 required considerable work since the entire package had to be
ported from a FORTRAN 77 and assembly language base to a pure C base. In the days of DOS,
memory and speed were critical issues and the Ryan-McFarland FORTRAN compiler was the only
high level, robust, compiler that existed (originally sold also as the IBM Professional Fortran). Slow
operations were translated to assembly language both for speed and for code size. The 640 kB
barrier was rigid and self managed dynamic linking had to be developed. Indeed, the complexity
of the code and the dearth of tools to support development amazes me still today. Once memory
dropped in price, EMS, XMS and similar contortions began being used to shoe horn the new power
in hardware into an already obsolete DOS.
IBM and Microsoft released the OS/2, the first PC based operating system to maintain some compatibility with DOS applications (necessary in the lab) but bypassing the 640 kB memory barrier
and running in true preemptive, protected, multitasking mode. We jumped to OS/2 at version 1.2,
recognizing that for scientific work the 640 kB barrier would remain a nightmare, and have never
looked back again (though the students sometimes would like to!). FORTRAN compilers did not
exist for OS/2 and the mix of assembly and FORTRAN was becoming a challenge to support as the
complexity grew. C was a more suitable language anyway and the ANSI standard made it feasible
to write one version that ran on a variety of hardware. Every line of code had to be translated and
converted – and not by automatic programs but manually to take advantage of the features of the
language.
1-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Introduction to Version 2.1
History
A few commands never made it across the translation – they were so seldom used that it was not
worth the effort. Similarly, with the new OS there was no need to write device drivers for every
device since the operating system provided much of the interface. Unfortunately, UNIX did not
provide the same services in the area of device drivers, but X-windows and the common Postscript
printers made their absence less noticable.
The bottom line is that GENPLOT is now almost 100% ANSI standard C with very few extensions.
Porting from OS/2 to most flavors of UNIX can be handled in a day given a compliant compiler.
If the POSIX subsystem of Windows NT weren’t such a joke, even Windows NT would be a viable
platform. Extensions can be easily written in C for new functions, for control of instruments, or for
stand alone applications.
Someone always asks me how big GENPLOT is now. The honest answer is that I do not know. In
UNIX or OS/2, only the necessary components of the code are loaded into memory at any time and
so size is nearly irrelevent. However, the bloat that marks Microsoft is certainly not present. The
actual executable code is on the order of one megabyte and the entire package compressed can still
fits on only two diskettes. The kitchen sink is not included and I don’t think 35 MB of additional
fonts and pictures would do much to enhance the usefulness (though some more example macros
will probably make it in the final distributions).
Finally, I looked to see how the average user of GENPLOT has changed over the past half decade; the
answer I find is little. Perhaps even more than before, I think the users of GENPLOT self-selected
individuals unafraid of the computer and keyboard, confident in their ability to understand written
manuals, sticklers for small details, and demanding in their expectations of the computer. Like me,
when someone says that computer cannot do this or that, my response is bull – it’s only that no
one has yet programmed the computer for that task. For serious GENPLOT users, the computer
is a slave and they demand that it perform for them as they desire, not as some short sighted and
idiotic programmer thought it should perform. Flexibility is the key to all things.
This preface would not be complete without recognizing, acknowledging, and thanking those users
who have tested the program over these past years, challenged me to incorporate new features, and
made so many suggestions that it challenges my talents to incorporate them all. I would especially
like to thank Roger de Reus, David Brunco, Anthony Dai, Sjoord Rooda, Larry Doolittle, Jon Custer,
Pat Smith, William Boyer and Mike Uttormark. Larry Doolittle and Mike Uttormark also assisted
in various pieces of the code, with Larry in particular heavily involved in the early conversion of the
RUMP portion of the program to C. And through it all, this effort would have been unsuccessful
without my business partner Patricia Ober, and my former partners Mike and Nancy Heisler. And
certainly, nothing is possible without the support and encouragement of my wife Lisa and son Ian!
I also recognize the support of the users who have bought GENPLOT and RUMP. Although I
can’t/won’t give up the day job, so to speak, GENPLOT provides enough income to keep me
supplied with a reasonably powerful computer at home and so supports my programming habit.
This eliminates the trickly questions concerning conflict of interest since development of GENPLOT
can be nearly independent of the day job, although both GENPLOT and my research certainly
benefit from each other significantly.
And so, with humble apologies for all those I’ve insulted, let’s get on with the real problem at hand.
How do you tame the beast called GENPLOT?
1-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
GETTING STARTED WITH GENPLOT
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
GENERAL REQUIREMENTS
THE USER
GENPLOT is an extremely powerful and flexible plotting package for the analysis of scientific and
engineering data. However, this flexibility comes at the cost of complexity, and the program is
optimized for power instead of for the novice computer user. The current expectation in software,
fostered by by Macintoy and now by Windoze applications, is that one should be able to sit down
at a new program without reading any manual and be immediately productive. This is not the
model for GENPLOT. If the simple DOS or UNIX prompt bring chills and tingles to your spine,
this program is probably not for you. However, even as a novice, you can very successfully utilize
the program if you are willing to invest the time to read substantial parts of the manual, and if
you can avoid being intimidated by the large set of commands and relatively long learning curve.
Eventually, some subset of the commands will become like a second language and the true power
and flexibility of this program will be made manifest.
For installation and efficient use of this program, you must have certain minimal skills with the
computer, the DOS, Windows, OS/2 or UNIX operating system, and simple programming concepts. Familiarity with command prompt usage is definitely a plus, as many of those commands are
replicated within GENPLOT (i.e. dir, cd, pushd).
Most of the install program or scripts are automated and will install with common defaults. In
general, the minimum for all users is:
•
Powering on the computer and booting from the hard disk.
•
Understanding the difference between RAM and hard disk memory.
•
Moving around the directory structure, searching and listing files using wildcards
specifications.
•
Ability to create, edit and save ASCII text files. The particular editor does not
matter as long as it does not embed formatting information and usually maintains
spaces, tabs, and long lines. NOTEPAD works well for simple activities, while a
programming editor such as EMACS is ideal.
•
Ability to navigate within the Program Files directory for Windows users.
•
General familiarity with building programs from the source code of UNIX/Linux
users.
GENPLOT is available for Windows, OS/2 and UNIX (primarily Linux) environements. The base
code is written relatively strict ANSI C, with a common core among all versions. Minimal differences
between the versions are related primarily to the underlying operating system (case sensitivity in
file names, for example). The only substantial differences are in handling graphics to the screen (the
GUI in Windows versus X-Windows for Linux). The UNIX code is entirely command line driven
while the Windows and OS/2 have some minimal GUI support.
The Windows version of GENPLOT is variously 0.9, 1.0 or 2.0. While all other programs make
revisions numbers every year, we choose to just continuously update the program and make those
changes available as soon as possible (sometimes weekly).
1-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
INSTALLATION AND QUICK START
Installation instructions are included for Windows (including Windows 95/98, NT, 2000, XP and
Vista), and UNIX (generic with Linux specific). It is necessary to consult only the section relating
to your specific operating system.
If you are installing for either DOS or OS/2, contact supportgenplot.com for the old instructions.
There just aren’t enough users left to justify the waste of paper (or electrons).
WINDOWS
Windows installation (all versions) uses the standard InstallShield application and will behave similar
to everything else you’ve installed. So there isn’t much need for detail.
Important: If you already have GENPLOT installed, it will be necessary to unistall it before
loading a new version. This is a new “feature” of InstallShield. From the control panel, open “Add
or Remove Program”, locate ‘‘GENPLOT’’ or ‘‘RUMP and GENPLOT’’ and then “Remove”. This
will not delete your current serial number or any user files you have added to the CGS directory.
Installation sequence:
•
For versions downloaded from the WEB or distributed by e-mail, locate the installation file and execute (or double click). The default names are either genplot setup.exe or rump setup.exe.
•
From the CD-ROM, load the CD and double click the setup.exe.
•
Unless you are really brave, accept the default location c:/program files/cgs and
the default folder creation. I think it works to be relocated, but this has never been
extensively verified.
•
Enter your name, company and serial number (Micky Mouse and Disneyland are fine
if so desired). If you do not know/have a serial number (or if you are just installing
an update), enter BETA-02-0000-abcd. For updates, GENPLOT will automatically
recognize the previous serial number. You can update it manually in XGENPLOT
from the HELP menu.
•
The “Typical” installation includes everything except programming support. Choose
“Custom” to add these few files. The fully configured size of GENPLOT is only 5.3
MB, so I don’t suggest worrying about the “Minimal” possibility.
To test, navigate to the CGS folder in the Start Menu and select XGENPLOT. Type the command
create y = x -range -10 10 plot. This will bring up a graphics window with a simple plot.
Type quit to exit.
GENPLOT is an asynchronous multithreaded application. Windows does not provide a mechanism
for killing threads with extreme prejudice, so closing the window using the standard “X” button is
not always effective. If possible, alway exit by typing quit in the command area. The task manager
(process tab) can be used to kill rogue threads after an inadvertant “X” closure (look for XGENPLOT
processes).
1-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Installation and Quick Start
Similarly, the graph window is a separate application communicating with XGENPLOT through a
pipe. This allows the graph window to crash without taking down all the existing work in XGENPLOT. If the graph window is inadvertantly close (by the “X” for example) or crashes, just execute
the command dev pm to create a new one. The pm refers to “Presentation Manager”, a throwback
to the OS/2 origins of Windows.
UNIX
In addition to the general requirements of a competent computer user, for the UNIX installation
and operation you should also
•
Understand the organization of your system source directories.
•
Have a moderate understanding of simple makefiles and the ability to customize
parameters within a makefile to conform to your system layout.
•
Understand the operation of the ANSI C compliant compiler on your system, and
the location of the command line option switchs. Knowledge of C may be helpful
when solving problems and determining correct options for the compiler.
System requirements
For UNIX, the system requirements cannot be clearly defined since every implementation of UNIX
and every particular installation seem to be totally different. Consequently, GENPLOT must be
distributed in source rather than an executable and must be built under UNIX on the target system.
We have been generally successful in installing to many flavors of UNIX, but due to the slight variations in C compilers and UNIX implementations, nothing is ever certain nor can it be guarenteed. It
may be necessary for the system administrator to make minor code revisions or adjust the compiler
options for local conditions.
In general, the requirements on the UNIX environment include:
•
System utilities such as make, install, tar and other similar generic commands.
•
An ANSI and POSIX 1003.1 compliant C compiler with extensions for (1) popen()
and pclose() pipe calls, and (2) the system spawn() family of calls. These are generally included as part of the compatibility or extended services of the C compiler.
•
X11R5 libraries and X-window server/client software. This is not necessary if you
do not intend to use the X-window graph screen (but then I’m not sure how you
plan to view the graphs).
•
File system support for long filenames. The constraining 8.3 format from DOS is
not adequate and thus GENPLOT cannot be installed to a FAT partition on a Linux
system. The file system must tolerate multiple extensions and filenames of up to 32
characters. I prefer case retention without case sensitivity, but case sensitive will
work also.
•
Approximately 5 MB of free space on the system partition.
•
A postscript, HP-PCL printer, or HP-GL plotter. Given the vagaries of the UNIX
spooler, postscript is highly recommended.
Installation sequence
GENPLOT is distributed as a gzip compressed tar file, usually cgs32j.tar.gz, the j being some
version that has since lost its meaning. This must be expanded into the source tree cgs with a
command like gzip -dc cgs32j.tar.gz | tar -xvf -.
1-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Installation and Quick Start
Under the cgs tree, the root level contains makefiles generically written for several flavors of UNIX.
Not all have been tested (especially recently) and the code may require minor changes to work with
any specific system.
Makefiles exist as pairs, such makelnk and makelnx.h for Linux. Edit the appropriate makexxx.h
file. Approximately 20 lines down are the normally modified configuration parameters specifying
the location of the source code and the desired location of the executables. Documentation on the
differences between install and configuration directories is provided in the makefiles.
Run the make command, logging all errors, typically by make -f makelnx. Note all errors and modify the source code as necessary. The development is primarily in Windows, and incompatabilities
arise often from programmer incompetence.
Install the software. This is highly system dependent and the standard makefile install switch
will probably not work. But it is a start. Check particularly the macros for INSTALLLIB and INSTALLEXE. Normally, the installs are run either as make -f makelnx install or make -f makelnx
rump install.
Locate and edit the installed version of ”devices.dat” to define local printers. The structure of this
file is moderately self-explanatory. Appendix D in the manual has details – although the specific
drivers may differ.
You may want to modify genplot.ini (and/or rump.ini) in the system install directories. These are
globally executed macros for all users.
Test. Run GENPLOT from a command line and type the command dev x create y = sin(x)
-range -10 10 plot. This should create a simple plot in the X-window graph screen.
The readme.unx file contains additional details about the makefiles to help resolve configuration
difficulties.
1-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
GENPLOT: THE PROGRAM
A BIT OF HISTORY
GENPLOT is a generic plotting package that is particularly useful for presenting and analyzing
scientific research data. The program itself is written in FORTRAN 77 (F77) as a callable subroutine
and is therefore available for incorporation into other user-written F77 programs. As such it provides
powerful, user friendly graphics capabilities with minimal programming effort. In addition, using a
very simple shell (Appendix S) GENPLOT can be configured as a standalone program. This is how
you have received it. In this form, a user may make X-Y graphs (no pie charts allowed - this is for
scientists, not managers), plot data and simulation curves, transform the data in various ways, and
later spruce up the plots for publication.
GENPLOT has been written over a number of years at Cornell University with input from numerous
people, including Larry Doolittle, Rick Cochran and Mike Heisler. Mike Thompson must, however
unfortunately, take responsibility for its current gross and unmanageable size. Users over the years
have alternately blessed GENPLOT’s capabilities and vehemently cursed its author for the lack of
written documentation. Now, hopefully, this manual will introduce a new user to some of its power,
while providing the power user with a complete list of the commands and their syntax.
One final warning about the author. I am often accused of having absolutely zero patience with
computers – the answer must be available immediately with minimal fuss but maximal flexibility.
These requirements are mutually exclusive with an overly “friendly” user interface à la Macintosh.
Although the program works well for Macintosh users, the program is primarily designed for a power
user who types well and thinks at least three or four commands ahead of the screen. Pull down and
full screen menus are too slow and hence most of the user interaction is through that old fashioned,
non high tech, computer keyboard. Learn to enjoy typing things like abbrev max pow of progs
and min typ (abbreviations maximize the power of programs and minimize typing).
The author is also one of the primary users of the program. It is often said that GENPLOT does
everything I need, and almost everything anyone else has asked it to do. Unlike Microsoft Word,
bad behavior is never tolerated – key bugs are fixed immediately and annoying bugs are fixed as
they can be localized.
THE MANUAL
The manual consists of several sections including an introduction, some short examples, a few
tutorials and a long section on the command descriptions. The tutorials introduce the first time
user to the plotting and analysis capabilities. The command section is ordered by function, hopefully
in the relative order of usefulness. There is a summary section and an index to help you find things.
Online help is growing, but limited. Commands increasingly are self-documented with a -? option,
either listing to the screen or opening up a side window. This will become the default for at least
command syntax. First time (and older) readers are warned that there are some subtleties to the
command parsing language in GENPLOT, and all users should attempt to muddle through the
discussion in Section J and Appendix T at some point. For those delving deeply into GENPLOT,
Appendix T attempts to instill an understanding of the token concept and how GENPLOT splits
up command lines, an understanding which is of immense value in making GENPLOT work the way
1-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
GENPLOT: The program
you want within the syntax which is built into the program. Section J likewise explains the function
and expression evaluators within the command processors.
INVOKING THE PROGRAM
For UNIX and DOS users, GENPLOT is invoked by typing GENPLOT (assuming GENPLOT.EXE is
located somewhere within the scope of your command path). In Windows, navigate to the CGS
folder and click on either XGENPLOT or GENPLOT. In most cases, you will want to use XGENPLOT
which provides a better “window” for viewing the commands and the limited GUI pull down menus.
GENPLOT runs in a normal command prompt window, primarily as a backup if some bug in the
windowing code creates problems.
GENPLOT wakes up to the user with a blank data set of X,Y points. Associated with this X,Y
data set are two variables called NPT and NPTMAX. NPT specifies the number of points which are
currently valid in the X,Y set while NPTMAX gives the dimensioned size of the X,Y arrays (or the
maximum NPT can ever be). This X,Y curve is referred to as the DEFAULT curve and is used by
most of the GENPLOT commands unless you specify otherwise. Other curves may also be defined,
as discussed later. By definition, a CURVE refers to a collection of real X,Y points (or X,Y,Z in 3D
mode) and an integer representing the number of points, NPT.
The full format of the GENPLOT initialization from a command line is:
GENPLOT [-Buffer <bufsize>][-INi <initialization file>][-Help][-3D]
The initial buffer size may be modified from the default 2048 points using the buffer command
line option. While this sets the initial size, the size is dynamically increased as necessary to some
configuration maximum (currently 67 million points). Likewise, an initialization file may be specified
using the ini option; if no file is specified, the program assumes GENPLOT.INI. The -HELP option
lists out the format of the GENPLOT command and returns to DOS immediately.
Once GENPLOT is running, commands are typed at the GENPLOT: prompt in a pseudo English
format. Commands and arguments are taken from the typed command line sequentially. The
command processor (see Appendix T) allows multiple commands and arguments to be given on a
single command line. There is little difference to GENPLOT if commands are given entirely on a
single line or broken into multiple lines; GENPLOT will prompt in each case for the information
necessary to continue. For the first time user, it is probably better to let GENPLOT prompt each
time for the information until one learns the order of parameters for each command. Like many
computer programs, the format of the commands is somewhat strict and arguments are usually
required in a specific order. The order of these arguments is considered “natural” by the author, but
if in doubt the command reference and online help provide the specific format for each command.
Some commands also accept optional arguments or modifiers which may be given in any order
following all required arguments.
GENPLOT AS A SUBROUTINE
GENPLOT can also be called as a subroutine from within your own applications (C based, or at least
able to call C routines). This capability allows you to generate data from within your own program
and use the GENPLOT interface for the graphics. Alternatively, GENPLOT has the ability to call
user subroutines which may manipulate the data in ways we never imagined necessary.
These
capabilities are detailed in Appendix S.
1-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
ESSENTIAL INFORMATION
GENPLOT INITIALIZATION SEQUENCE AND OPTIONS
Syntax: GENPLOT [-Buffer <bufsize>] [-INi <initialization file>] [-Help] [-3D]
This is the primary user command to initialize GENPLOT. Options to this command allow the user
to modify the maximum number of points GENPLOT will handle or to specify an initialization file
to be executed upon entering GENPLOT. GENPLOT is always initialized with a blank data buffer
which can contain a maximum of <bufsize> points. If unspecified, <bufsize> defaults to 2048.
The maximum allowed <bufsize> is 16380. Buffer space for the default curve is allocated during
initialization and requires 8 bytes of memory per point.
Immediately following initialization, GENPLOT searches for an initialization macro file which is executed before responding to user commands. The default initialization file is GENPLOT.INI, although
any file may be specified using the -INI switch. (WARNING: No error message is issued if the file
does not exist.)
The option -HELP simply prints a brief statement of the command syntax for GENPLOT and returns
to the DOS prompt.
You must exit from GENPLOT using the QUIT command. The RETURN command is only available for
subroutine calls to GENPLOT. Under this command shell version of GENPLOT, RETURN generates
an obnoxious error message and returns immediately back into GENPLOT.
KEYBOARD EDITING
GENPLOT includes a fairly powerful keyboard editor for correcting typing errors and recalling
previous commands. The editor makes use of both the arrow keys and EMACS like control sequences
to edit the current command line. The <↑>, F3 and <↓> keys recall previous command lines. The
remaining keys edit the displayed line. The editor defaults to overwrite mode at the beginning of
each keyboard request.
Control Key
∧B
∧F
∧A
∧E
∧L
∧N
∧P
∧H
∧D
∧K
∧U
∧I
Action
Cursor keys
Move cursor BACK one character
Move cursor forward one character
Move cursor to beginning of the line
Move cursor to END of the line
Repaint current line
Copy NEXT command line into buffer
Copy PREVIOUS command line into buffer
Erase previous character
DELETE a single character
KILL (erase) to end of the line
Erase entire buffer
Toggle between insert and overwrite mode
Tab (converted to space)
1-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
<←>
<→>
<HOME>
<END>
<↓>
<↑> <F3>
<BACKSPACE>
<DELETE>
<INS>
<TAB>
Getting Started with GENPLOT
Essential Information
Control Key
∧]
∧J
∧T
∧G
∧C
∧Z
Action
Cursor keys
Toggle between default insert and overwrite mode
Line feed (converted to RETURN)
TWIDDLE (exchange) two previous characters
ESCAPE from level (abort current command)
ABORT (executes normal ∧C processing)
End of File marker
<ESC>
In several modes of GENPLOT, the <ESC> key will escape out of a current command and return to
the next higher command level. For example, <ESC> pressed at a request for text within ANNOTATE
will return immediately to ANNOTATE.
BREAK OR CONTROL–C
Many commands within GENPLOT may be prematurely aborted using a single Control–C or Break
key. For example, the plotting of symbols (but not lines) may be aborted at any time by typing
a break. However, if a second break (or Control–C) is typed before GENPLOT responds to the
first, GENPLOT will exit back to DOS (the whole purpose of break). Moral of the story – don’t go
flipping out on the break key.
UPPER/LOWER CASE AND EXPRESSIONS
User command input lines are passed through a standard command parser before being interpreted
by GENPLOT. This command parser separates the input into a series of tokens. Each token is
then normally uppercased and returned to GENPLOT for interpretation. In several cases (such
as specifying labels), it is necessary to pass strings containing embedded spaces and/or mixed case
words. Strings can be passed unmodified by enclosing the entire string in single quotes. Hence,
labels which require mixed case should always be quoted. The exception to this rule occurs when
GENPLOT already knows that it is expecting a character string and prompts directly for the text
string. In such cases, GENPLOT will disable the parsing and case conversion and take the entire
line as a single entity. For example, consider specifying the bottom label. As a single command
line, this would require LABEL BOTTOM ’X Axis’. If you type only LABEL BOTTOM, GENPLOT will
prompt for the actual label. At the prompt, the label is typed without quotes. Note that because
the entire line is taken as the label, it is impossible to place another command on the same line.
Mathematical expressions are also often written with embedded spaces to improve legibility. The
expression may then either be enclosed in quotes or may be enclosed in open/close parenthesis pair.
Parsing of mathematical expressions will continue through a command line until all parenthesis are
matched. Hence, the following is valid EVALUATE (sin(2*pi/3) + 3*8.3).
Quotes are required when
• In labels that contain spaces and are given on the command line.
• In labels that contain mixed case and are given on the command line.
• In equations or expressions that contain spaces but not surrounding parenthesis. See the Function
Evaluator for details on equations and expressions.
1-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Essential Information
CURVES AND ARRAYS
Multiple data sets may be manipulated within GENPLOT by using the ARCHIVE command. The
ARCHIVE command moves the data from the default curve of GENPLOT to another section of
memory creating several variables. WARNING: ARCHIVE does not permanently store the data.
ARCHIVE actually sets up a variable of type CURVE with a structure consisting of two arrays (X and
Y), an integer (NPT, the number of points in the curve), and a string (the descriptor of the curve).
The elements of the structure of a CURVE named C1 may be accessed with the expressions C1:X,
C1:Y, and C1:NPT. The description of the curve may be accessed as C1. For example
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
eval c1:npt
/* print the number of points
eval c1:x(10)
/* print the 10th element of x
let y = sin(c1:y)
/* change y
annotate label / %c1% /* use the id in a label
¼
The variable C1 refers to the curve and not any of its numeric arguments. C1:X refers to an array
(specifically the X values in curve C1) and C1:NPT refers to an integer (the number of points in C1.
See the Function Evaluator section and the ARCHIVE/RETRIEVE commands for more information and
details. Note that the default curve elements are simply referred to by X, Y, NPT and IDS without
a curve name.
SOME PECULIARITIES
Many GENPLOT commands toggle a plotting mode on or off, such as logarithmic scaling or automatic screen erasing. Some of the commands require either an ON/OFF response while others
require a YES/NO response. The response necessary for any particular command must unfortunately
be memorized or learned.
USING THE CURSOR AND BOX ON PC GRAPHICS SCREENS
The screen cursor is used in numerous commands to either place objects on the screen or select data
points. Once the cursor appears, it will move in response to the arrow keys. Pressing any other
key generally causes the value of the cursor to be returned to GENPLOT. In the CURSOR command,
the <space> or 0 key causes the value to be returned to GENPLOT and GENPLOT will return
immediately with another cursor.
The cursor operates in two speeds, fast and slow. In the normal (fast) mode, each press of an arrow
key moves the cursor by several pixels. Holding the <SHIFT> key down while pressing the arrow keys
will slow the movement of the cursor to individual pixels. The <INS> key toggles between the fast
and slow modes. The first time <INS> is pressed, the unshifted arrow keys will become the single
pixel movements and the shifted arrows will be the fast movements.
The cursor returns to GENPLOT when any unrecognized key is pressed. If you didn’t really want
to use the cursor, <ctrl>-C will normally abort the currently active command.
Commands such as subplot and zoom require a region of the screen to be selected. These commands
utilize a box-type cursor when available. When a box cursor is selected, the arrow keys drag one
corner of the box as marked by a dog–ear. In this mode, the box may be shrunk or enlarged as
necessary. The <SPACE> key toggles the dog–ear to the opposite corner of the box. The box may
be moved rigidly without changing its size by pressing the <DEL> key. While moving rigidly, the
dog–ear will be removed. Pressing <DEL> again toggles back to the original mode.
1-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Essential Information
Cursor Key
<←>
<Home>
<↑>
<PgUp>
<→>
<PgDn>
<↓>
<End>
<SHIFT>
<INS>
<CR>
<SPACE>
<CTRL-C>
<DEL>
<SPACE>
Action
Move one or more pixels left
Move left and up
Move up
Move right and up
Move right
Move right and down
Move down
Move left and down
While held, toggle cursor speed for arrow keys
Toggle the speed of the arrow keys
Enter the coordinates
Enter the coordinates and return for more
Abort from cursor command
Toggle between rigid motion and moving one corner
Switch cursor attachment to diagonally opposite corner
LABELING DETAILS
When specifying any text to be labeled to the screen, the following special character sequences may
be used. These embedded sequences allow the character set to be changed or the drawing of super
and subscripts.
∧0
∧1
∧2
∧{this}
{that}
∧–
\[char]
∼
change to character set 0 (see CHRSET)
change to character set 1
change to character set 2
superscripts the text enclosed in {...}
subscripts the text enclosed in {...}
backspace character (hyphen)
quote character. \∧ draws the ∧ character
newline character for paragraph labeling
Subscripts and superscripts are drawn displaced and at a smaller size than standard characters. The
size and position of the superscripts can be changed by using the SGRAPH command. See Reference
section 4i for more details.
¾
label
label
label
label
½
»
1 1 ’Hi there’
/* Draws ‘‘Hi there’’ at (1,1)
/
Thompson
/* Draws ‘‘THOMPSON’’ at cursor
/ ’Si {3}N {4}-SiO {2}’ /* Draws Si3 N4 − SiO2 at cursor
/ ’Hi∼’ ’there’
/* Draws ‘‘Hi’’ ‘‘there’’ on two lines
¼
HARD COPY
Probably the most frustrating time during data analysis is when you have a completed a plot on
the screen with numerous labels and annotations, and you want a nice hard copy of the entire plot.
Generally there are three solutions. First, you can do a screen dump to your plotter at low resolution
1-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Essential Information
in one color. Second, you can select a hard copy device and retype all the commands necessary to
create the plot. The third alternative is to remember (at the beginning of a session) to use the
HCOPY command. HCOPY is a powerful but often misunderstood command. HCOPY does not make
a hard copy of the screen, but rather it is a background process which, when on, keeps track of
all the plotting commands sent to the device. Under user control, HCOPY can replay these plotting
commands any other device and utilize the full capabilities of the device. Remember, HCOPY is useful
for only the current plot on the screen (it is reset when the screen is erased) and it only remembers
plot commands from when it is turned on. HCOPY is described in full gory detail in section A of the
reference.
The simplest and most common use of HCOPY is to turn it on immediately when entering GENPLOT
using HCOPY ON. The HCOPY file itself can be redirected to a ram disk or hard disk by setting the TMP
environment variable. Once initialized, HCOPY keeps track of all plotting vectors executed between
erase operations. If HCOPY is on, the command HCOPY DEV <gd> will cause all of the vectors to be
redrawn to the device <gd> (such as a pen plotter). HCOPY files may also be saved for later replaying.
However macro files would be better for this purpose.
HCOPY is not intended for production work. If you have many similar plots to do or some analysis
that is done regularly you should use macro files. You might think of a macro file as the source code
of a program. The HCOPY file would be the object file and your final plot the executable program.
You probably don’t rely on just keeping the object code for your programs around. The source code
is modifiable and readable.
HCOPY files are temporary files only a few kilobytes in size. We strongly recommend enabling HCOPY
in your initialization file HCOPY ON as long as you are using an XT or faster machine with a hard
disk.
1-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
WALKING THROUGH: TUTORIALS
FORMAT OF THE EXAMPLES
The commands which the user is expected to type within these examples appear in two forms. This
first one is used when there are only one or two lines of text:
>> typewriter style.
and the second one is used for larger sections of text. In the longer sections, the user typing is shown
underlined.
¾
»
GENPLOT: you type this
GENPLOT:
½
¼
You can enter commands in upper or lower case. Before you try these tutorials you must know
what kind of device you will be plotting on. We will use <gd> when we refer to a graphics device.
You must replace this with the name of the graphics device that you are using. If you know that
it is an EGA, VGA, CGA, Hercules or AT&T 6300 then you can proceed with the tutorials. If
not, please see the installation section of the manual which discusses what devices are supported
and how you might identify them. If you are a knowledgeable user you may set an environment
variable, GTERM, which GENPLOT will use automatically to select your graphics device. See the
installation section for information on this.
In the following pages we have first two quick examples of using GENPLOT and then some more
extensive tutorials showing more commands and some of the mistakes that one can make.
TWO QUICK EXAMPLES
To begin, we’ll show three examples, how to plot a simple data set from a data file, how to create
and plot a function curve, and using SETUP.
Using a data file
Data files are generally a series of x,y ordered pairs; each ordered pair would be on its own separate
line in the file. The x and y coordinates of the ordered pair must be separated by a comma, space or
a tab. This would be considered an ASCII (American Standard Code for Information Interchange)
format file. There is also a BINARY format which will be mentioned later.
To make sure that DOS can find GENPLOT change to the GENPLOT directory.
>> cd c:\genplot
Using your favorite editor, create a file containing X,Y pairs, one per line, with X and Y separated
by spaces or a comma (no specific format is required). Something like the following would be fine.
2-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
1,1
2,2
3,5
4,8.6
5.333 6.555
If you save the file as TEST.DAT, you can use it in the following example. We have supplied a
TEST.DAT file in the tutorial directory, \GENPLOT\TUTORIAL. You can use our file or one of your own
for the this quick example. Start GENPLOT by typing the command GENPLOT and wait for the load
to be completed. By default GENPLOT begins with a 2048 point buffer (NPTMAX) with no points
initialized (NPT=0). The command READ <filename> reads an X,Y data set from the disk. The
following example changes directory to the tutorial directory, and shows 3 synonymous commands
for reading the data:
¾
»
GENPLOT/3D Shell & buffer allocation [MOT 1.00]
GENPLOT [Rev. 1.00 11/01/89]
[copyright 1987-2004 Computer Graphic Service, Ltd., All rights reserved]
GENPLOT: dev <gd>
GENPLOT: cd c:\genplot\tutorial
/* to use our file
GENPLOT: read test.dat
or
GENPLOT: read test.dat -column 1 2
or
GENPLOT: read
File to read (ABORT): test.dat
Current data consists of
X minimum = 1.00000
Y minimum = 1.00000
½
5 points. Max: 2048
, maximum =
5.3330
, maximum =
8.6000
¼
(GENPLOT will read data direclty from the keyboard with READ CON, but we’ll leave it for you to
look in the manual for more about that.) Following the read command, GENPLOT will respond
with the status of the current data set, listing the number of points assigned and the minimum and
maximum values for X and Y. We only need one command to display the data, but we want to
introduce a valuable command now before you get any further along so we will use two commands.
>> hcopy on
>> plot
If you have not already assigned a graphics device (with the DEVICE command or through the
GTERM environment variable), a list of graphics devices will be listed on the screen and you will
be prompted for the name of a device. The IBM standard devices are VGA, EGA, CGA and BW.
(NOTE: This device query is one of the few keyboard reads which does not go through the uniform
command processing — PLOT EGA will NOT work.) If all of the necessary files can be found on the
disk, you should be staring at a plot of your data on the screen, consisting of crosses with a box style
X–Y plot. If you are on a single screen system and the graph is not currently visible,
you must use the F10 key to toggle between the text and graphics views.
2-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
10
Y Axis
8
6
4
2
0
0
1
2
3
4
5
6
X Axis
½
¼
The hcopy on command made no difference in how the plot turned out. What it did was start saving
your plotting commands to disk so that you can reproduce what you have done without retyping
the commands. To replay the current plot to the screen use:
>> hcopy dev /
HCOPY can be turned on or off and replayed to any supported device. Marks can be set in the
hcopy file so that you can backup to specific points. It is explained in detail in Section 4a with
an example at the end. When you quit GENPLOT you will be prompted about the disposal of
the HCOPY disk file, to delete the file is the default reply. It is recommended that you use macros
(Section 4k) to create and save complex plot sequences rather than keep many HCOPY files around.
Macros are smaller and easier to modify. HCOPY files are best used when doing some “sprucing up”
on individual plots.
Creating a data set
Plotting an analytic function is almost as easy as plotting data files. Two steps are required, creating
the data and plotting the data. The CREATE command allows you to generate data from an analytic
function. The format is:
CREATE Y = f(x) [-FROM x1] [-TO x2] [-BY dx | -POINTS npt]
The FROM, TO and POINTS are optional arguments; if not specified the previous values will be used.
The defaults are 0, 1 and 200 respectively. Create a sine wave with
¾
»
GENPLOT: CREATE Y = SIN(X) -FROM -10 -TO 10 -POINTS 200
or
GENPLOT: CREATE Y = SIN(X)
/* rather dull
½
¼
2-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
GENPLOT has built–in functions which are described in the section on the Function Evaluator.
You can make a general equation as you would in a FORTRAN program. Be careful about spaces
however. The command line parser expects blanks to separate items.
The CREATE command generates data in the default curve. Once it is there, it can be plotted by
typing
>> plot
You should now see a plot of sin(x) showing up on your graphics screen. The graph is unfortunately
boring since the axis are labeled X and Y and the data is in the form of points.
If you have thought about trying hcopy dev / go ahead. You will get the sine curve back. The
above plot command caused the screen to be erased and so the HCOPY information from the
previous plot was also erased.
Setup
Now for a little sprucing up. Type the command:
>> setup
Up pops a full screen to fill in the axis labels and various other information to define the way the
plot looks. The cursor keys, tab keys, and certain control keys move you about on the SETUP menu.
Pressing <ESC> returns you to main GENPLOT command level. The <Enter> key moves the
cursor to the next field. From within SETUP, change the labels on the X axis (BOTTOM) to be
Time and the left axis to be Amplitude. You note that there are actually four axes including top,
bottom, left and right. More on those later. Press
>> <ESC>
to return to the command level and issue the command
>> plot
again, and we have labelled axes. The same operation may be done at GENPLOT command level
using the LABEL command. The format is similar but all typing. The same axes would result by
typing LABEL BOTTOM ’Time’ LABEL LEFT ’Amplitude’. If one types only the LABEL command,
GENPLOT will prompt first for which axes the LABEL command is to refer to, and then for the
actual text to be used for the label. Since it is expecting text, it automatically takes all of the text
typed in at the prompt rather than just a single token so quotes are not needed.
2-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
1.0
Amplitude
0.5
0.0
-0.5
-1.0
-10
-5
0
5
10
Time
½
¼
2-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
TUTORIAL 1: PLOTTING
Plotting a data set can be as simple or complex as you want. The minimum commands require you
to select a plotting device (replace <gd> with your device name), read the data set from the disk
and draw the plot.
¾
»
C:> c:\genplot\genplot
GENPLOT: c:
GENPLOT: cd \genplot\tutorial
GENPLOT: hcopy on
GENPLOT: type t1.dat
0.0
,0.0,
0.14,
4.0,
0.28,
8.0,
0.43, 10.0,
0.57, 12.0,
.
.
.
.
4.16, 39.9,
/* start GENPLOT
/* Tutorial directory
/* we may need this
/* let’s see the data
GENPLOT: dev <gd>
/* select the device
GENPLOT: read t1.dat
Current data consists of
18 points. Max: 2048
X minimum = 0.00000E+00, maximum =
4.1603
Y minimum = 0.00000E+00, maximum =
39.900
GENPLOT: plot
½
¼
The first two commands moved us to the tutorial directory of GENPLOT. GENPLOT supports
many of the DOS commands for moving between disks and the tree structured file system. Filenames, however, may be specified as full pathnames as well; read c:\genplot\tutorial\t1.dat
is equivalent to the read above.
Assuming that you installed the tutorial data files, you should have the following plot. Single
screen users may need to press the F10 key to toggle between text and graphics views.
2-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
40
Y Axis
30
20
10
0
0
1
2
3
4
5
X Axis
½
¼
No other information is needed. The data is scaled and plotted. Default values are chosen for many
things such as the axes labels, symbols and line type. The above commands set the device, read a
file and plot the data. It will default to graphing ’+’ symbols for each data point. This is because
the default line type is 0 (points but no line) and the default symbol type is 3 (the + sign is symbol
3). You can change the symbol to circles with the SYMBOL command. The line type can be changed
with the LTYPE command. The remainder of this section will deal with altering these and other
values to get the kind of graph that you want.
The DEV command need only be done once per session unless you want to specifically change output
devices. So we will not mention it again in this section.
Before we move on to labeling axes an explanation is in order. Axes are referred to by their location,
top, bottom, left or right, not by x or y. The reason for this is that you can have more than one
scale for the x–data or the y–data. One scale on the bottom axis for one data set and another scale
on the top axis for another data set. We will get to that later.
If you just entered GENPLOT at this tutorial the axes will be labeled X and Y. If you are continuing
from the quick examples, they will have retained Time and Amplitude labels. In either case let’s
change the bottom axis label by typing
>> label bott ’Time (sec)’
The quotation marks are necessary since the label text is on the same line as the first part of the
command and we want embedded blanks and lower case letters. If no text had accompanied the
LABEL command, GENPLOT would have prompted you for the information. BOTT is an abbreviation
for BOTTom; most GENPLOT commands have abbreviations. The label on the plot will not change
until the next time you plot. Before we do that, let’s set the y, or left, axis
>> label left
GENPLOT now prompts for the label, and we enter
2-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
>> Speed (mph)
Now to redraw it,
>> plot
¾
»
40
Speed (mph)
30
20
10
0
0
1
2
3
4
5
Time (sec)
½
¼
Lines and Overlays
We also want to draw a line through the data connecting the points. This involves the command
LTYPE which stands for line type. The default, type 0, is not to have a line. There are seven other
line styles from type one, a solid line, to seven which is dot–dot–dash–dash. The various line types
are listed in the reference section and consist of various combinations of dots and dashes. For now,
we will use a solid line,
>> ltype 1 overlay
OVERLAY is a new command. It means overlay the current data on the current plot without erasing.
It is convenient for plotting several data sets on one plot or for viewing data transformations. It can
also used to add symbols to a line or, as you have just done, to add a line through the symbols. If
you have a color monitor, type
>> ov -color 2
The line will have changed to color 2. Actually, the line in color 2 has been just plotted over the
white, color 1, line but the effect is the same. The -COLOR 2 is an option to the OVERLAY command
which temporarily overrides the current pen color. The PLOT and OVERLAY commands have numerous
options listed in the reference section.
2-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
40
Speed (mph)
30
20
10
0
0
1
2
3
4
5
Time (sec)
½
¼
Now we want to change the symbol. Type
>> symbol 1
This command will generate a warning message because the line type is still set to type 1, solid lines,
and hence the symbols are not active. GENPLOT is simply reminding you of this mode. Type
>> plot
You get a line but no symbols. We must change the line type to get symbols, and
>> lt 0 ov
will add the symbols. As a final added touch before we mess up this plot completely, type
>> ids
This command puts up a legend which identifies the data being plotted with the file name that it
was derived from. You could also use IDENTIFY to set some arbitrary label for the line. Try
>> identify
and then put in some string of text for your label. Since GENPLOT prompted you for the string
you do not need quotes to include lowercase or imbedded spaces. You could also have entered the
string with the IDENTIFY command but quotes would be required if it contained blanks or if you
wanted mixed upper and lower case.
You might want to try hcopy dev / at this point to see if you get what you expect.
2-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
40
!t1.dat
A line
Speed (mph)
30
20
10
0
0
1
2
3
4
5
Time (sec)
½
¼
Multiple Data Files
Now lets try for multiple data sets on a plot. First, we need to expand the axes scales since I happen
to know that the second data set is beyond the first. If we allow autoscaling to set the axes for the
first set, the second data set will be off the screen. This introduces the REGION command.
¾
»
GENPLOT: region bottom
Lower range limit (unchanged): 0
Upper range (unchanged): 10
GENPLOT: reg left 10 80 plot
GENPLOT:
½
¼
By explicitly setting a region for the left and bottom axes, the autoscaling on those axes is disabled.
Autoscaling may be re–enabled at a later time using the commands REGION LEFT AUTO and REGION
BOTTOM AUTO. Setting the region does not mean that the labels will extend the exact value specified. GENPLOT still attempts to make nice axes by extending the range. We could have forced
GENPLOT to use the specified limits exactly on the axes with the FORCE command. As it is, it will
change the 10 to 80 range to be 0 to 80.
2-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
80
Speed (mph)
60
40
20
0
0
2
4
6
8
10
Time (sec)
½
¼
GENPLOT only has one main, or active, curve. If you read in another set of data or create one
with a function, you will loose the current curve. To save a curve in memory during a session we
can use the ARCHIVE command.
>> archive data1
The data is saved to a curve called data1 in memory, not to disk. data1 will be lost when you exit
GENPLOT, unless it is written (see WRITE) out specifically to disk. But as an archived curve, it can
be conveniently used in analysis and plotting. At this time, we will read and plot the second set of
data in one line
>> read t2 sym 2 ov
That is, read T2.DAT (.dat is default), change the plotting SYMBOL to type 2 and OVERLAY it on
the current plot. Can you guess what happens if we type PLOT instead of OVERLAY? Try it,
>> plot
The T1 graph has now been lost. This is a reminder that GENPLOT works with only one data set
at a time. While you can plot functions against your data and you can name and archive a data set
for quick retrieval, there is only one active X and Y set of data at any given time.
2-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
80
Speed (mph)
60
40
20
0
0
2
4
6
8
10
Time (sec)
½
¼
We can quickly retrieve T1 since we archived it earlier as data1.
>> ov data1 -sym 3
Now let’s do it a little differently,
>> read t1 read t2 -append
This will append the T2 data to the T1 data set, creating one larger data set. Notice that on the
second read the number of points is up to 34. Now plot the new data,
>> plot
Note that the entire data set has the symbol left over from our last plot of T2. Symbols and line
types stay with the current plot not any particular set of data. Let’s play it safe and save this new
data set to disk,
>> write t12 -ascii
The -ASCII is not necessary since it is the default, but it reminds us that the data is being saved in
human readable format. You may also wish to archive this data set as well.
>> archive t12
Since we are going to add an additional data set to this graph lets turn on auto identification,
>> autoids on
This commands causes the legend information (IDS) to be automatically added to the plot after any
PLOT or OVERLAY commands.
2-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
Using 4 Axes
I’m sure that you have noticed that there is a box drawn around the plot. This is not just for looks.
It also provides you with the ability to have two different scales for the data set, or sets. The axes
are referred to by their location, such as top, bottom, right and left, rather than x and y since you
could have two different y axes.
Now to set up the other two axes for the third data set. First, let’s make sure that the current plot
is where I expect it to be. If you have been experimenting or stopped for a while, type
>> read t12 plot
Then type
>> plx top ply right reg top auto reg right auto xtop on yright on
That was a long one, if you do it often you could create a macro for it or use Setup. PLX and PLY
tell GENPLOT which axis to plot the data against, in this case the top and right axes respectively.
Next we will tell it to auto scale the top axis for the X data with reg top auto and then for the Y
with reg right auto. Finally we need to turn the labeling for the other axes on. This is important;
by default the labels on the top and right sides are not printed unless told otherwise. Setting the
axes to plot against is not enough. If you don’t turn the labeling on, it will not show up.
Read data set T3, change the symbol and overlay it
>> read t3 sym 3 ov
Surprise! No T3 data. You get the id for the curve, but not data points. Even though everything
was turned on, OVERLAY overlaid the data against the current values of the top and right axes,
which on the present plot are the same as the bottom and left axes. Hence the data from T3 was
completely off scale. The axes are autoscaled only on a PLOT command, and the values are used for
all subsequent OVERLAYS unless explicitly changed using a REGION command.
Before we actually plot the other axes set, specify labels for the top and right axes. I will leave the
titles up to you. The commands are
>> label top ’text’
and
>> label right ’text’
Still at this point, there are no numbers or labels on the the top or right axes. Type
>> axis
A new axis is drawn with all the labeling. The AXIS command is just a PLOT command without the
OVERLAY. Now to put up the data.
¾
»
GENPLOT: ov -symbol 3 -lt 0
GENPLOT: read t12
GENPLOT: plx bot ply left ov -sym 2 -lt 0
GENPLOT:
½
¼
2-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
A Top Label
80
8
10
12
14
16
18
!t3.dat
!t2.dat
95
90
85
40
80
75
A Right Label
Speed (mph)
60
20
70
0
0
2
4
6
8
10
65
Time (sec)
½
¼
A final addition to the graph just to get this command in somewhere. Type
>> grid
to get grid lines on the plot. Those with color monitors will note that it comes out in the current
color. You can use
>> grid -color 3
to change its color.
¾
»
A Top Label
80
8
10
12
14
16
18
!t3.dat
!t2.dat
95
90
85
40
80
75
A Right Label
Speed (mph)
60
20
70
0
0
2
4
6
8
10
65
Time (sec)
½
¼
2-14
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
Two other commands will give you useful information about the current state of the plot. STATUS
will tell you about the data set size and values. PARMS will tell you the current settings for the
various plot values, axis labels, colors, symbols, scaling, etc. The values on your screen may vary
slightly from those below.
¾
»
GENPLOT: status
Current data consists of
19 points. Max: 2048
X minimum = 0.00000E+00, maximum =
4.1600
Y minimum = 0.00000E+00, maximum =
39.900
GENPLOT: parms
Autoranging X: BOTH
Y: BOTH
Top axis: OFF
Right axis: OFF
Bott range: 0.000000E+00 1.000000
Top:
Left range: 0.000000E+00 1.000000 Right:
LType: 0, SYMbol:
3 NPOint:
1
Plot device: AUTO
Current Pen: 1
Maximum: 7
Pen Speed:
Plotting area: 10.00 by 7.80
Reduction:
Plot offset:
0.00 by 0.00
Margins:
½
0.000000E+00
0.000000E+00
18
1.00
0.85 by
1.00000
1.00000
0.75
¼
At this point if you have a printer or plotter configured you might try the HCOPY command to that
device. After all that is what it was designed for. For example:
>> hcopy dev hp150
will replay the current plot to an HP LaserJet at 150DPI. (See Appendix D for device configuration
information.) Again we recommend that you use macros for generating complex plots and using
HCOPY for finishing touches.
2-15
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
TUTORIAL 2: ANNOTATE
Annotate is a sublevel which has a number of commands of its own. It is used to “Annotate” the
plot by adding labels, arrows, boxes, circles, etc. If you are out of GENPLOT type the following,
filling in your graphics device where it has <gd>.
¾
»
C> genplot
GENPLOT/3D Shell & buffer allocation [MOT 1.00]
GENPLOT [Rev. 1.00 11/01/89]
[copyright 1987-2004 Computer Graphic Service, Ltd., All rights reserved]
GENPLOT: dev <gd>
GENPLOT: cd \genplot\tutorial
½
¼
Now to get some data again
>> read t1 read t2 -append
Label the axes,
>> lab left Speed lab bottom Time plot
The labels appear in mixed case. Had you tried to make a longer label, Time (sec), Time would
have been used for the label and (sec) would have been treated as the next command, giving you
an error. For multiword labels you must either quote the string or just type LABEL and answer the
prompts. Identify the plot,
>> ids
Now we can get into it,
>> annote
the prompt changes to ANNOTE to indicate that you have entered a new command level. You can
exit the Annotate subprocessor by typing RETURN, QUIT, GENPLOT or by giving a command which
ANNOTE does not recognize.
Annotate always returns to GENPLOT level when it doesn’t understand a command. The advantage
of this is that you don’t need to formally exit to keep working, just type the next command you
want. The disadvantage is that when you misspell an Annotate command, you get kicked back to
GENPLOT.
The Cursor
You will use the cursor a lot in Annotate to place things on the plot so we need to explain how it
works. Annotate commands generally need to know where to put things on the plot. You do this by
specifying an x,y coordinate either through the keyboard or by using the cursor. In an interactive
session the cursor is easier. If you were using a macro file, you might want the coordinates placed
directly in the command. A macro file for this tutorial is given in the example section. When a
command activates the cursor a cross-hair will appear on the screen. For some devices it extends
across the entire screen both vertically and horizontally. For other devices it will appear to be about
one inch in each direction.
2-16
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
You move the cursor using the arrow keys on the keyboard. The shift key changes the speed of
the cursor from fast to a single pixel per key stroke. The keys on the corner of the keypad cause
diagonal movement. We hope that this is simple enough that we need not spend any more time on
it. Whenever the cursor is used the coordinates are displayed on the text screen so that later you
could write them down and use them in a macro file. You can break out of the cursor by using
<ctrl-c>.
¾
»
½
¼
We want a plot similar to the one shown. Let’s start with the rectangle around the file name in the
upper left corner. Type
>> rect
Since this command needs more information you will be requested for the (x,y) coordinates for
opposite corners in the rectangle. Using the cursor is the default entry so just press
>> <enter>
(From now on we will just use <cr> for <enter>) The cursor is displayed. Using the arrow keys,
move the cursor to the upper left corner of the file name and press
>> <cr>
Move the cursor to the lower right corner of the identity and
>> <cr>
Then you are asked about a line type for the rectangle. Numbers are used as in the LTYPE command.
The default is a solid line, type 1. A rectangle is drawn and you are returned to the text screen.
Now for an arrow. Select the arrow command,
>> arrow
2-17
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
Then
>> <cr>
for the cursor. Put the start of the arrow around the point (2,45) by moving the cursor to that point
and hitting
>> <cr>
Next move the arrow to the point in the graph where the two curves meet, around (4,40). Hit
>> <cr>
and the arrow is drawn. We’ll place the label ’Shift Point’ near the end of the arrow. Labels may
be placed on the screen by cursor control also; however, we have the option of determining where
the cursor is relative to the text. The ORGMODE command specifies the origin of text and takes a
two letter argument. The first letter is either R, C or L referring to the right, center or left of the
text. The second letter of the argument is either B, C or T for bottom, center or top. Move the
text origin to the right–bottom corner and start the label,
>> org rb label
>> <cr>
Now, move the cursor to the start of the arrow and hit
>> <cr>
You will be prompted for the text to be used. Type in
>> Shift Point
or whatever else you might like. The text should appear to the left of the arrow and will end properly
at the start of the arrow.
Shifting the origin to the left–top we can put two more labels on,
>> org lt label
>> <cr>
and place the cursor somewhere on the right side of the lower half of the curve. Key
>> <cr>
to set the point then type the label
>> First
as in first gear. Let’s do the next label without the cursor. But first we should make life a little easier
for ourselves. GENPLOT generally works in coordinates of inches. However we can tell it within
ANNOTATE to use the coordinate system of the graph with the COORMODE command. This command
also takes an origin, allowing you to move your information around globally without changing every
label that you have put in. Type the following two commands,
>> coormode user 0 0
>> label 7 53 ’Second’
2-18
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
Text can be placed at angles also. Try putting the word ’acceleration’ along the top part of the
curve. Use the cursor with the command
>> ang 40 org lb label
This sets the angle to 40 degrees and the origin of the text to the left-bottom corner.
Put a large label on using
>> org lb ang 0 size 0.4 label 3.75 15 alfa
Now for a short paragraph style explanation on the plot. Change the size to 0.15 and set a label
just under the Alfa for some text,
>> size 0.15 label /
Notice that the cursor came up without asking. The ’/’ means accept the default argument for the
next input which is the cursor. Place the cursor a little below Alfa allowing enough room for the
height of the text. Now type the following three lines for the text being sure to include the ’∼’, it
is the line continuation character.
¾
»
Data for~
Alfa Milano 3.0~
Road & Track 9/87
½
¼
Finally we will circle the large label just to show how circles work. Now circle the ALFA using the
>> circle
command and the cursor. Circle requires three points which will define an arc. A start and end
point for the arc and a third point to determine its radius. You may want to experiment with this.
It allows you to put circles along side of things. Put the start on the left side of the ALFA. Place
the end point on the right side and put the mid point along the X axis about in the middle of the
word. Good luck.
2-19
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
¾
»
½
¼
SIMPLE PLOT REMINDERS
Symbols and lines
You cannot draw both lines and symbols at the same time. To draw symbols the linetype must be
set to zero by issuing LTYPE 0. To draw a line LTYPE must be greater than 0. If you want both
symbols and lines to appear on the same plot, use the OVERLAY command. This command plots
the current data set without redrawing the axes or erasing the current plot, as the PLOT command
defaults to doing.
An example is:
>> read filename plot -lt 0 -sym 1 ov -lt 1
Note that abbreviations were used for these commands. Here the data file was first plotted as circles,
followed by a solid line.
Two data files on one graph
The OVERLAY command is also used to plot more than one set of data on the same graph.
GENPLOT only plots one data set at a time. The following command string will plot two sets,
one with circles, the other with triangles:
>> read file1 lt 0 sy 1 plot read file2 sy 2 ov
To have solid lines drawn through the symbols, use:
>> lt 0 read file1 pl -sym 1 ov -lt 1 read file2 ov -sym 2 ov -lt 1
The plotting order of this command is: (1) circles of file1, (2) line of file1, (3) triangles of file2, and
(4) line of file 2.
2-20
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
TUTORIAL 3: DATA ANALYSIS
Let’s start with a bit of a disclaimer. We cannot tell you the best way to analize your data. Nor
can we be responsible for analysis techniques that are misapplied. If you are unfamiliar with the
data analysis techniques (such as SPLINE or Non–Linear Least Squares) that are available within
GENPLOT you should either learn about them or not use them. Improperly done analysis is a
DIGO operation, Data In — Garbage Out.
The purpose of this tutorial is to show you some concepts and methods for doing common data
manipulations in GENPLOT. The first concept to keep in mind is that GENPLOT, unlike most
programming languages, works on arrays or curves not single variables. For example:
>> let y = sin(x)
sets all the Y values in the curve to the sine of the corresponding X values.
Averaging
Let’s suppose that you have a large data set and you want to smooth the data by averaging every
5 points. The first thought may be to create some variable and then have a for statement to loop
through the data as you would in FORTRAN.
¾
»
/* average 5 points */
archive data1
/* store the data
allocate j integer
let j = 3
for repeat npt-4 do let y(j) = (y(j-2)+y(j-1)+y(j)+y(j+1)+y(j+2))/5 let j = j+1
½
¼
This method is very slow because the command parser is an interpretor. In this example it has to
interpret the equation for each iteration of the loop. Using the fact that GENPLOT works on curves
and allowing us to dump 2 points from both ends:
¾
»
/* average five points */
/* you lose the 2 points at each end */
archive data1
let npt = npt-4
/* we are going to loose 4 points */
let y = [y(i)+y(i+1)+y(i+2)+y(i+3)+y(i+4)]/5
let x = x(i+2)
/* shift x, dropping the first 2 */
½
¼
First of all we archive the data. ARCHIVE on puts a copy of the data aside in memory it does not
save it to disk. This allows you to quickly bring back the data if you make a mistake or to plot the
original data with the smoothed curve. Next we decrement npt by 4. npt is an internal variable
which is the number of points in the current curve. We need to subtract 4 to prevent the index of
(i + 4) from exceeding the actually data. As the data is modified y(i) becomes the average of the
five points around y(i + 2). Like npt, i is an internal GENPLOT variable that is used as the index
variable. You don’t need to set it, nor should you. It will be incremented from 1 to npt by 1. No
checking is done to keep the index of the array within bounds. If y(i) exceeds the range of valid data
or goes outside the data space and scribbles over GENPLOT code the results are unpredictable.
2-21
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Walking through: tutorials
However, this is a feature as you will see in the next example. Next you shift the x values down 2
elements to match the center points for the averages.
Skipping Data
The commands below will remove every other point from the data.
¾
Genplot:
Genplot:
Genplot:
Genplot:
½
»
archive c1
let npt=npt/2
let y = c1:y(2*i-1)
let x = c1:x(2*i-1)
/* toss every other point */
¼
Notice in this example that the data from the archived curve is used rather than using the default
curve. This can be useful when the computation is using information that may have already been
modified. Also note that with i going from 1 to npt the index, (2 ∗ i − 1), exceeds npt without
complaint.
Selecting a range
Sometimes you want to work with a subset of the data. The easiest way to select a set of data to
work with is to use CULL DATA. This command can be used to either remove, cull, or to keep only
the section selected. If you wanted to sum the center part of the data you could do the following.
¾
Genplot:
Genplot:
Genplot:
44.89
Genplot:
½
»
archive data1
cull -keep -box /
eval sum(y)
retr data1
/* Set aside the original curve
/* Use box cursor to select data
/* Evaluate the sum
/* Display the result
/* Retrieve the curve
¼
The previous examples showed that GENPLOT does not mind accessing data beyond the current
setting of NPT. In fact we used that to our advantage. Another way to use that is in selecting subsets
of data where you may know the points you want but not the actual data values. The following
example selects a 200 points out of the middle of the data set.
¾
Genplot:
Genplot:
Genplot:
Genplot:
Genplot:
½
»
create y = sin(x) -f -10 -t 10 -p 1000
archive c1
let npt=200
let y = c1:y(i+399)
let x = c1:x(i+399)
¼
2-22
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
EXAMPLE MACROS
PLOTTER SETUP
This sets parameters for the HP7470A plotter that produce a vertical plot with enough space on
the bottom for a legend. Such a plot could be used in a report. The plot could be viewed without
turning the page sideways.
flipxy yes
offset 4 2.25
size 7.5 7
sgraph csmax 0.16
sgraph tsize 0.20
syms 0.15
PLOTTING TUTORIAL
—Plot 1—
dev ?
cd \genplot\tutorial
read t1.dat plot
/* set the device
/* set the directory
/* read and plot the file
—Plot 2—
dev ?
cd \genplot\tutorial
read t1.dat
label bottom ’Time (sec)’
label left ’Speed (mph)’
plot
/* set the device
/* set the directory
/* set the bottom axis label
/* set the left axis label
/* plot the new graph
—Plot 3—
dev ?
cd \genplot\tutorial
read t1.dat
label bottom ’Time (sec)’
label left ’Speed (mph)’
plot
ltype 1 overlay
overlay -color 2
/* set the device
/* set the directory
/* plot a line
/* change the line color
2-23
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
—Plot 4—
dev ?
/* set the device
cd \genplot\tutorial
/* set the directory
read t1.dat
label bottom ’Time (sec)’ label left ’Speed (mph)’
ltype 1
symbol 1 plot
/* replot with new symbol, wrong ltype
ltype 0 overlay
/* plot with symbols
pause
ids
/* identify the plot
identify ’A line’
/* add to the legend
—Plot 5—
dev ?
/* set the device
cd \genplot\tutorial
/* set the directory
read t1.dat
symbol 1 ltype 0
region bottom 0 10 region left 0 80 /* fix plot region for two curves
plot
—Plot 6—
dev ?
/* set the device
cd \genplot\tutorial
/* set the directory
read t1.dat ltype 0
label bottom ’Time (sec)’ label left ’Speed (mph)’
region bottom 0 10 region left 0 80 /* set plotting region
plot
read t2 plot -symbol 2
/* replot losing t1 data
—Plot 7—
dev ?
/* set the device
cd \genplot\tutorial
/* set the directory
label bottom ’Time (sec)’ label left ’Speed (mph)’
ltype 0
region bottom 0 10 region left 0 80
read t1 read t2 -append
/* read in data
archive t12
/* archive it
autoids on
/* turn on auto identify
autox top autoy right
/* autoscale top and right axes
xtop on yright on
/* turn on top and right axes
label top ’A Top Label’ label right ’A Right Label’
read t3 axis
/* read data an put up axis
plx top ply right ov -symbol 3
/* plot against top-right axes
plx bottom ply left ov t12 -sym 2
/* plot t12 against bottom-left axes
2-24
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
ANNOTATE TUTORIAL
cd \genplot\tutorial
/* set current directory
dev ?
/* select device
read t1.dat read t2.dat -append
/* read the data
label left speed label bottom time
/* set axis labels
plot ids
/* plot and identify the graph
annote
/* enter annotate mode
size 0.20
/* set label size
coormode user 0 0
/* set coordinate mode
rec .25 60 2.5 65 1
/* make rectangle around legend
arrow 3 45 4 40
/* draw arrow to graph
org rb label 3 45 ’Shift Point’
/* label the arrow
org lt
/* change label coordinate point
label 1.5 20 ’First’ label 7 53 ’Second’ /* label the curves
angle 40 org lb label 4.6 45 Acceleration /* an angled label
org lb angle 0 size 0.4 label 3.75 15 alfa /* a large label
size 0.15 label 6.5 20
/* a paragraph style label
Data for ~
/* ~ used to continue label
Alfa Milano 3.0~
Road & Track 9/87
circle 3.6 18 5.4 18 4.2 8
/* draw a circle
ERRORBARS
chrset 3 lt 0 symsiz 0.22
subticks off logar left on axctrl left -speclog -subticks
label left ’^2H^3 * r’ label bottom ’Saturation level ^2d’
create y = sin(x)-ln(x) -from 1 to 10 by 1
archive t1
symbol 1 plot t1 -errx .2*sqrt(x) -erry .2
sgraph idlskp 3 sgraph idspac 2.0 identify ’Data 3/3/88’
lt 1 fit spline
ov -fit -points 200 -exclude t1
identify ’Spline fit’
lt 2 fit poly 4
ov -fit -points 200 -exclude t1
identify ’4^{th} order polynomial fit’
2-25
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
NON-LINEAR AXIS
create y = 1+2*x from 1 to 5 points 10
ltype 1
force yes region bot 1 5
label top ’Temperature (^0J^1C)’
label bot ’1000/T (K)’ label left ’Log of diffusion time’
reg top 2 8
xtop nonlinear
define bottom_to_top(x) = (1000/x)-273
define top_to_bottom(x) = 1000/(x+273)
plot
2-26
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
TITLE PAGE EXAMPLE
/* *****************************************************************
/* This example was provided by Neil Gershenfeld at Cornell Univ. *
/* It consists of real data for a plots which was submitted for
*
/* publication. It illustrates some of the more detailed control *
/* which is available for controlling the final plot appearance.
*
/* *****************************************************************
size 10 7.75
/* -------------- Labelling parameters -------sgra tsize .2
/* Title size
sgra susiz .65
/* Subscript size (65%)
sgra csmax .2
/* Set up mychoice of parameters
/* -------------- Legend positioning ---------sgra idtskp .2
/* Start .2 inches from top Y axis
sgra idlskp 3.3
/* Skip over from left 3.3 inches
sgra idsize .14
/* Size of IDS labels
sgra idspac 1.7
/* Line spacing of 1.7x character size
chrset 3 linestyle 1
label bot ’T(K)’
label left ’internal friction Q^{-1} (10^{-3})’
region bot 0 100
region left 0 1.5
axctrl top -noticks
/* Eliminate tick marks on the top axis
axis
linestyle 2 ltype 0 symsize .175
/* Plotting characteristics
/* alresi
read s28prl.q sort let y = 1e3*y let ids = ’Al_{75}Re_{21}Si_{4}’
sym 1 linestyle 2 overlay linestyle 1 ids
/* almnrusi
read s19prl.q sort let y = 1e3*y let ids = ’Al_{76}Mn_{17}Ru_{4}Si_{3}’
sym 2 linestyle 2 overlay linestyle 1 ids
fit linear -xrange 0 100
linestyle 2 ov -fit -from 0 -to 100 -points 10 -lt 1
/* alru
read s17prl.q sort let y = 1e3*y let ids = ’Al_{79}Ru_{21}’
sym 5 linestyle 2 overlay linestyle 1 ids
/* alcrru
read s23prl.q sort let y = 1e3*y let ids = ’Al_{78}Cr_{17}Ru_{5}’
sym 6 linestyle 2 overlay linestyle 1 ids
symsize .15
sgra idspac 2.8
/* Smaller filled symbols
/* Skip more space this time
/* pdsi
read pdsiprl.q sort let y = 1e3*y let ids = ’Pd_{80}Si_{20}’
sym 7 linestyle 2 overlay linestyle 1 ids
sgra idspac 1.7
/* Back to normal
/* o-almn
read s29prl.q sort let y = 1e3*y let ids = ’o-Al_{6}Mn’
sym 9 linestyle 2 overlay linestyle 1 ids
2-27
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
/* A little additional labelling on structure
annote orgmode lc size .5
label 6.1 6.3 }
/* Put up the } character
size .12
label 6.4 6.3 ’quasicrystal’
/* And the label
return
sub_plot -enter 1.3 4.4 4.4 7.0
/*
chrset 1
label bot ’T(K)’
label left ’Q^{-1} (10^{-3})’
sgraph tsize .36
sgraph csmax .33
sgraph susiz .9
sgraph tloff 0
/*
ltype 0 symsize .375 linestyle 1
reg left 0 .4 reg bottom 0 5
axctrl right -noticks subticks off
axis
read s19prl.loq
let y = 1E3*y ov
read s28c2prl.loq let y = 1E3*y ov
read s17prl.loq
let y = 1e3*y ov
read pdsiprl.loq let y = 1e3*y ov
sub_plot -cancel
/*
/*
/*
/*
-sym
-sym
-sym
-sym
Title size on sub-plot
Size of tick mark labels
Superscript size
Left label not moved
/*
/*
/*
/*
/*
/*
/*
2
1
5
7
Set regions
More control
Draw axis
almnrusi
alresi
alru
pdsi (bigger syms)
¾
»
1.5
0.4
Al75Re21Si4
Al76Mn17Ru4Si3 quasicrystal
Al79Ru21
Al78Cr17Ru5
}
-1
0.2
Pd80Si20
o-Al6Mn
Q
internal friction Q-1 (10-3)
-3
(10 )
0.3
0.1
1.0
0.0
0
1
2
3
4
5
T(K)
0.5
0.0
0
20
40
60
80
100
T(K)
½
¼
2-28
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
COVER PLOT EXAMPLE
/* ***************************************************************************
/* This macro file generates the plot which is used on the front cover of the
/* GENPLOT manual. It is a reasonable example of the commands and structure
/* required to generate a complex, publication quality graph.
/* ***************************************************************************
echo off
genplot
setv myshift = &getarg -prompt ’Enter the shrink factor (1.0): ’ -default 1.0
chrset 3
shrink 1.0*myshift offset 3.0 1.0 margin 0.5 0.5 size 6 6
get laser.cul let y = log(y*0.492)-8 let x = 1000/x
let ids = ’Laser Quenched’ arch laser
get implant.all let y = log(y)-8 let x = 1000/x arch implant
let ids = ’Ion Implanted’ arch implant
retrieve laser
retrieve implant -append
archive limit
/* Combine both curves to create a curve which
/* will be EXCLUDED during drawing of the fit
/* to the data.
force yes subticks off
define top_to_bottom(x) = 1000/(x+273)
define bottom_to_top(x) = (1000/x)-273
xtop nonlinear
yright off
reg left -10 -6 log left on
reg bot 1.055 1.345
sgraph idlskp 2.00
sgraph idsize 0.16
sgraph tboff 0.15
label left ’SPEG rate (cm/sec)’
label bot ’1000/T (K^{-1})’
label top ’Temperature (^0J^3C)’
lt 0 autoids off
linewidth 2 symsize 0.14 sym 2 pen 2 pl laser
symsize 0.18 sym 7 pen 4 ov implant
symsiz 0.22
/* First data set plotted
/* Second data set plotted
/* For later EXCLUDE option
linewidth 1 retrieve laser sym 2 pen 2 ids retrieve implant sym 7 pen 4 ids
/* Note - could also have simply used "LSQFIT" instead of "FIT LINEAR OV -FIT"
autoids off
retrieve laser
fit linear
ov -fit -from \$xmin -to \$xmax -points 5 -lt 1 -exclude limit -pen 2
retrieve implant fit linear
ov -fit -lt 2 -exclude limit -pen 4
2-29
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
chrset 1
annote
coormode inches 0 0
pen 2 draw line 2.175 4.923 2.575 4.923 1
pen 4 draw line 2.175 4.692 2.575 4.692 2
pen 1
/*
/*
shrink 1.5*myshift
annote coormode inches -1.9 -1.3
sample
type left 2d 6.0 3.2 7.6 4.8
dotted 4 0.375
solid 0.750
ret
orgmode lc
angle 90
size 0.14
label 6.3 3.45 ’a-Si’
label 6.9 3.45 ’c-Si’
orgmode lc
label 7.5 3.45 ’Al^‘2^=O^‘3^=’
return
anno
sgraph arwlen 0.1 sgraph arwang 0.4
setv delta 0.25
setv mid
4.2
setv start 5.0
setv stop 5.9
/*
/* incident beam
annote
pen 3 draw arrow start mid-delta stop mid+0.1*delta
/* reflected beam, dashed line + arrow head
draw line stop mid+0.1*delta start mid+delta 2 /* 5.9 4.26 5.0 4.6 2
draw arrow 5.1 mid+0.9*delta start mid+delta
pen 1 orgmod cc angle 0 label start mid+delta+0.2 ’Reflection’
/* transmitted beam
pen 3 draw arrow 6.0 mid 8.2 4.3 pen 1 label 8.0 4.5 ’Transmission’
/* constant thickness
pen 3 draw arrow 6.0 5.1 7.2 5.1
draw arrow 7.2 5.1 6.0 5.1
draw line 6.0 5.0 6.0 5.2 1
draw line 7.2 5.0 7.2 5.2 1
pen 1 label 6.6 5.3 ’500nm Si’
2-30
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Getting Started with GENPLOT
Example Macros
¾
»
½
¼
2-31
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
QUICK REFERENCE
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Quick Reference
Essential Information
GENPLOT INITIALIZATION SEQUENCE AND OPTIONS
Syntax: GENPLOT [-Buffer <bufsize>] [-INi <initialization file>] [-Help] [-3D]
This is the primary user command to initialize GENPLOT. Options to this command allow the user
to modify the maximum number of points GENPLOT will handle or to specify an initialization file
to be executed upon entering GENPLOT. GENPLOT is always initialized with a blank data buffer
which can contain a maximum of <bufsize> points. If unspecified, <bufsize> defaults to 2048.
The maximum allowed <bufsize> is 16380. Buffer space for the default curve is allocated during
initialization and requires 8 bytes of memory per point.
Immediately following initialization, GENPLOT searches for an initialization macro file which is executed before responding to user commands. The default initialization file is GENPLOT.INI, although
any file may be specified using the -INI switch. (WARNING: No error message is issued if the file
does not exist.)
The option -HELP simply prints a brief statement of the command syntax for GENPLOT and returns
to the DOS prompt.
You must exit from GENPLOT using the QUIT command. The RETURN command is only available for
subroutine calls to GENPLOT. Under this command shell version of GENPLOT, RETURN generates
an obnoxious error message and returns immediately back into GENPLOT.
KEYBOARD EDITING
GENPLOT includes a fairly powerful keyboard editor for correcting typing errors and recalling
previous commands. The editor makes use of both the arrow keys and EMACS like control sequences
to edit the current command line. The <↑>, F3 and <↓> keys recall previous command lines. The
remaining keys edit the displayed line. The editor defaults to overwrite mode at the beginning of
each keyboard request.
Control Key
∧B
∧F
∧A
∧E
∧L
∧N
∧P
∧H
∧D
∧K
∧U
∧I
∧]
∧J
∧T
∧G
∧C
∧Z
Action
Cursor keys
Move cursor BACK one character
Move cursor forward one character
Move cursor to beginning of the line
Move cursor to END of the line
Repaint current line
Copy NEXT command line into buffer
Copy PREVIOUS command line into buffer
Erase previous character
DELETE a single character
KILL (erase) to end of the line
Erase entire buffer
Toggle between insert and overwrite mode
Tab (converted to space)
Toggle between default insert and overwrite mode
Line feed (converted to RETURN)
TWIDDLE (exchange) two previous characters
ESCAPE from level (abort current command)
ABORT (executes normal ∧C processing)
End of File marker
3-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
<←>
<→>
<HOME>
<END>
<↓>
<↑> <F3>
<BACKSPACE>
<DELETE>
<INS>
<TAB>
<ESC>
Quick Reference
Essential Information
In several modes of GENPLOT, the <ESC> key will escape out of a current command and return to
the next higher command level. For example, <ESC> pressed at a request for text within ANNOTATE
will return immediately to ANNOTATE.
BREAK OR CONTROL–C
Many commands within GENPLOT may be prematurely aborted using a single Control–C or Break
key. For example, the plotting of symbols (but not lines) may be aborted at any time by typing
a break. However, if a second break (or Control–C) is typed before GENPLOT responds to the
first, GENPLOT will exit back to DOS (the whole purpose of break). Moral of the story – don’t go
flipping out on the break key.
UPPER/LOWER CASE AND EXPRESSIONS
User command input lines are passed through a standard command parser before being interpreted
by GENPLOT. This command parser separates the input into a series of tokens. Each token is
then normally uppercased and returned to GENPLOT for interpretation. In several cases (such
as specifying labels), it is necessary to pass strings containing embedded spaces and/or mixed case
words. Strings can be passed unmodified by enclosing the entire string in single quotes. Hence,
labels which require mixed case should always be quoted. The exception to this rule occurs when
GENPLOT already knows that it is expecting a character string and prompts directly for the text
string. In such cases, GENPLOT will disable the parsing and case conversion and take the entire
line as a single entity. For example, consider specifying the bottom label. As a single command
line, this would require LABEL BOTTOM ’X Axis’. If you type only LABEL BOTTOM, GENPLOT will
prompt for the actual label. At the prompt, the label is typed without quotes. Note that because
the entire line is taken as the label, it is impossible to place another command on the same line.
Mathematical expressions are also often written with embedded spaces to improve legibility. The
expression may then either be enclosed in quotes or may be enclosed in open/close parenthesis pair.
Parsing of mathematical expressions will continue through a command line until all parenthesis are
matched. Hence, the following is valid EVALUATE (sin(2*pi/3) + 3*8.3).
Quotes are required when
• In labels that contain spaces and are given on the command line.
• In labels that contain mixed case and are given on the command line.
• In equations or expressions that contain spaces but not surrounding parenthesis. See the Function
Evaluator for details on equations and expressions.
CURVES AND ARRAYS
Multiple data sets may be manipulated within GENPLOT by using the ARCHIVE command. The
ARCHIVE command moves the data from the default curve of GENPLOT to another section of
memory creating several variables. WARNING: ARCHIVE does not permanently store the data.
ARCHIVE actually sets up a variable of type CURVE with a structure consisting of two arrays (X and
Y), an integer (NPT, the number of points in the curve), and a string (the descriptor of the curve).
The elements of the structure of a CURVE named C1 may be accessed with the expressions C1:X,
C1:Y, and C1:NPT. The description of the curve may be accessed as C1. For example
3-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Quick Reference
Essential Information
¾
»
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
eval c1:npt
/* print the number of points
eval c1:x(10)
/* print the 10th element of x
let y = sin(c1:y)
/* change y
annotate label / %c1% /* use the id in a label
¼
The variable C1 refers to the curve and not any of its numeric arguments. C1:X refers to an array
(specifically the X values in curve C1) and C1:NPT refers to an integer (the number of points in C1.
See the Function Evaluator section and the ARCHIVE/RETRIEVE commands for more information and
details. Note that the default curve elements are simply referred to by X, Y, NPT and IDS without
a curve name.
SOME PECULIARITIES
Many GENPLOT commands toggle a plotting mode on or off, such as logarithmic scaling or automatic screen erasing. Some of the commands require either an ON/OFF response while others
require a YES/NO response. The response necessary for any particular command must unfortunately
be memorized or learned.
USING THE CURSOR AND BOX ON PC GRAPHICS SCREENS
The screen cursor is used in numerous commands to either place objects on the screen or select data
points. Once the cursor appears, it will move in response to the arrow keys. Pressing any other
key generally causes the value of the cursor to be returned to GENPLOT. In the CURSOR command,
the <space> or 0 key causes the value to be returned to GENPLOT and GENPLOT will return
immediately with another cursor.
The cursor operates in two speeds, fast and slow. In the normal (fast) mode, each press of an arrow
key moves the cursor by several pixels. Holding the <SHIFT> key down while pressing the arrow keys
will slow the movement of the cursor to individual pixels. The <INS> key toggles between the fast
and slow modes. The first time <INS> is pressed, the unshifted arrow keys will become the single
pixel movements and the shifted arrows will be the fast movements.
The cursor returns to GENPLOT when any unrecognized key is pressed. If you didn’t really want
to use the cursor, <ctrl>-C will normally abort the currently active command.
Commands such as subplot and zoom require a region of the screen to be selected. These commands
utilize a box-type cursor when available. When a box cursor is selected, the arrow keys drag one
corner of the box as marked by a dog–ear. In this mode, the box may be shrunk or enlarged as
necessary. The <SPACE> key toggles the dog–ear to the opposite corner of the box. The box may
be moved rigidly without changing its size by pressing the <DEL> key. While moving rigidly, the
dog–ear will be removed. Pressing <DEL> again toggles back to the original mode.
Cursor Key
<←>
<Home>
<↑>
<PgUp>
<→>
<PgDn>
Action
Move
Move
Move
Move
Move
Move
one or more pixels left
left and up
up
right and up
right
right and down
3-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Quick Reference
Essential Information
Cursor Key
<↓>
<End>
<SHIFT>
<INS>
<CR>
<SPACE>
<CTRL-C>
<DEL>
<SPACE>
Action
Move down
Move left and down
While held, toggle cursor speed for arrow keys
Toggle the speed of the arrow keys
Enter the coordinates
Enter the coordinates and return for more
Abort from cursor command
Toggle between rigid motion and moving one corner
Switch cursor attachment to diagonally opposite corner
LABELING DETAILS
When specifying any text to be labeled to the screen, the following special character sequences may
be used. These embedded sequences allow the character set to be changed or the drawing of super
and subscripts.
∧0
∧1
∧2
∧{this}
{that}
∧–
\[char]
∼
change to character set 0 (see CHRSET)
change to character set 1
change to character set 2
superscripts the text enclosed in {...}
subscripts the text enclosed in {...}
backspace character (hyphen)
quote character. \∧ draws the ∧ character
newline character for paragraph labeling
Subscripts and superscripts are drawn displaced and at a smaller size than standard characters. The
size and position of the superscripts can be changed by using the SGRAPH command. See Reference
section 4i for more details.
¾
label
label
label
label
½
»
1 1 ’Hi there’
/* Draws ‘‘Hi there’’ at (1,1)
/
Thompson
/* Draws ‘‘THOMPSON’’ at cursor
/ ’Si {3}N {4}-SiO {2}’ /* Draws Si3 N4 − SiO2 at cursor
/ ’Hi∼’ ’there’
/* Draws ‘‘Hi’’ ‘‘there’’ on two lines
¼
HARD COPY
Probably the most frustrating time during data analysis is when you have a completed a plot on
the screen with numerous labels and annotations, and you want a nice hard copy of the entire plot.
Generally there are three solutions. First, you can do a screen dump to your plotter at low resolution
in one color. Second, you can select a hard copy device and retype all the commands necessary to
create the plot. The third alternative is to remember (at the beginning of a session) to use the
HCOPY command. HCOPY is a powerful but often misunderstood command. HCOPY does not make
a hard copy of the screen, but rather it is a background process which, when on, keeps track of
all the plotting commands sent to the device. Under user control, HCOPY can replay these plotting
commands any other device and utilize the full capabilities of the device. Remember, HCOPY is useful
for only the current plot on the screen (it is reset when the screen is erased) and it only remembers
3-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Quick Reference
Essential Information
plot commands from when it is turned on. HCOPY is described in full gory detail in section A of the
reference.
The simplest and most common use of HCOPY is to turn it on immediately when entering GENPLOT
using HCOPY ON. The HCOPY file itself can be redirected to a ram disk or hard disk by setting the TMP
environment variable. Once initialized, HCOPY keeps track of all plotting vectors executed between
erase operations. If HCOPY is on, the command HCOPY DEV <gd> will cause all of the vectors to be
redrawn to the device <gd> (such as a pen plotter). HCOPY files may also be saved for later replaying.
However macro files would be better for this purpose.
HCOPY is not intended for production work. If you have many similar plots to do or some analysis
that is done regularly you should use macro files. You might think of a macro file as the source code
of a program. The HCOPY file would be the object file and your final plot the executable program.
You probably don’t rely on just keeping the object code for your programs around. The source code
is modifiable and readable.
HCOPY files are temporary files only a few kilobytes in size. We strongly recommend enabling HCOPY
in your initialization file HCOPY ON as long as you are using an XT or faster machine with a hard
disk.
FONTS
GENPLOT uses information from the Hershey character sets. It is in a vector or stroke form which
allows it to be freely scaled and rotated. As the bold and english characters get large they do not fill
in properly and may not appear as nice as they did when used in smaller sizes. Some compensation
can be made on devices that are capable of using wider pens or line widths.
The complete character set is shown on the following page. The characters are arranged on the chart
in order. Since most screens only display the standard Roman characters, you reference the Greek
and Symbol characters by using the Roman character that is in the same column. For example
to get a Θ you would switch to character set 6 and type a ‘Q’. The Greek characters are not in
alphabetic order, but in an order that maps them closely with similar sounding Roman characters.
Delta is with ‘D’ and Gamma is with ‘G’ for example.
Details on selecting character sets are given in the “Essential Information” section and under commands that alter or use the characters such as CHRSET and ANNOTATE LABEL.
3-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Quick Reference
Essential Information
3-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Quick Reference
COMMANDS IN BRIEF
3-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Quick Reference
Commands in Brief
3-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
COMMAND REFERENCE
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
A. DEVICE CONTROL
CLS
DEvice
ENcursor
ERase
GRPAge
GRPRint
HCopy
SPeed
Clear the text screen
Select plotting device
Enable/Disable the cursor, used in macros
Erase the graphics screen or go to a new page
Select graphics page on EGA adapters
Graphics screen dump (Use HCOPY)
Save plot for dump to hardcopy device
Set pen speed on pen plotters
This section contains commands that select and control your graphics devices. The DEVICE command
is used to select the active graphics device. If you are not sure of what devices are available,
DEVICE can give you a list of those configured. CLS clears the text screen, ERASE erases the graphics
screen. GRPRINT attempts to do a screen dump to the printer; however, very few printer and
screen configurations support this command. Other commands control the graphic devices such as
ENCURSOR which controls cursor availability; GRPAGE, which selects the video graphics page devices
with multiple pages; and SPEED which controls the pen speed on pen plotters. Finally there is
HCOPY. HCOPY is a vector save processor which saves your work as you go, and which can play back
the vectors at a later time to a hard copy device.
DEVICE
Syntax: DEvice {? | List | <device> | AUTO }
Syntax: DEvice [-OPTION <string> | -[NO]GRAPH | -[NO]TEXT ]
The DEVICE initializes a new plotting device. The list of currently configured devices can be obtained
using the command DEV LIST. Device names are specified in the DEVICES.DAT file and are generally
mnemonics such as EGA, VGA, BW, COL, CGA, HERC and AT&T (so almost IBM devices).
Other configured devices may include raster devices such as the HP LaserJet, HP pen plotters, true
Tektronix terminals and several other oddballs.
The actual device names and their characteristics are specified by the \GENPLOT\DEVICES.DAT file.
Appendix D includes details on modifying this file to change the characteristics of a given device or
to add new devices. While it is unnecessary to read Appendix D to use the default devices, it is
useful to at least scan the section of Appendix D on the relevent driver to learn the capabilities of
the device.
If no device is specified prior to a PLOT attempt, the environment variable GTERM is queried for a
default device. If this variable is not set, you will be prompted to enter a device name. To set
GTERM, include the DOS command SET GTERM=EGA or similar command in your AUTOEXEC.BAT file.
The command DEVICE AUTO also looks up the GTERM and sets the user value.
The options -GRAPH, -NOGRAPH, -TEXT and -NOTEXT may be specified at any time and do not reinitialize the device. These options cause the appropriate screen to be displayed (or hidden) on devices
where appropriate (and implemented). For example, these commands work with the EGA--VGA driver
4a-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
and are equivalent to the action of the [F10] key. The utility of these commands is usually confined
to macro files where control of the screen view is useful.
The command DEVICE -OPTION <text> may also be given at any time without reinitializing the
driver. The string parameter <text> is passed directly to the driver as a device dependent control
string. Only a few devices drivers, including EGA-VGA, support this capability — see the device
driver descriptions in Appendix D for details.
¾
»
GENPLOT: dev ega
GENPLOT: device ?
Currently configured devices:
SPECIAL
SPECIAL
00 00 x x x x 15 UNKNOWN
Special request code
VGA
EGA-VGA
02 -2 x x x
15 SCROLL*KEY*GRAPH VGA 16 col - 640x480
EGA
EGA-VGA
01 -2 x x x
15 SWAP*KEY*GRAPH
EGA 16 col - 640x350
BW
IBMCGA
01 00 x x x
01 SCREEN
CGA BW
- 640x200
CGA
IBMCGA
02 00 x x x
03 SCREEN
CGA 3 col - 320x200
6300
IBMCGA
03 00 x x x
01 SCREEN
PC 6300 device
STOCK
IBMBIOS
06 00 x x x
01 SCREEN
BIOS BW calls
HERC
HERCULES 01 00 x x x
01 SCREEN
Hercules graphics
HP300
HPRASTER 01 01
01 DISK*PRN
300 DPI HP Laser Jet
HP150
HPRASTER 01 02
01 DISK*PRN
150 DPI HP Laser Jet
HP75
HPRASTER 01 03
01 DISK*PRN
75 DPI HP Laser Jet
EPSON
RASTER
02 02
01 PRN
EPSON printer
DEBUG
DEBUG
01 00
x x 08 DISK*CON
Debug device
NULL
NULDRV
01 00
x x 08 SCREEN
Null device
Enter desired device code: (NULL) EGA
GENPLOT: device -graph device -notext
/* Show graph, no text
GENPLOT: device -option lw*notext*nograph /* Set the device options
GENPLOT:
½
¼
See Appendix D for complete information on devices.
Special Devices
In addition to devices directly specifying graphics screens or hardware plotting devices, there are
several special devices for unusual applications. These include SPECIAL, DEBUG and NULL. These
special names are mentioned only briefly here and Appendix D has additional details.
Special
The SPECIAL device is included for those occasions when an output device has not been previuosly
configured in the DEVICES.DAT file. The SPECIAL device will request the parameters necessary to
select a device, including the driver name, mode, sub–mode and output channel. These are explained
in Appendix D. If you use this command more than twice for the same device, you probably should
be adding the device to the DEVICES.DAT file. The primary purpose of the SPECIAL device is to try
out a device driver or particular I/O channel without constantly changing the DEVICES.DAT file.
Debug
This device sends the low level vector drawing commands to a disk file or to the screen instead of
an actual plotter. We use it to debug complex macro codes and new commands. You are welcome
to try it to see the level of complexity a driver must implement.
Null
This is the bit bucket. All plot vectors are drawn in vacuum. This device is commonly specified if
you are debugging a complex macro file also.
4a-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
Stock
The STOCK device is included in the default DEVICES.DAT file to test for hardware incompatibilities
in graphics screen. This device is a completely BIOS compatible plotting device for PC screens. It
requires only a CGA level BIOS implementation and draws in the b/w high resolution mode. There
are no special calls to video registers nor direct writes to screen memory; everything is done through
the BIOS interface. This driver should be able to plot to any machine that emulates IBM graphics
devices. The driver is ridiculously slow, but will work when CGA or EGA fail on video adapters
which are not strictly compatible. (Try it some day for fun to see how slow graphics would be if we
strictly adhered to the IBM BIOS convention).
CLS
Syntax: CLS
Clears the text screen and returns the cursor to home position.
Example: CLS
ERASE
Syntax: ERase
Erase the graphics screen if a device has been selected. Also resets the HCOPY file if enabled. On
non-video devices, ERASE does a FRAME operation causing the plot to be advanced to a clean page
of paper (if possible).
Example: erase
See also: CLS, AUTOERASE
GRPRINT
Syntax: GRPRint
GRPRINT attempts to produce a hardcopy of the video graphics display. It is implemented on some
PC devices and on Tektronix devices. This is a pixel copy of the display, and you end up with only
the screen resolution on your hardcopy device. It is generally better to redraw your graph directly
on the hardcopy device using either a macro file (section K) or using the HCOPY command described
below.
On PC devices, the GRPRINT command simply requests a print screen of the graphics view. A
driver for handling the graphics print screen must be installed to avoid gibberish. See the GRAPHICS
command (in your DOS manual) for CGA graphics.
For EGA graphics screens, very rudimentary print screen routines equivalent to GRAPHICS are included in the \GENPLOT\UTIL directory. The GRHP driver outputs EGA graphics to the HP LaserJet
and the GREPSON supports output to EPSON type printers. These files are TSR programs and must
be run before starting GENPLOT. They will remain resident until you turn off your computer.
Generally, it is better to actually plot to your printer because the printer resolution is substantially
higher than that of the screen. When you dump the screen, screen pixels are converted to some
equivalent pixels on the printer. Lines get wider and objects may lose their proportions because of
differing horizontal and vertical resolution.
Example: grprint
4a-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
See also: macros, HCOPY
ENCURSOR
Syntax: ENcursor {yes | no}
By default, cursor entry modes and cursor usage are enabled if the current graphics device implements a cursor. At times, however, it is desirable to disable cursor input completely, such as in macro
files. The ENCURSOR command allows the cursor to be disabled whether or not it exists. If disabled,
cursor requests will generate either an error message or take coordinates from the keyboard. The
ENCURSOR NO will disable the cursor and ENCURSOR YES will reenable it.
GRPAGE
Syntax: GRPAge <n>
On devices supporting multiple graphics pages, GRPAGE selects the active drawing page. In the
dual monitor configuration of an EGA adapter with 256Kb of video memory, two graphics screen
pages are available and either may be selected by this command. (Note: In single monitor EGA
configurations, page two is used for graphics and page one for text and hence multiple pages cannot
be specified.)
Example: grpage 1
SPEED
Syntax: SPeed <n>
For hardware pen plotters, SPEED sets the pen speed in device dependent units. On HP-GL devices
(the most common driver supporting speed setting) speeds are specified in cm/sec. Some pen types
and paper types may require a slower pen speed for good quality. Default within GENPLOT is 18
cm/sec. It is not possible at GENPLOT level to set different speeds for individual pens.
Example: sp 15
HCOPY
Syntax: HCopy [options]
HCOPY (hard copy) is a subprocess running under GENPLOT which captures and stores graphics
plot sequences in a file. The graphic sequences are stored at a very low level. For example, rather
than storing data points, the actual plotting vectors and pen changes which are sent to the plotter
will be stored. This information is sufficient to make a new copy of the plot on any device at the
natural resolution of that device; ie. a low resolution plot on the CGA can be transferred as a high
resolution plot on a LaserJet printer. WARNING: HCOPY is initially disabled when GENPLOT
starts and must be turned on before any plot sequences can be stored. If HCOPY is not enabled,
no vectors are saved and the plot cannot be redrawn on another device. HCOPY ON should be one of
the first commands executed (perhaps in your GENPLOT.INI file) if you intend to use the HCOPY
capabilities described below. Turning HCOPY ON as an afterthought once you have a particularly
pretty plot on the screen will not work.
HCOPY is most useful when you draw and annotate single purpose plots which you then want printed
on a laser or pen plotter. In this sense, it is a very fancy screen dump routine (if you remembered
to initialize it first). While HCOPY can save completed figures, macro files are much better suited
4a-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
to regenerating complete figures since they can be easily edited. HCOPY files, containing vector
strokes, are for all practical purposes uneditable; only minimal editing capabilities are provided.
HCOPY must be initialized using HCOPY ON before any vectors are stored. Once enabled, the
HCOPY vector file can be played back to the screen, another device, or saved to disk. Playback is
accomplished by the HCOPY DEV <device> command. HCOPY SAVE <file> saves the hard copy file
to disk for later replay. HCOPY UNDO undoes one graphics command and redraws the screen. Other
commands implement rudimentary editing capabilities. A relatively complex example of HCOPY
use can be found at the end of this section.
HCOPY files contain only a single page of plotting. Each time the screen is erased, the stored
vectors are also erased. Multiple plots on a single page are possible if AUTOERASE is turned off, and
you manually move each plots around the page using the OFFSET and SHRINK commands.
READ ME: HCOPY does not save the current screen nor does it dump the screen to a hardcopy
device. When it is enabled, it saves, into a file, each plotting stroke as it occurs. When requested,
HCOPY can replay this file to any other device. Obviously, HCOPY cannot replay vectors that are
drawn before it is enabled. The HCOPY file will be created in the directory pointed to by the TMP
variable or in the current directory. If you break out of GENPLOT while HCOPY is active, a file
such as T$0000.HCP will remain.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
dev ega
hcopy on
plot...
create...
ov...
hcopy dev /
hcopy dev postscript
plot...
hcopy dev postscript
/* start hcopy
/* some commands
/* replay it to the screen
/* do it on the printer
/* replay it to the printer
¼
Help
Syntax: HCopy HELP
Displays the Hcopy commands.
¾
GENPLOT: hc help
HCOPY commands:
HElp
ON
OFF
DEVice PLot
UNDO
GENPLOT:
½
»
APpend
SAVe
PAuse
MArk
END
LABel
RESet
LIST
STATus
BACkup
¼
On
Syntax: HCopy ON
4a-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
Starts or resumes saving the plot information to the current HCOPY file, or opens a new HCOPY file
if no current one exists. The temporary file containing the vector strokes is opened in the directory
pointed to by the TMP environment variable. If TMP is undefined, the file will be opened in the current
directory. The temporary filename is always of the form T$xxxx where xxxx is a number starting at
0000. The filename will always be unique and will not overwrite existing files in the TMP directory.
Example: hc on
See also: HCOPY OFF, HCOPY END
Off
Syntax: HCopy OFF
Synonym: PAuse
HCOPY OFF temporarily stops saving plot information to the HCOPY file. All information in the
current file is retained. Use HCOPY ON to restart collection of data.
WARNING: Some commands which change parameters while HCOPY is off will not be recorded
when a HCOPY ON is subsequently executed. Pen speed, for example, will not be remembered when
the plot continues.
Example: hc off
See also: HCOPY ON
End
Syntax: HCopy END
Stop saving plot information and close the file. The user is asked whether the HCOPY file should
be deleted as it is closed. Normal response is YES.
Example: hc end
Undo
Syntax: HCopy UNDO [-NORedraw]
The HC UNDO command will effectively cause HCOPY to forget about the last command line which
caused plotting. Since the vectors cannot be removed from the screen, the entire plot is redrawn.
The -NOREDRAW option will bypass this redraw, but the vectors will still be erased from HCOPY
memory.
The UNDO will undo all plotting which resulted from the last command line, including macros. In
the example below, the effects of both label commands and all effects of the MORE LABELS macro will
be undone by the single HC UNDO command.
Example: ANNO LABEL / ’Hello’ LABEL / ’Mike’ XEQ MORE LABELS
Example: hc undo
UNDO is not guaranteed to always work. Generally it will be successful if the HC UNDO is done
immediately after the vectors are drawn and no intervening commands modify the plotting common
blocks.
Device
4a-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
Syntax: HCopy DEVice [<device> | /]
The HCOPY DEV <device> causes the contents of the current HCOPY file to be replayed (plotted)
on the specified device. Specifying / as the <device> will cause the file to be replotted to the current
device (repaint the screen). A common usage would be to execute an HCOPY DEV HP300 to make
a copy of the current screen plot for your notebook (again assuming that you remembered to turn
HCOPY ON.
¾
»
GENPLOT: hc on plot ov c1
GENPLOT: hc dev hp7475
/* Send current Hcopy file to plotter
/* Replot Hcopy file on the screen
GENPLOT: hc dev /
½
¼
Save
Syntax: HCopy SAVe <file>
The HCOPY SAVE command saves the current HCOPY vector file to the specified disk file. If HCOPY
was active, a new file is opened. Once you have a good plot, HCOPY SAVE <file> will safely put it
on disk for plotting later, perhaps after you go home for dinner. If <file> is specified as /, HCOPY
will leave the file with the temporary name of the form T$0000.HCP. The default file extension for
all HCOPY files is .HCP.
Example: hc save graph1.hcp
See also: HCOPY APPEND
Plot
Syntax: HCopy PLot <file name>
HCOPY PLOT <file> causes the vectors stored in the specified HCOPY file on disk to be plotted to the
currently active device. (Note the difference between this command and HCOPY DEVICE command.)
Any HCOPY file currently collecting vectors is paused to avoid duplicating the information. This
command is normally used at the end of a long day to plot a collection of HCOPY files which have
accumulated to disk — you can go home for a well deserved dinner.
Examples:
>> hcopy plot tex5b.hcp
>> for %f in (t$*.hcp) do dev hp300 hc plot %f dev null
See also: HCOPY SAVE
Append
Syntax: HCopy APpend <file name>
APPEND opens a previously saved HCOPY vector file and positions it at the end. Subsequent plot
commands are then appended to this file. This command should always be immediately followed
by a HCOPY DEV / command to plot the the information currently in the file to the graphics screen.
The plot will also re-establish the graphics environment properly.
4a-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
WARNING: Many a saved file has been lost by opening them with APPEND and then proceeding
to erase the screen. Remember that any screen erase will delete all previously stored vectors in the
HCOPY file. Moral of the story is to copy the .HCP file to another name before using APPEND.
Example: hc ap \plots\plot1a hcopy dev / ov test
See also: HCOPY SAVE
Label
Syntax: HCopy LABel <text>
LABEL and its companion MARK are provided for minimal editing capability in the HCOPY file. Both
set a marker in the HCOPY file and labels the marker either with default text (MARK) or with the
specified text (LABEL). The HCOPY BACKUP command at a later time will rewind the file to this point.
HCOPY LIST will provide a list of all markers currently identified.
HCOPY MARK or HCOPY LABEL should be executed routinely during a complex plot. If an error is made
after a marked point, it is a simple matter to backup the hard copy file to the last good position.
The current pen color may remain in effect when you backup! If you change colors between the mark
and backup you will need to change it again.
¾
»
GENPLOT: axis
GENPLOT: hc label one
Position:
10 Text: ONE
GENPLOT:
½
¼
See also: HCOPY MARK, HCOPY BACKUP
Mark
Syntax: HCopy MArk
Sets a mark in the Hcopy information. HCOPY MARK is synonymous with HCOPY LABEL except that
no text is included with the mark in the HCOPY file. See comments in LABEL above.
¾
»
GENPLOT: hc mark
Position:
10 Text:
GENPLOT:
½
¼
See also: HCOPY LABEL, HCOPY BACKUP
Backup
Syntax: HCopy BACKUP
Synonyms: BACKspace
HCOPY BACKUP rewinds the HCOPY file to the last marked point. Any vectors drawn after the MARK
or LABEL command are forgotten as far as HCOPY is concerned. The vectors themselves are not,
4a-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
however, erased from the screen. Use HCOPY DEV / to redraw the plot minus the deleted vectors. You
can backup multiple levels as long as subsequent BACKUP commands are given before any additional
vectors are drawn. See HCOPY LIST to obtain a listing of the current marks in the file.
Example: hc backup
See also: HCOPY LABEL, HCOPY MARK, HCOPY LIST
List
Syntax: HCopy LIST
The HCOPY LIST command lists all marks and their associated text for the active HCOPY file.
¾
GENPLOT: hc list
Current saved points and
Position:
25 Text:
Position:
10 Text:
Position:
0 Text:
GENPLOT:
½
»
text:
TWO
ONE
Start
¼
Reset
Syntax: HCopy RESet
HCOPY RESET clears all vectors and marks in the current HCOPY file and resets the file to the
beginning. This reset is also automatically done by any screen erase operation, including normally
PLOT, AXIS or ERASE.
Example: hc reset
Status
Syntax: HCopy STATus
Gives the HCOPY status. Displays things like marks, labels and the current HCOPY file name.
¾
»
GENPLOT: hc status
Hard copy file: T$0000.HCP
Save of vectors enabled
GENPLOT:
½
¼
4a-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section A – Device Control
AN HCOPY EXAMPLE
¾
GENPLOT: hc on
GENPLOT: hc list
Current saved points and text:
Position:
0 Text:
GENPLOT: axes
GENPLOT: hc label ’after axis’
Position:
10 Text: after axis
GENPLOT: create y = sin(x) ov
GENPLOT: hc undo
GENPLOT: ov -pen 2
GENPLOT: hc label after ov
Position:
25 Text: after ov
GENPLOT: hc list
Current saved points and text:
Position:
25 Text: after ov
Position:
10 Text: after axis
Position:
0 Text: Start
GENPLOT: plot
GENPLOT: hc list
Current saved points and text:
Position:
0 Text: Start
GENPLOT: hc status
Hard copy file: T$0000.HCP
Save of vectors enabled
GENPLOT: hc end
Delete HCOPY file? (YES) no
HCOPY saved: T$0000.HCP
GENPLOT: hc status
Hard copy not initialized
GENPLOT: hc on
GENPLOT: plot
GENPLOT: hc status
Hard copy file: T$0001.HCP
/*
a
Save of vectors enabled
GENPLOT: hc end
Delete HCOPY file? (YES) yes
GENPLOT:
½
»
/* turn on hcopy
/* check the current list
/* plot the axes
/* label the point in the plot
/* create, overlay sin(x)
/* Undo the overlay
/* Redo the overlay in pen 2
/*
and label it
/* examine the current list
/* replot the graph
/* the hc file has been rewritten!
/* get status
/* end hcopy
/* the file is saved
/* hcopy is off
/* on again
/* replot
/* get the status, note that
new file is selected
/* stop again
/* trash the file
¼
4a-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
B. BASIC PLOTTING
AUTOEras
AUTOIDs
FILL
GRID
IDENTify
IDS
NPOint
OVerlay
PLot
TITle
UNZoom
ZOOM
Controls if PLOT or AXIS erase the screen
Set automatic legend creation by OVERLAY and PLOT
Fill a region with solid color (CRT only)
Draw a simple grid on the plot
Draw a legend entry with specified text
Draw a legend entry with default text (filename)
Set point plotting interval
Overlay a curve on the current plot
Plot a curve, function or fit
Put a title on the top of the graph
Return to normal plot scales from a ZOOM
Expand the plot around a specified region
The basic commands for plotting are treated in this section. In addition, the commands which create
a legend of the curves on the plot are described in this section. See IDS, AUTOIDS, IDENTIFY and
TITLE below.
PLOT
Syntax: PLot [options]
Plots the current data set, using whatever options are set along with reasonable default values for
those options that you have not specifically set. Formally equivalent to AXIS OVERLAY. Usually the
screen is erased and a complete plot is done. This is all controlled with various options which is why
there are so many commands in GENPLOT. To plot an second curve over the first see the OVERLAY
command.
The full syntax is:
Syntax: PLot [ [-Curve] <archive>] [options]
Syntax: PLot [-FIT][-From <r>][-To <r>][-Points <n>|-By <r>][options]
Syntax: PLot [-Func <fnc>][-From <r>][-To <r>][-Points <n>|-By <r>][options]
Syntax: options
options: [-Bargraph | -Histogram | -PT label]
options: [-SYMbol <n>][-LType <n>][-L&S]
options: [-PEN <n>][-LINEwidth <lw>][-SYMSize <sz>]
options: [-EXClude [<curve> | -SELF | PLOT] ]
options: [-IDS | -IDENTIFY <text>]
options: [-ERRX <exp> | [-ERRXL <exp>][-ERRXH <exp>]]
options: [-ERRY <exp> | [-ERRYL <exp>][-ERRYH <exp>]]
options: [-ERRWIDTH <x> <y>]
If AUTOAXIS is turned off, this command is identical to OVERLAY. If AUTOERASE is turned off, the
screen will not be erased prior to drawing the axis.
4b-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
The options available in the PLOT command may also be specified by a variable string. For plotting
the main curve, options are taken from the string variable PLOT:OPTS; for -FUNCTION or -FIT
modes, the options are taken from FUNCTION:OPTS; and for archived curves, the options are taken
from <c1>:OPTS where <c1> is the name of the curve. The options specified by these variables are
parsed first and hence typed options can override the string options.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
pl
/* Plot the current data set
pl data1 -sym 3
/* Plot archived data set using symbol 3
/* Define a function
define s(t) = sin(t)
pl -f s(x) -p 50
/* Overlay 50 points from the function
declare PLOT:OPTS = ’-errx sqrt(x) -erry abs(sqrt(y))’
plot -lt 1
/* Options taken from PLOT:OPTS also
¼
See also: OVERLAY, AUTOAXIS, AUTOERASE
<archive>
Syntax: PLot [-Curve] <archive name>
Plots the data contained in the named archived curve. See the ARCHIVE command for information
on saving curves in memory. The -CURVE specifier is optional and is normally not given.
See also: ARCHIVE, RETRIEVE
–Function
Syntax: PLot -Function <fnc> [-From <r>] [-To <r>] [-Points <n> | -By <r>]
The specified function <fnc> is expanded into a temporary curve over the specified range and
plotted. The options and function correspond to definitions in the CREATE command. The IDS
string is set to the specified function and additional options for the plot are taken from the string
variable FUNCTION:OPTS. See the CREATE command for further details on specifying the range and
function.
The -FIT option is equivalent to the option -FUNCTION FIT(X).
–PT label
Syntax: PLot ...
-PT label
The data is plotted with the number corresponding the position of the point in the data set. For
point 1, a 1 is drawn centered at the position where the data point would lie. The curve cannot
contain more than 9999 points (which would be unbelievely slow and unreadable anyway).
¾
»
GENPLOT: symsiz 0.50 plot -lt 0 -sym 1
GENPLOT: symsiz 0.18 ov -pt_label
GENPLOT:
½
/* Draw large circles
/* Put numbers inside
¼
See also: SYMBOL, SYMSIZE
4b-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
–Fit
Syntax: PLot -FIT [-From <r>] [-To <r>] [-Points <n> | -By <r>]
This form of the PLOT command is used to plot the results of a curve fit. It has meaning only
after the FIT command executed. The command is identical to PLOT -FUNCTION FIT(X) where the
function FIT(X) is defined by the FIT command. Generally you want to compare your fit against
the data so you would want to use OVERLAY instead of PLOT; the syntax is the same.
¾
GENPLOT: plot c1 -lt 0 -sym 1
GENPLOT: fit c1 linear ov -fit -lt 1
GENPLOT:
½
/* Draw data
/* Overlay the fit
¼
–Symbol
Syntax: PLot ...
-SYMbol <n>
Overrides the symbol number to be used on the overlay. It is not necessary at this level to set ltype
to zero, it will be done automatically. However, you may specify -LT <n> after the -SYM setting
to get lines and symbols using L&S. The setting of the symbol within the main program remains
unchanged. See the SYMBOL command for more information about available symbols.
See also: SYMBOL
–Ltype
Syntax: PLot ...
-Ltype <n>
Sets the line type for this plot, temporarily overriding the current linetype setting in GENPLOT. See
the LTYPE command for more information about the types available. Does not change the current
line type set by the LTYPE command. A linetype of zero causes symbols to be plotted instead of the
line.
See also: LTYPE
–L&S
Syntax: PLot ...
-L&S
Draws a symbol at each point using the current SYMBOL then connects them with a line using the
current LTYPE. The line does not go through the symbols.
Almost equivalent to the command sequence below except a slightly different exclusion algorithm is
used.
>> plot -lt 0 ov -lt 1 -exclude plot
–Pen
Syntax: PLot ...
Synonym: -COLOR
-PEN <n>
Sets the color on video devices, on plotters it selects the pen number. It temporarily overrides the
current symbol setting in GENPLOT. It does not change the current color set by the COLOR or PEN
commands.
4b-3
c
-Computer Graphic Service, Ltd. °1988-2007
»
June 5, 2007-
Command Reference
Section B – Basic Plotting
See also: PEN
–LINEwidth
Syntax: PLot ... -LINEWidth <lw>
Synonym: -LW <lw>
This options sets a temporary line width to be used for the current overlay only. The line width is
specified in units of 0.007 inches, but need not be an integer. The axis line widths are not affected
by this option nor is the setting in the main module changed. See the LINEWIDTH command for
additional details.
–SYMSize
Syntax: PLot ...
-SYMSize <size>
This options sets a temporary symbol size to be used for drawing data as symbols (or -PT SYMBOLS).
The size is specified in inches. The setting of symbol size in the main module is unchanged by this
option. See the SYMSIZE command for additional details.
–IDS and –IDENTIFY
Syntax: PLot ...
Syntax: PLot ...
-IDS
-IDENTIFY <text>
The options -IDS and -IDENTIFY cause the current curve to be identified in the legend by symbol
or line type followed by a descriptive text. For -IDS, the text is the default IDS of the curve. With
-IDENTIFY, the text immediately follows the option and should be enclosed in quotes. See the
IDS and IDENTIFY commands for additional information. This option formats -IDS and -IDENTIFY
should be used if either the symbol or linetype is overridden in the plot command and a legend is
needed.
¾
»
GENPLOT: PLOT -LT 1 -IDS
GENPLOT: OVERLAY C2 -SYM 7 -identify ’Modified fit’
½
¼
See also: IDS, IDENTIFY
–Bargraph
Syntax: PLot ...
-Bargraph
Plot the data as a bargraph. Each point is drawn as a rectangle from the X axis to the Y value, with
the sides of the rectangles centered between X values. The data is not sorted by this command and
hence we strongly suggest the use of SORT before using this option (unless you like strange plots).
4b-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
¾
»
0.12
Fraction of Samples
0.10
0.08
0.06
0.04
0.02
0.00
0
10
20
30
40
Particle Size
½
¼
–Histogram
Syntax: PLot ...
-Histogram
Plot the data as a histogram. Almost the same as the BARGRAPH mode except that the vertical
line segments do not extend down to the axis. A true histogram may be generated from the data
by TRANSFORM Y BIN <dx>
¾
»
0.12
Fraction of Samples
0.10
0.08
0.06
0.04
0.02
0.00
0
10
20
30
40
Particle Size
½
¼
4b-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
–ERROR bars
Syntax: PLot ... [[-ERRXL <exp>][-ERRXH <exp>] | [-ERRX <exp>]]
Plot ... [[-ERRYL <exp>][-ERRYH <exp>] | [-ERRY <exp>]]
Plot ... [-ERRWidth <x> <y>]
The error bar options specify the size of error bars in each of the directions on the plot. Independent
error bar expressions may be specified for plus and minus on X and Y. The -ERRX and -ERRY options
cause the corresponding expression to be used for both the plus and minus error of the corresponding
error. -ERRXL sets the lower (minus) error bar in X and -ERRXH set the high (plus) error bar. If an
expression is not set, it defaults to zero and is not drawn.
The option -ERRWIDTH is sticky (i.e. needs only be set once in a GENPLOT session) and determines
the size of the cross bar at the end of each error bar. The <x> specifies the size (in inches) of the
cross bar for X error bars. A size of zero generates a line only.
The expressions for the error bars may be arbitrarily complex but are more commonly either a simple
expression (or constant like 0.37) or the elements of an error bar curve (ERROR:X). See the Function
Evaluator section for more details about expressions. For a data point at 5.0, an error datum of 0.5
draws an error bar between 4.5 to 5.5.
A data file might consist of columns of data and the corresponding errors. To plot this data, the
error data is read into a separate curve and the expressions are set to point to this other curve.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
/* plot data with error function
plot -errx sqrt(x)
read datafile -col 3 4
/* read columns 3 and 4 for error
archive erxy
/* archive the error data
read datafile
/* read the data columns 1 and 2
plot -errx erxy:x -erry erxy:y /* plot error bars for both
¼
¾
»
10
Data 3/3/88
Spline fit
4th order polynomial fit
1
0.1
.01
.001
0
2
4
6
8
10
Saturation level
½
¼
4b-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
–Exclude
Excluding Symbols from Line Drawing
Syntax: plot ...
-EXCLude [<curve> | -SELF | PLOT]
For those who are doing plots for publication, it is sometimes necessary to keep lines of a curve
from going through the data point symbols. The -EXCLUDE option of PLOT and OVERLAY is designed
to handle these cases. EXCLUDE prohibits drawing any vector within a circular region, of radius
proportional to the current symbol size, around each data point in a curve. The vectors are clipped
so that they just touch, but do not enter, the circular exclusion region. This command is extremely
slow if the number of data points becomes large (100 or greater) since every vector stroke must
search through the entire list of points.
The data points to be excluded are normally specified as a curve name (see ARCHIVE). The archived
curve should contain all of the points of interest since only a single curve may be specified. For
drawing lines, this results in lines connecting the data points which do not pass through the actual
symbols centered on the data.
The other option is to specify the current curve for exclusion -SELF. For symbols, this creates a
layering effect; i.e. no symbol will draw in the region of a previous symbol. Note that because the
exclusion area is circular, perfect exclusion works only for symbol type 1, circles.
WARNING: The -SELF option only works for the main curve. Specifying a curve, -FIT or FUNCTION will cause -SELF to fail. When plotting a function or fit, the current data set can be
selected by specifying PLOT as the archive curve name.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
read t1 archive t1 read t2 archive t2 retrieve t1 -append archive both
fit poly 3 reg bot 0 8 axis lt 0
symsiz 0.30 ov t1 -sym 2 -identify ’Curve T1’
symsiz 0.25 ov t2 -sym 1 -identify ’Curve T2’
ov -fit -lt 1 -exclude both -identify ’Polynomial Fit’
¼
4b-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
¾
»
70
Curve T1
Curve T2
Polynomial Fit
60
Velocity (mph)
50
40
30
20
10
0
0
2
4
6
8
Time (sec)
½
¼
¾
»
GENPLOT: create y = fit(x) -points 50
GENPLOT: symsiz 0.25 plot -lt 0 -sym 1 -exclude -self
GENPLOT:
½
¼
¾
»
70
Measured Data
Polynomial fit
60
Velocity (mph)
50
40
30
20
10
0
0
2
4
6
8
10
Time (sec)
½
¼
OVERLAY
4b-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
Syntax: OVerlay (All options are the same as PLOT)
This command is used to plot more than one curve on the same graph. The given data is plotted
as an overlay on the current graph. It does not erase the current graph and will use the same axes
and labeling. If no curve is specified, the current data set will be plotted. OVERLAY can be used in
conjunction with LTYPE to plot lines and symbols of a data set. See PLOT above for an explanation
of the options. PLOT and OVERLAY are identical except that OVERLAY does not erase the screen and
does not draw an axis.
The full syntax is identical to that of PLOT.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
overlay
ov data1 -pen 2
define s(t) = sin(t)
ov -f s(x) -p 20
/*
/*
/*
/*
Overlay current data set on plot
Overlay an archived data set in color 2
Define a function
Overlay 20 points from the function
¼
4b-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
NPOINT
Syntax: NPOint <n>
Determines the number of data points which are plotted. NPOINT 1 causes plot or overlay to draw
every point while NPOINT 2 causes only every other point to be drawn.
GRID
Syntax: GRID [-PEN n | -COLor n] [-LType n] [-VECsize x]
Normally, only the outside of an axis is drawn with major and minor tick marks. Occasionally, it is
convenient to have grid markings over the entire plotting area. The GRID command causes lines to
be draw across the plot at every major tick mark, much like graph paper. The major tick correspond
to the current axes against which X and Y are plotted (see PLX and PLY commands). The AXCTRL
-GRID command can provide a much finer grid at minor tick marks for detailed work, but only draws
solid lines.
The type and color of the GRID may be controlled with by the options. The settings of these switches
are sticky, i.e. they retain their new value from one execution of the GRID command to the next.
Options:
-pen <n>
-color <n>
-ltype <n>
-vecsize <x>
Selects pen <n> to be used for subsequent grids
Synonymous with -PEN above
Sets line type for GRID. Default is type 4 (dots). See the LTYPE
command for examples of line types.
Sets the basic vector size for LTYPEs other than 1. Default is 0.01
inches. Smaller numbers give dots closer together.
¾
GENPLOT: grid -pen 2 -ltype 1
GENPLOT: grid
½
»
/* Draws grid with pen 2 and solid lines
/* Draws grid with previously set values
¼
See also: AXCTRL
FILL
Syntax: FILL [x1 x2 | /]
Fills a region. The region is specified by giving an (x,y) coordinate or by using the cursor (/ mode)
to select a point within the area to be filled. The area will be filled with the current color up to the
first border found of the same color. Be careful, if the region does not have a complete border of
the current color, FILL will leak out and fill your entire plot.
Note: Only the EGA and VGA drivers support this command currently. Use it for cute effects only.
Filling gets too close to business graphics and will probably never be fully implemented.
Example: fill /
AUTOERASE
Syntax: AUTOEras {ON | OFF}
4b-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
Normally the screen is automatically erased (a new page is started on paper devices) when a PLOT
or AXIS command is executed. AUTOERASE controls this automatic erasing feature. The default is
ON. Turn AUTOERASE OFF and use OFFSET to place several graphs on a single sheet of paper.
Remember that once drawing has occurred, it is not erasable regardless of the device. Think of
GENPLOT graphics as a pen drawing on paper. You can draw over it, but once it is there the only
way to change it is to start a new page. You don’t want to turn AUTOERASE OFF to change your axis
scale without replotting your data for example. What will happen is that you will get both your old
and your new axis on the screen.
autoerase off
See also: AXIS, OFFSET
ZOOM
Syntax: ZOOM
The ZOOM command causes a region of the plot to be expanded to fill the entire plot area. The scales
for the X and Y axis are modified so as to match the area selected by a cursor. A new axis is drawn
and the current data set is plotted using the current LTYPE, SYMBOL and PEN settings.
ZOOM obtains the high and low coordinates from the cursor and effectively executes the command
sequence:
REGION BOT xlow xhigh REGION LEFT ylow yhigh PLOT
The original sized plot can be retrieved using UNZOOM. Multiple ZOOMS are possible. UNZOOM always
returns to the original screen regions.
The region is selected with the cursor in box mode. The cursor is attached to one corner of the box.
Depending on the mode, the cursor keys move either the entire box or just the attached corner.
Box Cursor Key Controls
<DEL>
Toggles between rigidly moving the box and moving only one corner
<SPACE>
Switches from one corner to the diagonally opposite corner
<SHIFT>
Momentarily switches the cursor speed as long as held down
<INS>
Toggles the speed of cursor movement
<CR>
Enters the coordinates
Note that this does not zoom in on a section of the screen but actually replots the data within the
given section. Only data in the current data set is zoomed. If you have multiple curves on one plot,
you will have to replot them with the new regions set.
See also: UNZOOM
UNZOOM
Syntax: UNZoom
This is the undo of the ZOOM command. The first ZOOM executed saves the settings of the regions.
UNZOOM restores these settings and executes AXIS OVERLAY. If any regions have been changed by
the user since the ZOOM command, they will be lost when UNZOOM is executed. Only data in the
current data set is replotted by UNZOOM. Subsequent UNZOOM commands have no effect until a new
ZOOM command is executed.
See also: ZOOM
4b-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
AUTOIDS
Syntax: AUTOIDs {ON | OFf}
When AUTOIDS is enabled, any PLOT or OVERLAY command will automatically draw the curve ID in
the legend area using the IDS command. The default is AUTOID OFF. The position of the legend can
be changed using IDENTIFY options or SGRAPH parameters. See the IDS command below for further
information..
IDENTIFY
Syntax: IDENTify [<text>] [-PLACE <x> <y>] [-SKIP] [-CLOSE]
The IDENTIFY command is identical with the IDS command below except that the text is specified
with the command. The text string is not required if any of the options are given; in such cases no
text will be drawn. The legend in GENPLOT consists of an example section of the current line type
or symbol followed by the specified <text>. By default, the legend is drawn in the upper left corner
of the plot. IDENTIFY and IDS are very similar and the command strings let ids = ’my text’
ids and identify ’my text’ cause the same legends to be placed on the screen.
The options -PLACE, -CLOSE and -SKIP operate as in IDS. See IDS for more informations.
IDS
Syntax: IDS [ [-CURVE] <curve>] [-PLACE <x> <y>] [-SKIP] [-CLOSE]
The IDS command causes the text associated with a curve to placed on the screen as a legend
identifier with the current linetype or symbol type. This provides a method of identifying curves
and symbols with text describing the data set. AUTOIDS interacts with this command by causing
an IDS command to be automatically executed immediately following any plot or overlay operation.
If AUTOIDS is enabled, the identifier will have the correct symbol and linetype even if the default
values are overridden with plot command line options. If a legend is not generated automatically, the
legend generated by IDS will use the current settings of LTYPE and SYMBOL. The legend, by default,
is drawn at the upper left of the plot.
The optional specification of a curve causes the IDS value to be taken from the specified curve rather
than the main curve. For the main curve, the text for the identification is stored in a variable IDS,
which may be modified using the LET command or viewed with the STATUS command. This IDS
string is initially set to SUBROUTINE PASSED VALUES. Reading data causes the filename to be placed
in the IDS string. Creating a data set with the CREATE command will set IDS to the equation used.
The value maybe set to any string using LET IDS = ’my text’.
For archived curves, the text is the string associated with the curve name itself. The ARCHIVE
command will save the current IDS setting with the data. The string may be changed at anytime by
letting the curve name equal a string LET C1 = ’Data from first run’. Retrieving a curve also
retrieves the value of the IDS string.
–Place
The option -PLACE should be used only for the locating the first legend entry. This option requests
the absolute inch position of the upper left corner of the legend. No text will be drawn above or to
the left of this point and the -CLOSE box will extend just to the point. If the default is accepted for
the X position (or a / is typed), the cursor is enabled and the position is set to the cursor point.
4b-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section B – Basic Plotting
SGRAPH can also be used to change the default position and characteristics of the legend. The
SGRAPH parameters IDLSKP, IDTSKP change the starting position of the legend, IDSIZE changes
the label sizes, IDSPAC changes the spacing between lines, and IDLSIZ specifies the length of the
example line. Note that the units for specifying the position via SGRAPH are different than in PLACE. SGRAPH parameters must specify displacements from the axis edges while -PLACE calculates
the displacements from an absolute location. See the SGRAPH command for further information on
changing these parameters.
–Skip
The option -SKIP may be specified one or more times and causes a single blank line to be inserted
in the legend table each time.
–Close
The -CLOSE option closes the legend box by drawing a solid line around all the identifying labels
and text drawn so far. The text drawn by this IDS will be drawn first (if appropriate) and will also
be enclosed by the box.
See also IDENTIFY.
TITLE
Syntax: TITle <text>
The TITLE command puts a title on graph. The text is automatically centered above the top of the
plot, roughly where a title to a top axis would have been placed. If the automatic positioning of the
title is not required, the ANNOTE LABEL command provides greater flexibility. TITLE is primarily used
in automatic macros which create lots of similar plots. WARNING: If the TOP axis is enabled
TITLE will overwrite the axis labelling.
4b-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
C. READ/WRITE/USE DATA SETS
ARCHive
REad
RETRieve
SHow
STatus
WRite
Save the current data set under a name
Read a data file or digitize data
Make an archived data set the current data set
Display the current data set as x,y pairs
Display the data set information
Write the current data to a disk file
This section describes commands which read, write, temporarily save and list information about
data sets. A data set is a collection of X,Y points representing a curve on a plane. In this section,
the READ, WRITE, STATUS, SHOW, ARCHIVE and RETRIEVE commands will be discussed. The READ and
WRITE commands provide for reading and writing the main curve data set to disk files. The STATUS
command provides general information about the data in curves, including the number of points in
the data set and the minimum/maximum range of the data. SHOW provides a convenient method to
print out the curve data to the screen. The ARCHIVE command temporarily saves the main curve
data set to RAM memory as a named curve, and the RETRIEVE command can be used to retrieve a
named data set to the main curve. Some commands also allow direct operation on named data sets.
(Reminder, the main curve is the default storage buffer — most commands work on the main curve
if no other curve is specified.)
DATA FILES
GENPLOT supports two type of external (disk stored) data files, a free format ASCII file and a
special unformatted BINARY data file. The detailed format of each data file is given in Appendix
F. The term ASCII refers generically to a character based data format (ie. human readable), and
not to a particular data structure. GENPLOT will successfully read ASCII data files of almost
any format which consists of columns of numbers (or expressions) separated by commas, blanks or
tabs. Any given column in the file may be read as the X or Y variable, or multiple columns may be
read into predefined arrays (see the Function Evaluator). Only one data point (X,Y) will be read
from each line and any expressions used must evaluate to simple real numbers. You can create data
files using any text editor of your choice (EDLIN if you’re crazy enough). Most text editors will
produce files compatible with GENPLOT. The simple test is to write a file, and then type it using
the DOS TYPE command. If the file appears as separate lines of data, GENPLOT will probably
be able to read it. In most cases, GENPLOT cannot read data written with word processors that
use imbedded formatting commands such as WORDPERFECT, DW4, etc. Check if your editor
provides an ASCII output mode.
GENPLOT BINARY files also consist of multiple columns of numbers; however, the data are stored
in a specific, highly structured format which provides flexibility and very rapid data reading. Details
on the format are given in Appendix F along with an example program to generate binary files
directly. Note that BINARY files may be created outside of GENPLOT by a user using only either
the Ryan–McFarland F77 compiler or the IBM Professional FORTRAN compiler. Other compilers
will probably produce incompatible data files. GENPLOT includes the ability to write BINARY
files itself; see the WRITE command below.
4c-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
The BINARY data format is preferable for large data sets. Reads from BINARY files are substantially faster (factors of 10–100 times) than ASCII data reads, but are limited in the structure and
flexibility of the data format. ASCII file flexibility comes at the expense of data reading speed and
file size. One useful way to generate BINARY files is to let GENPLOT read an ASCII file and then
write it back out as a BINARY file.
READ
Syntax: REad [-CURVE <curve>] {<file>}
options: [-APpend] [-Binary|-AScii|-USER]
options: [-COLumns <n><n>] [-LIST <..>]
Syntax: REad %DIGITIZE [-HOLD] [-APPEND] [-TABLET <tab>]
Synonyms: GET <file> [same options]
The READ command is reads data files into the main curve. The file must consist of ordered pairs
(X,Y) on successive lines of the file, if ASCII format, or columns of numbers stored in the BINARY
format. The columns of numbers in an ASCII file can be separated by commas, spaces or tabs. You
may also put more than one column of numbers in your ASCII data file, ie. data from a spreadsheet.
If you wish to plot the fourth column of numbers (y variable) against the second column of numbers
(x variable), these columns may be read by typing READ <file> -COLUMNS 2 4. The default is to
read only the first two columns.
By default, the command assumes first that the file is stored in BINARY format. If the BINARY
read fails, an ASCII file format read is attempted. Current data in the main curve is deleted unless
the -APPEND option is specified. Data for X is then read from column 1 and data for Y from column
2. These defaults may be overridden using the options listed below.
Data may be read directly into an existing curve by specifying the -CURVE <curve> option. The
curve will not be created and must be of sufficient defined size to hold the data set. See ALLOCATE
to allocate a curve for the read. Note that the -CURVE option must immediately follow READ and
will preceed even the filename.
Options:
-BINARY
-ASCII
-APPEND
-COLUMNS
-LIST
Requires the file to be BINARY format.
Requires the file to be ASCII format.
Appends the file data to the data currently in the main curve. Data
may be appended to the main curve up to the maximum number of
points allowed in the main curve. On ASCII files, partial reads are allowed and data is read as long as space exists. A BINARY file will be
read only if the entire data set fits.
Specifies the columns for the X and Y points. Default is -COLUMN 1 2.
By default, column 0 is the point number within the array, allowing one
to read a file with only a single column and assign the other variable to
the point number.
READ <file> -COLUMN 2 1 will reverse the order of X and Y.
READ <file> -COLUMN 0 1 will read a single column of data to the Y
array and put the point number into X.
Does a read to a named set of array variables. Will not modify the
main curve. See detailed description of –LIST below.
4c-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
-USER
%DIGITIZE
Calls a user written routine to read the data. See Appendix S under
the USER$ INTERFACE for more information.
Reads data from a digitizing device.
Incompatibilities: The -LIST and -APPEND options are mutually exclusive.
¾
»
GENPLOT: read file1 -ascii -column 2 1
Curve ID: file1.dat
Current data consists of
19 points. Max: 2048
X minimum = 0.00000E+00, maximum =
39.900
Y minimum = 0.00000E+00, maximum =
4.1600
½
¼
Entering Data Directly
Data can be entered directly into the main curve by specifying CON as the filename. CON is the
filename corresponding to the console, so you are just reading from the console file (aren’t file
mapped devices fun). After specifying the console by READ CON, data is entered as X,Y pairs one
per line. ASCII format is assumed since no one wants to type the binary codes. Data entry is
terminated using the end of file character, ∧Z on the PC (control Z).
¾
»
GENPLOT: read con
1 2
2 3
3 4
4 5
6 7
∧ Z
Curve ID: con
Current data consists of
6 points. Max: 2048
X minimum =
1.0000
, maximum =
6.0000
Y minimum =
2.0000
, maximum =
8.0000
GENPLOT:
½
¼
%DIGITIZE
Syntax: %DIGITIZE [-HOLD] [-APPEND] [-TABLET <tab>]
The digitizing option, selected by specifying %DIGITIZE as the filename, allows data to be digitized
from the current graphics device or special graphics tablet. Although digitizing is possible from any
device having a cursor, this is typically useful only on either a graphics tablet or a HP plotter (with
a bullseye pen available from HP). Digitization requires initially a calibration of the actual plot to
determine the scaling and rotation of the axes. This is accomplished by requesting 3 known points
4c-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
from the user. Assuming these points are not colinear, the program determines the X and Y scaling
and rotation. Subsequent points are entered into the current data set. If the -APPEND option is
chosen, the points are appended to the current data set instead.
After the orientation and scaling of the plot has been performed once, subsequent digitizations may
choose to use the same calibration by specifying the option -HOLD. Previous scaling and plot rotation
factors are used without further warning.
The -TABLET <tab> option initializes the specified tablet for digitization. Tables are like graphics
devices and must be specified in the DEVICES.DAT file as well. Very few tablet drivers have been
written but documentation is available for writing your own if interested.
¾
»
/* Select digitize
GENPLOT: read %digitize
Enter three known, non-collinear points ... [1][2][3]
[X,Y] of the 3 known points: 0,0 1,0 0,5
Theta X:
18.3 Theta Y:
18.1
Enter points with cursor. End with the <0> button
I,X,Y:
1
8.237
1.2883
I,X,Y:
2
7.284
2.1189
GENPLOT:
GENPLOT: read %digitize -hold -append /* Read more data
Enter points with cursor. End with the <0> button
I,X,Y:
3
2.883
4.2285
GENPLOT:
½
¼
The information provided as Theta X: and Theta Y: are the rotation of the respective axes from
the normal values. If these numbers differ greatly, it indicates a bad calibration; data collection
should be aborted and the calibration retried.
–LIST
Syntax: -LIST <array1> <col1> <array2> <col2> <array3> <col3> /
This option allows for reading arbitrary columns from a data file into an arbitrary list of arrays.
The arrays must have been previously defined using the ALLOC <array> ARRAY <npt> command
(see Function Evaluator). In -LIST, for each array specified, a column of the data set is read into
that array up to the defined size of the array. A maximum of 40 arrays and columns may be specified
by a single read command. This command may be used with spreadsheet type files to read all the
data simultaneously if the number of points is known. Columns may be specified in any order (not
necessarily ascending) but each column may be specified only once! Reading the same column into
two arrays is not allowed, however the LET command will perform the task handily.
The following example shows a complex read which reads an arbitrary size file and then allocates
and reads multiple columns of the data into several named curves.
4c-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
¾
»
GENPLOT: read file2 -col 5 2 archive NI ENERGY
/* Read energy, set NPT
Current data consists of
100 points. Max: 2048
X minimum = 0.00000E+00, maximum =
39.900
Y minimum = 0.00000E+00, maximum =
4.1600
GENPLOT: alloc NI INITIAL curve npt
GENPLOT: alloc NI FINAL curve npt
GENPLOT: read file1 -list NI INITIAL:Y 3
Variable (end): NI INITIAL:X 2 NI FINAL:Y 4
Variable (end): /
Number of points:
100
Arrays min/max pts:
GENPLOT: let NI FINAL:X = NI INITIAL:X
½
/* Allocate NPT size curve
/* And another
/* Specify READ -LIST
/* More variables
/* End with <cr> or a /
80
100
/* Make all X’s the same
¼
The first standard read was necessary to determine the number of points in the file. Once the number
of points was known, the curves NI FINAL and NI INITIAL were allocated and the data was directly
read into the X and Y elements of the curves. The final LET command made the X elements of both
the NI INITIAL and NI FINAL curves the same. This example was taken from a macro where both
the basename NI and the filename were passed as arguments.
Example ASCII data file
ASCII files consist of columns of data separated by spaces, commas or tabs. Each value may consist
of numeric data, arithmetic expressions. Columns which are never read may be comments. Columns
are specified by their token number, not by the actual position in the file. Consider the following
file:
¾
»
GENPLOT: type file1
3.4, 5
10
6.555
2*7.6 1.5E2
½
4
7
8
3
Some text which won’t be read
¼
The first column consists of 3.4, 10 and 13.2 and column 2 is 5, 6.555 and 150. Column 3 is 4, 8,
and 3. Column 4 would be 7, ’Some’ and ’ ’, an invalid column if we tried to read it.
See also: TYPE, WRITE
WRITE
Syntax: WRite [-CURVE <curve>] <file> [-Binary [-Notext] | -Ascii [-Append] | -USER]
The write command stores the data in the main curve to a disk file in either the ASCII or BINARY
format. By default, GENPLOT stores files in ASCII mode. BINARY mode should normally be
used to minimize disk usage and reading time. However, other software programs will probably not
be able to read this format. If compatibility is required, or you want to be able to look at the file,
specify the -ASCII option to get a normal X,Y ASCII file.
4c-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
The -ASCII format causes the data to be written out in fixed format floating point numbers,
(G14.7,2X,G14.7 for you FORTRAN folks). No header or other textual information is written
with the file. The -APPEND option may be used to append the points to the current file.
The -BINARY file writes data out in the version 4.0 format described in Appendix F. This format
includes a header which may contain an arbitrary block of ASCII text. If -BINARY is specified, the
user is queried for the text to be included with the file. The query for text may be bypassed by
specifying -NOTEXT.
The option -USER passes control of the write routine to a user written subroutine USER$WR. This
routine permits writing of special data file formats. See Appendix S under the USER$ INTERFACE
for more information.
If the optional -CURVE is specified, the write outputs data from the archived curve instead of the
main curve. Note that the -CURVE option must immediately follow WRITE and preceed the filename.
¾
»
GENPLOT: write file1.new -ASCII
GENPLOT: write file1.new -ASCII -APPEND
GENPLOT: write file1.new -BINARY -NOTEXT
GENPLOT: write file1.new -BINARY
Enter lines of text. End with a blank line
Data from standard operations. Nothing useful in
this data set except that we have it stored in binary mode.
<cr>
/* blank line to end comment
GENPLOT:
½
¼
See also: READ
STATUS
Syntax: STatus [ [-CURVE] <curve>]
This command simply displays to the screen the status of the main data set or the specified curve
data set. The -CURVE specifier is not required. Information included is the number of points currently
defined in the main curve, the maximum number of points the curve can hold, and the minimum
and maximum values of the X and Y arrays. The status information is also printed when a data file
is read.
¾
GENPLOT: status
Curve ID: test.dat
Current data consists of
19 points. Max: 2048
X minimum = 0.00000E+00, maximum =
4.1600
Y minimum = 0.00000E+00, maximum =
39.900
GENPLOT: status c1
Curve ID: Backup data from yesterday
Current data consists of
883 points. Max: 883
X minimum = 0.00000E+00, maximum =
4.2900
Y minimum = 0.00000E+00, maximum =
97.210
GENPLOT:
½
4c-6
c
-Computer Graphic Service, Ltd. °1988-2007
»
¼
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
See also: SHOW, PARMS
SHOW
Syntax: SHow [ [-CURVE] <curve>] <low x> <high x>
The SHOW command displays to the screen all data points in the main or specified curve with X
coordinates between the low and high values specified, inclusive. Printed on the screen is the number
of the point within the data set, followed by the X and the Y values. Defaults for low and high
values are minus and plus infinity respectively. The following example accepts the default value for
the lower X bound by using the ’/’ and gives the upper X bound as 10.0. Points with values between
the curve minimum and 10.0 will be displayed.
¾
»
GENPLOT: status
Current data consists of
48 points. Max: 2048
X minimum = 5.28000
, maximum = 14.1600
Y minimum = 0.00000E+00, maximum = 139.900
GENPLOT: show
Lower X bound (minimum): / 10.0
I:
3 X:
8.160000
Y:
104.5000
I:
7 X:
6.260000
Y:
101.0000
I:
19 X:
7.620000
Y:
101.0000
I:
20 X:
6.740000
Y:
102.0000
I:
22 X:
5.280000
Y:
100.0000
GENPLOT:
½
¼
4c-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
NAMING DATA SETS: ARCHIVING THEM TO MEMORY
WARNING: Despite the choice of command names, ARCHIVE and RETRIEVE only do a memory
based save of a data set. No permanent copy of the data is written to disk and any data archived
will be lost when GENPLOT is exited. YOU HAVE BEEN WARNED!
GENPLOT normally works only with the main, or default, curve for plotting and analysis. However,
during a routine data analysis, it is often important to work with several curves or data sets. Rather
than rereading the curves in from disk many times, the ARCHIVE and RETRIEVE commands
are provided. This is a MEMORY BASED curve archival - not disk based; any curve archived will
disappear when GENPLOT is exited. Using ARCHIVE <curve name>, the main data set is “archived”
into a named curve in memory. At any later time in the GENPLOT session, the data in that named
curve may be retrieved to the main curve using RETRIEVE <curve name>, or the data in the named
curve may be plotted or overlaid directly using the PLOT <curve name> or OVERLAY <curve name>
commands.
Data sets archived to named curves may be used in mathematical operations as described in the
ARCHIVE command summary below.
ARCHIVE
Syntax: ARCHive <curve name>
The archive command creates a curve variable and copies the current main data set into the curve
variable. An archived curve may be plotted directly, or may be retrieved to the main curve using the
RETRIEVE command. Curves should be given names which do not conflict with any other variable
name, and which do not conflict with commands in GENPLOT (OVERLAY would be a really poor
choice for a curve name).
Formally, archiving a curve is equivalent to several function evaluator operations (see Function
Evaluator). The curve becomes several arrays and variables, each of which can be used wherever
expressions are expected. Consider the command ARCHIVE TEMP. Archive first allocates a curve
of length NPT called TEMP. This creates array TEMP:X, TEMP:Y and an integer TEMP:NPT.
TEMP:NPT is set equal to the current number of data points, and the main X,Y curve is copied to
the TEMP:X and TEMP:Y arrays. The original data is unmodified. An error will be generated if
there is insufficient memory to allocate the curve.
Since the allocation of a curve really allocates two arrays, mathematical operations on the archived
curves are possible. The command LET TEMP:X = 2*TEMP:X for instance will double the X coordinate of the curve TEMP.
¾
»
GENPLOT: archive TEMP
/* Save current data to curve TEMP
GENPLOT: plot TEMP -ltype 1 -pen 2
/* Plot the data
GENPLOT: let TEMP:Y = TEMP:X*TEMP:Y /* Some strange transformation
/* Copy TEMP back to main curve
GENPLOT: retrieve TEMP
GENPLOT: read errfile archive yerr
/* Read and archive error file
/* plot a function and overlay the archived TEMP curve with error bars
GENPLOT: plot -function ln(x) ov temp -erry sqrt(temp:y)
GENPLOT:
½
¼
4c-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section C – Read/Write/Use Data Sets
See also: RETRIEVE
RETRIEVE
Syntax: RETRieve <curve name> [-APPEND]
Retrieve copies an archived data set <curve name> back into the main curve for further analysis. The current main data set is lost unless the -APPEND option is specified. An error will
be generated if <curve name> does not exist. Consider RETRIEVE TEMP. NPT is set equal to
MIN(NPTMAX,TEMP:NPT). The X and Y main curves are then copied from the arrays TEMP:X
and TEMP:Y. The data in curve TEMP is left unchanged.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
read file1
archive d1 plot
read file2 plot
ov d1
retrieve d1 -append
plot
/*
/*
/*
/*
/*
/*
read first set
save file1 and plot it
read and plot second set
overlay file1 on file2 curve
append file1 to file2
plot auto-scaled with both
¼
See also: ARCHIVE
4c-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
D. LINETYPES, SYMBOLS, COLORS, ETC
COLor
LINEWidth
LType
PEn
SYmbol
SYMSize
VEcsize
VISibili
Set line color
Set the line thickness on laser printers
Select solid, dashed, dotted, symboled lines
Set line color
Select symbol for plotting
Set the symbol size
Set the length of dashes in dashed lines
Set line visibility
This manual section describes commands to control the symbols, linetypes, colors, visibility and
style of plotting strokes. Some of the commands only affect the data being drawn, such as those
specifying the linetype or the symbol to be used for data sets. Others, meanwhile, control the pen
color to be used for all drawing, or specify characteristics of the symbols or lines.
The commands LTYPE, SYMBOL, SYMSIZE and VECSIZE will be discussed first. These commands
control the type of symbol or lines which are used to draw the data. For simple plotting commands,
either symbols or lines are used to represent the data. Currently, any of 7 line types or 13 symbols
may be specified. Each of these choices may be further highlighted using different pen colors as
discussed in the second section. The commands LTYPE and SYMBOL work in conjunction with each
other to specify lines or symbols, and the type of either. SYMSIZE changes the size of the symbols
drawn while VECSIZE changes the repeat spacing of dot-dashed lines.
The second discussion will cover the PEN (COLOR), LINEWIDTH and VISIBILITY commands. These
commands have global applicability and change the pen color (actually pen number), the width of
lines drawn (on some devices) and visibility status of drawn vectors (draw, erase or complement).
Once set, the value remains in effect for most commands.
LTYPE
Syntax: LType <n>
The LTYPE and SYMBOL commands work together to select either lines or symbols for the plotted
data. If LTYPE is set to 0, then symbols are active and the symbol set by the SYMBOL command will
appear, centered on each data point. See the SYMBOL command for a description of the symbols.
The default setting on GENPLOT entry is for symbols, LTYPE 0. If LTYPE is set to other than zero,
either solid or dot-dashed lines will result. If <n> is negative, the absolute value is used and the
autochange mode will be enabled as discussed below. The possible line styles are shown below:
Line Types
0
1
2
3
4
5
6
7
Symbols
Solid
Dashes
Dash–Dot
Dot
Dash–Dash–Dot
Dash–Dot–Dot
Long Dash – Short Dash
————
-----......
..............
. . . .
.. .. .. ..
–-–-–4d-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section D – Linetypes, Symbols, Colors, etc
If <n> is set to a negative value, the current line type will be taken as the absolute value. As
with PEN -n, each time a line is drawn, LTYPE will be automatically incremented to the next valid
value, wrapping back to 1 after reaching 7. This mode allows multiple OVERLAY commands to be
distinguished easily and automatically. Like the PEN command, LTYPE is reset to -1 when a new axis
is drawn.
The -LTYPE option of the PLOT and OVERLAY commands does not change this LTYPE value. You can
get symbols and a line for a curve by plotting with a line and then overlaying that line with symbols.
See the example below.
Notes: If LTYPE is set to a negative value for auto–increment and you use the -LTYPE option of the
Plot or Overlay commands to override the current line type, LTYPE will still increment as usual.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
ltype 2 pen 2
plot
ltype -3
plot c1 overlay c2
ov c3 -lt 1 -pen 3
ov c3 -lt 0 -symbol 2
/* Specify dashed lines, pen 2
/* Plot the curve w/ dashed lines
/* C1 with ltype 3, C2 with type 4
/* C3 overlaid as solid line, pen 3
/* C3 overlaid with symbols
¼
See also: SYMBOL, VECSIZE
SYMBOL
Syntax: SYmbol <n>
The LTYPE and SYMBOL commands work together to select either lines to connect data on a plot or
symbols to show the points. SYMBOL is always active but symbols may be drawn ONLY IF LTYPE is
set to 0. Default on GENPLOT entry is for symbols. The SYMBOL command sets the current symbol
to <n>. While any number is valid, the useful range of <n> is from 0 to 13, as shown below. If <n>
is negative, the absolute value is used and the autochange mode will be enabled as discussed below.
0
1
2
3
4
·
◦
4
+
×
5
6
7
8
9
¦
?
filled box
•
filled triangle
Symbols
10 filled triangle (point left)
11 ∗
12 filled triangle (point right)
13 filled star
If <n> is set to a negative value, the current symbol will be taken as the absolute value. As with
PEN -n, each time a curve is drawn, SYMBOL will be automatically incremented to the next valid
value, wrapping back to 1 after reaching 13. This mode allows multiple OVERLAY commands to be
distinguished easily and automatically. Unlike the PEN command however, SYMBOL is not reset to -1
when the screen is erased.
The -SYMBOL option of the PLOT and OVERLAY commands does not change the current value of
SYMBOL. You can get symbols and lines on a plot by plotting with symbols and then doing on overlay
of the same data with a line. See the example below.
4d-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section D – Linetypes, Symbols, Colors, etc
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
ltype 0 symbol 7 pen 2
plot
symbol -3
plot c1 overlay c2
ov c3 -lt 0 -symbol 3
ov c3 -lt 1
/* Specify solid squares, pen 2
/* Plot the curve symbols
/* C1 with symbol 3, C2 with symbol 4
/* C3 overlaid with symbol 3
/* C3 overlaid as a line
¼
See also: LTYPE, SYMSIZE, PLOT –PT LABEL, OVERLAY –PT LABEL
SYMSIZE
Syntax: SYMSize <r>
This command sets the size, in inches, of the symbols which are plotted for the data. The default
size is 0.15 inches. On a normal 8.5x11 plot with only a few points to be plotted, a SYMSIZE of 0.25
will look better. The solid symbols (7–13) require slightly larger symbol sizes for legibility, typically
0.25–0.30. If large, filled, symbols are specified, it may also be necessary to increase the linewidth
on Laser Printers to fill in the symbols. The other use of extremely large symbol sizes is for creating
a circle which will be filled with the point number using the -PT LABEL option of PLOT.
¾
»
GENPLOT: symsize 0.23 plot -lt 0 -sym 7
GENPLOT: symsize 0.50 plot -lt 0 -sym 1
GENPLOT: symsize 0.18 ov -pt_label
½
/*Larger symbols for legibility
/*Draw large circles at data
/*Put numbers inside circles
¼
See also: SYMBOL, PLOT –PT LABEL, OVERLAY –PT LABEL
VECSIZE
Syntax: VEcsize <r>
This command sets a vector spacing variable, and works in conjunction with LTYPE to generate nonsolid lines. The linetypes 2-7 are patterns specified in units of the vector spacing variable. Hence,
the length and spacing of the dotted and dashed segments of all non-solid lines are determined by
the value of this variable. Doubling the value will create a line with exactly the same aspect ratio,
but with all lengths and spacings doubled. The setting of VECSIZE will affect all non-solid lines
drawn, including those drawn by ANNOTATE or SAMPLE.
The default vector spacing is 0.003 inches. Reasonable values lie in the interval [0.001, 0.01].
¾
»
GENPLOT: vecsize 0.01 plot -lt 4
GENPLOT: vecsize 0.001 plot -lt 2
½
/* Coarse dotted line
/* Very fine dashed line
¼
See also: LTYPE
4d-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section D – Linetypes, Symbols, Colors, etc
PEN (COLOR)
Syntax:
PEN <n>
Synonyms: COLor <n>
The pen number <n> is selected as the current pen, and will be used for all plotting and labeling
(with the possible exception of the GRID and the AXES). The default is pen 1. On video terminals,
PEN numbers are mapped into either color changes or changes in the attribute of a black/white line
(if possible). On hardware devices with several physical pens, the PEN command causes the actual
pen to be changed on the next command which generates pen motion. The maximum number of
pens supported by the current plot device is read in from the DEVICES.DAT file. Specifying a pen
number greater than this maximum will cause the last pen to be selected.
If the PEN value is specified as negative, the actual color used will be the absolute value of the PEN
color. This is an autochange mode however. After a curve is drawn (using PLOT or OVERLAY), the PEN
color will automatically be incremented to the next legal value, wrapping back to 1 after reaching
the maximum allowed. When an ERASE command is executed, the pen number is reset to –1 causing
the colors to start again from pen 1. This provides an extremely useful, and automatic, method to
distinguish among several curves on color devices.
Using the -PEN option of the PLOT and OVERLAY commands does not affect the value of PEN.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
pen 1
pen -3
overlay c1 overlay c2
plot c1 overlay c2
/*
/*
/*
/*
/*
Specify pen 1 (white on crts)
Select pen 3 now with auto change
C1 plotted pen 3, C2 plotted pen 4
C1 plotted pen 1, C2 plotted pen 2
C1 is pen 1 since plot erases
¼
Notes
1) On the IBM EGA with a monochrome monitor, the pen colors are mapped into bright, blinking
and low intensity, and are not terribly useful. Use LTYPE or SYMBOL to distinguish different curves.
2) The pen command has no affect on the axes colors. The axis is initially drawn using PEN 1. See
AXIS and SGRAPH commands for how to change these default color setting for the axes.
LINEWIDTH
Syntax: LINEWidth <n>
This command specifies the width or thickness of the line drawn. It is valid only for devices which
can support such changes, usually only laser printers. The width, <n>, is specified in units of 0.007
inches and may be fractional if desired. All axis linewidths scale with the setting of this linewidth.
The default line width is one. Note that unlike most plotter specifications, the linewidth IS NOT
set when a device is initialized. It is only set after a call to LINEWIDTH, or when the axes are drawn.
As with the PEN command, the axes linewidths are not drawn using the default linewidth. The
linewidth for the axis may be changed with SGRAPH commands; see AXIS and SGRAPH commands for
more information.
4d-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section D – Linetypes, Symbols, Colors, etc
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
dev postscript
linewidth 1
plot -lt 1
linewidth 7
ov -lt 0 -sym 7
linewidth 1
/*
/*
/*
/*
/*
/*
Use the POSTSCRIPT driver
Specify thin line
Plot symbols with this linewidth
Extremely thick lines
Draw solid symbols
And back to normal
¼
VISIBILITY
Syntax: VISibili {-1 | 0 | 1}
This command sets the visibility attribute for all subsequent plotting. Vectors drawn to the device
may have one of three attributes: visible, invisible or complement (see notes). Visible, the default,
causes vectors to overwrite what is currently on the plotter. Invisible is equivalent to an erase
operation. Complement causes the individual pixels to be reversed in their state. This allows
vectors to either draw over, erase or complement whatever is currently on the plot. (Side note: the
cursor is drawn using complement mode so it can pass through data without erasing it.)
Visibility
1
drawing on
0
drawing off (erase)
–1
draw complementing
(toggle pixel between on and off)
Notes
1. Very few devices can implement this command. For example, once a pen plotter draws a line it
can’t be erased. The IBM screen drivers implement all of the visibility modes, but results may not
be totally what one expects.
2. Line drawing of closely spaced points may not give expected results in the complementing mode
since each pixel may be drawn more than once, and each drawing will complement it.
3. While the erase mode may be nice to eliminate a misdrawn curve from the screen, it will not
remove the curve from an HCOPY file.
4d-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
E. AXIS CONTROL
AUTOAxis
AUTOX
AUTOY
AXCtrl
AXis
BOXmode
CHRset
FORCe
INTicks
LABel
LOGarith
PLX
PLY
REGion
SETUP
SUBTicks
XTop
YRight
Toggle automatic drawing of axes with the PLOT command
Toggle auto–scaling for the X axes
Toggle auto–scaling for the Y axes
Control detailed appearance of an individual axis
Draw the axes
Toggles drawing of the top and right axes
Select the character set for labeling
Force GENPLOT to use your exact axis scale
Toggles direction of the tick marks
Set the axis label
Use logarithmic axis
Select the axis to use for the plotted X data
Select the axis to use for the plotted Y data
Specify the minimum and maximum values for the axis
Enter the graph setup screen to set plot information
Toggle subtick mark plotting
Toggle format of the top axis labelling
Toggle format of the right axis labelling
In this section, we will discuss the commands which modify and control the nature of the axes
which are drawn on the screen. Axes are automatically drawn for any PLOT command (except with
AUTOAXIS OFF) or when the AXIS command is given directly. There are actually 4 axes drawn on
the screen, the top, bottom, left and right. They are referred throughout this document by those
names. By default, the X axis is the bottom and the Y axis is the left axis. Through the use of the
commands described in this section, the nature of each axis can be modified.
The section is divided into 3 parts. The first contains commands which actually draw the axes and
control whether axes are drawn with the PLOT command. The second section describes commands
which set the range of the various axes, and determine how the data is plotted relative to these
axes. The final section describes commands which affect the appearance of the axis, including how
to label the axes, turning individual axes on or off, changing the direction of the tick marks, and
similar commands.
One of the primary commands for new users is SETUP. Because SETUP has so many purposes, placing
it in the manual is difficult and it has been put with AXIS simply because much of its purpose is in
handling the status of the axes.
DRAWING THE AXES, AND THE SETUP COMMAND
AXIS
Syntax: AXis
Synonyms: AXEs
This command uses the current settings of all axis parameters to draw an axis to the current
plotting device. The AXIS command itself is quite simple, but there are many commands which
4e-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
allow modification of how the axis is drawn. If AUTOERASE is enabled (default), the screen is erased
before each axis is drawn. Multiple axes may be plotted on the same page by turning AUTOERASE OFF
and moving one axis relative to the other. This relative moving is done with the OFFSET command.
Don’t turn AUTOERASE OFF to change axis labels. The new ones will just overwrite the old ones.
When an AXIS is drawn, it will autorange the axis scale to include the current data set. The minimum
and maximum of each axis is then modified slightly to create nice tick mark spacing and labeling.
If FORCE is enabled, the minimum and maximum will exactly fit the data. If a REGION for the axis
has been set by the user, the axis scale will display that region. GENPLOT may again modify the
region slightly for nice labeling but this can be stopped as above with the FORCE command.
Once axes are drawn for the current data set, the scale will not change until a new axes is drawn or
specifically changed using REGION. Thus if a second data set is overlaid onto the first, it may or may
not lie within the region of the graph. The REGION command can be used before an AXIS command
to set a range that includes both data sets. The second data set could also be plotted against the top
or right axes. See PLX and PLY for more information on this. The Tutorial section has an example
of dealing with these features.
The PLOT command also includes an implicit AXIS command unless AUTOAXIS is turned off, as
described below.
The pen used for drawing the axis is determined by the setting of the AXCOLR variable accessible
by the SGRAPH command. The axis, tick marks and labels are normally drawn with pen 1. The
SGRAPH variable AXCOLR can be modified to set the pen used to draw individual elements of the axis.
Similarly, the axis linewidth is also controlled by an array AXWIDTH accessible through SGRAPH. The
AXWIDTH values scale to the current line width to draw the major axis in a heavier line than other
plot markers. On all devices, the major axis is drawn twice to make it slightly darker. The default
settings of AXWIDTH and AXCOLR draw the axis with pen 1 and the major axis twice as wide as the
current LINEWIDTH setting.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
plot
axis
sgraph axwidth(1) 3 axis
sgraph axcolr(1) 7 axis
autoerase off axis
/*
/*
/*
/*
/*
Draw
Draw
Bold
Axis
Draw
axis and put the data on it
just the axis
line for axis (laser printer)
drawn with pen 7
axis without erasing screen
¼
See also: SGRAPH, AUTOERASE, LINEWIDTH, PEN, FORCE, REGION, AUTOAXIS, OFFSET
AUTOAXIS
Syntax: AUTOAxis {ON | OFf}
Synonyms: AUTOAXes {ON | OFf}
AUTOAXIS is a compatibility command of questionable utility. It is useful only if you are accustomed
to typing PLOT when you mean OVERLAY. By default, GENPLT does an implicit AXIS every time a
PLOT command is issued. The AUTOAXIS command provides a way to make PLOT synonymous with
OVERLAY. With AUTOAXIS OFF, axes will only be drawn in response to an explicit AXIS command.
Otherwise, axes are drawn for either AXIS or PLOT commands.
4e-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
¾
»
GENPLOT: autoaxis off
GENPLOT: plot
GENPLOT: autoerase off axis
GENPLOT:
½
/* Draw axis and put the data on it
/* Plot just the data
/* Add axis without erasing screen
¼
See also: PLOT, OVERLAY, AXIS
BOXMODE
Syntax: BOXmode {Yes | No}
The BOXMODE command switches GENPLOT from drawing all four axes to drawing only the bottom
and left. The right and top axis are effectively disabled from drawing. Default is to display all axes,
BOX YES.
BOXMODE NO is actually a strange mode. The left and bottom axes are drawn with (0,0) as the
intersection point. If either the left or bottom range does not include 0, the other axis will not be
drawn. The mode is implemented to allow drawing of standard X,Y plots where 0,0 is at the axis
intersections. Labels and tick marks are still drawn as for the BOX type axis. It is suggested that
tick mark and axis labeling be turned off when making hard copy output in BOXMODE NO mode.
¾
»
GENPLOT: reg left -2 2 reg bot -1 2
GENPLOT: boxmode no
GENPLOT: axis
GENPLOT:
½
/* Reasonable scales
/* Turn off top & right
/* Draw the axis
¼
See also: PLX, PLY, AXIS
SETUP
Syntax: SETUP
This is a full screen editor of sorts which displays most of the plot parameters and allows them
to be modified in an easy manner. The setup screen allows one to implement many of the AXIS
control commands described in this section, plus a few of the plot description commands such PEN
and LTYPE.
The cursor indicates the field currently being modified. Moving within a field or from one field
to another is possible using either the cursor keys, or EMACS like control codes. Note that any
change in one field may affect another field. For instance, typing into the minimum range field will
automatically turn off AUTOSCALE for that axis; likewise, setting plotting to use the left AXIS will
automatically turn off the RIGHT axis marker. To exit SETUP, press <ESC>. Typing ∧C or ∧G will
attempt to abort SETUP without making any changes.
In addition to the cursor keys the following keys are implemented within the setup screen (probably
more):
INS
DEL
Toggle between Insert/Replace mode
Delete a single character
4e-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
∧K
∧D
∧E
∧A
∧N
<CR>
∧Z
Delete to end of field
Delete a single character
Go to end of the field
Go to the beginning of the field
Go to next field
Go to next field
Go to previous field
¾
»
LABELS:
Bottom:
Left:
Top:
Right:
Bottom:
Left:
Top:
Right:
PEn:
1
X
Y
X
Y
Minimum
0.000E+00
0.000E+00
0.000E+00
0.000E+00
LType:
0
Maximum
1.00
1.00
1.00
1.00
SYMbol:
Auto
Scale
X
X
X
X
3
Force Scales:
Auto-axis: X
Minor Ticks: X
Ticks In: X
====================
<ESC> to exit
½
Log
Mode
Status
On Copy User
X
X
Off
Plot
Using
X
X
X
X
SYMSIZ: 0.140
Auto-IDS:
NPOint:
1
Box-Mode: X
¼
CONTROLLING THE AXES REGIONS
REGION (SET)
Syntax:
REGion {BOTtom | Left | Top | Right}{AUTO | <min> <max> }
Syntax:
REGion AUTO
Synonyms: SET (same options)
This command specifies the range, or region, for one of the four axes. Issuing this command has
several effects. First, autoscaling of the range for that particular axis is turned off. Autoscaling may
be restored by specifying AUTO or by using the AUTOX or AUTOY commands discussed below. Second,
4e-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
the minimum and maximum range for the axis are set to the specified values. If plotting is based on
this axis, the plotting range is immediately changed. However, the actual minimum and maximum
ranges may be changed slightly when the next axis is drawn, since “nice” values are desired for axis
labels. This rounding of the values may be suppressed completely using the FORCE command.
The command REG AUTO resets all axes to autoscaling mode. Any single axis can be reset using REG
LEFT AUTO. These commands are similar to the AUTOX and AUTOY commands.
One of the rounding modes of the “nice” values is the inclusion of zero in the range if the data gets
close to zero. For instance, data ranging from 1 to 7 will have a range specified from 0 to 7, since
zero-suppressed graphs are a real pain to view (author’s personal opinion). An SGRAPH variable,
ZFORCE, determines when zero is forced to be included in the data. If (min/max) of the range is less
than ZFORCE, then the minimum is set to zero. ZFORCE defaults to 0.3. It may be changed with the
SGRAPH command to any value, including zero.
When GENPLOT is initialized, all axes are in AUTOSCALE mode with no regions specified.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
region left 0 2
reg bot 0 4 axis
force yes
reg bot .258 .992 axis
force no
reg bot .1 .8 axis
sgraph zforce 0.1
reg bot .1 .8 axis
autox both autoy both
/*
/*
/*
/*
/*
/*
/*
/*
/*
Left axis now goes from 0 to 2
Bottom set from 0 to 4, axis drawn
Force scales exactly
Will be drawn exactly as specified
Reset force mode
Range set to 0 to 0.8
Reset ZFORCE value
Range will be allowed, no zero
Reset autoranging for all axes
¼
See also: AUTOX, AUTOY, FORCE, PLX, PLY
FORCE
Syntax: FORCe {Yes | No}
This command changes the status of the scale forcing flag. Normally, when you specify a region or
scale for an axis, GENPLOT picks appropriate minimum, maximum, and interval values for that
axis to include the region specified. However, in order to make the plot attractive, these values are
rounded up and down to “reasonable values” and hence generally the regions include more range
than was specified. If FORCE is set to YES before specifying a region, GENPLOT is obliged to use
the exact values given for the minimum and maximum axis ranges. Auto ranging of the axis scales
with FORCE YES will also generate minimum and maximum exactly following the range of the data.
The default is FORCE NO.
WARNING: Specifying equal lower and upper values with the FORCE YES mode will result in a
system hang since an axis will be drawn over a 0 length interval (tough luck).
Example: See REGION command.
See also: REGION, AXIS
AUTOX
4e-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
Syntax:
AUTOX {BOTH | Top | BOTTom | Off}
Synonyms: AUX {BOTH | Top | BOTTom | Off}
The AUTOX command enables/disables autoranging (autoscaling) on either or both of the two x
axes. Note that the REGION command now implements an equivalent of this command. Autoranging
is initially in effect for all axes. When autoranging, GENPLOT chooses minimum and maximum
values for the axis sufficient to display the entire curve. Using the REGION command to set the range
manually disables this autoranging feature for the particular axis. AUTOX re-enables the autoranging
feature for either the top, bottom or for both axes.
Example: See REGION command.
See also: REGION, AUTOY, AXIS
AUTOY
Syntax: AUTOY {Both | Left | Right | Off}
Synonyms: AUY {Both | Left | Right | Off}
The AUTOY command enables autoranging (autoscaling) on either or both of the two y axes. Note
that the REGION command now implements an equivalent of this command. Autoranging is initially
in effect for all axes. When autoranging, GENPLOT chooses minimum and maximum values for
the axis sufficient to display the entire curve. Using the REGION command to set the range manually
disables this autoranging feature for the particular axis. AUTOY re-enables the autoranging feature
for either the left, right or for both axes.
Example: See REGION command.
See also: REGION, AUTOX, AXIS
PLX
Syntax: PLX {Bottom | Top}
GENPLOT maintains two independent X axes, the bottom and top scales. Data may be plotted
against either coordinate system as desired. The PLX (meaning PLot X against) command specifies
whether the scale of the top or of the bottom axis is to be used for subsequent PLOT or OVERLAY
commands. On initialization, plotting is done against the bottom axis (default PLX BOTT). Regions
for both axis may be specified and then different data sets can be alternately plotted against either
axis.
It is not sufficient to specify that plotting be done against the top axis to get the labeling for it.
You must turn on labeling for the top axis using the XTOP command.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
reg left 0 2 reg bot 0 4
reg top 3 7 reg right -1 1
xtop on yright on
plx bot ply left plot
plx top ply right ov c1
/*
/*
/*
/*
/*
Set primary regions
Set alternate regions
Turn top and right labeling on
Plot primary data
Overlay C1 using top and right
¼
4e-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
See also: REGION, PLY, XTOP
PLY
Syntax: PLY {Left | Right}
GENPLOT maintains two independent Y axes, the left and right scales. Data may be plotted against
either coordinate system as desired. The PLY (meaning PLot Y against) command specifies whether
the scales of the left or of the top axis are to be used for subsequent PLOT or OVERLAY commands.
On initialization, plotting is done against the left axis (default PLY LEFT). Regions for both axis
may be specified and then different data sets can be alternately plotted against either axis.
It is not sufficient to specify that plotting be done against the right axis to get the labeling for it.
You must turn on labeling for the right axis using the YRIGHT command.
Example: See PLX command.
See also: REGION, PLX, YRIGHT
LABELING AND CONTROLLING LOOK OF AXES
LABEL
Syntax: LABel {Bottom | Left | Top | Right} <text>
The LABEL command specifies the identifying label to be use for a particular axis. Each of the
four axes (bottom, top, left and right) has a separate label which is a literal string consisting
of a maximum of 65 characters. The string may contain embedded commands to draw symbols,
superscripts, subscripts or to change characters sets. These imbedded commands also count in the 65
character limit. See ESSENTIAL INFORMATION for more information on specifying superscripts,
subscripts and special symbols. Unless you specifically set the character set in the label, the label
will be drawn using the character set active when the axis is actually drawn. LABEL is the only
command where it is often easier to set the names using SETUP rather than direct typing. SETUP
allows for natural character insertion and correction of mistakes.
The string <text> must be enclosed in quotes if it contains blanks or lower case characters and is
given on the same command line. If you are prompted for the title, a string is assumed and no
quotes are necessary; the entire string is taken as the title, untranslated.
Note: On the left and right axes, the axis label location is adjusted so that it will not run into the
longest tick mark label. If your ticks are labeled from 0.0 to 9.0 then the axis label will be about
0.5 inches from the axis line. If your data causes the ticks to be labeled from say, -10.0 to -100.0,
GENPLOT will move the axis label farther away from the axis to allow for the extra digits and the
minus sign. This will cause the label to be off the screen. The OFFSET or MARGIN commands can be
used to prevent this clipping.
¾
»
GENPLOT: label bottom ’Temperature’
GENPLOT: label left
Title: Oxide density (g/cm^{2})
GENPLOT:
½
/* Label bottom axis simply
/* Label left, prompt for title
/* Complex title (no quotes)
¼
4e-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
SUBTICKS
Syntax: SUBTicks {ON | OFf}
This command allows sub-tick marks to be either drawn and not drawn on plots. Subticks are the
minor division marking between the major, labeled, tick marks. In publication plots, minor tick
marks generally clutter the plot and should not be included. The minor tick marks are disabled
with the command SUBTICKS OFF. They may be reenabled for local use with SUBTICKS ON. The
major tick marks are unmodified in any event.
The length of both the major and minor tick marks is settable using the SGRAPH command. The
minor tick mark length (in inches) is controlled by the variable TICK2 and the major tick mark
length by TICK. The size of the labels at major tick marks is set by CSMIN and CSMAX variables.
Labels will never be larger than CSMAX. If the labels would have to be smaller than CSMIN to fit on
the graph, labeling will be disabled. Subticks may be controlled on an individual axis basis using
the AXCTRL command.
¾
GENPLOT: subticks off plot
GENPLOT: subticks on
GENPLOT: sgraph tick2 .1
GENPLOT:
½
»
/* Draw with no minor tick marks
/* Reenable the minor tick marks
/* Set length of minor tick marks
¼
See also: INTICKS, SGRAPH, AXCTRL
INTICKS
Syntax: INTicks {Yes | No}
Normally, the tick marks in GENPLT are directed into the plot, as preferred by publications. For
some data, and for analyzing data, it may be preferable to have the tick marks extend outward from
the plot. The INTICKS commands determines the direction of the tick marks. INTICKS YES causes
the tick marks to be plotted inward, while INTICKS NO causes them to be plotted outward. Default
is inward, INTICKS YES. Inticks may be controlled on an individual axis basis using the AXCTRL
command.
See also: SUBTICKS, SGRAPH, AXCTRL
XTOP
Syntax: XTop {OFf | ON | Bottom | Nonlinear | Youdraw}
The XTOP command controls the status of the top X axis. This axis has four possible modes, given
by the options above. Three are relatively simple and the fourth is unbelievably complex. OFF is
self explanatory; labeling of the upper axis is turned off and only the line itself and the tick marks
corresponding to the lower axis are drawn (okay – its only almost off). The ON command turns the
upper axis on as a completely independent axis. The title and the range will be those specified for
the top axis. The BOTTOM mode is a “copy” mode, where the top becomes an exact duplicate of the
bottom in range and in labeling. Sometimes it’s nice to have two axes. The default mode is XTOP
OFF.
WARNING: Turning the top axis on will not automatically cause the data to be plotted against
it. Use the PLX command for controlling which axis the data is plotted against.
4e-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
XTOP NONLINEAR (and its synonym YOUDRAW) is a complex axis drawing mode which ties the top axis
to the bottom axis through an arbitrary, possibly nonlinear, transformation. The top axis is not
independent from the bottom axis, but is labeled in a different coordinate system. An example of
this use is in Arrhenius plots where the data X coordinates are 1000/T where T is the temperature.
However, it is nice to have the actual temperature listed on the plot as well. This can be done on
the top axis. The data must be plotted against the linear axis or unpredictable results will occur.
Since you must define the functions that relate the top and bottom axes anyway (see below), it is
easy to convert the data so that it can be plotted against the linear scale.
Two functions must be defined for NONLINEAR; one describing the transformation necessary to take
a coordinate from the bottom axis to the top, and the corresponding inverse function converting a
top coordinate to the bottom. These functions are called TOP TO BOTTOM(X) and BOTTOM TO TOP(X),
and may be set using the DEFINE command. The title specified for the top axis is used on the top
axis. This mode will handle reasonable non–linear functions, but will fail miserably if they get too
ugly.
When using the cursor with NONLINEAR, the value of both the linear axis and the non-linear axis will
be returned. Normally, XCUR will be set to the linear axis since plotting is done against the bottom
axis. To get XCUR set to the non-linear axis value, make sure that the REGION for the bottom and
top are identical and then set PLX to top. The value in XCUR under these conditions will correspond
to the non-linear axis. Linear coordinates may be transformed to the non-linear one via an EVAL
BOTTOM TO TOP(XCUR) command also.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
/* Force my regions
force yes
region bot 1 4 reg top 2 8
/* Set bot/top regions
reg left 0 1
/* Set other regions
label top ’Temperature (C)’
/* Set top label
/* Set bottom label
label bot ’1000/T’
xtop on axis
/* Draw independent axes
xtop bottom axis
/* Repeat bottom axis on top
region bot 1 4 reg top 1 4
/* Set bot/top same
xtop nonlinear
/* Set Non-linear now
define bottom to top(x) = (1000/x)-273
/* 1000/T to T ◦ C
define top to bottom(x) = 1000/(x+273)
/* Inverse function
axis
/* Nice non-linear axis!
let x = top to bottom(x) overlay /* Transform and plot
¼
4e-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
¾
»
Temperature ( C)
600
9
400
200
0
Log of diffusion time
8
7
6
5
4
3
1
2
3
4
1000/T (K)
½
¼
See also: YRIGHT, DEFINE
YRIGHT
Syntax: YRight {OFf | ON | Left | Nonlinear}
The YRIGHT command controls the status of the right Y axis. This axis has four possible modes,
given by the options above. OFF is self explanatory with labeling of the right axis is turned off and
only the line itself and the tick marks corresponding to the left axis are drawn (okay – its only
almost off). The ON command turns the right axis on as a completely independent axis. The title
and the range will be those specified for the right axis. The LEFT mode is a “copy” mode, where the
right becomes an exact duplicate of the left in range and in labeling. Sometimes it’s nice to have
two axes. The default mode is YRIGHT OFF.
WARNING: Turning on the left axis will not cause the data to be plotted against it. Use the PLY
command for controlling which axis the data is plotted against.
The NONLINEAR is a non-linear axis drawing also and operates identical to the XTOP mode described
above. The corresponding functions are LEFT TO RIGHT and RIGHT TO LEFT.
Example: See XTOP
See also: XTOP, PLY
LOGARITH
Syntax: LOGarith {Bottom | Left | Top | Right}{ON | OFf}
WARNING: The LOGARITHM command affects only the labeling of the axes, and not the plotting
of data to the axes.
4e-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
The LOGARITHM command changes the labeling of a particular axis from linear to logarithmic. Consider an axis whose range is from 0 to 5. In linear labeling mode, major tick marks would be labeled
as 1,2,3,4 and 5. In logarithmic mode, the tick marks are labeled 101 , 102 , 103 104 and 105 . Minor
tick marks, likewise, fall on sub-boundaries for logarithmic plotting. This is a labeling command
only! Data will still be plotted from 1 to 5, not from 10 to 100,000. To plot logarithmic data, the
transformation must be done using LET, as in the example below. Once the logarithmic mode is set,
it must be unset using the LOGARITHM <type> OFF command.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
reg left -1 5
/* Specify left region
logari left on
/* Log labeling on left axis
create y = x*exp(x) -from 0 -to 10 -by .1 /* Create y = x ∗ ex
axis
/* Draw the axes
let y = log(y) ov -lt 1
/* Take LOG and plot the data
logar left off
/* Turn logarithmic mode off again
¼
The left axis will be labeled from 1 to 105 , but the plot is still linear from 0 to 5. The let command
transformed the data to the common logarithm we needed to plot. See AXCTRL to switch labeling
from 100 to 1.
¾
»
Diffusion time
Temperature ( C)
10
5
10
4
10
3
10
2
10
1
10
0
600
400
200
0
-1
10
1
2
3
4
1000/T (K)
½
¼
See also: AXCTRL
CHRSET
Syntax:
CHRset <n>
Synonyms: CHARActe <n>
4e-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
The CHRSET command changes the character set (or font) used for labeling on plots. <n> is an integer
between 0 and m, where m is the maximum number of fonts present in the \GENPLOT\HDATA.CHR file.
The default character set is 1. See ESSENTIAL INFORMATION for changing fonts temporarily
within a string.
0
1
2
3
4
Special symbols
Normal
Greek characters
Bold characters
Bold Greek characters
Character Sets
5
Old English
6
Different order of Greek character
7
Different order of bold Greek characters
8
Script
9
Bold Script
The number and type of character sets available is determined by the \GENPLOT\HDATA.CHR file
which is loaded at execution time. This file contains all the vector strokes necessary for making
the characters. Several versions of HDATA.CHR are available, from HDATA2.CHR containing only 2
character sets to conserve memory to a fully implemented 9 character sets including Script and Old
English. Initially, all 9 sets are loaded. See Appendix R to change which set is loaded in your
implementation. See the Quick Reference section for samples of the character sets.
¾
»
1 Normal
ABCdef123
2 Greek
3 Bold
ABCdef123
4 Bold Greek
5 Old English
8 Script
9 Bold Sript
½
¼
AXCTRL
Syntax: AXCtrl <TOP | BOTtom | LEFT | RIGHT> <options>
options: [-On|-OFF] [-BRief|-NOBRief] [-LABel|-NOLABel]
options: [-ROtate|-NOROtate] [-JUSTify|-NOJUSTify]
options: [-SPEClog|-NOSPEClog] [-SUBtick|-NOSUBtick] [-TIcks|-NOTIcks]
options: [-INticks|-NOINticks] [-DX <r>] [-DX2 <r>] [-MX <n>] [-Grid]
options: [-XStart <frac>] [-YStart <frac>] [-LENgth <frac>]
AXCTRL gives you more precise control over what parts of each axis appear and how they appear.
You can turn the tick marks, labels and the axis on or off as well as changing the appearance of
4e-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
the axis labeling. You must specify the axis that you want to change and then give an action. The
word NO can proceed all of the options to change their state. For example -NOBRIEF will reverse the
affect of -BRIEF.
–ON, –OFF
-ON or -NOOFF enables drawing of the specified axis with the remaining options. -OFF or -NOON
completely disable the specified axis. No line nor labels are drawn. -OFF can be used to disable box
mode with the top and right axes.
See also: XTOP, YRIGHT, BOXMODE
–BRIEF
The -BRIEF option will remove all the axis tick mark labeling except the first and last ones. Use
-NOBRIEF to return to full axis labelling.
»
Y Axis
¾
1.0
0.8
0.6
0.4
0.2
0.0
0.0
0.2
0.4
0.6
0.8
1.0
Y Axis
NoBrief
1.0
0.8
0.6
0.4
0.2
0.0
0.0
1.0
Brief
½
¼
–LABEL
The -NOLABELS draws the axis but will disable the labelling of any tick marks. The title will remain.
Tick mark labelling is restored with -LABELS. This mode allows a title only to exist for a given axis.
–ROTATE
The -ROTATE option causes the axis tick mark labels to be rotated 90 degrees. In -NOROTATE, the
numbers running parallel to the axis, the default for X type axes. In -ROTATE, the numbers are
drawn perpendicular to the axis (default for the Y axis).
–JUSTIFY
In -NOROTATE mode, the labels for the first and last tick marks on the axis are displaced toward the
center of the axis so that no more than half a character width extends beyond the axis boundary.
This is the -JUSTIFY mode, justified left and right edge labels. In -NOJUSTIFY, the labels for the
4e-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
first and last tick marks will be drawn centered on the tick mark as is done for the intermediate tick
marks.
¾
»
Y Axis
2.0
1.5
1.0
0.5
0.0
0.0
0.2
0.4
0.6
0.8
1.0
NoJustify
Y Axis
2.0
1.5
1.0
0.5
0.0
0.0
0.2
0.4
0.6
0.8
1.0
Justify
½
¼
–SPECLOG
By default GENPLOT will draws the labels on logarithmic axes as 10n . Specifying -SPECLOG will
cause values between 0.001 and 10000 to be drawn as decimal values.
–SUBTICK
-NOSUBTICK will remove the tick marks between the major tick marks. No labeling is affected. The
tick marks can be regained with -SUBTICK. The SUBTICKS command controls this mode for the entire
plot rather than a single axis.
See also: SUBTICKS
–TICKS
The -NOTICKS options will remove all of the tick marks and all of the numbers along an axis. Tick
marks and labels are restored using -TICKS.
–INTICKS
Tick marks may be directed into (default) or out of the plot. To specify outward tick marks, use
-NOINTICKS. -INTICKS will cause the marks to turn inward. The INTICKS command controls this
for the entire graph.
See also: INTICKS
–DX, –DX2, –MX
The spacing between major and minor tick marks, and the format of the labels, is normally automatically chosen based on the range of the axis. The -DX, -DX2 and -MX options request override
values. Any override parameter set to zero will automatically use the default value.
4e-14
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
-DX and -DX2 set the spacing of the major and minor tick marks respectively in user units. Both
major and minor tick mark positions are determined from zero and DX need not be a multiple of DX2.
For an axis with range 0 to 20, a DX value of 2 and a DX2 value of 0.2 will draw and label 11 major
tick marks and draw 101 minor tick marks. For logarithmic labelled axes, negative values of DX2
value select drawing subtick corresponding to (5), (2,5), (2,3,4,5,6,7,8,9), (1.1,1.2,...,5.0,5.2,...,9.8)
for -1,-2,-3 and -4 respectively.
-MX controls the format of the labelling. Positive values of MX specify the number of decimal digits
to draw. For MX of 3, the value 1 would be drawn as 1.000. Any negative value of MX causes
only the nearest integer value to be drawn. Logarithmic axes should be specified with negative MX
values.
¾
»
Brief
1.0
0.0
0
2
4
6
8
10
12
14
16
18
20
Y Axis
-dx 2 -dx2 0.2
1.0
0.8
0.6
0.4
0.2
0.0
0
5
10
15
20
Default
½
¼
–GRID
The -GRID command effectively lengthens the major and minor tick marks to the full length of the
plot. This will produce a much finer grid than is possible with the GRID command. Minor tick marks
can be disabled to draw a less dense grid using the -NOSUBTICKS option.
See also: GRID
–XSTART, –YSTART, –LENGTH
The options -XSTART and -YSTART specify the starting point of the axis as a fraction of the total
axis area. Normally, only either -XSTART or -YSTART is specified to move the axis up the page or
slightly away from the bottom of the previous axes. If the axis is displaced along the direction it
labels, the tick marks will still be labelled correctly with respect to the plotting area. However, it
may be necessary to specify a shorter -LENGTH to prevent drawing outside the logical plot area.
The -LENGTH value specifies the length of the axis, again as a fraction of the entire plot area length.
For a REGION specified of 0 to 20, the specifying the -LENGTH as 0.6 and the -XSTART as 0.2, an X
axis would be drawn and labelled only between 4 and 16.
4e-15
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section E – Axis Control
Y Axis
0
2
4
6
8
10
»
-NoRotate -NoSubtick
¾
10
8
6
4
2
0
5
10
15
-xstart 0.2 -length 0.6
0
5
10
15
20
Default
¼
¾
»
-NoIntick
½
10
8
6
4
2
0
0
5
10
15
20
Default
-ystart -0.2
10
8
6
4
2
0
0
5
10
-ystart 0.2 -length 0.6
½
¼
4e-16
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
F. SIZE AND POSITION OF PLOT
FLIPXY
MARGins
OFfset
SHrink
SIZe
SUB Plot
Flip the X and Y axes on the page
Set the margin around the plot area
Offset the entire plot on the device
Reduce the size of the plot
Set the size of the plotting area
Adjust size and offset to create a plot within a plot
This section describes the commands which control the positioning and size of the plot on the
physical page. The plotting area may be magnified, offset on the page, changed in size, or rotated
90 degrees on the page. The manual will initially discuss definitions relevant to the plot description,
especially the distinction between hardware, logical, and data plot areas. The detailed format of the
commands SHRINK, SIZE, OFFSET, MARGINS and FLIPXY will follow.
There are actually three physical plot areas which must be distinguished. The first, and the largest,
is the actual paper (or screen) size, roughly 8.5x11.0 inches. Software (and sometimes hardware)
clipping routines prevent the pen from ever being placed outside of this hardware plotting area. This
area is referred to as the hardware plotting area, and its boundaries are the hard clip boundaries.
The relationships between these areas are shown in the diagram below. All of the parameters shown
may be modified by the commands discussed below.
¾
»
hardware plot area
xsize
logical plot area
ymargin
1.0
0.0
ysize
xmargin
Y Axis
0.5
-0.5
-1.0
xoffset
-10
-5
0
5
10
X Axis
yoffset
½
¼
The second plot boundary is referred to as the logical plot area, defined as the nominal area in which
GENPLOT will confine its drawing. This logical plot area may lie either completely within or only
partially within the hardware plot boundaries. It is perfectly possible to tell GENPLOT to make a
4f-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section F – Size and Position of Plot
plot larger than the physical screen, but only vectors within the hardware plot region will actually
be drawn. Nominally, all axes and labels are designed to fall within the logical plot boundaries;
however, no clipping is done at the logical plot boundary and hence drawing may extend outside
this region freely, up to the limits of the hard clip boundaries.
The final plot boundary is the data plot region. This region is a subset of the logical plot area, and is
the only region where data vectors are plotted. Under almost all situations, this region is delineated
by the four axes. Data points and vectors are drawn only if they fall within the data plot area;
vectors outside the area will be clipped so that only the region within the boundaries are displayed.
Again, physical clipping at the hardware boundary is also in effect.
• Hardware plot area - Physical plot page, hardware clipped
• Logical plot area - Nominal plot area within GENPLOT, not clipped
• Data plot area - Plot area where data may be displayed, software clipped
In the drawing above, the outer boundary represents the physical page size, the size of which is
determined from the particular device driver. The next inner region, dimensioned XSIZE by YSIZE,
is the logical plotting area. The size of this area is specified by the SIZE command. The lower left
corner of the logical plotting area is offset from the hardware origin by the values XOFF and YOFF as
specified by the OFFSET command.
Lying within the logical plotting area is the data plotting area. The size of the data plotting area is
reduced from the logical plot area by the margins in X and Y (XMARGIN, YMARGIN), as specified by
the MARGIN command. These margins are designed to provide sufficient space around the data plot
area for the axes tick marks, labels and titles. The actual size of the plot area is hence
Data Plot area: length = XSIZE-2*XMARGIN
height = YSIZE-2*YMARGIN
Note, GENPLOT does not like specifying offsets and sizes that cause the data plotting area to exceed
the hardware plot boundaries. The right and top margins may be positioned outside the hardware
plot area, but the size of the logical plot area will be reduced to prevent the data plot area from
exceeding the hardware clip boundaries. Both the margins and the size must be positive quantities.
Only the hardware boundaries and the data plot area clip vectors to be drawn. It is acceptable to
set XMARGIN and YMARGIN to zero so that the data plotting area is equal to the logical plot size.
However, it will be necessary to offset the plot in order to have labels appear on the plot.
In addition to the layout described above, it is also possible to rotate the plot by 90 degrees. In
reality, this is simply a case of having the hardware plot area exchange X and Y values. All other
definitions and relationships hold for the logical and data areas. The FLIPXY command handles the
orientation of the plot.
Finally, the entire plot may be shrunk or magnified by a constant. The SHRINK command divides
every vector by a constant before plotting. This results in a plot which is magnified, when the
argument is less than 1 and shrunk when the argument is greater than 1. Generally, you should
shrink a plot rather than changing its size when trying to fit it into a given area. SHRINK maintains
the size relationships between axes and labels, whereas labels maintain a constant size if the plot
is reduced using the SIZE command. Use SIZE to set the aspect ratio of the plot, and SHRINK to
generate the proper size plot.
The current settings of all these parameters is listed by the PARAMETERS command.
4f-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section F – Size and Position of Plot
SIZE
Syntax: SIZe [<xsize> <ysize>]
The SIZE command sets the horizontal and vertical lengths of the logical plotting area, XSIZE and
YSIZE. The values <xsize> and <ysize> are specified in inches and may be mathematical expressions. If <xsize> or <ysize> is less than or equal to zero, the current setting of the corresponding
XSIZE or YSIZE variable will not change. Both XSIZE and YSIZE are always maintained as positive
real values. Default values for <xsize> and <ysize> in the SIZE command are 0.0, ie. no change.
The current setting of the plot area may be obtained with the PARAMETER command.
Since the logical plotting area includes margins in X and Y for the axes labels and titles, the actual
axis length will be reduced from the size given with this command. The actual X axis length will
be XSIZE − 2 ∗ XM ARGIN and the Y axis length will be Y SIZE − 2 ∗ Y M ARGIN (see MARGIN
command below). The size specified by this command may also be modified if the data plotting area
would extend outside the hardware plotting area. In such cases, the SIZE is reduced to a maximum
value for which the data plotting area just extends to the right or top hardware clip boundary. Note
that the top and right margins may be placed outside the hardware clip boundary, only the data
area must remain legal.
Note: The size specified is scaled by the current SHRINK setting. Physical size will be the specified
values divided by the current SHRINK value. Also, setting the size does not prevent the drawing of
labels or text outside of this area. Labels may be drawn up to the hardware clip boundaries.
¾
»
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
size 11.0 8.4 margins 0.85 0.75
axis
size 8.0 8.0 margins 0.0 0.0
offset .85 .75
axis
shrink 2 axis
shrink 1 size 80 80 axis
/*
/*
/*
/*
/*
/*
/*
Reset default values
Standard axis
Set data area to 8x8
Fake the margin
Draws a real 8x8 data box
Draws a real 4x4 data box
Fill entire hardware area
¼
See also: MARGIN, PARAMETER (PARMS), SHRINK, SUB PLOT
OFFSET
Syntax: OFfset <xoff> <yoff>
The OFFSET command specifies the distance, in inches, between the hardware plot origin and the
logical plot area, XOFF and YOFF. The command is normally used either to center a plot on the
hardware page, or to move the plot so that all of the axes labels are plotted properly. At initialization,
XOFF and YOFF are set to (0.5, 0.0). The values <xoff> and <yoff> are specified in inches and may
be mathematical expressions. If <xoff> or <yoff> is less than zero, the current setting of the
corresponding XOFF or YOFF variable will not change. Default values for <xoff> and <yoff> in the
OFFSET command are -1, ie. no change. The current setting of the offset may be obtained with the
PARAMETER command.
Note: The offset specified is scaled by the current SHRINK setting. Physical offset will be the specified
values divided by the current SHRINK value. Also, setting the offset does not prevent the drawing of
labels or text in this area. Labels may be drawn up to the hardware clip boundaries.
4f-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section F – Size and Position of Plot
You can put several plots on one page by turning AUTOERASE OFF and using OFFSET to vary the
location of each plot.
¾
»
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
size 8.0 8.0 offset 1.5 0.2
axis
autoerase off shrink 2.0 erase axis
offset 9.5 0.2 axis
offset 1.5 8.2 axis
offset 9.5 /
axis
shrink 1 autoerase on offset 0 0
/*
/*
/*
/*
/*
/*
/*
Centered plot
Standard axis
Draw one axis
Second axis same page
And a third
And the fourth
Reset parameters
¼
See also: SIZE, PARAMETER (PARMS), SHRINK, AUTOERASE, SUB PLOT
MARGINS
Syntax: MARGins <xmarg> <ymarg>
The MARGIN command may be used to the change the size of the margins maintained around the data
plot area for axes tick mark, labels and titles. At initialization, the margins XMARGIN and YMARGIN
are set to 0.85 and 0.85 inches respectively, sufficient space for normal axes labels. The values
<xmarg> and <ymarg> are specified in inches and may be mathematical expressions. If <xmarg> or
<ymarg> is less than zero, the current setting of the corresponding XMARGIN or YMARGIN variable will
not change. Default values for <xmarg> and <ymarg> in the MARGIN command are -1, ie. no change.
The current setting of the margins may be obtained using the PARAMETER command.
Twice the margins (for both sides of the plot) are subtracted from the logical plot size to determine
the window for actual data plotting. If the tick mark labels become too long to fit within the
hardware plot area (especially a problem on the Y axes where they are drawn horizontal), the
margin may be increased to provide adequate space for the labels. An alternate solution to this
problem is just to OFFSET the plot horizontally. Normally, the other use for the MARGIN is to set
both XMARGIN and YMARGIN to 0.0 so the data plot area coincides with the logical plot area. An
OFFSET must be specified in this case for the axes labels to be plotted at all.
Note: The margins are also scaled by the current SHRINK setting. Physical margins will be the
specified values divided by the current SHRINK value. Plotting of labels may also extend beyond the
margin area up to the hardware clip boundaries.
¾
»
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
size 11.0 8.4 margins 0.85 0.75
axis
size 8.0 8.0 margins 0.0 0.0
offset .85 .75
axis
/*
/*
/*
/*
/*
Reset default values
Standard axis
Set data area to 8x8
Fake the margin
Draws a real 8x8 data box
¼
See also: OFFSET, PARAMETER (PARMS), SHRINK
4f-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section F – Size and Position of Plot
SHRINK
Syntax: SHrink <factor>
The SHRINK command provides a simple way to shrink (or magnify) a plot by a constant value in
both X and Y, maintaining the current aspect ratio. It is especially useful for fitting plots into a
small area without the labels becoming unreasonably large compared to the plot (as would happen
by simply setting the SIZE to a smaller value). At initialization, the shrink factor is set to unity.
The value <factor> is dimensionless and the absolute value of the specified number will be used.
A value of 0.0 results in a drug infested error message and no change. The default in the SHRINK
command is 1.0, resulting in a full size plot again. The current setting of SHRINK may be determined
with the PARAMETER command.
Shrink values greater than one result in plots smaller than full size. For example, SHRINK 2 produces
a graph exactly 1/2 as large in all aspects as the original. The effect of SHRINK is not cumulative
though; typing another SHRINK 2 command will produce exactly the same graph. SHRINK 1 returns
to the default of full size plots. Shrink factors less than one result in magnification of the plot.
SHRINK 1/2 will produce a plot twice as large (although, almost certainly, the plot will be hardware
clipped to less than this value).
The shrink factor affects all of the previous plot layout commands. The numbers specified as inches
will be divided by the shrink factor. For instance, with SHRINK 2, specifying an offset of 1.0 × 1.0
will result in an actual physical offset of only 0.5 × 0.5. Only the hardware clip boundaries are
unaffected by the SHRINK command. Vectors plotted in absolute inches are also affected by the
command. ANNOTATE especially will place absolute positions at the shrink factor value rather than
at the specified inches.
¾
»
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
size 11.0 8.5 margins 0.85 0.75
axis
shrink 2.0 axis
shrink 0.8
shrink / axis
/*
/*
/*
/*
/*
Reset default values
Standard axis
An axis half the size
An axis 1.25x larger
Back to the default
¼
See also: SIZE, OFFSET, MARGIN, PARAMETER (PARMS)
SUB PLOT
Syntax: SUB Plot [-CANcel | -ENTer x1 y1 x2 y2]
This command will automatically adjust SIZE and OFFSET to create another plot based on the cursor
or given coordinates. This is generally used to create a subplot within the current plot area. It could
also be used to put multiple plots on one page. You can either use the box cursor (see Essentials
for how to use the box cursor) to select the size and location of the plot or specify the coordinates
on the command line. If the coordinates are entered manually with the -ENTER option they should
specify opposite corners and be given in inches.
Once you are in subplot mode, GENPLOT commands will operate on that plot region. Use SUB PLOT
-CANCEL to cancel the subplot region and return to the original plot area. The -CANCEL option returns
plotting to the standard plot area. You can have more than one subplot on the page, but -CANCEL
always returns you to the main plot area.
4f-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section F – Size and Position of Plot
When using SUB PLOT, keep in mind that you are drawing on the equivalent of a pen plotter. The area
behind the subplot will not be erased. Below is an example of SUB Plot usage. This was generated
by one of the example macros from Section 5.
¾
»
1.5
0.4
Al75Re21Si4
Al76Mn17Ru4Si3 quasicrystal
Al79Ru21
Al78Cr17Ru5
}
-1
0.2
Pd80Si20
o-Al6Mn
Q
internal friction Q-1 (10-3)
-3
(10 )
0.3
0.1
1.0
0.0
0
1
2
3
4
5
T(K)
0.5
0.0
0
20
40
60
80
100
T(K)
½
¼
FLIPXY
Syntax: FLIPXY [YES | NO]
The FLIPXY YES command causes the plot on the physical paper to be rotated by 90 degrees. By
default (normally), the X axis is chosen to be the long direction of the paper; this command rotates
the plot 90 degrees so the Y axis corresponds to the long paper direction. This is often necessary
when plots are to be included in typed text or when making some figures. If the direction of the
plot is flipped, it is almost always necessary to either change the plot SIZE, and/or to SHRINK the
entire plot to fit within the new hardware boundaries. At initialization, FLIPXY is set to no.
To rotate the plot, use the FLIPXY YES command. It may be reset later using FLIPXY NO. Both
rotated and normal plots may be included on the same page if desired — no reinitialization of the
plotting device is necessary for the FLIPXY command. I apologize, but there is currently no way to
specify the opposite direction of rotation.
The direction of rotation is generally chosen such that plots can be incorporated into most word
processing software. For hard copy devices such as POSTSCRIPT, there may also be an alternate
sub–device which handles the rotation more conveniently than FLIPXY. See Appendix D.
This command works on video monitors as well as hard paper plotters. However, be prepared to sit
sideways for several hours when working in FLIPXY YES mode (or turn your monitor by 90 degrees).
Note: The FLIPXY command is active only at the lowest level of a device driver. Hence, all of the
above commands, SIZE, OFFSET, etc. still refer to X and Y in terms of the plot, not in terms of the
paper. The Y direction is now along the long paper direction for all commands.
4f-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section F – Size and Position of Plot
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
/*
/*
/*
/*
/*
/*
/*
flipxy yes
shrink 1.8 size 8 8
offset 0.0 4.0
axis
flipxy no shrink offset 0 0
autoerase off axis
shrink 1 autoerase on
Go to flipped screen mode
Make if fit
Offset refers to user X,Y
Draw rotated axes
Alternate direction
And the other direction
Reset
¼
4f-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
G. PLOT INFORMATION
CURsor
PARameter
SHow
STatus
Examine data point values with the cursor
List various plotting parameters
Display the current data set as x,y pairs
Display the data set information
This section describes commands that allow you to examine information about the plot. The CURSOR command displays individual point values. STATUS tells you how many points you have, the
maximum you can have and what the current minimum and maximums are. SHOW will print your
data values on the screen and PARMS will show the current plot settings such as labels and regions.
CURSOR
Syntax: CURsor [ [-CURVE] <curve>] [-TRACK [-Point <n>]]
The CURSOR command provides the user interface to read data values or trends directly from the appropriate devices. The CURSOR command will return with no action or an error message if attempted
on a device without a hardware cursor. It is normally used with video devices.
WARNING: It is possible to hang the system if a cursor is requested from a device which sometimes
has a cursor, but which in actuality does not! DO NOT DO THIS! GENPLOT will go out and look
for a cursor point but never get one.
The exact nature of the cursor depends on the current plotting device. On graphics screens, it is
generally some form of a cross–hair extending full screen when possible. On plotters, such as HP pen
plotters, the cursor is implemented using the pen as the pointing object. Without options CURSOR
displays the cursor at the last cursor location or at the last plot location. The cursor is moved using
either keyboard arrow keys or keys on the plotter.
The cursor coordinates are returned by pressing other than an arrow key or by pressing the appropriate hardware enter key. In CURSOR, the current coordinates are printed to the terminal. If the key
pressed to enter the coordinates was either a <space> or the <0> key, the cursor will immediately
recycle and be redisplayed. Pressing any other key terminates the cursor mode. The coordinates
corresponding to the LEFT and BOTTOM axes are always printed. TOP and RIGHT coordinate values
are also printed if either axes is enabled (on). Values for nonlinear axes are current as long as the
region defined for the nonlinear axis is identical to the linear counterpart.
When cursor finishes, it sets the variables XCUR, YCUR and CCUR (also CURX and CURY) to the last
coordinate reported and the key value which terminated the cursor mode. The values correspond to
the appropriate coordinates for the current settings of PLX and PLY. The values remain defined and
valid until the next CURSOR command.
4g-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section G – Plot information
¾
»
GENPLOT: region left 0 10 region bottom -5 20
GENPLOT: region top 1 4 region right 0 2000
GENPLOT: axis curs
/* Draw axes and request cursor
Cursor: Z (space) recycles.
cursor: XB = -1.825764
YL =
1.865079
cursor: XB =
2.344764
YL =
4.365079
GENPLOT: xtop on curs
/* Turn top axis on
Cursor: Z (space) recycles.
cursor: XB =
7.500001
YL =
5.000000
XT =
2.000000
YR =
999.9999
GENPLOT:
½
¼
–Track
The -TRACK option causes the cursor to follow your data point by point, instead of freely moving
over the screen. It is generally implemented only on screen devices. On devices that draw characters
in the graphics mode (not Hercules) the point number and the X and Y values of the current data
point are printed automatically on the screen as the cursor moves. The -POINT sub–option causes
the cursor to start at the <n-th> point rather than at last position (or the first point if this is the
first call to CURSOR). Data points which lie off the plot screen cause the cursor to be placed on one
of the plot boundaries; the values listed on the terminal are correct nonetheless. The LEFT and
RIGHT arrow keys move the cursor through the data set. On IBM–PC devices, the movement may
either be one point at a time in slow mode, or several points at a time in fast mode (see discussion
of the PC devices below). The UP and DOWN arrows cause movement through the data set in
a direction which causes the Y value to increase or decrease respectively, stopping when the local
maximum or minimum is found.
The ‘F’ key causes the cursor to go into “find” mode. If you have a large data set it can take quite
a while to move to the point of interest TRACKing the data. Pressing the ‘f’ key frees the cursor from
the data and allows you to move it freely across the screen. Pressing any another key will force the
cursor to “reattach” to the closest point and start tracking again. On mice, holding down the left
button is equivalent to the ’f’ key mode.
Pressing the <space> key at any time causes the current point value to be printed on the terminal;
pressing any other key leaves the cursor mode as described above.
If a curve is specified with the CURSOR command, the tracking cursor will follow data in that curve
instead of the main curve. The -CURVE option is not required but the curve name must occur before
any other options.
4g-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section G – Plot information
¾
»
GENPLOT: create y = sin(x) -from -10 -to 10
/* Make some data
GENPLOT: plot
/* Plot it
GENPLOT: curs -track -point 100
/* Track cursor from 100
I: 100 X: -0.5025118E-01
Y: -0.5023003E-01
I: 120 X:
1.959799
Y: 0.9252877
I: 85 X: -1.557789
Y: -0.9999154
GENPLOT: cursor -track
/* And again, default point
I: 85 X: -1.557789
Y: -0.9999154
GENPLOT:
½
¼
IBM–PC video devices
IBM–PC devices implement the cursor as a cross-hair which complements the pixels currently displayed on the screen.
The cursor on IBM-PC video screens is moved using the arrow keys (including the diagonal arrows)
of the keypad. The cursor has two speeds, a fast mode which corresponds to jump movements of
several pixels each time a key is pressed, and a slow mode which moves the cursor one pixel at a
time (auto–repeat works). On device initialization, the arrow keys pressed by themselves move the
cursor in fast mode. Simultaneously holding the <SHIFT> key down while pressing one of the arrow
keys switches the mode, in this case slowing the motion down to single pixel mode. These actions
may be reversed by pressing the <INS> key once; the arrows now move the cursor in slow mode while
the shifted arrows move the cursor in fast mode. Pressing the <INS> key again will toggle back to
the original settings. The setting of the cursor movement remains from one CURSOR invocation to
the next.
IBM PC Key Controls
←
Move left
<Home>
Move left and up
↑
Move up
<PgUp>
Move right and up
→
Move right
<PgDn>
Move right and down
↓
Move down
<End>
Move left and down
<SHIFT>
Momentarily switches the cursor speed as long as held down
<INS>
Toggles the speed of cursor movement
<CR>
Enters the coordinates
<f>
Switch from track to free movement
STATUS
Syntax: STatus [ [-CURVE] <curve>]
This command simply displays to the screen the status of the main data set or the specified curve
data set. The -CURVE specifier is not required. Information included is the number of points currently
defined in the main curve, the maximum number of points the curve can hold, and the minimum
and maximum values of the X and Y arrays. The status information is also printed when a data file
is read.
4g-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section G – Plot information
¾
»
GENPLOT: status
Curve ID: test.dat
Current data consists of
19 points. Max: 2048
X minimum = 0.00000E+00, maximum =
4.1600
Y minimum = 0.00000E+00, maximum =
39.900
GENPLOT: status c1
Curve ID: Backup data from yesterday
Current data consists of
883 points. Max: 883
X minimum = 0.00000E+00, maximum =
4.2900
Y minimum = 0.00000E+00, maximum =
97.210
GENPLOT:
½
¼
See also: SHOW, PARMS
SHOW
Syntax: SHow [ [-CURVE] <curve>] <low x> <high x>
The SHOW command displays to the screen all data points in the main or specified curve with X
coordinates between the low and high values specified, inclusive. Printed on the screen is the number
of the point within the data set, followed by the X and the Y values. Defaults for low and high
values are minus and plus infinity respectively. The following example accepts the default value for
the lower X bound by using the ’/’ and gives the upper X bound as 10.0. Points with values between
the curve minimum and 10.0 will be displayed.
¾
»
GENPLOT: status
Current data consists of
48 points. Max: 2048
X minimum = 5.28000
, maximum = 14.1600
Y minimum = 0.00000E+00, maximum = 139.900
GENPLOT: show
Lower X bound (minimum): / 10.0
I:
3 X:
8.160000
Y:
104.5000
I:
7 X:
6.260000
Y:
101.0000
I:
19 X:
7.620000
Y:
101.0000
I:
20 X:
6.740000
Y:
102.0000
I:
22 X:
5.280000
Y:
100.0000
GENPLOT:
½
¼
PARAMETER
Syntax:
PARamete
Synonyms: PARMS
4g-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section G – Plot information
GENPLOT includes a very large number of parameters describing everything from the layout of the
physical plot on the page, to the range and titles for the axis, to the type of symbols or lines used
to draw the data. The important parameters (almost by definition) are listed to the terminal using
the PARAMETER or PARMS command. The information given by PARMS falls into three major sections
or categories.
The first section is information directly concerning the data and the plotting parameters. The first
line specifies which axes are currently active for plotting the data (see PLX and PLY commands).
The second line gives the status of the autoranging mode for the X and Y axes, either BOTH, TOP,
BOTTOM or OFF for X and similar for Y (see AUTOX and AUTOY commands). The next line indicates
the status of the top and right axes, which can be either OFF, ON, BOTTOM or NONLINEAR
for the top and similar for the right axis (see XTOP and YRIGHT commands). The next four lines
give the current titles which are attached to the four axes. Following the titles are regions defined
for each axes (see SET and REGION commands). Any axis which is autoranged may have 0,0 as the
range indicated here. Finally, the linetype, the symbol, and the skip factor currently selected for
data plotting is given (see LTYPE, SYMBOL and NPOINT commands). NPOINT specifies how much of
the data set is to be plotted; NPOINT of 3 indicates every 3rd point.
¾
»
GENPLOT: parms
/* Request parameters currently set
Plotting X against Lower scale
and
Y against Left scale
Autoranging X: OFF
Y: OFF
Top axis: OFF
Right axis: ON
Bottom: Time (ns)
Left:
Current Density (Amps/cm)
Top:
Position (mm)
Right: Absolute Conductance
Bott range: -5.000000
20.00000
Top:
0.0000000E+00 4.000000
Left range: 0.0000000E+00 10.00000
Right: 0.0000000E+00 2000.000
LType: 0, SYMbol:
3 NPOint:
1
Plot device: EGA
Size:
10.00 by
7.80
Offset:
0.00 by
0.00
Margin:
0.85 by
0.75
Cursor available.
Hard copy not initialized
Current directory: F:\MIKE\GENDOC
Shrink:
Pen:
Speed:
1.000
1 of maximum
18
GENPLOT:
½
15
¼
The second major section describes the physical layout of the plot on the physical device, along
with information about the physical device currently attached for plotting. The selected plot device
is listed first (see DEVICE command), followed by specifications of the plot size, margins, offset
and shrinkage (see SIZE, OFFSET, MARGIN, and SHRINK). The currently selected pen, the maximum
number of pens supported by the device, and the speed of the pen (device dependent units) are also
provided (see PEN and SPEED commands). Finally, the availability of a cursor on the current device
is given.
4g-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section G – Plot information
The last section of the parameter listing may be any number of lines long and gives the status of
various sub-processes within GENPLOT. At a minimum, the status of the HARDCOPY processor
(see HCOPY commands) is listed, and the currently attached directory is given (see WHERE and CD
commands). If macros or other processors are established with non-default values, these would be
listed in this information as well.
4g-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
H. DATA ANALYSIS
EXchange
CReate
CULL data
EDIT dat
FIT
LSQFit
FIX Grid
SORT
TRANSfor
USER
Exchanges the X and Y elements
Create a data set with a function
Select a range of data
Add or delete data points with cursor
Fit the data to a curve
Least linear square fit
Force the data set against a linear grid
Sort the data by X value
Transform the data by various functions
User written general transformation and operation module
This section describes commands which analyze, fit or modify an existing data set or which create
new data sets. The commands can be subdivided into two categories. Commands in the first
category transform or modify the main curve, such as sorting, exchanging X and Y coordinates, edit
the data set, or impose a fixed grid. These include the SORT, EXCHANGE, TRADE, FIX GRID, CULL DATA
and EDIT DATA command.
The second sub–division is more complex and includes the commands CREATE, TRANSFORM, and FIT.
The CREATE command is used to create a data set from an analytic function (such as a theoretical
fit or a fitting function). The type and complexity of the function is limited only by the function
evaluator. Most of the intrinsic functions available in a FORTRAN environment are also available
in the function evaluator.
The TRANSFORM performs data transformations which are either impossible or difficult to perform
using the LET comand. For example, linear rescaling of the X data can be performed using the LET
command LET x = x*10+8. However, differentiation of the data set is difficult to write in a single
LET statement, and hence is included as a TRANSFORM command. Other transform capabilities include
generating histograms, differentiation and integration, fourier transforms, and autocorrelation. The
extension of this command to arbitrary transformations can be accomplished with the USER command
which passes program control to a user written FORTRAN subroutine.
Finally, GENPLOT includes a very powerful set of data fitting routines, obtained using the FIT
command. Data may be fit to a linear function (returning standard deviations and error estimates),
polynomial functions (up to order 6), splines (including smoothing splines), or to a user specified
arbitrary function. This last capability allows experimental data to be analyzed in terms of any
analytic function of 10 or fewer independent variables (if you need more variables, contact CGS).
This non-linear fit searches the parameter space of these variables to obtain the best fit (in a least
squares sense) of the data to the analytic function. The best fit estimate and an estimate of the
error are returned for each parameter.
With the exception of FIT, all of the commands are relatively simple to use. The complexity of using
FIT increases from simple in the case of linear, polynomial or spline fits, to reasonably complex in
the case of the generalized non-linear fitting routine. In accordance with the general maxim that
the most obscure a routine is the more powerful and useful it will be, users are advised to master
the complexity of the non-linear least squares. It is probably the most powerful and most generally
used of the analysis routines.
4h-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
USER
Syntax: USER [[-CURVE] <curve>] [-LOAD <user routine>]
The command USER transfers control of GENPLOT to a user written subroutine. This subroutine
may process commands or modify the data as necessary to implement any degree of user control.
Typical uses of the USER command include unusual transformations, control of instruments, or
implementation of additional commands. If an alternate curve is specified, it must be given before
any other options.
The USER subroutine, along with subroutines implementing the -USER options of the READ and WRITE
commands, are normally loaded from the dynamic module USER$.OVL. The -LOAD option redefines
the name of the load module to user routine and loads (or reloads) the specified module. Any
currently loaded module is first deallocated. user routine is limited to the name and extension
only and should be either in the current directory or in the C:\GENPLOT directory. If no extension
is specified, the default .USR is assumed (to distinguish it from normal GENPLOT routines). See
the Appendix S for details on writing USER routines.
¾
»
GENPLOT: USER
... Default USER$.OVL is loaded and the subroutine USER$ is executed.
GENPLOT: USER -LOAD RUMP
... Current USER routine is deallocated and RUMP.USR is loaded. The
... subroutine USER$ is passed control.
RUMP file reading routines now loaded
GENPLOT:
½
¼
SORT
Syntax: SORT [[-CURVE] <curve>] [options]
options: [-REverse|-Normal] [-STRict|-DELete]
options: [-RANdom] [-NOSort] [-AVErage] [-XONly] [-YONly]
The default option is — NORMAL.
The SORT command performs an in-place heap sort of the current data set. The result is either
ascending or descending in X value depending on the setting of the -REVERSE option. Either the
main or specified curve is sorted based on the X coordinate. If an alternate curve is to be sorted, its
specified must immediately follow the SORT command. A sort based on Y can be done by using the
EXCHANGE command before and after SORT. Arrays may be sorted by copying them to the X buffer
with Y set to zero.
The options -XONLY and -YONLY allow only the X or Y data sets to be modified without modifying
the other. The option -YONLY is obviously incompatible with SORT but can be used with the other
options described below.
The -STRICT and the -DELETE options are synonymous and generate a data set strictly ascending
or descending as required by the SPLINE fit function. In a strict sort, each X value may occur only
once; multiple points at the same X abscissa are deleted. By default, the Y value at such a point
is set to the Y value of the first point located. The -AVERAGE options modifies this default so that
the Y value is set equal to the average of all matching points. The number of data points deleted
by the -STRICT option is printed after completion of the sort.
4h-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
The option -NOSORT does not sort the data but can be used with the -DELETE option to delete
duplicate points without actually sorting the data. -NOSORT can also be used -REVERSE to simply
reverse the order of the data set.
The -RANDOM option is the inverse of the -SORT option and does an unsort by randomizing the data
set. The X,Y pairs will be randomized as pairs unless the -XONLY or -YONLY is specified.
The heap sort used by this command is extremely efficient and should take less that 10 seconds for
any data set on an AT level computer. Pressing <CTRL><BREAK> will abort out of the sort, but the
resulting curve will be only partially sorted and may be corrupted if any points have been deleted.
¾
GENPLOT:
GENPLOT:
GENPLOT:
SORT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
SORT
SORT -REVERSE
SORT -REVERSE -DELETE
3 points deleted
exchange sort exchange
retrieve c1 sort archive c1
/* Simple sort of a buffer
/* SLOW now (AARGH)
/* Strict sorting
let npt = 80 let x = array
let y = 0 sort let array = x
/* Sort 80 element array
/* And replace it
/* Sort on Y instead
/* Sort a curve
¼
EXCHANGE
Syntax: EXchange [[-CURVE] <curve>]
Synonyms: TRADE [[-CURVE] <curve>]
The EXCHANGE or TRADE command simply exchanges the X and Y elements of the main curve or
specified curve. The points are switched with no checking or sorting, from point 1 to point NPT.
Two exchanges will result in X being returned to the X coordinate. The EXCHANGE command may
be used to reverse the plotting order, or to set up a data set for operations which use only one of
the X,Y variables (such as SORT above).
¾
GENPLOT: EXCHANGE
GENPLOT: SORT
GENPLOT: TRADE
GENPLOT:
½
»
/* Y -> X, X -> Y
/* Sort on the Y variable
/* And reset to original X,Y order
¼
See also: SORT
4h-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
FIX GRID
Syntax: FIX Grid [[-CURVE] <curve>] [options]
options: [-Points <n>][-Range <xmin><xmax>] [-FROM <xminx>][-TO <xmax>]
Option Defaults:
-RANGE Range of the X coordinate of the current data set.
-POINTS Number of points in the data set (NPT)
The FIX GRID command causes the data in the main curve (or the curve specified immediately
following the command) to be linearly interpolated so that the X coordinates of the modified data
set are evenly spaced within the specified interval. This command is used, for instance, prior to a
Fourier transformation to create a evenly spaced X coordinate set with NPT equal to an even power
of 2. The other primary use is to fix the X grid before adding or subtracting two curves taken under
different conditions with different abscissa. In this latter case, it is preferable to use SPLINE fitting,
and then create a new data set from the SPLINE fit since this command uses only linear interpolation.
However, FIX GRID is substantially faster and, if the data does not have massive curvature, similar
results are obtained.
If a range is specified using either -RANGE, -FROM or -TO options, the X coordinates in the final data
set will extend from exactly <xmin> to <xmax>. If either <xmin> or <xmax> extend beyond the actual
X range of the data set, the Y value for points outside the real X range will be set to the value at the
boundary (no extrapolation, constant value extension of the function to plus and minus infinity).
If the -POINTS option is specified, the final data set will contain exactly <n> points; otherwise the
final data set will have the same number of points as the initial data set. The parameters are not
“sticky” and must be specified each time FIX GRID is used.
Limitations: The success of FIX GRID can only be guaranteed in cases where the initial data set and
the final data set can be stored in the main curve simultaneously, i.e. npt + nptnew < nptmax.
FIX GRID will normally succeed in cases with many more points, but pathological positioning
of the X coordinates may cause the error message "So sorry Charlie, possible data error
(FIX GRID)" to occur. The data set may be corrupted in such cases.
¾
»
GENPLOT: read test1
Current data consists of
19 points.
X minimum = 0.00000E+00, maximum =
Y minimum = 0.00000E+00, maximum =
GENPLOT: fix grid -points 512
GENPLOT: archive c1 read test2
Current data consists of
47 points.
X minimum = 0.00000E+00, maximum =
Y minimum = 0.00000E+00, maximum =
GENPLOT: fix grid -points 512
GENPLOT: let y = y+c1:y
GENPLOT:
½
/* Read real data
Max: 2048
39.900
4.1600
/* Create a set for FFT
/* Archive and read next
Max: 2048
39.900
8.7100
/* Fix its grid also
/* Add the curves together
¼
4h-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
CULL DATA
Syntax: CULL data [[-CURVE] <curve>] {DELETE | KEEP | ZERO | WINDOW }
options: {XRANGE <x1> <x2> | YRANGE <y1> <y2> | RANGE <x1> <x2> <y1> <y2>|
options: CURSOR | BOX | FOR <logical exp> | ABORT}
Option Defaults:
-RANGE Default range is [±∞, ±∞]
-XRANGE Default range is [±∞]
-YRANGE Default range is [±∞]
Data culling is the processing of keeping or deleting data by specifying some criteria. In GENPLOT,
the culling may be performed in either keep, delete, zero or window mode. The zero and window
mode maintains the number of points and the X coordinates but zeros the Y value either within or
outside the specified range. The data range may be specified by either a X and/or Y range (numbers
or by cursor), or by specifying a logical expression involving data, functions or other criteria.
If an archived curve is to be culled, the curve specification must immediately follow the command.
The next item on the command line selects the mode of operation as either KEEP, DELETE, ZERO or
WINDOW. Every point in the data set is tested against the criteria. Points which satisfy the condition
are operated on as specified by the mode. Points not satisfying the criteria have the obvious opposite
action taken. The WINDOW mode causes all data points not satisfying the criteria to be zeroed, points
satisfying remain unchanged.
The criteria is either specified as a rectangular region of the data space, or as a logical expression. The
RANGE, XRANGE or YRANGE specify where the rectangular region is located. For XRANGE and YRANGE,
the opposite Y or X range is considered ±∞. Data points falling on the boundary satisfy the test
criteria. The BOX and CURSOR specifications are equivalent to the RANGE specification, except that
the range is designated using a box cursor on the screen. See the ZOOM command for a description
of using the box cursor.
The logical expression may include both logical and real expressions. A real expression is considered
true if the value is greater than zero. All other values are considered false. Expressions may depend
on the data set itself or on any other currently defined function, array or curve. The actual data
is modified as the tests proceed. Hence, local forward references are valid (such as Y(I+2)), but
backward references may fail (such as Y(I-2)). If such references are required, ARCHIVE the main
curve to a temporary named curve and perform the test on the archived version (see the ARCHIVE
command).
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
/* Delete all points with X value in the range [-1.38,1.85]
cull data delete xrange -1.38 1.85
/* Now, keep only points with Y in the interval [1.7 4.6]
cull data keep yrange 1.7 4.6
/* Now, delete all points where abs(f(x)-y) >= 0.1*abs(y)
cull data delete for [abs(f(x)-y) >= .1*abs(y)]
¼
Note: Quotes would be necessary on the last expression if the braces are not used.
4h-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
EDIT DATA
Syntax: EDIT dat [[-CURVE] <curve>]
Suppose your boss wants you to plot your data, and he expects it to fit his theory exactly. The
problem is, there are a few strange points which don’t seem to fit. How do you get rid of them?
The EDIT DATA command is a plot–screen oriented data editor. It allows points to be deleted from
or added to the main or specified data set using the cursor as a pointing device. (Ah — for the days
of faking the data.) If you want to change your data to fit the theory better, then this command is
pretty handy. This makes bosses happy, but watch out for your colleagues.
If no curve is specified, the current data set is edited. Generally, the data should be plotted using
symbols just prior to executing this command. EDIT DATA will enter a cursor mode with the cursor
free to move over the entire screen (free mode). Pressing <T> toggles the cursor to the tracking
mode. As in CURSOR -TRACK, the cursor in track mode can only lie on data points. Other keys have
the following affect:
<space>
print out the current position of the cursor (data units)
<D>
delete the nearest point (within reason)
<X>
delete the nearest point (within reason)
<A>
add a point at the cursor position (if in free mode)
<T>
toggle cursor between tracking mode and free mode
<F>
enter tracking mode to find a point
<other>
exit edit data mode and return to GENPLOT
On screens properly equipped, deleting the point will actually cause the current symbol to be erased
at the point. Adding a point adds a symbol at the given position as well. If the data is plotted as
a line, the line segments will not change although the data will be modified. EDIT DATA only draws
symbols, not lines.
¾
»
GENPLOT: plot -lt 0 -sym 3
/* Nice data plot for EDIT
/* Enter the editor
GENPLOT: edit data
Cursor at:
103.746
20.1183
Point # 008 deleted:
104.000
20.000
Point # 128 added:
105.024
23.121
GENPLOT:
½
¼
CREATE
Syntax: CReate Y = <fnc> {[-From <r1>] [-To <r2>] | [-Range <r1> <r2>]}
[-Points <n> | -By <dx>]
Option Defaults:
<fnc> None. Must be specified.
-FROM Previous -FROM specification. The value is retained as a string rather than just a
number; function declarations will be evaluated each time.
-TO Previous -TO specification. Retained as a string also.
-RANGE See -FROM and -TO defaults.
-POINTS Previous -POINTS specification. Retained as a string.
-DX Previous -DX specification. Retained as a string.
4h-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
The CREATE command replaces the data in the main curve with values created according to the
specified function. This command allows you to create and plot almost any arbitrary function. The
function may be of interest itself or it may be the theoretical fit of experimental data. In either case,
CREATE operates by first creating a uniform grid in X extending from the lower <r1> to the upper
<r2> X limit, consisting either of exactly <n> points or of points spaced by <dx>. The Y value of
each X grid point is then set equal to the function specified.
The tokens ’Y =’ are actually optional, but if present must be separated by spaces from each other
and the <fnc>. The function itself, as a single token, must not contain spaces unless it is enclosed in
quotes or a pair of bounding parenthesis. If the function is not specified on the same command line
as CREATE, the equation may be entered in response to the “ Y(X) = : ” prompt without concern
for spaces or quotes. However, no options may be used with the CREATE function in this format.
Support is provided for almost any function you will routinely use. See the Expression Evaluator
section for further information.
The -FROM option specifies the lower bound in X for creation of the function while the -TO option gives
the corresponding upper bound in X. -RANGE is equivalent to specifying both -FROM and -TO. The
options -POINTS and -BY are mutually exclusive; only one may be specified and -BY takes preference
over -POINTS. -POINTS specifies the number of points which should be created in the the data set.
-BY specifies that the X coordinates should be spaced with increments <dx> for x1 ≤ minimum to
xn ≥ maximum value. The actual value of <dx> may be modified so that the entire range can be
covered by the maximum number of points, i.e. dx >= (xmax-xmin)/nptmax.
The option values <r1>, <r2>, <n> and <dx> are retained between calls of CREATE and hence need be
specified only if they have been changed. These parameters are stored as strings, and may contain
function calls themselves which will be evaluated each time CREATE is executed. At initialization,
the values of these parameters are:
<r1> - @MIN(X)
<r2> - @MAX(X)
<dx>
- 0
<points> - 200
Thus, unless modified, CREATE will create a curve extending from the minimum to the maximum of
the current data set using 200 points. If there is no data in the current data set, the default range
will extend from 0 to 1.
¾
GENPLOT:
GENPLOT:
Y(X) = :
GENPLOT:
GENPLOT:
½
»
create y = sin(x)*exp(x/10) -from -10 -points 1000
create
sin(2*x)*exp(x/10)
create c1:y+nint(x) -from @min(c1:x) -to @max(c1:y) -dx 1
create spline(x) -points npt*2
¼
TRANSFORM
Syntax: TRANSform [[-CURVE] <curve>] {X | Y | XY | List | Abort}{transform type}
The TRANSFORM command is used to transform X or Y data by a number of commonly requested
transformations. It does not implement simple transformations which are easily implemented in
the form let x,y = g(x,y),h(x,y). Rather, TRANSFORM is limited to those transformations where
vector math operations are inappropriate, such as integration, differentiation, fourier transforms,
histogram binning, rotations etc.
4h-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
TRANSFORM operates by default on data in the main data set. To operate on an archived curve,
specify the curve name immediately following the TRANSFORM command. Some transforms can be
applied to either one or both of the X and Y arrays of the main curve. If the first token following
TRANSFORM is an X, Y, or XY, the transformation will be applied to the appropriate variable(s).
If none is specified, only the Y variable will be transformed. The subsequent tokens specify the
particular transformation and any parameters required by the transformation. The special token
LIST will list the currently available transformations and return to request the transformation again.
Either accepting the default or typing ABORT will cause no transformation to occur and will return
immediately to GENPLOT.
Specifying X, Y or XY does not always make sense. In general, specifying X causes the X and Y
arrays to be exchanged with the transformation operating on the new Y array. The arrays are
again exchanged before return to GENPLOT. The XY mode is identical to Y for all except the ROLL
command; for ROLL, both X and Y are rolled together with XY mode.
Some transforms, such as SQUISH, only make sense operating on both X and Y and will always do so.
Other commands, such as ROTATE, will have the “sense” (direction) of the transformation changed
by specifying X. Still others, such as BASELINE, may go bonkers if X is specified. Finally, the second
exchange of X and Y back to their original arrays is inappropriate for some commands (such as
histogram binning) and is bypassed. See the descriptions of the specific transformations for further
information.
The list of available transforms is given below. Several, including the FFT, have numerous suboptions
to further control the type of transformation.
Syntax
Description
AUTOCorrela
BASEline <cursor>
BIN <width>
CBIN <width>
CENTERBin <width>
CONVolution <cv>
CORRelation <cv>
DECONVoluti <cv>
DEPHase
DIFference
DY/DX
FFT <options>
FILTER fft <fnc>
HISTogram <width>
INTegral
ROLL <pts>
ROTate <deg>
SMooth
SMOOTH fft
SQUISH <n>
SUM
ZERO pad <npt>
Generate autocorrelation of data
Subtract a baseline defined by two points
Synonym for HISTOGRAM
Synonym for CENTERBIN
Generate histogram with centered bins
Generate convolution of data set with curve
Generate crosscorrelation of data set with curve
Deconvolute data set by specified curve
Generate continuous phase curve by adding 2nπ
Difference between points (not DIFFERENTIAL)
Evaluate differential of data set at each point
Fast Fourier Transforms (many modes)
Filter data set in frequency space using FFTs
Histogram data into a bins of specified width
Evaluate integral of data set at each point
Roll (shift) points within the data set
Rotate the data about origin by specified angle
Smooth X or Y by a 5 point smoothing algorithm
Smooth X or Y by FFT filter algorithm
Compress data by keeping only every Nth point
Sum elements of the curve (not an INTEGRAL)
Pad data to NPT by adding 0’s and even spacing X
List
Syntax: List
4h-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
The LIST command types out a list of the recognized transformation commands (normal terse mode).
Following this quick list, the query for the type of transformation will be repeated. Type ABORT to
exit transform without modification to the data set.
¾
»
GENPLOT: transf
Transform X or Y? (abort) list
Valid transformations:
LIst
/
ABORT
ROTate
ROLL
SUM
HISTogram
BIN
CENTERBin
AUTOCorrela CORRelation CONVolution
ZERO pad
BASEline
DEPHase
X
DIFference
CBIN
DECONVoluti
Y
DY/DX
FFT
SQUISH
XY
INTegral
FILTER fft
COMPress
Transform type [LIST]: abort
GENPLOT:
½
¼
Abort
Syntax: ABORT
Abort out of the transformation operation without doing anything. Usually typed if you’re not sure
what you’re doing, or if you realized that the transformation you wanted doesn’t exist after asking
for a LIST of transforms. No harm will have come to the your data.
SUM
Syntax: SUM
The SUM command is not equivalent to the INTEGRAL command described below. Rather SUM simply
i
X
adds all the previous points in the array. y ←
yj . The number of points in the array is
j=1
unmodified.
DIFference
Syntax: DIFference
The DIFFERENCE command is not equivalent to the DY/DX command described below. Rather DIFFERENCE does a point by point difference between the value of the current and previous point. The
value at the first point is set to zero. DIFFERENCE is the format inverse of the SUM command.
y(i) ← yi − yi−1 . The number of points in the array is unmodified.
Integral
Syntax: INTEGRAL
Synonyms: INTEGRATE
The INTEGRAL command does a point-to-point trapezoidal integration of the data set. The data
are not sorted prior to integrating, and the value of the integral at the first data point is taken as
4h-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
zero. The number of data points does not change with the integration transformation. Formally,
the integration is performed as:
Ynew (1) ⇐ 0
Ynew (I) ⇐ Ynew (I − 1) + [Xold (I + 1) − Xold (I)] ∗ [Yold (I + 1) + Yold (I)]/2.0
Yold ⇐ Ynew
DY/DX
Syntax: DY/DX
Synonyms: DIFFERENTIATE
The DY/DX command estimates the derivative of the function at each point in the data set using a
3 point constant curvature algorithm. A quadratic function is fit between the given point and the
two directly adjoining points. The differential is evaluated from this quadratic. The two end points
are handled by assuming the data continues with the same curvature. This differentiation is exact
to second order. The number of data points is unmodified by this command and the derivative is
given at the original X values.
Rotate
Syntax: ROTATE <deg>
The data set is rotated about the X,Y origin counterclockwise by specified number of <deg> degrees.
Specify X or negative <deg> for clockwise rotations. Both X and Y arrays are always modified by
this transformation.
ROLL
Syntax: ROLL <pts>
The ROLL command rolls each point with the array or curve by the specified number of points to
high number positions. For ROLL 1, the first point becomes the second, the second the third, and
the last is rolled into the first position. The <pts> value may be an arbitrary integer, but only the
equivalent shift is performed (i.e. ROLL NPT is a no operation). The ROLL may be performed on
either X or Y independently or on the entire curve using XY mode.
SQUISH
Syntax: SQUISH <n>
Sometimes, but not very often, you have too much data. The SQUISH command eliminates data by
keeping only every Nth point from the data set. This command always operates on both X and
Y with the final number of points in the set equal to NPT/N. (Hint: SQUISH can be used in FFT
transformations to obtain a finer frequency grid.)
COMPRESS
Syntax: COMPRESS <n>
COMPRESS operates similarly to SQUISH but rather than simply throwing out the unused data points,
the Y values of deleted points are summed. The X array takes on the value of the mid point of each
summed Y block. The last Y element of the new array may have fewer summed values if NPT is not
evenly divisible by N.
4h-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
ZERO pad
Syntax: ZERO pad <npt>
The ZERO PAD command fills out a data set to the specified number of points by appending points
with Y set to zero. The X values of the additional points are created assuming a constant difference
between points as determined by the last two known X values. This command is normally used to
expand a data set to an even power of 2 before using the FFT operations.
BASEline
Syntax: BASEline <x1> <y1> <x2> <y2>
A baseline subtraction can be quickly performed using the BASELINE transform. While this does not
strictly adhere to the LET philosophy discussed above, it is so commonly used as to be included as
a transform. The BASELINE command requests two points; the default response / will bring up the
cursor to define the two points. The two points entered define a baseline which is subtracted from
each Y element of the curve. A vertical baseline is considered an error and can be entered to abort
out of the command.
SMooth
Syntax: SMooth
The data in the specified X or Y buffer are replaced by a 5 point weighted average of nearby points
to reduce noise. The implemented smooth is the 5 point Savitsky-Goulay algorithm where
yn =
−3 ∗ yn−2 + 12 ∗ yn−1 + 17 ∗ yn + 12 ∗ yn+1 − 3 ∗ yn+2
35
The smooth is stable and can be executed several times to any desired degree of smoothing.
SMOOTH fft
Syntax: SMOOTH fft <width>
The data is smoothed using the equivalent of an FFT filter operations. The filter is an inverted
quadratic 1 − (A ∗ F )2 where A is proportional to the specified <points> width. Larger values of
<points> removes higher frequency components for a correspondingly smoother curve. The linear
component of the data trend is removed before the FFT so the data set will always begin and end
at the same points and only data in between will be smoothed.
The X coordinates of the data set are ignored completely in this transformation and are assumed to
be uniformly spaced.
HISTOGRAM, BIN, CBIN, CENTERBIN
Syntax: BIN <width>
Synonyms: HISTogram <width>
Syntax: CBIN <width>
Synonyms: CENTERBIN <width>
The TRANSFORM Y HISTOGRAM command transforms the data set into a frequency of occurrence
histogram on the specified variable (X or Y). The Y data space is divided into a series of windows (or
bins) of the specified width <width>, extending around the actual Y data range. Within each interval,
the number of times the Y coordinate falls within the window is counted, this is the frequency of
occurrence for that window. The resulting data set after transformation has X coordinates set equal
4h-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
to the midpoint of each window, with the Y value set to the frequency of occurrence for that window.
The default width is 0.01 of the data range, i.e. data is bined into 100 regions. Bins are set up such
that there is one “empty” bin (i.e. with a value of 0) on either side of the data; this is necessary to
obtain a correct -HISTOGRAM plot. The specified <width> value may be modified if it would require
more data points for storage than are available in the curve.
Consider the following example.
¾
GENPLOT: show / /
I:
1 X:
173.0000
I:
2 X:
1.000000
I:
3 X:
2.000000
»
Y:
Y:
Y:
/* Show current data
19.00000
29.00000
18.00000
GENPLOT: transf y
/* Start the transformation
Type of transform [LIST|abort]: bin
/* Bin operation wanted
Min and max of data:
0.00000000E-01
2.00000000
Bin width (range/100): 5
/* And specify width size
GENPLOT: show / /
I:
1 X:
12.50000
Y: 0.0000000E+00
I:
2 X:
17.50000
Y:
2.000000
I:
3 X:
22.50000
Y: 0.0000000E+00
I:
4 X:
27.50000
Y:
1.000000
I:
5 X:
32.50000
Y: 0.0000000E+00
GENPLOT: plot -histogram
GENPLOT:
½
/* Nice way to plot it
¼
In the original data set, there were two points with y values between 15.0 and 20.0, the second bin
window. One point laid in the window between 25.0 and 30.0, resulting in the final transformation
of 0,2,0,1,0. The final plot command uses the -HISTOGRAM mode to draw the data in a normal
histogram type plot.
HISTOGRAM does not perform the second exchange on the data set on exit from TRANSFORM. X always
corresponds to the window midpoint and Y to the frequency of occurrence in either X or Y.
CBIN does a “centering” histogram with intervals centered about the origin. The BIN commands create bins between (0,width), (width,2*width) etc. CBIN yields bins at (–width/2,width/2), (width/2,1.5*width).
See also: PLOT –HISTOGRAM and OVERLAY –HISTOGRAM
DEPHase
Syntax: DEPHase
The DEPHASE command is used primarily after a FFT -PHASE transformation. Dephasing will add
2nπ to the given Y values to produce a continuously increasing (or decreasing) phase function
without the discontinuities. (It is not so useful for other inverse trigonometric functions since they
wrap mod π).
4h-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
FFT
Syntax: FFT <options>
The FFT transform approximates the fourier transform for a discrete data set. For code efficiency,
the FFT routines zero pad all curves to the next higher power of two. If this is larger than the
dimension of the array, the data set is instead truncated to the largest possible power of two. The
corresponding X array is assumed to be equally spaced and the frequency, if returned, is determined
by the first and last X points dω = 1/(xn − x1 ). The FFT algorithm is defined by:
Hn =
N
−1
X
Z
hk e2πikn/N
hn =
1
N
h(t)eiωt dt
−∞
k=0
N
−1
X
∞
≈
Hn e−2πikn/N
k=0
≈
1
2π
Z
∞
H(ω)e−iωt dω
−∞
Numerous options are allowed by the FFT command. The options are listed below according to
mutually exclusive blocks; only the last option defined from each block will be used. Options
marked with the * default on each entry to FFT. Options marked with a # are the initial default
but the setting is sticky, i.e. it will persist from one call to FFT to the next.
Option
Defaults
Description
-FORWARD
-INVERSE
-POWER
*
Evaluate the forward FFT transformation
Evaluate the inverse FFT transformation
Estimate the power spectrum from the data
-SQUARE
-PARZEN
-WELCH
#
Use a square window for power estimation
Use the PARZEN window for power estimation
Use the WELCH window for power estimation
-DATA
-CBUF
*
Perform FFT operation on the main data
Perform FFT on the complex arrays CBUF$R,
CBUF$I
-COMPLEX
*
Return complex transform in Y, real followed by
imaginary
Return the real component of the transform in Y
Return the imaginary component of the transform
in Y
Return the magnitude of the transformation
Return the phase of the real/imaginary transformation in Y
Return the phase followed by a DEPHASE transformation
Do not modify the Y array on return
-REAL
-IMAGINARY
-MAGNITUDE
-PHASE
-DEPHASE
-NOMODIFY
-DEFINE
-FULL
-HALF
Define/fill in CBUF$R and CBUF$I arrays with
transform
#
Return both negative and positive frequencies
Return only positive frequencies in the transform
4h-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
Option
Defaults
-RESOLUTION <n>
Description
Use every Nth point to improve structure at low
frequency
Synonymous with -RESOLUTION
-SKIP <n>
FFT transformations can be performed on either data in the main curve, or full complex transformations on a complex array described by a pair of real arrays. The array pairs must be called CBUF$R
and CBUF$I. The arrays are automatically defined and filled with the real and imaginary parts of the
transformation if the -DEFINE option is given. Once the arrays are defined, arbitrary rotations or
transformations of the arrays can be performed and the resulting complex pair inverted back to real
data space by TRANSFORM FFT -INVERSE -CBUF -REAL. This command returns the real component
of the transform to the Y array but inverts the CBUF pair.
The options -FORWARD -INVERSE and -POWER specify the type of transformation to be performed.
The 1/NPT normalization occurs on the inverse transformation only. Power estimation is valid only
for data in the main curve and is calculated using one of the windowing functions -SQUARE, -PARZEN
or -WELCH. Other windows may be used by multiplying the data by the appropriate window function
and selecting -SQUARE within the FFT transformation. The Y array is returned for a power spectra
as dB (20*log10 ). Specific weights used are:
Parzen :
¯
¯
¯ j − 21 (N − 1) ¯
¯
¯
wj = 1 − ¯ 1
(N + 1) ¯
µ
Welch :
wj = 1 −
2
j − 21 (N − 1)
1
2 (N + 1)
¶2
The set of options -COMPLEX, -REAL, -IMAGINARY, -MAGNITUDE, -PHASE, -DEPHASE and -NOMODIFY
select the data to be returned in the Y array. For other than -NOMODIFY, the X array is returned
with the corresponding frequency at each point. On -INVERSE, the original X values are restored if
the last FFT transform was a -FORWARD transformation on the same data set.
Normally, working with real data, the Fourier transforms are symmetric about zero frequency.
Rather than work with both halves, the FFT transform can return only the positive half spectrum,
selected using the -FULL or -HALF options.
The “resolution” of a Fourier transform can be enhanced by only keeping every Nth point in the
original data set. For a given N, the maximum frequency is reduced by N, but the number of points
per unit frequency is increased by N. There is no real increase in the resolution of the transform,
just more points across the existing data. The options -RESOLUTION and SKIP are synonymous and
specify the degree of enhancement. These options should be used with care in the -POWER estimation.
The window functions become one sided and operate only on the beginning of the data set.
Autocorrelation, Correlation, Convolution and Deconvolution
Syntax:
Syntax:
Syntax:
Syntax:
AUTOCorrela
CONVolution <cv> [-PAD | -NOWARNING | -SNR <snr>]
CORRelation <cv> [-PAD | -NOWARNING | -SNR <snr>]
DECONVolution <cv> [-PAD | -NOWARNING | -SNR <snr>]
4h-14
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
These four commands, in one form or another, evalute the cross correlation between two functions.
The correlation corr(g, h) and the convolution conv(g, h) are defined by
1
T →∞ 2T
Z
+T
conv(g, h) = lim
corr(g, h) = lim
T →∞
1
2T
g(τ )h(t − τ ) dτ
−T
Z +T
g(t + τ )h(τ ) dτ
−T
The AUTOCORRELATION evalutes the cross correlation of the function with itself and is defined as
1
g(τ ) = lim
T →∞ 2T
Z
+T
f (t)f (t + τ ) dt
−T
N
1 X
f (j)f (i + j)
N →∞ N
j=1
g(i) = lim
CONVOLUTION calculates the convolution of the main data set with the specified curve, such as a
detector response curve, by multiplying the Fourier transform of the two curves. DECONVOLUTION
will attempt the inverse by dividing the Fourier transform of the main data set by the Fourier
tranform of the specified curve. To avoid problems with zeros in the Fourier transforms, the -SNR
ratio should be set to some reasonable value. The magnitude of the inverse Fourier transform is
limited by the -SNR value; a typical SNR value is 30.
The CORRELATION command generates the cross correlation between the two data sets. This generates a function describing the overlap of the data sets.
The -PAD option causes the data set to be zero padded to the next power of two greater than the
sum of the number of points in the main and specified curves. This allows evaluation of the lead
and lag values where the correlation is zero. The -NOWARN will suppress the warning message if the
spacing of X in the main and specified curves are different.
FILTER fft
Syntax: FILTER fft <filter fnc>
Data can be filtered in the frequency domain using the FILTER FFT transformation. This command
transforms the data set into the frequency domain via a FFT transformation, multiplies each frequency by the defined function, and transforms the data back into the space domain. The function
specified can use the variable f$ which will be set to the spatial frequency at each point as the
data is multiplied. The data set is padded to the next even power of two with zeros before the
transformations are attempted. The frequency is determined from the first two X values. A low
pass filter might be defined as 1/(1+f$/5) and would place the 3 db spatial frequency point at 5.0.
LSQFIT
Syntax: LSQFit [[-CURVE] <curve>] [options]
Produces a linear least square fit to the current data set or the set specified immediately following
the LSQFIT command. A limited range of the data can be specified using the options. The best fit
line will be drawn through the data after calculation of the least squares fit.
4h-15
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
Note that this is similar to FIT LINEAR command. However FIT LINEAR does not currently allow
for limited regions and does not automatically plot the best fit line. Conversely, LSQFIT does not
create the function FIT(X) after finding the coefficients.
Recommended new usage:
FIT LINEAR OVERLAY -F FIT(X) -FROM @MIN(X) -TO @MAX(X) -LT 1
–Xrange
Syntax: LSQfit -XRange <xmin> <xmax>
Synonyms: LSQfit -Range ...
Causes least squares fit to use only points with X values between specified values.
–Yrange
Syntax: LSQfit -YRange <ymin> <ymax>
Causes least squares fit to use only points with Y values between specified values.
–Cursor
Syntax: LSQfit -CURsor
Uses the cursor to specify a box (X and Y) range of data to use for the fit.
FIT
Syntax: FIT [[-CURVE] <curve>] {LIst | ABORT | LINear | POLYnomial <n> |
SPLINE [-SMOOTH] | NLSFIT}
The FIT command and its various sub-processors allow data in the main curve (or the specified
archived curve) to be fit to a number of special analytic functions or common fitting algorithms.
Simple fits include a linear least squares fit and a general polynomial fit up to order 6. The cubic
spline, a method of producing a smooth curve through sparse data points is also provided. In addition
to this standard cubic spline, a smoothing spline is also implemented to allow the fit function to
pass only near a point rather than requiring the spline to pass directly through the data. Finally, a
generalized non-linear least squares fitting routine is included which allows the data to be fit to any
user defined function.
Each of the different fitting routines share a common final action, that of automatically defining
a FIT(X) function (through the DEFINE command). Before exiting, the fit routines establish the
current FIT equation with all necessary parameters. This works in coordination with the -FIT
option of the PLOT and OVERLAY commands which plot the function FIT(X) for comparison with
the data. It is identical to the command OV -FUNCTION FIT(X). Generally you will want to do this
with line type 1 so you get a line through you points.
Several variables may also be given values as appropriate:
CF$
VARIANCE$
CHISQR$
SIGMA$
Fit coefficients
Linear and Poly fit variance
NLS fit χ2
Linear, Poly and NLS fit σ
The defined FIT(X) may also be used directly, as for instance in evaluating the residuals through
LET Y = Y-FIT(X). In addition, each of these routines also make the fit parameters available to the
4h-16
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
user (such as slope and offset for a linear fit). See each specific description for enumeration of these
fit variables.
LIST
Syntax: FIT LIST
This will list the available fitting functions to the screen.
LINEAR
Syntax: Fit LINear [-RANGE | -XRANGE <xmin> <xmax>] [-WEIGHT <exp>]
[-SILENT]
The LINEAR fitting routine determines the best fit, in a least squares sense, of the data to a line,
returning the best fit slope and offset, sigma error bars for the slope and offset, the variance, and
the correlation coefficient. Once the fit is determined, the function FIT(X) is defined as the best fit
line. The slope and offset are available as the variables CF$(2) and CF$(1) respectively.
FIT(X) = CF$(2)*X + CF$(1)
Pathological data may result in a zero for the determinant of the matrix used in the solution and
an error message. Get some bloody data which looks like a line to avoid this error.
The options -RANGE and -XRANGE are synonymous and allow the fit to be limited to a finite range
of the abscissa. To limit the fit to more stringent conditions, use CULL DATA before running FIT to
limit the curve only the desired data.
The -WEIGHT allows an expression to weight each of the points individually. Note that the errors in
the slope and offset do not have terribly significant meaning if the weight does not equal unity. The
variance is currently independent of the weighting function and only represents the mean square
deviation variance of the data from the line. Weighting is done as a forward weight where a value
of 2 would cause the point to be twice as significant.
¾
GENPLOT:
GENPLOT:
GENPLOT:
Slope
8.70078
GENPLOT:
GENPLOT:
Slope
2.84236
GENPLOT:
GENPLOT:
Slope
0.22852
GENPLOT:
½
»
read temp archive c1
read temp -col 3 4
fit c1 linear
/* Request linear fit
Offset
sigma(slope) sigma(offset)
VAR
R
6.31978
0.4240
0.9278
5.712 0.980
pl ov -fit -lt 1
/* overlay the fit
fit linear -xrange -200 200
Offset
sigma(slope) sigma(offset)
VAR
R
2.18572
1.2482
0.2774
2.508 0.999
archive tmp$curve cull data keep for ’x+y>3 .or. x-y<1’
fit linear retrieve tmp$curve
Offset
sigma(slope) sigma(offset)
VAR
R
9.82384
0.0281
1.8283
5.712 0.928
¼
In the example above, the best guess for the slope is 8.70 ± 0.42 and an offset of 6.32 ± 0.93.
The variance is 5.712 and the correlation coefficient is 0.98. For scientific purposes, a correlation
coefficient less than 0.9 indicates that the data is not a straight line.
4h-17
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
The -SILENT option suppresses the output of the fit parameters for automatic macros.
POLYNOMIAL
Syntax: Fit POLYnomial <n> [-RANGE | -XRANGE <xmin> <xmax>]
[-WEIGHT <exp>] [-SILENT]
The polynomial fit is the general power series extension to the linear least squares fit routine. FIT
POLYNOMIAL allows the data to be fit to a polynomial power series in X with coefficients up to order
< n > (where < n >≤ 6). The coefficients of the polynomial are determined to minimize the square
deviation of the curve from the actual data points. Only the best fit values for the coefficients and
the variance are reported to the console. Standard deviations of the coefficients in a polynomial fit
are ill defined and hence not provided.
Once the fit is determined, FIT(X) is defined containing the polynomial definition. The variables
CF$(1) through CF$(n+1) contain the coefficients of the polynomials with FIT(X) defined as:
FIT(X) = CF$(1)+CF$(2)*X+CF$(3)*X*X ...
Note, the actual definition of FIT(X) is written in a different form to minimize the number of
multiplications required to evaluate the function.
Polynomial fitting must also be carried out with eyes fully open and aware of the possible errors.
The lowest power polynomial which adequately represents the data should be used; increasing the
order of the fit does not always result in improved agreement. High order coefficients may be used
to slightly decrease the variance by introducing wild curvatures between points of the data set. In
addition, the higher power coefficients are subject to increasing error bars. It is recommended that
one always compare the fit with the actual data before accepting the results.
Errors: This fitting function may generate an error message for a zero matrix determinant during
solution. Small determinants are characteristic of ill–posed problems and generally result from trying
to fit a sixth order polynomial to a perfectly straight line. Read the warning above.
The options -RANGE and -XRANGE are synonymous and allow the fit to be limited to a finite range
of the abscissa. To limit the fit to more stringent conditions, use CULL DATA before running FIT to
limit the curve only the desired data. See the examples in FIT LINEAR.
The -WEIGHT allows an expression to weight each of the points individually. The variance is currently
independent of the weighting function and only represents the mean square deviation variance of the
data from the polynomial. Weighting is done as a forward weight where a value of 2 would cause
the point to be twice as significant.
¾
»
GENPLOT: fit polynomial 4 -weight 1/max(sqrt(y),0.01)
CF$(1-n) = 0.731441
25.0348
Variance:
0.20048939
GENPLOT: ov -fit -lt 1
GENPLOT:
½
-10.9758
2.86571
-0.272395
/* overlay the fit
¼
The -SILENT option suppresses the output of the fit parameters for automatic macros.
4h-18
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
SPLINE
Syntax: FIT SPLINE [-SMOOTH <rms deviation>]
The SPLINE command calculates the coefficients of the cubic spline which passes through all of the
data points. A cubic spline is a piecewise cubic interpolation of a data set which is continuous
in value, first and second derivatives at each point (knot). The four coefficients of the cubic are
calculated between each pair of points with the two degrees of freedom used to establish continuity
in the derivatives. If the -SMOOTH option is specified, the condition that the cubic spline pass through
every data point is relaxed and an average deviation is allowed. The spline now has the additional
constraint of minimizing the integrated curvature within the allowed RMS deviation. The quality of
the fit is a very strong function of the -SMOOTH value chosen. Several iterations are usually necessary
to determine the appropriate value.
The coefficients are stored in an array SPL$DATA within the function evaluator. Once this array is
defined, the cubic spline may be evaluated at any point using the SPLINE(x) function, or the first
and second derivatives are evaluated using DSPLN(x) and DDSPLN(x).
NLSFIT
Syntax: Fit NLSFIT <commands>
NLSFIT is a powerful fitting routine which attempts to fit a user defined function to the experimental
data, varying parameters in the function to minimize the least-squares deviation of the data from
the function. Hence, fits can be based on quantitative models, or at least justifiable functions.
In brief, NLSFIT takes a function and a set of variables upon which the function depends. The
numeric value of each of these variables is then modified and the variance between the function
and the data is determined. Using the change in the variance, a new guess is made for each of
the variables, iterating through the parameter space until a sufficiently good minimum is located.
In this search, NLSFIT evaluates the derivative of the fitting function with respect to each of the
parameters at every point in the experimental data set. These derivatives may either be given
analytically, or NLSFIT will determine them numerically. NLSFIT combines the gradient search
and function linearization methods to minimize the number of steps required to converge to the best
solution. The algorithm is loosely based on that given in “Data Reduction and Error Analysis for the
Physical Sciences” by P.R. Bevington (McGraw Hill), chapter 11. Since the concepts are identical,
the interested user is referred to Bevington’s text for a detailed description of the algorithm.
In essence, NLSFIT performs a n-dimensional search for the minimum of the variance function.
Given the complex geometry of an n-dimensional space, finding a local minimum is sufficiently
difficult; no attempt is made to verify that this is a global minimum. Reasonable initial guesses
for each of the parameters are necessary, and the final solution may depend on the exact initial
conditions specified. Again, the fewer parameters needed to fit the data, the more confidence one
has in the solution. In particular, it is essential to avoid creating non-independent parameters to
the fit; ie. what are the best values for A and B where FIT(X) = A+B (perhaps not this obvious,
but people ask equivalently stupid questions!).
Running NLSFIT requires 6 steps, from obtaining the data and defining the function to actually
performing the fit and plotting the results. The steps required are summarized below.
1. Read the experimental data to be fit into the main curve.
2. Define a fitting function F(X). F(X) depends implicitly upon several other variables, A0 , A1 , . . . , An .
(See DEFINE and SETV).
3. Set A0 , A1 , . . . , An parameters to reasonable initial values (SETV). At this point, it is wise to plot
the data and overlay your initial guess.
4h-19
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
4. Enter NLSFIT. Inform NLSFIT of the function (F), the parameters to be varied (An ), and possibly analytic derivatives of F with respect to the parameters. (See FUNCTION and VARY
subcommands below).
5. Execute the NLSFIT command FIT to search space.
6. Return to GENPLT to plot the data and overlay the best fit.
7. Remember – Garbage In ⇐⇒ Garbage Out.
In the following sections, each of the sub-commands within the NLSFIT processor are described.
The subcommands FUNCTION, VARY and FIT are absolutely necessary to obtain a fit. Following these,
HELP, STATUS, RESET, RETURN and REMOVE are useful and relatively simple. ACCURACY, MAX ITERAT
and MODES are for the advanced users wishing to change the stopping criteria or the internal modes
of NLSFIT. Finally, after the command descriptions is a full-fledged, drawn out example of the use
of NLSFIT. The section ends with a more detailed look at exactly what NLSFIT does.
Function
Syntax: FUNCTION [function name] or EQUATION [function name]
This command is used to tell NLSFIT the function whose variance from the experimental data is to
be minimized. This function must be a user-defined function (through DEFINE) of a single variable X,
which P
represents the abscissa of the data set. If MYFIT is the specified as the function, the residual
χ2 =
(y − myf it(x))2 . The fitting function must also depend implicitly (ie. in the function
declaration but not as a replaceable argument) on other variables; these are the variables which are
modified to minimize the residual error. The function name must be a single, simple function name;
it may not contain any mathematical operations or other function calls. If you include parenthesis
arguments in the name, they will be truncated, ie. MAIN GAUSS(X) is exactly equivalent to MAIN
GAUSS.
Assume that the following function have been defined through DEFINE:
AMP2(X,Y) = A0*X*Y
AMP(X)
= A0*SIN(X)
MYFIT(X) = AMP(X)*SIN(A1*X)*AMP2(X,A2)
The following are legal declarations of the function to NLSFIT.
FUNCTION MYFIT
FUNCTION MYFIT(X)
FUNCTION AMP
Function will be MYFIT(X)
Same as above. (X) is truncated and ignored.
A different function
The following are illegal function declarations for various reasons as listed:
FUNCTION
FUNCTION
FUNCTION
FUNCTION
AMP*FIT
SIN
AMP2
AMP(2*X)
Only a single name can be specified - no operations.
Even though function is legal, it is not user defined.
Will give garbage. AMP2 is not a function of 1 var.
Legal, but will produce garbage since (2*X) is ignored.
Validity of the function is tested both at declaration time and at the start of the FIT operation. The
X value for which the function is to be evaluated is passed to the function as the first (and only)
replaceable argument in its declaration.
EXPERTS: It is not valid to assume that the X variable passed to the function will come from the
array representing the data. Internally, a variable XTMP is declared and X coordinates are copied to
this coordinate. However, if both the derivative and function calculations are performed in vector
mode, the index variable I will be defined and valid and XTMP will be linked to the X array. If vector
4h-20
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
mode is disabled by user intervention or because of memory limitations, the I variable may or may
not be accurate and should not be used.
See also: STATUS and RESET in this section, DEFINE in function evaluator.
VARY – Specifying Parameters to be searched
Usage: VARY [var] [analytic derivative fnc] or VARY [var] /
NLSFIT will attempt to search parameter space for up to 10 parameters, and to determine optimal
values for each. (A version of FIT$.OVL is available from CGS for working with 20 parameters.)
The VARY command is used to specify which parameters are to be varied by NLSFIT in its search. In
addition, the VARY command must tell NLSFIT how the derivatives of the fit function with respect
to these parameters is to be obtained. The REMOVE command (below) undoes the action of VARY
command. Each parameter [var] specified to VARY must be a real variable, either allocated using
the ALLOCATE command or specified using the SETVAR command. The variable must exist when
specified, as well as when the fit is actually executed.
For each parameter V which NLSFIT varies, it must determine the derivative of the fit function (F )
with respect to that variable (∂F/∂V ). That derivative may be determined numerically (requiring
two evaluations of the function), or the derivative may be specified as an analytic function. If an
analytic function is to be used, it must be specified at the same time as the parameter in the VARY
command. Analytic derivatives must be of the same format as the fit function, ie. a simple function
name which has been DEFINED previously (see FUNCTION above). If the derivative is specified as
“/”, numeric derivatives will be used instead. Note that analytic and numerical derivatives may be
mixed, some variables using analytic derivatives and others using numeric derivatives.
In general, analytic derivatives should be defined only if they are simpler than the function itself
(such as V1 in V1+X), or if a finite difference differentiation would be expected to have problems
(such as V1 in 1E16+V1*X). Numeric differentiation requires two evaluations of the function for each
derivative, hence requiring approximately twice the time. However, given the human propensity for
errors in differentiation, it is normally safer to let the program do them numerically unless they are
particularly simple. See the example fit in this section. The only known difficulty in calculating
derivatives numerically is when the initial guess is zero – don’t do that!
Assume
FIT(X) = A0*SIN(A1*X)
DFDA1(X) = X*A0*COS(A1*X)
DFDA0(X) = SIN(A1*X)
A fitting function
Analytic derivative dF/dA1
Analytic derivative dF/dA0
Legal
VARY A0 DFDA0
VARY A1 /
Vary parameter A0, analytic derivatives
Vary parameter A1, numerical derivatives
Illegal
VARY A0 DFDA0(X)
VARY A1 1
VARY A1 X*A0*COS(A1*X)
Derivative can only be a function name
Derivative must be / or a function name
Derivative can only be a function name
Note: A variable must be REMOVEd before its definition may be changed. A second VARY command
without a REMOVE will simply add the variable to the list a second time, resulting in untold trouble
with the fit algorithm.
See Also: STATUS, REMOVE and RESET in this section. ALLOCATE and SETVAR in the
function evaluator.
REMOVE
4h-21
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
Syntax: REMOVE [var]
Synonyms: RELEASE [var]
UNVARY [var]
The REMOVE command removes the variable [var] from the internal list of parameters which are
varied in creating the best fit. The derivative mode for the parameter is also deleted at this time.
All parameters may be removed at once using the RESET command.
WEIGHT
Syntax: WEIGHT <expression>
The WEIGHT specifies an expression to weight each of the points individually. The variance and
chi-square value is calculated with the weighting also. The expression may be an array specification,
such as weight:x or a general expression 1/sqrt(y). Weighting is done as a forward weight where
a value of 2 would cause the point to be twice as significant.
FIT
Syntax: FIT
This initiates the actual fitting procedure.
After several rudimentary checks of the specified constants
P
and functions, the value of χ2 =
(y − f it(x))2 is evaluated and the first estimate of the new
parameter values are obtained. After each iteration, the current value of chi squared and all of the
parameters are printed out. FIT continues to iterate until one of the two convergence criteria are
reached; either χ2 changes by less than ² (see ACCURACY command) or the maximum number of
iterations is reached (see MAX ITER command). After convergence, the final value for each parameter
will be printed, along with an estimate of the sigma value. The values of χ2 and σ are available
after the fit in the variables CHISQR$ and SIGMA$ respectively.
¾
»
NLSFIT: fit
-------------------------------------------------------------CHISQR
BP
V0
-------------------------------------------------------------2.835
1.300
0.5000E+05
0.1022
1.323
0.5020E+05
0.6186E-1
1.323
0.5020E+05
0.6186E-1
1.323
0.5020E+05
Variable
-------BP
V0
Value:
-----1.323083
50204.21
Sigma
----0.0023
1.3804
NLSFIT:
½
¼
During the solution, the screen will indicate whether it is evaluating the function, the derivatives
or making the next guess. At each iteration, χ2 and the current best guess for the parameters are
printed. Note how rapidly the technique convergences (credit goes to Bevington). Once χ2 ceases
to decrease on iteration, the final results are printed. The SIGMA listed is estimated from the
4h-22
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
curvature of the correction matrix, giving an error bar for each parameter which will result in a
doubling of χ2 . In reality, the surfaces of constant χ2 are ellipsoidal (in n space) and true error bars
along the principal axes of the ellipsoid are difficult to assign. The naive (and perhaps best) guess
is just the sigma error, BP = 1.3231 ± 0.0023 and V 0 = 50204 ± 1. This was an extremely good fit
by the way.
ERROR MESSAGES: The algorithm alternates between the gradient search and a function
linearization techniques. Sometimes, it gets a little confused, especially when the χ2 is changing
slowly. In some cases, it gets more than a little confused and goes into hyperspace. This results
in a message about a “weird function” and termination of the fit. In every case thus far, the best
fit has already been obtained and the message can be safely ignored. Small changes in the initial
conditions will also generally eliminate the message. I expect one can create pathological functions
which will bring up this error message repeatedly, and I can only say good luck.
HELP
Syntax: HELP
Synonyms: ?
The HELP or ? command within NLSFIT prints out a short list of the available commands. To obtain
more detailed help, return to the GENPLOT level and use HELP at that level.
¾
GENPLOT: fit nlsfit
NLSFIT: help
NLSFIT commands:
HElp
?
RETurn
FIT
VARY
REMove
MAX Iter MODES
NLSFIT: ret
GENPLOT:
½
»
/* Ask for a list of commands
QUit
INFormat
FUNction
STATus
EQuation
LET
MAIN
RESET
WEIGHTs
ACCuracy
/* Return from NLSFIT to GENPLOT
¼
RESET
Syntax: RESET
This command releases all parameters and functions from NLSFIT. The convergence criteria ² is
reset to 10−4 and the number of iterations is reset to 10. This command effectively returns NLSFIT
to its initial state.
RETURN
Syntax: RETURN
Returns to GENPLOT level. Most commands meant for GENPLOT will generate an error message
in NLSFIT. Return to GENPLOT to execute plot commands and view the data.
STATUS
4h-23
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
Syntax: STATUS
Synonyms: INFORMATION
Status provides a listing of the current settings in NLSFIT. Included in the summary is the function
which is fit (FIT), the parameters which are being varied (VARY) and the type of derivative (analytic
or numeric) for each. The dummy parameter in both the fit function and the analytic derivatives
is listed as XTMP. Also listed in STATUS are the convergence criteria ² (ACCURACY), the maximum
number of iterations allowed (MAX ITERAT), and the modes set (MODES).
¾
»
GENPLOT: fit nlsfit
NLSFIT: reset
/* Releases all variables and resets world
NLSFIT: accuracy 1E-7
/* Increase accuracy from default 1E-4
NLSFIT: function myfit
/* Fitting function. XTMP is added by NLSFIT
NLSFIT: vary bp /
/* Vary BP, no analytic derivative known
Number of parameter now: 1
NLSFIT: vary v0 dv0
/* Vary V0, analytic derivative is DV0(X)
Number of parameter now: 2
NSLFIT: status
/* Print out the status above
Non-linear Least Squares Fit Algorithm
Epsilon:
0.10E-06
Max Iter:
10
Vector mode: T
Equation: MYFIT(XTMP)
Variable 1 is BP
Variable 2 is V0
NLSFIT: ret
GENPLOT:
½
dF/da = none
dF/da = DV0(XTMP)
/* Return from NLSFIT to GENPLOT
¼
Convergence, ACCURACY and MAX ITER
Syntax: ACCURACY [eps]
Syntax: MAX ITER [n max]
During running of the FIT subcommand, NLSFIT will continue iterating until one of two stopping
criteria are reached. The first criteria, specified by the ACCURACY command, controls the square
deviation stopping criteria. The second criteria determines the maximum number of iterations
which will be attempted in any case and is set using the MAX ITER subcommand. If ² is the current
setting of the ACCURACY parameter, N MAX is the setting of the maximum iterations, and I is the
current iteration number, then the iterations in the FIT subcommand will terminate when
[χ2 (I + 1) − χ2 (I)]/χ2 (I) < ²
or
iteration number > N M AX
4h-24
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
The default values for ² is 10−4 , and for N MAX is 10. The RESET command will return these constants
to their original values.
See also: STATUS
MODES
Syntax: MODEs [YES | no]
There is only one user changeable mode in the production version of NLSFIT, that of VECTOR
operation (see STATUS). NLSFIT requires calculation of the derivative ∂F/∂A for every parameter
at every point in the data set (X,Y). This calculation can be done either point by point, or in
vector mode (default). In vector mode, the derivatives ∂F/∂A0 is calculated for all points X in one
operation. In point mode, ∂F/∂A0 , ∂F/∂A1 etc. are calculated in order for each point in order.
In vector mode, memory must be allocated to hold the derivatives. Given a curve containing NPT
points and M parameters to be varied, NLSFIT will attempt to allocate memory for M arrays of
NPT points. If there is insufficient memory, some of the parameters will have their derivatives
calculated point by point. Since the memory is released after NLSFIT runs, and VECTOR mode is
substantially faster than points, VECTOR mode should be used in most cases.
However, in some special cases, you may want the derivatives to be calculated in the specific order
given in point mode. Be prepared for a substantial degradation in performance if VECTOR mode
is turned off.
VERBOSITY
Syntax: VERBosity <level>
Synonyms: VERBOSE <level>
The information spewed out by NLSFIT to the screen is, at times, annoying. The VERBOSITY
command can be used to set a level of information to be output during an NLSFIT search. The
<level> resolves to an integer value between 0 and 3. A value of 0 disables all output. Once the
fit is complete, the results are stored in the appropriate variables and in the CF$ and SIGMA$ arrays
but no numbers or intermediates results are displayed. With a value of 1, only the final values and
errors are output to the screen. At level 2, informational messages during the internal stages of the
fit are displayed as well. Finally, at level 3, all intermediate estimates of the variables and various
informational data are displayed.
The default VERBOSITY level is 3. Lower levels are commonly used in automated macros to avoid
spewing the useless garbage to the screen and log file.
EXAMPLE
The following example fits experimental data for a peak on a background. The peak is assumed to be
a Gaussian characterized by a center, a full width at half maximum, and an amplitude. The baseline
is taken to be a simple quadratic in position. This example is essentially the problem described in
Bevington’s text.
4h-25
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
¾
»
[C:/FIT$/TEST] genplot
GENPLOT/3-D Shell w/ buffer allocation. [MOT v. 1.00]
*** GENPLOT Rev. 1.00 - 11/1/89 ***
*** Copyright 1987-1991 - Computer Graphic Service, Ltd., all right reserved ***
GENPLOT: dev ega
/* Graphics device
GENPLOT:
GENPLOT: /*-------------------------------------------------------------*/
GENPLOT: /*
Step 1: Read in some experimental data to be fit
*/
GENPLOT: /*-------------------------------------------------------------*/
GENPLOT:
GENPLOT: read test.dat
::::
Current data consists of
100 points. Max: 2048
X minimum = 0.90361
, maximum =
100.00
Y minimum =
52.778
, maximum =
298.61
GENPLOT: /*-------------------------------------------------------------*/
GENPLOT: /*
Step 2: Allocate and set variables to initial guesses
*/
GENPLOT: /*
*/
GENPLOT: /* Want a Gaussian on top of a quadratic varying baseline.
*/
GENPLOT: /*-------------------------------------------------------------*/
GENPLOT:
GENPLOT: setv amp = 200
/* Amplitude of Gaussian
Attempting to allocate new variable
GENPLOT: setv center = 56
/* Center of Gaussian
Attempting to allocate new variable
GENPLOT: setv fwhm = 4
/* FWHM of Gaussian
Attempting to allocate new variable
/* Offset of background
GENPLOT: setv offset = 200
Attempting to allocate new variable
GENPLOT: setv slope = -2
/* Slope of background
Attempting to allocate new variable
GENPLOT: setv quad = 0.01
/* Curvature of background
GENPLOT:
GENPLOT: /*-------------------------------------------------------------*/
GENPLOT: /*
Step 3: Define the fitting function. May be complex.
*/
GENPLOT: /*
In this case, separate into 3 fncs F,Z1 and Z2
*/
GENPLOT: /*
*/
GENPLOT: /*
Since the derivatives with respect to the
*/
GENPLOT: /*
baseline variables are simple, do analytically
*/
GENPLOT: /*
The others take too much though, so numeric
*/
GENPLOT: /*-------------------------------------------------------------*/
½
4h-26
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
¼
Command Reference
Section H – Data analysis
¾
»
GENPLOT:
GENPLOT: define z1(x) = (x-center)/fwhm
GENPLOT: define z2(x) = min(z1(x)**2,50)
GENPLOT: define f(x) = amp*exp(-z2(x)/2.0)+offset+slope*x+quad*x*x
GENPLOT:
GENPLOT: define doffset(x) = 1
/* Derivatives /wrt OFFSET
GENPLOT: define dslope(x) = x
/*
/wrt SLOPE
GENPLOT: define dquad(x) = x**2
/*
/wrt QUAD
GENPLOT:
GENPLOT: /*-------------------------------------------------------------*/
GENPLOT: /*
Step 4: Enter FIT NLSFIT and start telling NLSFIT about */
GENPLOT: /*
the functions and variables which have been set */
GENPLOT: /*-------------------------------------------------------------*/
GENPLOT:
GENPLOT: fit nlsfit
/* Enter NLSFIT
NLSFIT:
NLSFIT: function f
/* Specify fitting fnc
NLSFIT: vary amp /
/* Vary AMP, no derivative
Number of parameters now: 1
/* Vary CENTER, no derivative
NLSFIT: vary center /
Number of parameters now: 2
NLSFIT: vary fwhm /
/* Vary FWHM, no derivative
Number of parameters now: 3
NLSFIT: vary offset doffset
/* Vary OFFSET, deriv = DOFFSET
Number of parameters now: 4
NLSFIT: vary slope dslope
/* Vary SLOPE, deriv = DSLOPE
Number of parameters now: 5
NLSFIT: vary quad dquad
/* Vary QUAD, deriv = DQUAD
Number of parameters now: 6
NLSFIT:
NLSFIT: status
/* Query the status
Non-linear Least Squares Fit Algorithm
Epsilon:
0.10E-03
Max Iter:
10
Vector mode: T
Equation: F(XTMP)
Variable
Variable
Variable
Variable
Variable
Variable
1
2
3
4
5
6
is
is
is
is
is
is
AMP
CENTER
FWHM
OFFSET
SLOPE
QUAD
dF/da
dF/da
dF/da
dF/da
dF/da
dF/da
=
=
=
=
=
=
none
none
none
DOFFSET(XTMP)
DSLOPE(XTMP)
DQUAD(XTMP)
NLSFIT:
½
¼
4h-27
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
¾
»
NLSFIT:
NLSFIT:
NLSFIT:
NLSFIT:
NLSFIT:
NLSFIT:
/*-------------------------------------------------------------*/
/*
Step 5: Let NLSFIT run and see what happens.
*/
/*
Return to main program and view the result
*/
/*-------------------------------------------------------------*/
fit
CHISQR
1209.
40.23
39.95
39.95
AMP
200.0
207.4
208.8
208.9
CENTER
56.00
55.98
55.98
55.98
Variable
-------AMP
CENTER
FWHM
OFFSET
SLOPE
QUAD
FWHM
4.000
3.548
3.577
3.577
OFFSET
200.0
188.0
188.6
188.6
Value:
-----208.8500
55.97864
3.576676
188.5977
-2.393941
0.1040556E-01
NLSFIT: return
GENPLOT:
GENPLOT: plot -lt 0 -sym 3
GENPLOT: ov -fit -lt 1
GENPLOT: quit
SLOPE
-2.000
-2.348
-2.393
-2.394
QUAD
0.1000E-01
0.9974E-02
0.1040E-01
0.1041E-01
Sigma
----3.215849
0.6120375E-01
0.6725442E-01
2.040894
0.1028594
0.9816353E-03
/* Return to GENPLOT
/* Plot the data
/* Overlay the fit
/* Go home!
[C:/FIT$/TEST]
½
¼
Algorithm
Description of the NLSFIT algorithm
Given: Experimental data set (x, y) containing NPT points.
Given: F (X) : which depends also on A0 , A1 , A2 , . . . , An
where A0 , A1 , A2 , . . . , An are real parameters.
Given: (∂F/∂A0 ), (∂F/∂A1 ), . . . (∂F/∂An ) evaluated at each point
P
Given: χ2 = [(yi − F (xi )]2
Find: Values for A0 , A1 , A2 , . . . , An which minimizes the root mean square deviation (χ2 )
of F (X) from the experimental points (x, y).
NLSFIT will search the parameter space of A0 . . . An minimizing the function χ2 . The fitting
function F (x) is expanded about the current guess A0 . . . An in a Taylor series using either analytic
derivatives of the function F (x) with respect to An or using numerically estimated derivatives of
4h-28
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section H – Data analysis
the function. If no analytic derivative ∂F/∂An is available, the numeric derivative is obtained by
evaluating [f (x, An + dA) − f (x, An − dA)]/dA where dA is approximately 10−4 An . There is a
possibility that the derivative will be zero if the initial guess for A0 is set to 0 (I have to guess at
dA); otherwise, the numeric technique should be reasonably safe.
The algorithm selects a new estimate of A0 ...An based on a curvature matrix evaluated from these
derivatives. The new estimate is arrived at by a weighted sum of the gradient method and a
linearization of the function χ2 , alternating between these methods as necessary. Chi squared is
required to decrease at each iteration step, until either it changes by less than the specified ACCURACY
(²) or until the maximum number of iterations have been executed (MAX ITERATE).
4h-29
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
I. SPRUCING UP
LIne
ARRow
ARC
PARc
CIrcle
RECtangl
CONnect
DRaw
ANGle
LABEL
ORGmode
PARameter
PLACe
SIze
SPACing
CURsor
COORMode
HElp
RETurn
RESet
Draw a line between 2 points
Draw an arrow between 2 points
Draw an arrowed arc between 2 points
Draw an arc between 2 points
Draw a circle through three points
Draw a rectangle with the corners at the given points
Draw a line connecting several points, dot–to–dot
Drawing prefix command, it is not needed
Specify the text angle
Put a label on the plot
Sets the origin for label, relates the cursor point to label location
List the current labeling parameters
Put a label on the plot, see LABEL
Specify the text size
Specify the interline spacing for text
Find the coordinates that Annotate would need
Select the coordinate system to use
List the Annotate commands
Return to normal GENPLOT mode
Resets the Annotate parameters such as size and angle
Your plot can be enhanced by adding labels, boxes and arrows to better explain its meaning. Annotate is used to add labels, boxes, arrows and other things. Annotate is a sub-process. This means
two things. First that you have a new set of commands, specifically for drawing various objects and
labels. Second, that once you are in Annotate you stay in it until you enter a command that it
does not understand. At that point Annotate assumes that you typed a GENPLOT command and
returns you to the GENPLOT level. This also occurs when you misspell a command. Typing ’ ?’
within Annotate gives you the list of commands that are used by ANNOTATE.
ANNOTATE
Syntax: ANNotate
Synonyms: ANNOTE
ANNOTATE (or ANNOTE) is a powerful subprocessor which provides functionality to label and annotate
a plot with text, symbols and experimental designs. To get a complete list of commands, use the
? command. When invoked, the user enters ANNOTATE environment with a list of commands
distinct from GENPLOT. Once in ANNOTATE, the user remains there until an explicit RETurn
is made to GENPLOT, or an unrecognized command is typed. This feature, automatic return to
GENPLOT on unrecognized commands, is either a blessing or a curse depending on your point of
view.
There are 3 modes in ANNOTATE. The first is a text labeling mode which provides the ability
to place labels of arbitrary size and orientation on the graph. The second level provides special
commands to draw lines, circles and arrows (no, we are not getting into Alice’s Restaurant) or
4i-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section I – Sprucing up
combinations thereof. The third level is actually another subprocessor SAMPLE which draws a
sample structure for thin film work (or whatever else you make use of it for).
COORDINATES
Most of the ANNOTATE commands require coordinates specifying either where to place something or
for drawing line segments between the points. All coordinates in ANNOTATE are initially measured in
inches (scaled by the SHRINK factor) rather than user coordinates. You can use COORMODE to change
the coordinate system to your plot coordinates.
Coormode
Syntax: COORMode [user | inches] <xoffset> <yoffset>
COORMODE tells ANNOTATE how to interpret the coordinates that you specify. The “inches” option
is obvious. The “user” option causes ANNOTATE to position things based on the current axis or
user units. The offsets must be specified. They determine where the origin of the coordinate mode
is located. By changing these offsets you can move labels around the screen without changing each
label command. Usually you will enter “user” coordinates with offsets of 0.
>> coormode user 0 0
Coordinates may be entered either directly as numbers, or by placing the cursor at an appropriate
position. If no value is given at a request for coordinate (ie. press <cr> to the prompt for a coordinate
set), the cursor will appear and the coordinate will be taken from the screen. Many commands
require more than one coordinate set (such as a LINE draw). Once the cursor is enabled, all points
must be entered from the cursor. Likewise, once the first number has been entered manually, all
remaining values must be typed rather than using the cursor. The prompt for the first coordinate
can be bypassed by using the in-line default character ’/’ – it indicates a request for a cursor rather
than numeric input.
See the beginning of the manual under essentials for specifics on using the cursor.
Examples:
LABEL / ’This is a test’
LABEL 1.0 2.8 ’This is a test’
Brings up the cursor for placing the text on screen
Draws the text at 1.0 inches X 2.8 inches Y
TEXT LABELING
Typed text may be drawn on the screen in any size and at any angle. As with line and arrow
drawing, the position at which text is drawn may be specified by either coordinate directly (x,y) or
by requesting the cursor. See the LABEL sub–command below for specifying the cursor. The position
of the cursor relative to the text (ie. bottom left etc.) is controlled by the ORGMODE command. See
LABEL also for examples of multiple lines of text drawn one below another.
Label
Syntax: LABel [ / | x1 y1] [’text’]
Synonyms: PLACE
Positions a given character string somewhere on the plot. Use of the / allows the cursor to be
used to determine positioning. If the text is specified on the command line, it must be enclosed in
single quotes if embedded spaces or lower case characters are desired. If the text is not specified,
the prompt will be issued and quote characters are unnecessary. Any text line which ends in a ‘∼’
character specifies that another line of text should be input and drawn directly below the current
4i-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section I – Sprucing up
line (separated by the SPACING distance). An arbitrary number of lines may be so linked. Note
that each line will be positioned according to the ORGMODE in effect, giving either centered, right or
left justified text. The &ENCODE command described in Macro section K can be used to convert real
numbers to strings for inclusion in labels.
If the cursor is used to input coordinates, the coordinates will be displayed on the screen for incorporation into a macro later if desired.
Superscripts, Subscripts and Fonts
The following special character sequences may be used within label to change character sets or to
draw super and subscripts.
∧0
∧n
∧{this}
{that}
∧Pn
∧Fn
change to character set 0 (see also CHRSET)
change to character set n, from 0 to 9
superscript the text enclosed in {...}
subscript the text enclosed in {...}
Change to pen color n
Change to font/character set n
Subscripts and superscripts are displaced and shrunk from the standard character sizes. The default demagnification and shift of the superscripts and subscripts may be changed using SGRAPH
commands.
Special Labeling Characters
Other special characters are used to backspace, quote or continue labeling several lines in a paragraph
with a single LABEL command.
∧–
\[char]
∼
backspace character (hat–hyphen)
quote character. \∧ draws the ∧ character
newline character for paragraph labeling
The backspace sequence, ∧–, moves the current text point back the width of a space. This will
cause overwriting of the previous characters. It could be used to produce special symbols or may
be used to add both a superscript and a subscript. Since GENPLOT uses proportional spacing the
characters will not line up unless the width of the previous character is equal to the width of a space.
The quote character (\) causes GENPLOT to treat the next character literally and not as a special
character. This allows you to put special characters such as ‘∧’ in your text without it doing strange
things.
Lines ending with tildes ‘∼’ within one LABEL command will create a “paragraph” type label. At
the end of a line with a ∼the cursor will move down and start the next line of text even with the
previous one. The result will have an even left side and ragged right side. The SPACING command
described below sets the space between lines. See the tutorial section page 2–19 for an example.
Note: This paragraph mode does not work with the axis LABEL command.
¾
label
label
label
label
½
»
1 1 ’Hi there’
/
Thompson
/ ’Si {3}N {4}-SiO
/ ’Hi∼’ ’there’
/* Draws ‘‘Hi there’’ at (1,1)
/* Draws ‘‘THOMPSON’’ at cursor position
{2}’ /* Draws Si3 N4 − SiO2 at cursor
/* Draws ‘‘Hi’’ and ‘‘there’’ on two lines
¼
4i-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section I – Sprucing up
Orgmode
Syntax: ORGmode [lb | lc | lt | cb | cc | ct | rb | rc | rt]
Sets the origin of the text to be a specific location within the text. The default placement mode is
LB, meaning the left-bottom corner of the text region is placed at the point specified in a PLACE
or a LABEL command. Other mode options are LC (left center), LT (left top), CB (center
bottom), CC, CT, RB, RC, and RT (right top).
Parameter
Syntax: PARamete
Lists the character height and spacing, and the origin placement mode.
¾
»
ANNOTATE: parms
Graph labeling parameters:
Label Size: 0.20
Drawing Angle:
0.0
Interline spacing: 2.00
Origin for text specified at Left-Bottom
½
¼
Parms
Syntax: PARMS
Lists the character height and spacing, and the origin placement mode. Same as PARamete.
Angle
Syntax: ANGle <degrees>
Specifies the angle at which text is drawn. Angles are measured in degrees from a horizontal line
with positive angles counterclockwise. 0 degrees is horizontal left to right and 90 degrees is vertical
bottom to top.
Size
Syntax: SIze <inches>
Changes the size of the characters printed in a LABEL or PLACE command. The size is specified in
inches. (Warning — conflicts with the GENPLOT level are possible here since SIZE has a very
different meaning with GENPLOT and ANNOTATE.)
Spacing
Syntax: SPACing <units>
Sets the interline spacing for text in units of one character height. Using the tilde, ’∼’, at the end
of a line in LABEL will cause LABEL to place that text, move to a new line and request more text.
This spacing is used between the lines.
LINES AND ARROWS
Drawing lines and arrows on the plot
4i-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section I – Sprucing up
The following commands draw lines and arcs. The format for coordinates is normally [from] to
[to], with arrowheads at the [to] end. The PARC and ARC commands require a third point between
[from] and [to] to define the arc. The qualifier DRAW may be placed before any of these commands
without effect. If a ’/’ is given instead of the coordinates the cursor is activated to enter the points.
If nothing is given you will be prompted for the coordinates.
In the table [n] means that ‘n’ coordinates are requested.
Draw Commands
Description
ARRow [2]
ARc [3]
Parc [3]
Circle [3]
Rectangle [2] <ltype>
Line [2] <ltype>
Connect [n]
Draws an arrow between 2 points with arrowhead
Draws arc from 1 to 2 through 3 with arrowhead
Same as ARC but no arrowhead is drawn
Draws a circle through the 3 points
Draws a rectangle with specified corners
Draws <ltype> type line between 2 points
Connect the dots drawing
Line
Syntax: LIne [x1 y1] [x2 y2] <ltype> --or-- LINE / <ltype>
Draw a straight line between the two points.
Arrow
Syntax: ARRow [xbeg ybeg] [xend yend] --or-- ARROW /
Draws an arrow with the tail at the first point and the arrow head on the second point.
Arc
Syntax: ARC [xbeg ybeg] [xend yend] [xmid ymid] --or-- ARC /
Draws an arc with an arrow given a start, end and mid-point. The end point gets the arrow head.
Parc
Syntax: PARc [xbeg ybeg] [xend yend] [xmid ymid] --or-- PARC /
Draws an arc without an arrow given a start, end and mid point.
Circle
Syntax: CIrcle [x1 y1] [x2 y2] [x3 y3] --or-- CIRCLE /
Draws a circle through the three points.
Rectangle
Syntax: RECtangl [x1 y1] [x2 y2] <ltype> --or-- RECTANGLE / <ltype>
Draw a rectangle with the corners at the given points.
Connected
Syntax: CONnect [x1 y1] [x2 y2] / --or-- CONNECTED /
A connected line between the given points – ‘connect the dots’.
4i-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section I – Sprucing up
To end, when entering position list directly, enter a / to the request for the next point. When using
the cursor, pressing the space bar (or a 0) causes the cursor to reappear for another point. Exit by
pressing any other key.
Draw
Syntax: DRaw [arrow | arc | connected | etc.]
The DRAW command is effectively a no-op in current implementations. The command ARROW may be
prefaced by DRAW as in DRAW ARROW, however ARROW works by itself also.
OTHER
These commands are general and may be applicable to either text or line drawing modes.
Cursor
Syntax: CURsor
Gives the absolute position of the cursor in inches. The coordinates given are appropriate for the
DRAW and LABEL commands within ANNOTE. The cursor position report will be given when a key
is pressed. If the key is either the space bar or a 0, the cursor will be retained. Otherwise, control
is returned to the ANNOTE sub–process.
Help
Syntax: HElp
Lists out all commands recognized at ANNOTE sub–level. Effectively the ? command.
Return
Syntax: RETurn
Synonyms: Quit
Returns to normal GENPLOT mode from Annotate mode. Any errors or commands with bad
syntax will also return the user back into normal GENPLOT mode.
Reset
Syntax: RESet
Resets the size, angle, line spacing and origin mode parameters back to the defaults.
SAMPLE
Sample is a sub–process within ANNOTATE. It will be documented more fully at a later revision but
the commands are listed here for those who know of it’s existance or for those curious enough to
experiment.
Sample Subcommands
HElp
List SAMPLE commands
TYPe
Direction of the sample (Right/Left)
CYCles
How many wiggles on a side
AMPlitude
Size of the wiggles
INTCycle
Number of wiggles on the surface interface
INTAmpli
Size of the surface wiggles
4i-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section I – Sprucing up
SIze
1draw
2draw
SOLid
DOTTed
WAVy
CLose
RETurn
Size of sample for 1DRAW
Draw sample, set position by cursor or coords
Draw sample, set size and position as above
Add a layer to the sample using a solid line
Add a layer with a dotted line
Add a layer with a wavy line
Close off the end of the sample
Back to Annotate command level
Some day, I will get around to fully documenting these commands. For the brave, give them a try
and see what happens. I guarantee that none of them will cause your computer to explode.
4i-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
J. FUNCTION EVALUATOR
ALLOCate
DEALLocate
DEClare
DEFine
EValuate
LET
LISTVar
SAVEVars
SETVar
Allocate a variable – arbitrary type
Deallocate any variable
Allocate and set a STRING variable
Define a user function string
Evaluate a general math expression
Set a variable to a constant or expression
List the all defined variables
Save variables to disk file
Allocate and set a real number variable
WARNING:
1. There is only one set of variable names. A curve and a variable cannot possess the same name.
Allocation of one will result in the deallocation of the other, usually without warning.
2. Curves are actually structures consisting of several arrays and variables. See the section on
ALLOCATE for details on using curves.
3. The following variables are reserved. On threat of immediate and painful death, do not redefine
them!
PLOT
default curve
X
current data set abscissa
Y
current data set ordinate
Z
reserved
IDS
Identifying string of the current data set
NPT
number of points in the current data set
OPTS
reserved
NPTMAX
reserved
I,PI,E
internal variables
All other names not including a $ character may be used. Any name beginning or ending with the
$ character is considered reserved for GENPLOT.
GENPLOT includes an extremely powerful and versatile expression and function evaluator, allowing
the user to transform, scale and analyze data in an endless variety of ways. At one level, the
expression evaluator is invoked anytime a number is requested by GENPLOT (including reading
data from an ASCII file). For example, the REGION command may be given as
¾
»
GENPLOT: region bottom @min(x) 2*sin(pi/8)
GENPLOT:
½
¼
Legal expressions may include constants, pre–defined variables and functions, and user defined variables and functions (including the main data curve and any archived data). Allowed mathematical
4j-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
operations include all of the basic algebraic operations, most of the useful intrinsic FORTRAN
functions, and a complete set of relational and logical operators.
In addition to simple constant evaluation, the function evaluator handles the allocation of memory for
local variables, strings and functions for local use. Variables and functions are required, for example,
to use the non–linear fitting capability of GENPLOT. Each of these capabilities are described below.
Entire data sets may be archived as named curves, and may be referenced in an expression by either
their X or Y component. The structure of a curve is defined more fully later.
Finally, if the functions currently available within the function evaluator are insufficient for your
problems, the evaluator may be linked to user written FORTRAN functions as described in the
subroutine appendix. The range of variables which may be defined and changed within GENPLOT
are illustrated in the next screen.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
setv r1,r2 = 8.3144 3.1415926
let r1,r2 = 2*r1+3 sin(r2/3)
alloc buf1 array 1024
let buf1 = (i-1)/1023.0
alloc buf2 array 1024
let buf2 = sin(r1*buf1)
declare my name = ’Michael Thompson’
let my name = ’George Never’
define root(x,y) = sqrt(abs(x/y))
define root2(x) = root(x,z)
alloc c1 curve 3028
let c1:x = buf1 let c1:y = buf2 let c1:npt = 1024
let c1 = ’1024 point sin(x) curve’
¼
EXPRESSIONS
Expressions within GENPLOT may consist of any number of operations involving any number of
variables. Expressions are controlled by the same token parsing constraints as all other terminal
input (see Appendix T). In general, an expression cannot contain spaces unless they are enclosed
in a set of defining parentheses. The brackets {( and [ are considered identical as are }) and ].
Valid expressions are used as examples throughout this section.
VARIABLES
Variables may be named and allocated with GENPLOT. Each variable must be given a unique name
and has 3 attributes associated with it: linked or allocated, hidden or visible, and type (real, integer,
array, string, curve, external or module). Some understanding of these classes is necessary to fully
utilize variables within GENPLOT.
First, the simplest of the attribute is hidden or visible. Hidden refers only to whether the variable
is listed in a normal LISTVAR printout. Hidden variables may be used just as visible variables and
can in fact be listed using the LISTVAR -HIDDEN switch. Hidden variables are, for example, internal
variables of GENPLOT which are occasionally needed by a user but have no reason to be listed to
the screen in general use. Hidden variables also are internally generated by curve variables which
allocate hidden arrays.
4j-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
The linked and allocated variables are differentiated by the “origin” of the data specified. Linked
variables represent real variables within GENPLOT, such as the number of points in the main data
curve, called NPT. Linked variables pre-exist within the program and are essentially “published” to
the interactive user. Linked variables may be freely modified and used in any expressions. Allocated
variables are defined by the user or program but have no direct internal meaning to GENPLOT.
An example might be the definition of a constant used to convert from inches to meters setv
inch meter = 39.37. Allocated variables are defined at run time and memory is allocated only
when they are defined. Allocated variables can be later deallocated and removed from the list of
variables. Linked variables, however, can only be removed from the data list although their internal
value remains. (WARNING: There is no way a user can relink an internal variable once it is released)
The distinction between allocated and linked variables becomes important when changing values,
especially of character strings and arrays. Linked variables are fixed in length and size while allocated
variables may have their size adjusted by re-allocation.
The seven types of variables are
• Real numbers
• Integer numbers
• Real arrays
• Strings (including functions)
• Curves
• External functions
• Linked Modules
Real numbers and integers are self explanatory. The real array consists of a specified number of real
elements beginning with element 1. A string is fixed length and may contain arbitrary text, including
function definitions. Strings which are “evaluated” are assumed to be functions. External functions
are linked addresses to user written FORTRAN subroutines extending the function evaulator – see
Appendix S. Linked modules are the addresses of dynamic loaded programs (such as ANNOTE) and
are included for the sole purpose of possible deallocation.
Unlike the previous variable types, curve is not a single element but rather a collection of four
elements. Consider a curve variable called mydata. It consists, in reality, of the following components
• A string element called mydata with a length of 80.
• Hidden integer element mydata:npt containing the number of points.
• Hidden real array mydata:x containing the npt X coordinates
• Hidden real array mydata:y containing the npt Y coordinates
The base string mydata contains the identifying text of the curve; this is the text which would be used
by IDS to identify the plot. It may be set using LET mydata = ’Data of the first detector’.
The number of points in the curve may be referenced using mydata:npt. It is valid to increase or
decrease this number. However, an increase of mydata:npt above the allocated length will not result
in the allocation of additional space for the X and Y arrays; the curve must be reallocated to modify
the defined length of the arrays. The X and Y values may be used in expressions by referring to
their actual names, mydata:x or mydata:y. (The length of the arrays mydata:x and mydata:y are
determined when they are first allocated. However, their operational length is always determined
by the value of mydata:npt which may have any value.)
4j-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
Note that while it is possible to operate on an entire array in operation, such as specifying let
mydata:y = sin(mydata:x), it not possible to work similarly with curves. The command let
mydata = sin(x) results in the string describing the curve mydata being set to the string sin(x)
while the data in the set remains unchanged.
Subtleties of the STRING variables
Strings possess several subtleties simply because of the variety of ways in which they are used.
A string variable is normally allocated with only sufficient space to contain the specified string.
The LET command allows the value of the string to be changed, but will not allow the length to
be increased. This may result in truncating of some strings when not expected (no warning of
truncation is given). Strings larger than the defined size may be set using the DECLARE command to
reallocate them instead of LET as long as the variable is an allocated string variable. Using DECLARE
to change the value of a linked string or of a curve will delete the previous definition completely and
allocate a new string variable of the same name. (For example, the variable IDS is linked and must
be changed in value using the LET command.) The best advice is to use LET to change the value of
any string unless you know that it really is a locally allocated string.
• Functions should ALWAYS be redeclared with the DEFINE command.
• Do not use DECLARE to set a curve name or an linked string. Use LET instead.
• DECLARE may be used, rather than LET, to redefine an allocated string.
WARNING: Quotes are necessary around expressions containing spaces and spaces should be placed
around the ’=’ in any expression.
Working with ARCHIVED curves
The data of an archived curve can be used modified or used in any expression evaluation. However,
you must keep clear the meaning of the individual components of an archived curve. Assume we
have archived some data set with 50 points using ARCHIVE C1 and then read in a new data set
with 22 points. The expressions EVAL C1(3) and LET y = c1 are meaningless since C1 is the text
associated with the curve and not the data itself. The correct formulation would be EVAL C1:Y(3)
and LET y = c1:y. The integer variable C1:NPT contains the number of points in the C1 curve while
NPT refers to the number of points in the main curve. The expression EVAL C1:Y(NPT) probably
does not print out the Y value of the last element of the C1:Y array, but rather the 22nd point of
the array. EVAL C1:Y(C1:NPT) does print out the last Y value of the C1 curve. It may be helpful
to think of curves as data structures (as in the C language) and to :X, :Y and :NPT as elements of
the structure. (However, this analogy fails somewhat since LET C2 = C1 does not copy the entire
structure.)
A few quick examples may help.
1. LET C1:Y = C1:Y+R1 Scale Y values in C1 by R1.
2. LET Y = Y+R1*C1:Y Adds r1*y value of C1 to Y.
3. LET C1:NPT = C1:NPT-1 LET C1:Y = C1:Y(I+1)-C1:Y(I)
4. LET C1:Y = SIN(C1:X)+C1:Y*SIN(1/C1:X)
5. LET C1 = ’This data is so messed up as to be useless now’
4j-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
EVALUATE
Syntax: EValuate <expression>
EVALUATE is used to evaluate complex arithmetic expressions and print the result to the terminal.
The expression may include any legal combination of functions and variables. Since <expression> is read as a single token, it may not contain spaces unless it is enclosed in parentheses or
quotes. If an expression is specified, only a single number can be evaluated as in each EVAL command. However, the entire contents of arrays are listed if the expression consists of only the array
name, such as EVAL MYDATA:X. The result of an operation on an entire array cannot be listed; EVAL
SIN(MYDATA:X) is an expression and only the value of the first element will be evaluated. Multiple
elements of array operations can be printed using the REPEAT command as in REPEAT MYDATA:NPT
EVAL SIN(MYDATA:X(I)).
The following are legal if XTEMP is a real variable and F(X,Y) is a function.
¾
EVAL
EVAL
EVAL
EVAL
EVAL
EVAL
EVAL
EVAL
½
»
2.5*XTEMP
’y(17) + y(x(13))’
/* quotes needed for spaces
F(SIN(PI/3)*XTEMP,COS(F(1,0)))
@SUM(Y)
[(XTEMP .LT. 3) .OR. (F(XTEMP,0) .GT. 8)]
@MAX(Y)*@MIN(Y)*@AVE(X)
(XTMP<3).OR.(F(XTMP,0)>8)
SIN(2.8)*(F(X(13),Y(2)).GE.3)
¼
The following are illegal:
¾
EVAL 2.5 * SIN(pi/3)
EVALUATE F(1)
»
/* No spaces allowed in expression
/* Garbage results since only 1
argument for F
½
¼
See also: LET, SETV, DEFINE
LET
Syntax: LET <var>[,<var>...]
= <expression>[<exp2>...]
The LET command attempts to assign a variable, string or array (previously allocated) the value
specified by <expression>. It attempts to do so in the most useful manner given the form of the
variable and the expression. If the variable is an array, the expression will be evaluated over the
array. If it is a scaler value, the expression will be evaluated and assigned to the variable. The
expression is a single token and must contain no spaces unless enclosed in quotes. Array variables
may be indexed to refer to a single element only. LET is commonly used as the most general form of
data transformations.
If the <expression> evaluates to a real or integer number, the variable will be assigned that value as
in LET THETA = 27 If the variable is an array, the entire array will get the value. If <expression>
4j-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
is a vector operation then the <expression> is applied to the array indexing the array and the
expression appropriately.
Multiple variables may be set in a single LET command. The variables to be LET must be separated
with commas. These are evaluated individually beginning with the first. Evaluations of subsequent
variables will reflect the changes made in the previous steps. For example, LET X,Y = X**2,X**2
is equivalent to LET Y,X = X**4,X**2.
¾
LET
LET
LET
LET
LET
LET
LET
½
»
theta = 27
X = 27
X(17),X(18) = 17 18
Y = 2*SIN(Y)*COS(X)*ATAN(theta)
Y = ’G(X) + F(X)’
c1:y = c1:y+c2:y
I1 = I1+1
/*
/*
/*
/*
/*
/*
/*
a single value
an entire array
single array elements
a vector operation
G and F must be defined
Add archived curves c1+c2
a single value expression
¼
Errors will occur if <var> has not been allocated (see SETV or ALLOC). SETV can be used in cases
where you want to both allocate and set a value.
Note: LET <curve> = <expression> will change the text associated with the curve but will not
alter the values of X or Y. See the IDS command.
See also: SETV, ALLOC, DEFINE, DECLARE, ARCHIVE
SETVAR
Syntax: SETVar <var>[,<var>...]
= <expression>[<exp2>...]
SETVAR is the simplest method for defining and setting a real constant. If <var> is not yet defined
(by a previous SETV or ALLOC for instance), SETV will alloc <var> as a real variable and set its value
to zero. SETV then does an equivalent of LET to assign a value to the variable. Note that <var> is
always allocated as a REAL variable by this command. If the variable currently exists as another
type, the previous definition will be erased and a warning message issued. This is UNIX like - what
you ask for is what you get.
Hint: The command SETV var1 = var1 can be used to set a variable when you do not know if
it already exists. If it has been previously defined, it will remain unchanged, otherwise it will be
allocated with the value of zero.
¾
SETV theta 0.0
SETV beta = temp/8.3144
SETV beta = beta
SETV string = ’Hi there’
SETV Y = F(X)
½
»
/*Allocate a THETA variable
/* Allocate BETA and set value
/* Make sure BETA exists. If not,
its value after this is 0.0.
/* Only works if string was DECLARED
or ALLOCATED before as a STRING.
/* Can be used to emulate LET also
¼
4j-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
DEFINE
Syntax: DEFine <function(dummy1 [,dummy2 ...])> = <string expression>
User functions may be declared and nested to an almost arbitrary level. The arguments within
the <function> are considered dummies and are replaced at evaluation time with the appropriate
values. Functions must be declared by this method in order to have the dummy arguments
handled properly. Functions may contain other function and variable references as long as no circular
expressions are created. Circular expressions will most certainly crash the OS - such as DEFINE
DOT(X) = DOT(X).
Consider the request: DEFINE DOT(X,Y) = MIN(X,Y)/MAX(X,Y). The command allocates a string
variable DOT of an appropriate length. The expression is copied to the string variable except for
dummy arguments which are translated to &1, &2 to correspond to their place holders. Hence DOT
will be a string variable with the “value” of MIN(&1,&2)/MAX(&1,&2). EVAL DOT(1,2) will result
in evaluating MIN(1,2)/MAX(1,2) = 0.5. You may handle the &1 replacement yourself if you wish
(as in macros) and use DECLARE instead of DEFINE – but I can’t think why you would want to
do so.
¾
»
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
define
define
define
define
define
f(x) = sqrt(sin(x))
v(time,space) = space/time
g(z) = erfc(z)
n(users) = @sum(users)
h(x,y) = g(f(x))+f(g(y))
¼
DECLARE
Syntax: DEClare <var> = <string expression>
DECLARE allocates a string variable of the necessary length and makes its value equal to the
<string expression>. This is normally used in conjunction with the automatic expansion of
strings to create variable command arguments. The <string expression> must be enclosed in
quotes if you want it to contain lower case or blanks. String expressions may be used at almost any
time in the command line by enclosing the name with % characters. %var% is replaced at parse
time with the current value of the variable (as a single token). Examples are best here.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
»
DECLARE t bot = ’A bottom title’
/* Sets string t bot
TITLE BOTTOM %t bot%
/* And tells title
DECLARE t top = ’A top title’
/* Declare a second one
TITLE TOP ’%t top% next to %t top%’ /* Take a guess!
DECLARE t bot = ’A’
/* Title won’t change
since evaluation already done
½
¼
Declaration of strings are most useful in conjunction with general macros where arguments may be
passed as variables.
4j-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
ALLOCATE
Syntax: ALLOCate <name> [REAL | INTEGER | ARRAY <n> | STRING <len> | CURVE <n>]
ALLOCATE is the lowest level command for allocating memory for a user variable. Single variables
will be assigned a value of 0, arrays and strings are left undefined.
Variable
Allocation
REAL
Allocates space for a REAL*4 variable and assigns
value of 0.0
Allocates space for a INTEGER*2 variable and assigns value of 0
Allocates space for <n> REAL*4 elements of the
array, 1–N.
Allocates a <len> length string variable
Allocates X and Y arrays and a number of points
integer. Consider ALLOC C1 CURVE 1024. This creates a curve variable called C1. Arrays C1:X and
C1:Y are allocated with 1024 points. They are marked
hidden so they will not show up in the LISTVAR
command. Also allocated is C1:NPT which is set
initially to 1024.
INTEGER
ARRAY <n>
STRING <len>
CURVE <n>
Limits: Arrays/curves are limited to less than 16380 points (don’t push it!). Memory will be given
to variables until we run out of the 640 Kbytes allowed by DOS. GENPLOT does not (and probably
will not) use expanded or extended memory.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
alloc
alloc
alloc
alloc
junk real
counter integer
c1 curve 1024
final array 16000
¼
DEALLOCATE
Syntax: DEALLocate <name>
DEALLOCATE releases the memory associated with a variable, curve, array, function, string or module.
Data in the released memory is permanently lost. Deallocation may be necessary if you define a very
large number of arrays or curves and find yourself out of memory on these painful 640 Kb PCs. It
is also possible to deallocate dynamically linked modules such as ANNOTE to open up new space
for variables. See LISTVAR for details on modules. DEALLOCATE can remove any element from the
expression evaluator, including only a single component of a curve; however this is not recommended.
¾
»
GENPLOT: ALLOC c1 CURVE 1024 /* Allocate 8192 bytes for 1024 pt curve
/* Release the 8192 bytes for other uses
GENPLOT: DEALL c1
GENPLOT: DEALL m annote
/* Release the ANNOTE module
½
¼
4j-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
LISTVARS
Syntax: LISTVar [-Functions | -Vars | -Strings | -Curves | -Hidden | -Modules]
LISTV will list out all defined variables along with their values (or initial values if arrays or curves).
For each, the type of variable is specified and the defined length is shown. For curves, only the main
CURVE named variable is shown; the :X :Y and :NPT sub–elements are marked as hidden and are
not normally displayed. Strings and functions are displayed in their storage form – for functions this
means with the &1, &2, &3 ... dummy argument replacement.
The listing may be limited to only one type of variable by specifying one of the switches. LISTV -C
prints information only on curves currently defined. Hidden variables may also be listed using the
-Hidden switch.
Occasionally, names of class MODULE or EXTERNALS are listed. The class EXTERNAL refers to FORTRAN subroutines which have been linked into expression evaluator as complex function calls, for
example Bessel functions. These are normally user written routines handled through the USER$ interface. The class MODULE refer to dynamically linked modules which can be released. ANNOTE and
FIT are dynamic modules which are loaded from disk only as necessary and are linked as M ANNOTE
and M FIT. Normally these modules would remain resident once loaded but, since linked to the expression evaluator, they may be DEALLOCATED as any other variable. The module will be reloaded
from disk the next time it is required. P.S. I would suggest not trying to evaluate a MODULE.
WARNING: There are lots of “hidden” variables allocated or linked by GENPLOT itself which
will not normally show up. These generally have strange enough names that you are unlikely to
conflict with. They are all listed using the -HIDDEN option.
¾
»
/* Lists all variables defined.
/* Lists only defined functions
GENPLOT: LISTV
GENPLOT: LISTV -FUNCTION
GENPLOT: LISTV -VARS
½
¼
SAVEVAR
Syntax: SAVEVar <file name> [-FUNCTIONS | -VARS | -STRINGS | -CURVES]
This command effectively does a LISTVAR command to a disk file, generating a macro which will
reallocate and define all functions, variables, arrays and strings. It unfortunately, however, will not
save the values of arrays or curves; only simple variable’s values will be written to the disk file.
To re–establish the environment, such as when re–entering GENPLOT, simply XEQ the file written
by SAVEVAR.
¾
»
GENPLOT: savevar restart -functions
GENPLOT: quit
C:\local> genplot
GENPLOT: xeq restart
GENPLOT:
½
/* Save functions to RESTART
/* Load variables from RESTART
¼
4j-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
OPERATIONS
Standard FORTRAN expression are allowed with two extensions.
1. The relational operators have symbolic synonyms such as >= for .GE..
2. Logical and numeric operations may be combined. FALSE is defined as 0.0 and TRUE is 1.0;
any expression greater than 0.0 is TRUE.
Hierarchy
The following table lists the operators in order of evaluation hierarchy.
!
** or ^
- Factorials and exponentiation
- Unary minus
* /
- Multiplication and Division
+ - Addition and subtraction
.GT. .LT. .GE. .LE. .EQ. .NE. - Relational operators
<
<
>=
<=
==
<>
- (synonymous)
.NOT.
- Logical operators
.AND.
.OR.
.EQV.
.NEQV.
¾
»
SIN(X)*(X.LT.3).OR.(Y>=7.2)
SIN(X)*(X.GT.0)
’(X .LT. Y) .or. (Y .LT. 1.0) .and. (X*Y .GT. 0)’
½
¼
FUNCTIONS
Currently, defined intrinsic functions to GENPLOT include:
(This list is continually evolving, see the update sheets for latest info.)
Function
Description
ABS(x)
ASIN ACOS ATAN
ACOT
ASINH ACOSH ATANH
Absolute value
Inverse trigonometric functions (return radians)
DSPLN(x)
DDSPLN(x)
ERF(x)
ERFC(x)
EXP(x)
FACT(x)
FRAC(x)
GAMMA(x)
LNGAMMA(x)
INT(x)
LN(x)
LOG(x)
Derivative of spline at X (coefficients predefined?)
Second derivative of spline at X (coefficients predefined?)
Error function of X
Complementary ERF
ex
x factorial
Fractional part of X
Gamma function of X (not valid for negative integers)
Natural log of the gamma function
Integer part of X
Log e of X (natural)
Log 10 of X
Inverse hyperbolic trigonometric functions
4j-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
Function
Description
MAX(x1,x2,...)
MIN(x1,x2,...)
MOD(n,m)
M1N(n)
NDTR(x)
NDTRI(x)
NINT(x)
POLY(x,ar)
Maximum of list
Minimum of list
Remainder of N/M
Evaluates minus 1 to the nth (–1**n)
Normal distribution of X
Inverse normal distribution
Nearest integer to X
Evaluates expression using X and array AR as AR1 + AR2 ∗
X + AR3 ∗ X ∗ X + ...ARn ∗ X (n−1)
Returns random number, x is unused
Square root of X
Returns +1, –1 or 0
Trigonometric functions (arguments in radians)
Hyperbolic trigonometric functions
Spline evaluated at X (coefficients predefined?)
Average of array
Maximum of an array
Minimum of an array
Root mean squared deviation of array
Standard deviation of array
Sum of elements
RND(x)
SQRT(x)
SIGN(x)
SIN COS TAN COT
SINH COSH TANH
SPLINE(x)
@AVE(array)
@MAX(array)
@MIN(array)
@RMS(array)
@STD(array)
@SUM(array)
Constants
E
PI
2.718281828
3.141592654
See the begining of the chapter for reserved variables.
The functions @MIN and @MAX set an internal variable $I to the array index at which the corresponding
minimum or maximum was found. This allows you to get the value of x where y has its maximum
with a little trick like (expressions are evaluated left to right):
>> setv xatymax = 0*@max(y)+x($I)
LIMITS AND WARNINGS
There are very few restrictions or limitations on the function evaluator. However, despite any
implications to the contrary, there are some. If you exceed these limits, it is time to go program
a real computer instead of GENPLOT. I don’t expect you to exceed these limits, so I don’t check.
Hopefully heaven will help you if do exceed the range!!!
CALCULATOR: 200 pending operations. Translated, you are in trouble if you have more than 200
closed parenthesis together.
STACK LIMIT: 2000 bytes for total expression, including full expansion of all user defined functions.
Usage of space includes
a) 4 bytes for each constant
b) 1 byte for each operation or function evaluation
c) 5 bytes for each variable reference
d) 10 bytes for each pending operation beyond 4
FAILURES: Failures are not handled gracefully! Overflow, divide by zero and the like are treated
by “do something and continue”. NAN (not a number) may be returned which will
4j-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section J – Function evaluator
really upset GENPLOT. The evaluator may also evaluate some nonsense expressions. DON’T DO EITHER!
RESERVED: The variable name I is reserved within the function evaluator. Don’t redefine it if
you desire to live. I is an index counter for array operations. It can be used in
expressions to refer to the current element in an array specification. The following
example eliminates the first 10 elements of a data array by overwiting them (there
are easier methods to achieve this end):
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
let
let
let
let
npt
x =
y =
x =
= npt-10
/* Eliminate 10 points
x(i+10)
/* Copy X from 10 points up
y(i+10)
/* And Y.
x(i)*y(i+1)/x(max(i-1,1)) /* More complex but okay
¼
CRASHING THE EXPRESSION EVALUATOR
We have a philosophy of let the user do as he pleases, but let him beware. Crashing the evaluator is
difficult but is no big deal. Rather than encourage hacking, I will give you a simple example which
crashes the system. Executing this example will require that you reboot the PC to recover.
¾
»
GENPLOT: ALLOC C1 ARRAY 16
GENPLOT: LET C1(17) = 0.0
GENPLOT: quit
½
¼
Setting the 17th element of a 16 element array is reasonable if you know that it overlaps some other
useful variable. However, in this case, element 17 lies atop a DOS memory management block and –
bye bye system. See it’s not difficult and this knowledge hopefully will keep hackers from searching
too hard.
4j-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
K. MACROS
/*
BASE Macro
CMDLIN
ECHO
FOR
REPEAT
MACro
GOTO
IF
QUERY
SAVE Mac
SLEEP
TIMER
WAIT
Xeq
&GETARG
&QUERY
&YESNO
&ENCODE
Start a comment, the rest of the line is ignored
Specify a default macro directory
Expand a string into a command
Toggle the command display while a macro is running
Repeat command string for list of elements
Repeat a command string a fixed number of times
Collect commands in a macro file
Continue execution at the given label
Conditional execution of commands
Prompt the user for input from the macro
Save the commands from MACRO in a file
Delay for a given length of time
Start or print out stopwatch timer value
Wait for user action before continuing
Execute a macro file
Get the next argument from the macro command line
Get the next token from the user
Get a yes/no answer from the user
Real number to string encoding
This section of the manual describes commands which directly control macros, and commands which
are most useful in a macro environment. Macros are user written ASCII files containing numerous
GENPLOT commands; the GENPLOT equivalent of a subroutine call. Typically these are sequences
of operations which you repeat often, such as initialization, a particular fit to the data, or setting up a
plotter to a common graph size. Any disk file may be executed by typing XEQ <file>. Parameters
may be passed to a macro file, or the macro may request input from the user during execution.
Rudimentary flow control in the macros is implemented as IF commands and GOTO statements,
similar to the batch processor in DOS.
XEQ
Syntax: Xeq [<file> | NOW | -TTY | -RETURN]
Synonyms: CALL [<file> | NOW | -TTY | -RETURN]
The XEQ command causes program control to be passed to the specified file; subsequent GENPLOT
commands and text will be taken from the file instead of the console. Only certain error conditions
and specific queries will prompt the console for input. Each time GENPLOT would normally request
a line of input from the console, that input is obtained from the currently active XEQ level. Commands
from a macro file will be echoed to the screen as they are read (in a different color from the normal
text) unless command echoing has been disabled (see ECHO below).
Macros may be nested to a maximum of 5 levels; attempts to XEQ another macro from level 5 will
result in an error message and no execution. The following search order is followed in trying to
locate a requested macro file.
4k-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
1. Specified name in current directory
2. Name with extension .MAC in current directory
3. Specified name in the BASE MACRO directory
4. Name with extension .MAC in the BASE MACRO directory
The XEQ NOW command is a special format where the NOW token is replaced with the actual filename
of the temporary macro opened using the MACRO command. Temporary macros can be created using
the MACRO command, and then executed using XEQ NOW. NOW may be abbreviated to one character
allowing XEQ NOW to be abbreviated as X N. As a consequence however, N, NO and NOW cannot be
used as macro filenames.
Execution of a macro file continues until either the end of the file is reached or a command terminates
the macro. The commands XEQ -RETURN and XEQ -TTY will prematurely terminate a macro file. The
-RETURN option causes only the current level of macro to be exited; execution continues with the
“calling” program. The -TTY causes all macro levels to be terminated with subsequent input to be
taken from the console. The -RETURN is routinely used to exit a macro, while -TTY is normally used
when errors occur during execution of the macro.
WARNING: An F77 compiler “feature” causes only lines which end with a line feed to actually be
read. Some editors do not put a linefeed on the last line of the file! An error message will indicate
that the last line was not executed. Add a blank line to the end of your file to avoid this error.
Since we are human, errors may occur during macro execution. Graceful handling of such errors
is almost impossible. The command line which generated the error is aborted and any subsequent
commands on the same line are lost. GENPLOT then prompts for the disposition of current macro
level with the question "SETUP active. Terminate (YES|no)? ". The level may either be terminated or allowed to continue. If the level is aborted, the same question is asked of the next higher
level macro currently in effect until the console level is reached. The disposition of the macro is one
example of input which is ALWAYS taken from the console and never from the macro file.
BASE MACRO
Syntax: BASE Macro <directory>
The BASE MACRO command sets a default directory for macro files. XEQ will search this directory
as well as the current directory to find a requested macro file. Typically this directory contains a
collection of useful macros. When a CALL or XEQ command runs, the specified macro file is searched
for in the following order:
1. Specified name in current directory
2. Name with extension .MAC in current directory
3. Specified name in the BASE MACRO directory
4. Name with extension .MAC in the BASE MACRO directory
The <directory> specified to BASE MACRO is not checked for any validity. It is simply saved as a
string which is then concatenated with any file request to XEQ. The current setting of the BASE MACRO
may be obtained with the PARAMETERS command. The default at power–up is a null directory.
4k-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
ECHO
Syntax: ECHO {OFF | ON | message}
Normally commands within a macro file are echoed to the screen (underlined or in an alternate
color) as they are executed. This allows one to follow the execution and determine if and where
errors occur. Once a macro is debugged (and especially if it is extremely long), the echoing of such
commands becomes extremely annoying as well as slowing down the execution of the macro itself.
ECHO OFF will turn off this echo feature and allow macro files to run silently. Only the prompt
and the actual response from the macro file is suppressed; normal screen output from the executing
commands will continue to be echoed to the screen. ECHO OFF can be added to prevent unwanted
commands from appearing. We suggest turning ECHO ON just before exiting the macro.
If the token following an ECHO command is neither ON nor OFF, the entire line is taken as a comment
which is output to the console verbatim. This feature allows macro files to output intermediate
results and to give assurance to the user that they are actually running.
MACRO
Syntax: MACro
The MACRO command allows short single macros to be written within GENPLOT. The EMACS command can also be used to write simple macros and is in general much more flexible. The MACRO
command opens a temporary file and copies text (a short macro) from the console into the file.
This input mode is terminated and the file is closed by typing an End–of–File character (∧Z on
PCs or a ∧D in UNIX). There is no editing capability beyond the line editing features of the DOS
processor. The temporary file is given a name of the form T$0000.MAC, where the numbers 0000 are
incremented until a unique filename is generated.
The temporary macro created by the MACRO command may be executed using the XEQ NOW command.
NOW will be translated into the current temporary filename. The name of the current macro can be
obtained with the PARAMETERS command.
Use the command SAVE MACRO to permanently save the macro to disk under another name. If a
temporary macro still exists when GENPLOT is exited, the user will be queried for the disposition
of the macro. The macro will either be deleted, or left on the disk with its temporary name;
responsibility for renaming and saving the macro then rests with the user.
Note: The Emacs–like builtin editor, EM can also be used to write macros and is far more flexible.
See Section N.
SAVE MACRO
Syntax: SAVE Mac <file name>
SAVE MACRO will attempt to permanently save the temporary file opened using the MACRO command
under a new name. Since MACRO actually creates a real disk file, this is usually only a rename
function; the file will exist on disk whether or not SAVE MACRO succeeds. The macro may be saved
to a different directory or disk — a copy or rename is done as appropriate.
Any subsequent MACRO commands will open a new temporary macro file under a new unique
name.
4k-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
QUERY
Syntax: QUERY <prompt> <default> <VAR NAME>
The QUERY command in reality belongs with the commands ALLOC, DEFINE and DECLARE in the
function evaluator. However, its use is almost exclusively in macro files and hence is included in this
section. &QUERY is generally a better command to use and is described below. QUERY is an alternate
method for obtaining run-time information inside a macro from the user. QUERY reads information
from the console and assigns the result to a string variable. The format of QUERY must be exactly as
above; all three arguments must be provided on a single command line since no prompting is done
for any of the arguments.
The steps involved in a query are:
1 Output <prompt> to the console.
2 Read the command line from the console.
3 If the input is blank, assign the default as the input.
4 Allocate a string of name <VAR NAME> and assign it the value of the terminal input.
The strings assigned in this manner are often used as arguments to GENPLOT commands such as
TITLE. Errors may occur if insufficient memory remains to allocate the string variables.
Consider the following macro file which queries the user for titles for each of the four axes:
QUERY
QUERY
QUERY
QUERY
’Bottom X axis title: ’
’Top X axis title: ’
’Left Y axis title: ’
’Right Y axis title: ’
’X’
’X’
’Y’
’Y’
mytitle
mytitle
mytitle
mytitle
label
label
label
label
bot
top
left
right
%mytitle%
%mytitle%
%mytitle%
%mytitle%
¾
»
GENPLOT: ECHO OFF XEQ SETTITLES
Bottom X axis title: Time (ns)
Top X axis title:
Left Y axis title: Current (nA)
Right Y axis title:
GENPLOT:
½
/*
/*
/*
/*
Relatively simple
Choose defaults
Y axes
And more defaults
¼
CMDLIN
Syntax: CMDLIN
CMDLIN expands the next argument (possibly a string) and places it back on the command stack
(as if it had been typed directly) after removing one set of quotes. The example below illustrates
the use of this command (normally within a macro). Since &GETARG returns only a single token, the
CMDLIN is necessary to parse individual tokens from the input line.
¾
GENPLOT:
GENPLOT:
GENPLOT:
½
»
define user line = &getarg -prompt ’Enter a command line: ’
cmdlin %user line%
¼
4k-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
&: INLINE FUNCTIONS
Any command which begins with the & character is an inline function. The inline commands replace
themselves with some response string from the user or data as a single token. The response is
normally used as an argument to another command such as range or title. The entire response is
always passed as the argument — a response will not be parsed as is done at the normal command
level. Quotes are never necessary in the user response to an inline function and the response must
be given in uppercase for case sensitive arguments. The string returned by these commands can be
reparsed by using the CMDLIN command above.
&GETARG
Syntax: &GETARG [-PROMPT <text>] [-DEFAULT <text>]
Parameters from the calling procedure may be obtained in a macro file by use of the &GETARG command. &GETARG is an inline function which returns the next token on the command line which called
the macro. Each invocation of &GETARG will return subsequent tokens from the calling command line.
The -PROMPT and -DEFAULT options are provided to allow input to be requested from the console if
no argument is present, or to provide a default value in the event no argument is present.
The inline function &GETARG may be used as the argument to any GENPLOT command, or as a
command itself. The &GETARG is expanded at parsing time into a string and returned as the next
token on the command line. The following procedures are followed in handling &GETARG:
1. Check remainder of line for -PROMPT or -DEFAULT suboptions.
2. Parse the current command line of one macro level back, returning a single token.
3. If the token is non-blank, return in place of &GETARG.
4. If no tokens exist on the previous macro level command line and a -PROMPT has been specified,
prompt the console using the specified text and read the entire line in as the token.
5. If the token is still blank and -DEFAULT is specified, use the default text string.
WARNING: When prompting for the token under -PROMPT, the string will be accepted as case
sensitive with no automatic conversion to uppercase. This may create havoc if the token is being
used as an argument where only uppercase commands are recognized. Normally, however, the
-PROMPT is used to set titles or to input equations, both of which will tolerate lowercase as well as
uppercase characters.
Consider the following very simple macro which reads a data file and archives it to a given curve
name in memory. The calling sequence is XEQ README <file> <curve>.
read
&GETARG -PROMPT ’Enter the filename: ’
-DEFAULT TEST.DAT
archive &GETARG -PROMPT ’Enter curve to save as: ’ -DEFAULT C1
4k-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
¾
GENPLOT: XEQ README TEST C1
::::
Current data consists of
X minimum = 0.90361
,
Y minimum =
52.778
,
»
LET X = X+20
/* Note legal LET command
100 points. Max: 2048
maximum =
100.00
maximum =
298.61
GENPLOT: XEQ README
Enter the filename: test
::::
Current data consists of
100 points. Max: 2048
X minimum = 0.90361
, maximum =
100.00
Y minimum =
52.778
, maximum =
298.61
Enter curve to save as: C2
GENPLOT:
½
¼
&QUERY
Syntax: &QUERY [-PROMPT <text>] [-DEFAULT <text>]
&QUERY is an inline function which always returns a token from the user. This command is identical
to &GETARG except that input must come from the user and not from a previous command level. The
inline function &QUERY may be used as the argument of any GENPLOT command, or as a command
itself. The &QUERY is expanded at parsing time into a string and returned as the next token on the
command line. The following procedures are followed in handling &QUERY:
1. Check remainder of line for -PROMPT or -DEFAULT suboptions.
2. If -PROMPT has been specified, prompt the user using the specified text and read the entire line
in as the token.
3. If the token is still blank and -DEFAULT is specified, use the default text string.
4. If still blank return nothing.
WARNING: When prompting for the token under -PROMPT, the string will be accepted as case
sensitive with no automatic conversion to uppercase. This may create havoc if the token is being
used as an argument where only uppercase commands are recognized. Normally, however, the
-PROMPT is used to set titles or to input equations, both of which will tolerate lowercase as well as
uppercase characters.
The following one line command file named README.MAC would produce the output shown.
>> read &query -prompt ’Enter the filename:’
-default test.dat
4k-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
¾
»
GENPLOT: xeq readme plot
Enter the filename: test
::::
Current data consists of
100 points. Max: 2048
X minimum = 0.90361
, maximum =
100.00
Y minimum =
52.778
, maximum =
298.61
GENPLOT:
½
¼
One could also declare a string variable with:
>> declare filename = &query -prompt ’Give me a file:
’
&YESNO
Syntax: &YESNO [-PROMPT <text>] [-DEFAULT ’YES’ | ’NO’]
&YESNO is an inline function which returns an answer from the user. It returns a 1 for a YES answer,
0 otherwise. The result can be tested using the IF command. The inline function &YESNO may be
used as the argument of any appropriate GENPLOT command. It might be used as follows:
setv ans = &yesno -prompt ’Continue:
if (.not. ans) goto end
’ -default ’YES’
&ENCODE
Syntax: &ENCODE (FORTRAN-format) <expression>
Encodes a real number or real expression using the given FORTRAN format. The format must
specify a REAL number qualifier (G, E, F). This inline command is often used to draw the result of
an automatic calculation on the plot with ANNOTATE LABEL. The example below takes a result from
a curve fit and places it on a plot as a label:
¾
»
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
¼
fit poly 4 -weight 1/max(sqrt(y),0.01)
declare str1 = &encode (G14.7) 18.4*variance$
declare str2 = &encode (G14.7) cf$(1)
annote label 2 8 ’Value: %str2% Scaled Variance:
%str1%’
FORTRAN format consists of a string of identifiers enclosed in parentheses. The identifier Fxxx.yy
outputs a right justified number with yy decimal places in an xxx wide field. For example, (F7.2)
encodes π as “
3.14”. Exxx.yy and Gxxx.yy are similar and output an exponential format
“3.14E00” and general format (real or exponential as appropriate — in this case “
3.14”. Multiple numbers can be encoded only by concatenating strings as in the example above.
FOR
Syntax: FOR %F IN (<item1> <item2> ...)
DO {<command sequence>}
Syntax: FOR REPEAT <count> DO {<command sequence>}
4k-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
The FOR command allows a sequence of commands to be executed for each of a series of items in a
list, or to be executed a fixed number of times. This command is very powerful both at command
level and in macros. It is implemented in a manner analogous to the DOS batch command FOR.
In the first form, the command sequence is executed once for each item in the parenthetical list.
If any element in the list is a wildcard filename (contains either a * or a ?), the sequence will
be executed once for every file which matches the wildcard. In the second format, the command
sequence is repeated a fixed number of times. FOR sequences may not be nested — only one may be
active at any time. The <command sequence> may however call macro files.
In both cases, two replaceable variables are defined during execution. The string %F is replaced
at each execution of the command sequence with the current element from the list, or the current
filename. In the case of a FOR REPEAT, %F is always replaced with the string “repeat mode”. The
string %C is replaced each time with the count of the current command execution, beginning with
001 and incrementing each time the command sequence is executed. The string %C is always a 3
character, zero filled, string which can be used as a file extension (eg. test 3.%c. The maximum
number of iterations is 999 so %C will never overflow.
The first example below will overlay every .DAT and .NEW file with a different pen color. The second
example overlays curves C1, C3 and C4. Finally, the last example prints out the values of elements
101–200 of the X and Y arrays.
for %f in (*.dat *.new) do read %f overlay -pen %c
for %f in (1 3 4) do overlay c%f -pen %c
for repeat 100 do eval x(%c+100) eval y(%c+100)
The most common error which occurs using the FOR processor is forgetting the required DO token.
Sorry about requiring it, but some things are fixed in history.
REPEAT
Syntax: REPEAT <count> [ TIMES ] {<command sequence>}
The REPEAT command is identical to the FOR REPEAT command and allows a sequence of commands
to be executed a fixed number of times. The TIMES qualifier is optional and need only be given
for readibility. Two replaceable variables are defined during execution. The string %F is replaced
each time with the string “repeat mode”. The string %C is replaced each time with the count of the
current command execution, beginning with 001 and incrementing each time the command sequence
is executed. The string %C is always a 3 character, zero filled, string which can be used as a file
extension (eg. test 3.%c. The maximum number of iterations is 999 so %C will never overflow.
The first example below overlays a series of data files beginning with test.001 followed by test.002.
The second causes the iterative smoothing operation to be done 13 times.
repeat 37 times ov test.%c
repeat 13 times let npt = npt-1 let y = (y(i)+y(i+1))/2 let npt = npt+1
IF
Syntax: IF <expression> <command sequence>
The IF command allows conditional execution of the remainder of the command line based on
the value of a logical expression. Used with the GOTO command, IF provides rudimentary flow
control within macros. The <expression> is either a logical expression or a numeric expression
which resolves to .TRUE. if greater than zero or .FALSE. if less than or equal to zero. If the
expression is false, the remainder of the current command line is ignored and execution continues
4k-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
with the command line. If the expression is true, execution continues with the <command sequence>
following the IF command.
The <expression> must be a single mathematical token, and cannot contain spaces unless the
entire expression is enclosed in quotes or parentheses. If an error is detected during evaluation of
the expression, the command line is flushed and standard error processing occurs. The command
sequence may contain arbitrary commands including another IF command. To execute a large block
of statements, XEQ <file> is recommended following the IF statement instead of block GOTO’s.
Alternately, the standard ugly programming practices we used back in FORTRAN IV days with
GOTO commands can be used.
The following examples illustrate the use of IF. Both examples are valid at either console input level
or from a macro. However, the complexity of the second usage really makes sense only in the context
of a macro file.
¾
»
GENPLOT: xeq macro1
GENPLOT:
if x(2)<0.0 let x = -x
GENPLOT:
if @sum(x)<2 let x = x+1 goto loop1
GOTO$:
let x = x-1
GOTO$:
:loop1
GENPLOT:
xeq -RETURN
GENPLOT: plot
GENPLOT:
½
/*
/*
/*
/*
/*
/*
XEQ
Maybe negate X
IF
ELSE
ENDIF
Leave macro
¼
GOTO
Syntax: GOTO <label>
The GOTO command causes macro execution to continue on the line immediately following one with
the :<label> as the first token. Both backward and forward references to the labels are allowed.
Searching always begins on the first line of the file and only the first occurance of a given label will
be recognized. Labels are handled in the same manner as in the DOS BATCH processor (see your
DOS manual).
A line which marks a label may not contain any other commands. Label lines are read, listed to the
screen if ECHO is enabled, and ignored. Label are defined as any line where the first token contains
a ‘:’ as the first character. The reference to the label in the GOTO command should contain only the
name and not the initial colon. References to non–existent labels will cause the current command
file to be closed and execution to resume with the next higher level command file.
Internally, the GOTO command causes the current command file to be rewound to the beginning.
The file is then read sequentially until the line containing the label is found. Searching for the label
ceases at the end of file, ie. GOTO may not extend across XEQ file calls. All GOTOs are assumed to be
resolved at a file end. If echo is enabled during a GOTO execution, all lines read but not processed
will be preceded by a GOTO$ prompt. Notice that GOTO is very inefficient on long command files, just
as it is in the DOS batch processor. Sorry.
The following macro will painfully perform a bubble sort on a data set, using both the IF command
and the GOTO command. I would not recommend its usage, but the example is good.
4k-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
¾
»
echo off
alloc j integer let j = 1
setv xtmp = xtmp setv ytmp = ytmp
/* So many steps, essential
/* Allocate temp variables
:loop1
if x(j).le.x(j+1) goto is okay
let xtmp = x(j) let ytmp = y(j)
let x(j) = x(j+1) let y(j) = y(j+1)
let x(j+1) = xtmp let y(j+1) = ytmp
let j = max(j-1,1)
goto loop1
:is okay
let j = j+1
if (j.lt.npt) goto loop1
:end
/* Start of loop
/* Is order okay?
/* No, reverse both X,Y
/* New J value
/* And loop
/* Try next
/* And maybe go to loop1
echo on
½
¼
I’m not going to actually execute it since there undoubtedly would be thousands of commands flying
around. Note: J is used as the index variable, since I is a reserved variable name in the expression
evaluator software.
SLEEP
Syntax: SLEEP <secs>
The SLEEP command causes the program to go into hibernation for the specified number of seconds,
perhaps to let the impact of a particularly phenomenal plot sink in to the boss. The maximum sleep
time is 32 seconds, and the resolution is approximately 1/18.2 seconds (actually 1/216/3600 ). During
SLEEP, the machine is chugging along doing nothing but watching the clock counter in the BIOS.
Great way to waste CPU cycles and, if used with REPEAT, to get a nap yourself.
WAIT
Syntax: WAIT
The WAIT command actually executes the FORTRAN PAUSE command halting execution of the
program momentarily. In RMFORT, execution is halted until the <CR> key is pressed. This can be
used to stop macro execution for user intervention (changing the paper?). This command allows for
a much longer delay than is possible with SLEEP, and execution is guaranteed not to continue until
actual user intervention occurs.
While GENPLOT is in the WAIT mode, most DOS commands may be executed. However, WAIT
does not provide a prompt and any blank input line will return control to GENPLOT. The PAUSE
command provides access to a true secondary command processor and is preferable for pausing to
run other applications. See the Operating System and File Control section for a description of PAUSE.
4k-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section K – Macros
TIMER
Syntax: TIMER [-STart|-RESet]
The TIMER function allows the masochist or sadist to measure the elapsed time for execution of a
series of commands. The TIMER command prints the current time and the elapsed time (in seconds)
from the last TIMER -START or TIMER -RESET command.
¾
»
GENPLOT: create y = sin(x) -points 2048
GENPLOT: timer -start transf y fft -power timer
Time: 14:45:41.73
0.00
Time: 14:45:42.22
0.49
GENPLOT:
½
¼
/*
Syntax: /* <some comment>
The /* is the inline comment signifier. It is a command which causes the remainder of the command
line to be ignored. This is useful in macro files to provide commentary to the wary reader several
years in the future. Note, the /* must appear in a position where a command is expected, not where
an argument is expected.
Legal
Illegal
ECHO OFF
REGION LEFT
0.0 1.3
/* Turn off the echo
/* We are going to set the region
Consider the macro lines above. The first line is legal since the /* would be encountered when
GENPLOT is expecting a command; ECHO has completed. The second example, however, will result
in an error message since GENPLOT is expecting an argument to the REGION command at the time
the /* is encountered. This would result in an error message and aborting of the REGION commmand.
4k-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
L. OPERATING SYSTEM AND FILE COMMANDS
CD
DIr
<disk>:
DOS
MEMory
PAUSE
TYpe
WHEre
Change directory
Display directory
Change default disk
Send a command to the system to be executed
Display unused RAM space
Temporarily pause GENPLOT and bring in the system
Type a file on the screen
Gives the pathname of the current directory
This section describes the commands which provide a user interface to the operating and file system
of the PC. These commands, in general, perform functions comparable to their name counterparts
within the actual DOS interface. File system commands include the capability of walking around
the tree directory using A:, B:, CD, WHERE, etc, and the ability to print out text files to the screen
using TYPE.
<DISK>:
Syntax: A: | B: | C: | ...
| Z:
Changes the default disk to the specified one, e.g., A: or B: or C:. This is identical to typing A: at
the OS prompt. Use LS to list files contained on the disk.
CD
Syntax: CD <directory>
This command operates identical to the OS change directory command, CD or CHDIR. It causes the
current directory of a disk to be changed to the specified directory; CD C:DATA would make DATA the
current directory on the C: disk, and CD JUNK would move the current disk to the JUNK directory.
The only difference between the OS command and this GENPLOT command is that a directory
must be specified in GENPLOT; in OS, if no path is given the current attach point is displayed. To
determine your current attach point (directory), use the WHERE command.
Note that CD will not change the disk you are currently attached to, but rather will only change the
directory of the specified disk. As in OS, type C: or D: to change your attached disk.
WHERE
Syntax: WHEre
Synonym: PWD
Prints to the terminal the pathname of your current directory on the currently active disk.
LS, DIR AND LF
Syntax: LS [ [path] [wildcard] ]
4l-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section L – Operating System and File Commands
Synonyms: DIR [ [path] [wildcard] ] and LF [ [path] [wildcard] ]
The LS command provides a listing of all files in the current directory, all files in a specified directory,
or all files in a directory which match a wildcard pattern. If no arguments follow LS, the files in
the current directory will be listed. If only a directory name is given following LS, all files in that
directory will be listed.
A general <wildcard> specification may include both the path and a wildcard file specification. The
DOS wildcard characters are used to match any number of characters (*) or a single character (?) in
the filename. The format of the wildcard specifications is identical to that for the OS DIR function.
Examples:
LS
LS *.F77
LS A?BC.DAT
LS D:..\JUNK\*.BAT
Provides listing of current directory
Lists only files with the .F77 extension
Will list files A1BC.DAT, A2BC.DAT, etc
Full pathnames are also allowed
To obtain file size information as well, use the command DOS DIR.
TYPE
Syntax: TYpe <file name>
Displays the contents of the specified file. The output is similar to the DOS MORE filter with output
of one page at a time. Pressing Q will quit back to GENPLOT. <space> will proceed to the next
page and <cr> will advance by one line. This command does not handle non–text files very well.
DOS
Syntax: DOS <command>
Synonyms: OK; <command>
The DOS command invokes a secondary copy of the DOS command processor. This effectively loads
a new copy of DOS into memory unused by GENPLOT. Any command can be executed by this new
copy of DOS, including word processors, compilers, editors or other programs. The only limitation
is memory; GENPLOT retains a large block of the memory while paused.
The text in <command> (remainder of the command line) is passed to DOS for execution. Once the
command is completed, control returns to GENPLOT. If no <command> is given on the line with
DOS, you will be prompted for the command.
If no <command> or a blank command is given, control is passed directly to the secondary DOS shell.
GENPLOT is halted in the background, but remains in memory. The new DOS shell has substantially less memory, but usually enough remains to run simple programs. To return to GENPLOT,
type EXIT at the DOS prompt. Warning: The new DOS shell obtains only a copy of the environment
variables. Any change in the variables is lost once EXIT is executed.
4l-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section L – Operating System and File Commands
¾
GENPLOT: DOS copy a1.dat junk.dat
GENPLOT: DOS lotus
GENPLOT: DOS
Internal command: <cr>
C> copy a1.dat junk.dat
C> exit
GENPLOT:
½
»
/*
/*
/*
/*
/*
/*
/*
Does the file copy
Runs LOTUS spreadsheet
If no command is entered, you
are prompted for one
Blank line brings up DOS
Execute a DOS command
Return to GENPLOT
¼
PAUSE
Syntax: PAUSE
Pauses execution of GENPLOT and loads a secondary copy of the command processor. This is
identical to the GENPLOT DOS command with a blank response to Internal command: prompt.
The OS shell is capable of running any DOS commands which fits in the remaining memory. Program
control is returned to GENPLOT by the command EXIT.
MEMORY
Syntax: MEMory
The MEM command lists the amount of unused (or available) memory. Memory is allocated from
this pool each time a curve is archived, or for loading dynamic modules such as the graphics device
drivers. The command is useful to determine if space remains for a large curve or to diagnose why
certain device drivers won’t load.
¾
»
GENPLOT: mem
Largest memory block free (Kb): 156.1
GENPLOT:
½
¼
4l-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
M. MISCELLANEOUS
?
GENplot
Help
SCRIPT
LOGIt
Quit
REturn
RESET
SGRAph
A condensed list of commands
Remind the computer about what you doing
Interactive information about commands
Open a file in which to put comments
Put a comment in the logfile
Get out of GENPLOT
Returns from GENPLOT to the main calling program
Reset almost everything to start up values
Change some of the esoteric plotting parameters
?
Syntax: ?
The ? command provides a condensed, but almost complete, list of all commands available at a
particular level within GENPLOT. The commands are listed in the order that they are searched
and are grouped according to functionality. The minimum abbreviation accepted for each command
is shown in uppercase letters. The remaining lowercase letters are not necessary for a command to
be recognized but must match if given. Since this list is generated by the command evaluator itself,
it is by definition complete and up to date at all times. Synonyms of some commands will not be
listed by ?.
The ? command is implemented within GENPLOT, ANNOTE, SAMPLE, FIT and TRANSFORM subprocessors also. Within the subprocessors, HELP is normally synonymous with the ? command also.
GENPLOT
Syntax: GENplot
The GENPLOT command will return to the GENPLOT: prompt from any subprocessor. This command
can be used at anytime to remind yourself that you are in this program or to guarantee the next
command will be executed at the GENPLOT root level. From within subprocessors, GENPLOT is
normally equivalent to the corresponding RETURN command.
HELP
Syntax: Help [<topic>]
The help command loads in and initializes a menu driven help screen organized in roughly the same
manner as this manual. The topics may be selected either by moving the cursor or by pressing the
first letters of the topic name. Pressing <PG-DN> or <cr> at any level will dive into the next level of
help on that topic. Likewise, <PG-UP> returns to the previous level of help. At any time, HELP can
be made to jump to a given topic by pressing the ? key and typing in the appropriate command
name.
If a <topic> is specified on the command line with HELP, HELP will search initially for that command. HELP may also be invoked by the F1 key at any time. The existing command line remains
unchanged and HELP will attempt to find the appropriate level based on the existing text.
4m-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section M – Miscellaneous
RESET
Syntax: RESET
The RESET command at GENPLOT level will reset almost all plotting and lexical parameters to
their initial values. This command can be used to re–establish an almost as-initialized state for
GENPLOT. User defined curves and variables are not released by the RESET however. The current
plotting device will be retained as well as the current HCOPY and/or script files. This command
should normally be preceeded with GENPLOT to avoid resetting only a sub–processor (many of which
have their own RESET commands also).
QUIT
Syntax: QUIT
Completely and terminally quit the GENPLOT program. GENPLOT exits with very few questions
asked; make sure you want to quit before issuing this command. The current graphics device is
closed down, all curves and variables are released and temporary files will be deleted as appropriate.
If an HCOPY file or a temporary MACRO file exist, you will be prompted for the proper disposition of
these files on the way out.
WARNING: You cannot abort from QUIT! One started, GENPLOT will finish its exit. Some
subprocessors include, because of user’s bad habits, QUIT as a synonym for RETURN. However, using
QUIT to return to GENPLOT is a very bad habit to get into since one day you will undoubtedly
type QUIT one level too high.
Since other subprocessors may include QUIT command, macros should use GENPLOT QUIT to ensure
an immediate exit.
RETURN
Syntax: RETurn
When GENPLOT is used as a subroutine in a user written program, RETURN exits GENPLOT
and returns back to the calling program. In the default shell GENPLOT.EXE, you will be given a
harsh, uncomplimentary message reminding you to use QUIT. Control is immediately returned to
GENPLOT again. Use QUIT to actually leave GENPLOT.
SCRIPT
Syntax: SCRIPT {<file> [-APPEND] [-LOGONLY|-COMMANDS] |-END|-PAUSE|-CONTINUE}
Synonym: LOGFile (same options)
The SCRIPT (and the synonymous LOGFile) command opens a console logging file, referred to as
a script file. Once a script file is opened, much of the subsequent input and output to the console
device (eg. your screen and keyboard) is copied into the script file. Additional comments may be
inserted into the file using the LOGIT command described below. Only “relevent” information from
the command session is copied into the script file. For instance, graphics drawing sequences are
never copied into a script file even if they go to the terminal.
4m-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section M – Miscellaneous
SCRIPT normally opens a file in overwrite mode, erasing any existing text. The -APPEND option
causes the file to be positioned at the end with new text appended to the file. -LOGONLY and
-COMMANDS limit the information to be logged.
Options:
-APPEND
-LOGONLY
-COMMANDS
-END
-PAUSE
-CONTINUE
Given immediately following a filename, the file will be positioned at
the end prior to writing new information. This allows multiple sessions
to be copied to a single log file. An error message will occur with this
option if the specified file does not exist.
If the script file is opened with -LOGONLY, only specific LOGIT requests
will be output to the file. This mode allows macros to automatically
generate analysis files for instance.
If the script file is opened with -COMMANDS, only the user typed text will
be copied into the script file. Screen responses and prompts will not be
saved to the file. This mode is useful in creating macros.
Closes down any currently active script file. If the script file has been
-PAUSEd, it will be automatically restarted before being closed by this
command.
Temporarily stops collecting log data in the current script file. The file
is not closed, and logging may be restarted using the -CONTINUE option.
Restarts a previously paused script file. Will generate an error message
if no script file exists.
¾
»
GENPLOT: script e:junk.log
...
GENPLOT: script e:oldjunk.log -append
GENPLOT: eval x eval y
...
GENPLOT: script -pause
GENPLOT: get test.dat
...
GENPLOT: script -continue
GENPLOT: eval x eval y
GENPLOT: script -end
SCRIPT session closed
GENPLOT:
½
/* Open a script file
/* Append an old file
/* Pause the script
/* After reading, restart
/* Close the file now
¼
LOGIT
Syntax: LOGIt [<comment>]
The LOGIT command logs a comment or a series of comments to the current script file (see SCRIPT
above). A warning message is generated if no script file is currently active. The remainder of the text
on the command line after LOGIT is considered to be the comment. If no text follows LOGIT, the user
is prompted for an arbitrary number of comment lines. The multiple line comment is terminated by
typing the EOF character (<control-Z> followed by <ENTER> on the PC).
4m-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section M – Miscellaneous
The comments appear in the script file between markers of
*** BEGIN COMMENTS ***
and
*** END
COMMENTS ***
An editor or filter can be later used to extracts these comments from the script file. Because all
text on the same line after the LOGIT command is assumed to be a comment, this command must
be the last active command on a command string and cannot be followed by any other commands,
including /*.
¾
»
GENPLOT: logit This is the first inline comment
WARNING: No SCRIPT file currently active
*** BEGIN COMMENTS ***
This is the first inline comment
*** END
COMMENTS ***
GENPLOT: script junk.txt
GENPLOT: logit
Enter comments for the LOG file. End with ∧Z
*** BEGIN COMMENTS ***
This would be the start of a fairly long commentary
on what GENPLOT was currently doing.
To exit, we type a <ctrl-Z> to indicate the end-of-file.
∧Z
*** END
COMMENTS ***
GENPLOT:
½
SGRAPH
Syntax: SGRAph [LIST | <var name> <value>]
SGRAPH provides the user access to various esoteric plotting parameters defined deep within GENPLOT, such as superscript and subscript sizes, axis label offsets, etc. In general, all dimensional
units are in inches if not specified otherwise. The command SGRAPH LIST prints values for a few
(but not all) of the important parameters.
The first time SGRAPH is executed, the internal variables are actually “linked” into the function evaluator as $<name>. For example, the variable ARWLEN is linked as $ARWLEN. Consequently, once SGRAPH
has been executed once, variables may be evaluated or changed using EVAL and LET commands. For
example:
>> eval $arwlen
>> let $arwlen = 2*$arwlen
A full list of variables can be obtained using LISTV -H (since they are hidden).
Some of the variables and their meanings linked by SGRAPH are:
4m-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
¼
Command Reference
Section M – Miscellaneous
ARWLEN
ARWANG
AXCOLR(1)
AXCOLR(2)
AXCOLR(3)
AXCOLR(4)
AXCOLR(5)
AXWIDTH(1)
AXWIDTH(2)
AXWIDTH(3)
AXWIDTH(4)
AXWIDTH(5)
CSMIN
CSMAX
IDLSKP
IDTSKP
IDSIZE
IDSPAC
IDLSIZ
SUSIZ
SUBOFF
SUPOFF
SYMSIZ
TICK
TICK2
TSIZE
TSTAMP(1)
TSTAMP(2)
TSTAMP(3)
TBOFF
TTOFF
TLOFF
TROFF
ZFORCE
Arrow head length for arrow commands (ANNOTE)
Opening angle for arrow head drawing (ANNOTE)
Pen color used for axes lines
Pen color used for major tick marks
Pen color used for minor tick marks
Pen color used for axis labels
Pen color used for axis title characters
Width of major axis line
Width of major tick marks
Width of minor tick marks
Width of axis labels
Width of axis title characters
Minimum character size allowed for labeling axis numbers
Maximum character size which will be used for axis labeling
Distance from left axis line to start of IDS labels
Distance from top axis to start of IDS labels
Size of IDS labels
Spacing between IDS labels (character sizes)
Size of example line for IDS description
Subscript/superscript size as a fraction of current symbol size
Offset of subscripts as fraction of current size
Offset of superscripts as fraction of current size
Default symbol size
Length in inches of the major tick marks
Length in inches of the minor tick marks
Size of titles on axis
Time stamp X position
Time stamp Y position
Size of time stamp
Additional offset for title on bottom axis
Additional offset for title on top axis
Additional offset for title on left axis
Additional offset for title on right axis
Force ratio for lower axis limit being set to zero. If lower/upper
range <ZFORCE, then lower limit set to zero.
AFTER SGRAPH has been executed once, you can also use LET to change a value.
4m-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section M – Miscellaneous
¾
»
GENPLOT: sgraph list
/* display the initial values
Symbol Parameter:
SUSIZ:
0.6500
SUBOFF: 0.3750
SUPOFF: 0.7500
Axis Parameters:
TBOFF: 0.000E+00 TTOFF: 0.000E+00 TLOFF: 0.000E+00 TROFF: 0.000E+00
CSMIN: 0.7000E-01 CSMAX: 0.1800
TSIZE: 0.2200
TICK:
0.1600
TICK2: 0.8000E-01 AXCOLR: -1.
AXWIDTH: 1.700
Identify Parameters:
IDLSKP: 0.2000
IDTSKP: 0.4000
IDSIZE: 0.1500
IDSPAC:
1.500
IDLSIZ: 0.4000
Other Parameters:
ZFORCE: 0.3000
SYMSIZ: 0.1000
GENPLOT: sgraph axcolr(1) 2 /* change the axis color
GENPLOT: sgraph idspace .5
/* change ids spacing
GENPLOT: let $idspace = 1.0
GENPLOT:
½
¼
TIMESTAMP
Syntax: TIMEStamp
The TIMESTAMP command plots on the graph the current date and time. See the SGRAPH command
to move the position of the stamp. Format is Dec 03 1988 22:45:88.
4m-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
N. GENPLOT EDITOR – EMACS
There are many occasions in GENPLOT when it is necessary to change data files or edit macro
files. Most editors, however, are to large to load into memory on top of GENPLOT using the DOS
command. GENPLOT consequently provides a built-in editor modeled after EMACS. EMACS is a
common and extremely powerful scientific programming editor. GENPLOT does not implement a
real EMACS, but only a minimal look alike.
The EMacs [<file>] command will load a “minimal” editor, mainly for editing macro and data
files. The editor uses approximately 6 kB of space itself plus the file space. Commands are modeled
after the real EMACS editor albeit without the extensibility. Files are limited to 64 kB and only a
single file may be edited at a time. A brief discussion of the EMACS editor commands is given for
those unfamiliar with EMACS along with a full list of the immplemented commands. [F1] within
EMACS provides a single screen help listing of the most common commands.
USING EMACS
Syntax: EMacs [<filename>]
EMACS is a full–screen editor similar to a word processor. The cursor marks the active editing
position in the file. Normal text is either inserted at the cursor position or overwrites the existing
data (insert versus replace modes). EMACS commands (control or escape sequences) can be executed
at any time and generally operate on blocks of text. EMACS commands allow you to move the cursor
around, delete text, and perform other functions. All commands sequences begin either with the
Esc (escape) key or are combined with the Ctrl (control) or Alt keys.
STARTING EMACS
To edit a file, issue the command
>> emacs <filename>
where <filename> is the name of the file you wish to edit. If the file does not exist, it will be
created. When EMACS starts, the current text screen is copied into the kill buffer. Hence any text
on the screen ( ANNOTATE coordinates for instance) can be retrieved by yanking the kill buffer
immediately. See ∧Y under Delete Commands for yanking the kill buffer.
READING AND WRITING THE FILE
When you are done editing, you must save the modified file. The file can be saved under the current
name with:
>> Ctrl-X Ctrl-S
(Ctrl-X means hold down the Ctrl key and press X. This command, Save File, will save the edited
version in place of the original. To save the file under a new name, or if no name was specified when
EMACS was started, use Write File by typing:
>> Ctrl-X Ctrl-W <new filename>
4n-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section N – GENPLOT Editor – Emacs
You will be prompted for the filename at the bottom of the screen. This will create a new file with
the given name containing your modified or newly entered text.
A new file can be “found” and loaded into EMACS using Find File. The file currently in the buffer
is lost. However, if the current buffer has been modified, you will be prompted first to confirm the
operation.
>> Ctrl-X Ctrl-F <new filename>
A file may be inserted into the current buffer at the cursor position using Insert File:
>> Ctrl-X I
EXITING EMACS
To exit from EMACS type:
>> Ctrl-X Ctrl-C
If you have not saved your file, EMACS will ask you if you really want to quit. Otherwise it will
return you directly to GENPLOT command level.
MOVING AROUND THE SCREEN
As previously mentioned, EMACS inserts text at the current cursor location. To move the cursor,
use the arrow keys or the following control sequences:
Ctrl–P
Ctrl–N
Ctrl–F
Ctrl–B
Ctrl–V
Alt–V
Alt–<
Alt–>
Previous line
Next line
Forward a character
Backward a character
Next page
Previous page
Go to beginning of file
Go to end of file
ENTERING NEW TEXT
To insert text into a file you must put the cursor where you want the text. EMACS takes anything you
type, and puts it into the file. EMACS starts in INSERT mode so that text will be inserted before the
cursor. In REPLACE mode, the entered text will overwrite the current text. INSERT/REPLACE
mode is toggled by pressing the Ins key. The current mode is displayed on the status line at the
bottom of the screen.
MODIFYING EXISTING TEXT
Delete Commands
To delete a few characters, move the cursor to the characters and use
>> Ctrl-D, Del key, or ← (backspace)
Ctrl-D deletes the character the cursor is on while backspace deletes the previous character.
>> Alt-D Deletes a word.
To delete lines from your file,
4n-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section N – GENPLOT Editor – Emacs
>> Ctrl--K
This command deletes all text to the end of the line. If the cursor is at the end of the line, the
line–feed is deleted. Hence, Ctrl-K must be typed twice to completely kill a line.
Words and lines that are deleted are placed in a special buffer called the “kill buffer”. The contents of
this buffer can be retrieved back into the file at the current cursor position using Yank Kill, Ctrl–Y.
Only the last block of contiguous deletions is saved in the kill buffer. Initially, the kill buffer is filled
with the screen contents when EMACS was called. This feature can be used to extract coordinates
or values from the screen for macro files or data log files.
Deleting a Block of Text
A block of text can be deleted, or moved, by defining a region and moving it to the kill buffer. One
boundary of the region is the current cursor position. The other boundary is at an invisible point
called a “mark”. The “mark” can be set at the current position by typing:
>> Ctrl-@
The current position and the mark can be exchanged using:
>> Ctrl-X Ctrl-X
To view the region, press [F8] to highlight between the mark and point. [F8] toggles the highlight
mode each time. Once the region is properly marked, type:
>> Ctrl-W
to kill the region. The killed text is actually put into a kill buffer which can be yanked back into
the file in a different location with Ctrl-Y.
SEARCH COMMAND
Search causes the editor to search from the cursor for a string of characters. The full syntax is:
Ctrl--S <string>
Search forward
Ctrl--R <string>
Reverse search
<string> is the string of characters to locate and is entered at the prompt line. When the string is
found it becomes the current position. If <string> does not exist, the cursor position is unchanged.
If no <string> is entered, the previous <string> is used.
EMACS COMMAND SUMMARY
Summary notation:
∧A =⇒ Ctrl and A together
∼A =⇒ Alt and A together
For those familiar with using EMACS on mainframe computers, <ESC> followed by the letter may
be used in place of Alt.
∧B
∼B
Moving Around
Arrow keys move around as expected
backward char
∧F
forward char
backward word
∼F
forward word
4n-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section N – GENPLOT Editor – Emacs
∧N
∧A
∧V
∼<
∼L
next line
beginning of line
forward page
beginning of text
redraw screen
∧P
∧E
∼V
∼>
previous line
end of line
backward page
end of text
Deleting, inserting and modifying text
∧D
delete char
←−
backspace
∼D
kill word
∧K
kill line
∧W
kill region
∼W
copy region
∧Y
yank kill
(A region is between a mark and your current point)
∧@
set mark
∧X∧X
exchange point/mark
∧O
open line
∧X ∧O
delete blank lines
∧Q
quote key
∧T
twiddle
∼L
lowercase word
∼U
uppercase word
∼C
capitalize word
∧S
∧X∧S
∧X I
∧X∧F
Searching
∧R
reverse search
File handling and quitting
save file
∧X∧W
write file (new name)
insert file
∧X∧C
Exit/Quit
find file
∧X∧L
∧X=
F1
[F1]
[F3]
[F5]
[F7]
[F9]
∼[F1]
∼[F3]
∼[F5]
search
Miscellaneous
count lines
show information on current point
help
Function Key definitions
help screen
[F2]
read file
set mark
[F4]
save file
kill region
[F6]
yank kill
[F8]
highlight region
goto line
[F10]
exit
help screen
∼[F2]
insert file
exchange point/mark
∼[F4]
write file (new name)
copy region
4n-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section N – GENPLOT Editor – Emacs
If you find this minimal EMACS editor useful, you should try the real versions. Lugaru sells an
extremely powerful and fast version of EMACS for the PC called EPSILON. While we have no
vested interest in Lugaru, it is our opinion that it is well worth the asking price.
4n-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
O. 3–DIMENSIONAL PLOTTING SUPPORT
3-D
Axis
ARChive
Box
Contour
Function
Grid
Help
Hidden lines
Label
Mesh
Perspective
Plot
Quit
Range
Read
Resolution
RETrieve
Rotate
Show surface
Status
Stereo
Surface
Tilt
Z Search
Enter 3–D mode from GENPLOT
Draw 3–D axes
Save the current raw 3–D data set under a name
Put a box around the plot
Display data as contour plot
Define a function for display
Create a mesh from raw data
Display available commands
Toggle hidden line drawing mode
Set the label for an axis
Controls the number of lines drawn to represent function
Set the viewing distance
Display data
Leave 3–D mode and return to GENPLOT
Set the range to use on the axes
Read 3–D data
Set density of points along mesh
Retrieve an archived data set into current buffer
Set rotation about the Z axis for viewing
Set which surface to show in hidden line mode
Display 3–D status
Locks the coordinate system so that only tilt and rotate operate
Draw representation of the data as a surface
Set tilt from x–y plane for viewing
Search the 3–D space for minimum and maximum Z values
WARNING: The command HCOPY does not work in 3-D mode. The problem occurs when handling
hidden line suppression. Suppression calculations are done on the pixel resolution of the device
(accuracy of .1 inches on a screen but 0.003 inches on a laser printer). This resolution information is
lost in the HCOPY files. Hence, HCOPY does not properly work in 3-D mode and is not implemented
fully. You must repeat the specific plot commands to a hard plotter to get a print. Please do not
use HCOPY, or at least don’t ask us why it doesn’t work.
The curve is a relatively simple concept in the 2–D dimensional space of normal plotting. Its analog
in 3–D however is somewhat more complex depending on the particular application. In some cases,
a curve is the same collection of points connected by line segments, such as line drawing of a box.
More commonly though, the curve in 2–D translates into a surface in 3–D. GENPLOT supports
both models in the 3–D sub-processor. Lines and symbols are treated in a manner very similar to
lines and symbols in 2-D.
When plotting 2–D information it is easy to just connect the points. When trying to produce a
suface or contour plot however one frequently needs more information than is actually provided
for by the raw data. Points must be interpolated to provide a smooth transitions for the surface
or contour lines. Raw (x,y,z) data can be plotted by itself. The GRID command must be used to
produce a surface or complete “grid” of information from your raw data. You must use GRID or
FUNCTION before you can use either SURFACE or CONTOUR unless you have provided all the points
needed for a surface, with READ MATRIX for example.
4o-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
3–D
Syntax: 3-D
Enter 3–D mode from GENPLOT.
READ
Syntax: Read [DATA|matrix|internal] <filename>
Reads 3–D data from a file. The data option reads ASCII data in (x, y, z) form.
Read matrix will read a multicolumn GENPLOT binary file where each column in the file represents
Z values at constant Y. (Think of it as a matrix where the values of X and Y are integers between
1 and N.) MESH and RESOLUTION are reset to match the information in the file.
Read internal allows you to access GENPLOT’s temporary storage of 3–D information. Because
a 100x100 mesh may contain 100,000 points GENPLOT creates a temporary disk file to hold the
mesh information. When you do GRID or READ MATRIX a file called temp$.3d is created and contains
the current surface information. To save time on large raw data sets you could rename or copy this
file and use READ INTERNAL FILENAME to access it at a later time.
¾
Plot3-D:
Reading
Plot3-D:
Plot3-D:
Plot3-D:
Plot3-D:
½
»
read data datafile
grid
dos copy temp$.3d data.bin
read internal data.bin
¼
GRID
Syntax: Grid
Creates a 3–D surface or grid of information from raw data. This is required before running SURFACE
or CONTOUR on raw data.
PLOT
Syntax: PLot [DATA|surface|contour] [-SYMbol n] [-SYMsize r] [-LType n]
This command will erase the screen, draw the appropriate axes, and plot the points. The DATA
option, the default, does not require the use of GRID. You cannot use this with FUNCTION. Specifying
SURFACE or CONTOUR options will cause the appropriate 3–D plot to be displayed. You must use the
GRID command before displaying the data a surface or contour plot.
The -SYMBOL option sets the symbol to use for the points, default symbol type is 7. The -SYMSIZE
option sets the size of the symbol, default symbol size is 0.1. -LTYPE sets the line type, the default
is 0, which plots points with symbols. Line types above 0 display various line styles. See Reference
4d for the available symbols and line types. The symbol type and size and line type will remain in
effect throughout your current session.
See also: Overlay, Surface, Contour
4o-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
OVERLAY
Syntax: OVerlay [DATA|surface|contour] [-SYMbol n] [-SYMsize r] [-LType n]
This command overlays the data or surface on the current plot. It is the same as PLOT except that
it does not erase the screen or draw the axes. The SURFACE and COUTOUR commands are equivalent
to OVERLAY with the corresponding option.
See also: Plot, Surface, Contour
CONTOUR
Syntax: Contour
Display a contour plot of a surface. With raw data you must use grid first.
SURFACE
Syntax: Surface
Plot the current surface. With raw data you must use grid first.
AXIS
Syntax: Axis
Draws the axes for the plot. Unlike the 2–D section of GENPLOT this does not erase the screen.
In practical use one often displays the data several times before actually wanting the axes.
MESH
Syntax: Mesh [nx ny]
Controls the number of lines that are drawn at at constant X or Y. The arguments specify the
number of lines to draw. The defaults are 25 lines at a resolution of 100 points per line.
¾
»
Plot3-D: mesh
# of lines drawn at constant X: 25
# of lines drawn at constant Y: 20
Plot3-D:
½
¼
4o-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
¾
»
½
¼
FUNCTION
Syntax: Function <expression (x,y)>
Define a function to view. It does not actually create the data. The function is used when a graph
command such as SURFACE is selected.
¾
»
Plot3-D: function sin(sqrt(x*x+y*y))/sqrt(x*x+y*y)
Plot3-D: range -15 15 -15 15 -.5 1
/* interesting range
Plot3-D: plot surface
Plot3-D:
½
¼
HELP
Syntax: Help
Display summary of available commands.
HIDDEN LINES
Syntax: Hidden lines [ON | off]
Toggles hidden line removal on or off.
¾
»
Plot3-D: hidden
Hidden line suppresssion (on|OFF): ON
Plot3-D:
½
¼
4o-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
LABEL
Syntax: Label [x | y | z] [text]
Set the label for an axis.
¾
»
Plot3-D: label
Which axis: [X|Y|Z] x
Label: Diffraction index
Plot3-D: label y ’Temperature’
Plot3-D:
½
¼
NAMING RAW DATA SETS: ARCHIVING THEM TO MEMORY
WARNING: Despite the choice of command names, ARCHIVE and RETRIEVE only do a memory
based save of the data. No permanent copy of the data is written to disk and any data archived will
be lost when GENPLOT is exited. YOU HAVE BEEN WARNED!
3–D GENPLOT normally works only with a surface derived from the raw data. However, during a
routine data analysis, it is often important to work with several raw data sets. Rather than rereading
the data in from disk many times, the ARCHIVE and RETRIEVE commands are provided. This
is a MEMORY BASED curve archival - not disk based; any curve archived will disappear when
GENPLOT is exited. Using ARCHIVE <curve name>, the raw data set is “archived” into a named
curve in memory. At any later time in the 3–D GENPLOT session, the data in that named curve may
be retrieved to the main curve using RETRIEVE <curve name>, or the data in the named curve may
be plotted or overlaid directly using the PLOT <curve name> or OVERLAY <curve name> commands.
Data sets archived to named curves may be used in mathematical operations as described in the
ARCHIVE command summary below.
ARCHIVE
Syntax: Archive <curve name>
The archive command creates a curve variable and copies the current main data set into the surface
variable. An archived curve may be plotted directly, or may be retrieved to the main curve using
the RETRIEVE command.
Formally, it is equivalent to several function evaluator operations (see Function Evaluator) and
thus the curve components may be used wherever expressions are expected. Consider the command ARCHIVE TEMP. Archive first allocates a curve of length NPT called TEMP. This creates array
TEMP:X, TEMP:Y, TEMP:Z and an integer TEMP:NPT. TEMP:NPT is set equal to the current
number of data points, and the main X,Y curve is copied to the TEMP:X, TEMP:Y and TEMP:Z
arrays. The original data is unmodified. An error will be generated if there is insufficient memory
to allocate the curve.
The allocation of a 3–D curve really allocates three arrays, mathematical operations on the archived
curves are possible. The command LET TEMP:X = 2*TEMP:X for instance will double the X coordinate of the curve TEMP.
4o-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
¾
Plot3D:
Plot3D:
Plot3D:
Plot3D:
Plot3D:
Plot3D:
Plot3D:
½
»
archive TEMP
/* Save
grid /* Create the grid
plot surface /* plot the surface
retrieve TEMP
/* Copy
over TEMP
/* Plot
let TEMP:Z = TEMP:X*TEMP:Y /* Some
current data to curve TEMP
TEMP back to main curve
the data
strange transformation
¼
See also: RETRIEVE
RETRIEVE
Syntax: RETRIEVE <curve name> [-APPEND]
Retrieve copies archived raw data <curve name> back into the main curve for further analysis. The
current main data set is lost unless the -APPEND option is specified. An error will be generated if
<curve name> does not exist.
¾
»
Plot3D:
Plot3D:
Plot3D:
Plot3D:
Plot3D:
½
read file1
archive d1 plot
read file2 plot
ov d1
/*
/*
/*
/*
read first set
save file1 and plot it
read and plot second set
overlay file1 on file2 curve
¼
See also: ARCHIVE
PERSPECTIVE
Syntax: PERspective
Set the viewing distance in normalized units. The default is infinity.
QUIT
Syntax: Quit
Returns to where you started 3–D. Generally this will return you to GENPLOT.
RANGE
Syntax: Range <xmin xmax ymin ymax zmin zmax>
Set the range to use for the axes.
¾
Plot3-D: range 0 10 0 5
Minimum & max Z values: -1
Maximum Z value: 1
Plot3-D:
½
»
¼
4o-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
RESOLUTION
Syntax: Resolution <resx resy>
Sets the dot density along the mesh lines. While MESH sets the number of displayed lines along an
axis resolution sets the number of points contained in each line. It controls the smoothness of the
line segments between mesh intersections. The default is 100 points along each line. If you have 25
mesh lines there will be 4 points between each line.
¾
»
Plot3-D: res 100 100
Plot3-D:
½
¼
ROTATE
Syntax: Rotate <r>
Sets the rotation about the Z axis. The axes are first rotated then tilted.
¾
»
Plot3-D: rotate 10
Plot3-D: rot
Rotation about the Z axis: 15
Plot3-D:
½
¼
SHOW SURFACE
Syntax: Show surface [top <color> | bottom <color> | both <top color> <bottom color>
This has meaning only when hidden is ON. This gives the priority for which information to show and
which to hide. It also sets what pen color is used for the section of the surface desired.
¾
»
Plot3-D: show
Show which surfaces (TOP|bottom|both): both 2 3
Plot3-D:
½
¼
STATUS
Syntax: Status
4o-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
¾
»
Plot-3D: status
3-D data from <source>
Rotation about Z axis:
30.00
Tilt from the X-Y plane:
Viewing Distance (radii): 2.0
Mesh along constant X:
25 lines of 100 points
Mesh along constant Y:
25 lines of 100 points
X range:
Y range:
Z range:
(
(
(
0.00000,
0.00000,
0.00000,
45.00
10.0000)
10.0000)
10.0000)
Hidden line suppression disabled.
Stereo mode disabled.
Plot-3D:
½
¼
NLSFIT
Syntax: NLSFIT <commands>
NLSFIT is a powerful fitting routine which attempts to fit a user defined function to the experimental
data, varying parameters in the function to minimize the least-squares deviation of the data from
the function. Hence, fits can be based on quantitative models, or at least justifiable functions.
The function used in 3–D is identical to that used in the 2–D section of GENPLOT except that the
functions must be defined in both X and Y. Please refer to Section H for details.
STEREO
Syntax: Stereo
With STEREO off the coordinate system is altered each time a suface is plotted so that the surface uses
as much of it’s alotted box as possible. Thus when one rotates or tilts the surface it’s dimensions will
change. A stereo pair is produced by offseting two plots rotated 7 degrees from each other. These
plots must not change dimension. STEREO ON locks the coordinates from the first plot so that the
second one will have the same dimensions.
¾
»
Plot3-D: function sin(sqrt(x*x+y*y))/(sqrt(x*x+y*y)+1e-15)
/* 1e-15 to avoid 0/0
Plot3-D: range -15 15 -15 15 -.5 1
/* interesting range
/* make two plots fit
Plot3-D: shrink 2
Plot3-D: plot surface
/* plot first one
/* lock coordinates
Plot3-D: stereo on
Plot3-D: offset 5 0
/* move over
/* rotate and plot again
Plot3-D: rotate 7 ov surface
Plot3-D:
½
¼
4o-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Command Reference
Section O – 3–Dimensional Plotting Support
TILT
Syntax: Tilt
¾
»
Plot3-D: tilt 45 surface
Plot3-D: tilt 20 offset 10 0 surface
Plot3-D:
½
¼
¾
»
½
¼
Z SEARCH
Syntax: Z Search
Will evaluate Z values at various (x, y) points to determine the range of the data. This is normally
used before the RANGE command when you do not know the data range.
4o-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
P. RUMP
IMPORTANT NOTES
• RUMP as distributed includes stopping power tables appropriate for incident energies to 3.0 MEV.
If you are working above this energy, see appendix on QSTOPP and STOPP for generating higher
energy tables.
• RUMP does not normally handle resonances since these are very geometry dependent. To include
non-Rutherford cross sections, you must create a .ADT file as described in appendix on RES5.
• Forward scattering simulations requires manual entry of cross sections. See commands XSECT and
E2COEF.
• The native format for .RBS files has changed. The old format is still recognized by RUMP. However
translator programs from .RBS to other formats will need to be rewritten. See the appendix on the
new data format.
INTRODUCTION AND ACKNOWLEDGEMENTS
RUMP is a series of FORTRAN subroutines designed for the analysis and simulation of Rutherford
Backscattering Spectroscopy (RBS) data. It was initially developed at Cornell University in Dr.
J.W. Mayer’s research group by then graduate students L.R. Doolittle and M.O. Thompson with
assistance from R.C. Cochran. The development of the efficient simulation algorithm and the semiautomatic search algorithms formed a major part of L.R. Doolittle’s thesis. Numerous other graduate
students and researchers at Cornell and other sites have since contributed to the program. We wish
to acknowledge Dr. E.J. Kramer’s group at Cornell for introducing equations to SIM as well as being
the impetus for the forward scattering support. Dr. P. Revesz is also acknowledged for numerous
improvements in both the code and user interface including most recently the smoothing algorithms.
Finally, we most gratefully acknowledge all of the past and current graduate students at Cornell
who have used the program for real analysis and data reduction. We firmly believe that the value
of RUMP stems directly from the fact that it is used by the same people who are responsible for its
development.
The algorithms and subroutines comprising RUMP are considered to be in the public domain. The
source code for all RUMP specific routines are included in this distribution. They may be freely
modified, recompiled or distributed as long as the original copyright notice is retained in all source
code. CGS will act as a general repository for code corrections and enhancements and will attempt
to disseminate modifications in an orderly manner. However, while the code to RUMP is public
domain, the library support routines are part of a commercial product licensed for use on one
machine only and may not be distributed.
The meaning of the acronym RUMP is a question often raised in discussions. Let us set the record
straight; the name was invented solely to avoid trademark infringement - the earliest name of this
package was TRACOR. However, for those who demand full accounting and explanations, we suggest
the following expansions:
• Rutherford Universal Manipulation Program
• RBS Universal Master Package
4p-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
• RBS for the Upwardly Mobile Professional
• Rapid Unearthing of Multiple Parameters
• Random Utility for Making Pictures
• Rather Unusual Masochistic Package
PEDIGREE: RELATIONSHIP BETWEEN RUMP AND GENPLOT
RUMP is a data manipulation package similar to GENPLOT but is designed specifically for the
analysis and simulation of Rutherford Backscattering Spectroscopy (RBS) data. Both packages
were initially written around the same graphics and token processing libraries to provide a consistent (but not identical) user interface. The two packages diverged in recent years however as
GENPLOT became a commercial product for the microcomputer environment and RUMP development continued on a VAX mainframe. To reduce the continuing effort required to support separate
software packages, RUMP has once again been modified to conform to the current library support.
With this move, RUMP support and documentation (at some meager level) has been assumed by
CGS.
RUMP and GENPLOT are designed on equivalent software levels — both are the upper shell of
complex data analysis and graphics packages. RUMP is neither a subset of GENPLOT nor is GENPLOT a subset of RUMP. They are equivalent subroutines utilizing a common set of graphics and
system support libraries. Indeed, with sufficient memory GENPLOT is a command within RUMP
and RUMP can be a command within GENPLOT. The commands available in either packages can
be divided into two classes; upper level commands implemented within the main program itself and
lower level commands implemented in the underlying library. PLOT is an upper level command and
hence operates in a different manner in each package. However, SCRIPT and ANNOTE are support
library commands and are identical in both RUMP and GENPLOT. It is important to remember
this distinction if you will be using both packages or are already familiar with one.
This section of the manual deals only with commands which are specific to RUMP. Lower level
commands common to RUMP and GENPLOT are fully described in other sections of the manual.
We have attempted to clearly identify which commands operate identically between the two packages
as well as point out specific incompatibilities in the commands. Even if you are an old user of RUMP,
some commands have changed considerably and we ask that you please read through section 1 of the
GENPLOT manual paying close attention to the “Essential Information” (which is repeated in the
“Quick Reference” section).
4p-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
ALGORITHM AND DATA REFERENCES
Algorithms for the Rapid Simulation of Rutherford Backscattering Spectra, L.R. Doolittle, Nucl. Inst.
Meth. B9, 344 (1985).
A Semiautomatic Algorithm for Rutherford Backscattering Analysis, L.R. Doolittle, Nucl. Inst. Meth.
B15, 227 (1986).
Empirical Stopping Powers for Ions in Solids, J.F. Ziegler, J.P. Biersack, and U. Littmark, IBM
Research Report RC9250 (1982).
Numerical Recipes, Press, Flannery, Teukolsky and Vetterling, (Cambridge University Press, 1986).
Backscattering Spectrometry, W.K. Chu, J.W. Mayer and M.–A. Nicolet, (Academic Press, NY,
1978).
Ion Beam Handbook for Material Analysis, J.W. Mayer and E. Rimini, (Academic Press, NY, 1977).
L.R. Doolittle, Ph.D Thesis, (Cornell University, Ithaca, NY 1987).
4p-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
GENERAL CONCEPTS: BUFFERS AND DATA FILES
RBS experimental and simulation spectra are stored in RUMP in a set of internal buffers. These
buffers are reused on a rotating basis to accommodate new spectral data. Twelve buffers are configured in the PC version, each with a maximum of 1024 channels of data (mainframe versions generally
increase the buffer size to 2048 channels). The buffers are numbered from -1 through 10. The first
two buffers, -1 and 0, are always reserved for temporary calculations (-1) and for spectral simulations (0). The remaining ten buffers hold experimental spectra, copies of simulations or temporary
calculations (PERT). Buffers are referred to by either number or by content (the filename of the
corresponding data). At any point in time, one buffer is designated as the MAIN or ACTIVE buffer.
This designation is important in that many commands, for example THICKNESS, operate only on
the ACTIVE buffer. The ACTIVE buffer may be changed using commands such as GET or POINTAT
and can be identified using the BUFFERS command. The first two special buffers -1 and 0 cannot, in
general, be retained as the ACTIVE buffer.
Buffers are actually data structures containing not only the spectral information (counts per channel), but also experimental parameters required to analyze the data. These experimental parameters
describe the incident particle, the beam energy, charge integration, scattering geometry, etc. This
information is stored on a per buffer basis and may be modified using commands described in this
manual.
RUMP data files correspond closely to the buffer structure. The most recent version of the data file
utilize a format which is machine independent, allowing direct binary exchange of data files between
different mainframe and micro implementations of RUMP. An appendix to this section describes
the internal data file format in detail. The old format, written using FORTRAN unformatted I/O
records, is still recognized by the READ commands. Buffers are filled with experimental data by
reading the files using GET, REAL, PLOT or OVERLAY. The ACTIVE buffer can be saved, with the
current buffer experimental parameters, using REWRITE, SAVE or WRITE commands.
GENERAL CONCEPTS: SPECIFYING ELEMENTS
Elements names are required in many of the commands to RUMP. Internally, RUMP maintains a
list of 92 elements with isotope masses, abundances, and atomic density. Elements are specified by
their common one or two letter symbol such as Si or O. Full names are not permitted. A specific
isotope can also be specified for most commands by using the format 28Si or 31Si. (An obsolete
format Si+28 is also still supported.) If the isotope is listed in the internal tables, the actual mass
for the element is used. Otherwise, the specified atomic weight will be used as the atomic mass.
42Si is valid in RUMP but don’t expect meaningful results.
Charged beams are specified in the same manner except for the addition of plus signs after the
symbol. 4He++ is the symbol for normal double plus backscattering alpha particles.
GENERAL CONCEPTS: SIM AND PERT
RUMP includes a very fast and powerful, if not overly friendly, simulations package referred to
as SIM. SIM couples with an even less friendly package called PERT which automatically varies
parameters describing the simulation to reach a “best fit” with a given experimental spectrum. Both
SIM and PERT are sub-processors under RUMP with their own set of commands and data files.
There is no command to do a simulation; simulations are automatically performed when necessary
using experimental parameters from the ACTIVE spectra and elements and layer thicknesses from
a “sample description”. Commands within SIM are primarily directed to generating the sample
description and modifying some of the simulation parameters. PERT is solely concerned with the
search procedure.
4p-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
BASIC PLOTTING COMMANDS
PLot
OVerlay
REplot
AXis
COMPare
BLowup
EXpand
BYe
Quit
Erase screen and plot spectrum from buffer or file
Overlay spectrum from file or buffer on current plot
Plot the currently active spectrum
Draw axes only
Plot active and simulation buffers
Plot region of spectrum on an expanded vertical scale
Set region to a subset of current region and replot
Quit and exit program completely
Quit and exit program completely
PLOT
Syntax: PLot [file | buffer # | SIM | MAIN | ALT | LAST | NOW | THeory]
The PLOT command is the basic command for drawing axes and spectrum to the active graphics
device. Normally, the screen is erased (or a new page obtained), the axes are drawn and the requested
spectrum is plotted. The data are drawn using the current line type and symbol type. If the autoids
option is selected, the identifier string from the spectrum will also be drawn on the plot.
A filename or buffer number must be specified in RUMP version of the PLOT command. If a number
between 0 and 10 is specified, it is assumed to refer to a buffer and that buffer plotted. The
simulation buffer will be updated if necessary. If any buffer other than 0 is plotted, it becomes
the ACTIVE buffer after this command. If the simulation buffer 0 is plotted, the ACTIVE buffer
remains unchanged.
If a buffer number is not specified in PLOT, the token is compared first to a number of special names.
The names SIM, ALT and THeory refer to the simulation buffer 0 and hence PLOT THEORY is equivalent
to the command PLOT 0 described above. The name MAIN likewise refers to buffer 1 while NOW and
LAST refer to the currently ACTIVE buffer. These names should not be used for normal data files.
If the token following PLOT is neither a number nor a special name, it is assumed to be a valid
filename with a default extension of .RBS. The current buffers are first searched for one already
containing that filename (full pathname is checked). If found, the buffer becomes ACTIVE and
PLOT operates as described above. If no buffer currently contains the file, the buffers are scrolled
down to create an empty buffer 1 and the file is read into buffer 1. The original buffer 10 is lost in
the process (even if the file read fails). The ACTIVE pointer is set to buffer 1 and the spectrum is
plotted.
The selection of a buffer occurs before any plotting. The scale for the YIELD axis (if autoranging)
and the conversion from channel number to energy are determined from the plotted buffer. The
channel number range is converted to the equivalent energy range through the CONV parameters
SCALE1 and SCALE2. For a PLOTed spectra, both energy and channel scales are always correct.
The yield can be plotted either as a raw counts per channel or as a normalized yield, selected by the
RAW or NORMALIZED commands. In the normalized mode, the yield is normalized to conditions of 1
keV channel energy width, 1 µC of single plus equivalent charge, and a 1 msr detector solid angle.
This normalization should allow direct comparison of any spectra obtained at the same incident
energy in the same scattering geometry. (Note: Charge equivalency treats 2 µC of He++ the same
as 1 µC of He+ .)
4p-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
OVERLAY
Syntax: OVerlay [file | buffer # | SIM | MAIN | ALT | LAST | NOW | THeory]
OVERLAY operates identically to PLOT with the exception that no axes are drawn. Existing energy and
yield scales are used allowing comparison of numerous spectra. Plotting is always done based on the
energy scale, not the channel scale allowing overlay of data from different multichannel analyzers.
The channel axes will correct only for the first spectrum plotted unless all spectra have the same
CONV constants. The energy scale is always correct however. Since OVERLAY also uses the current
yield range, data may extend offscale if the range is inappropriate.
REPLOT
Syntax: REplot
The REPLOT command is synonymous with PLOT NOW. It quickly replots the ACTIVE buffer with a
little less typing.
AXIS
Syntax: AXis
The AXIS command normally erases the screen and displays a new set of axes. The conversion
between energy and channel number and the yield scale are determined from the currently ACTIVE
buffer (see PLOT above). If the ACTIVE buffer contains no valid spectra data, a warning message
indicating that the axes values are out of range may be issued.
COMPARE
Syntax: COMPare
The COMPARE command is another command designed to reduce typing. It is equivalent to PLOT NOW
LTYPE 1 OV THEORY LTYPE <old>. The ACTIVE buffer is plotted in the current line and symbol
types and the simulation buffer is overlaid as a solid line. The line type is returned to its previous
value.
BLOWUP
Syntax: BLowup <cursor marks> <factor>
The BLOWUP command allows you to expand the vertical scale for a portion of your data to see, for
example, a small impurity peak. The cursor marks a region to be expanded and an expansion factor
is read from the command line. Data from the current ACTIVE buffer is overlaid on the plot using
the current symbol or line type over only the identified region with the specified expansion factor.
The channel range may be selected using either the cursor or the keyboard (press <ESC> to escape
from cursor to keyboard input mode). The actual data in the ACTIVE buffer is not modified and
hence subsequent plots are not automatically expanded.
EXPAND
Syntax: EXpand <cursor marks>
EXPAND is a useful combination of two operations: a) use of the cursor to define a new region and
b) a replot of the ACTIVE buffer. Note that EXPAND redefines the plot region as in the REGION
command below and that only the ACTIVE buffer is redrawn. Other spectra on the current plot
will not be redrawn over the expanded range.
4p-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
QUIT
Syntax: QUIT or BYE
This command should be obvious (hopefully). All buffer and status information is lost when you exit,
as are any modifications to buffers which have not been saved. If a HCOPY, temporary MACRO
or SCRIPT file is active, they will be disposed of as appropriate (possibly with user input).
4p-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
PLOT SCALING AND AXES LAYOUT
PARMS
REGion
FOrcex
COunts
LInear
SQrt
LOg
NOrmaliz
RAw
LAbels
Display current plot parameters
Set the channel range
Force channel scale to be exactly as specified
Set the range of the YIELD axis
Specify linear mode for YIELD axis
Specify square root mode for YIELD axis
Specify Logarithmic mode for YIELD axis
Specify YIELD to be plotted in normalized units
Specify YIELD to be plotted as raw data
Set degree of labeling for axes
PARMS
Syntax: Parms
The PARMS commands displays some of the plotting and scaling information to the screen. See
Section D for additional information on the plot size and device information. The lower section
indicates the range of the channel data output, the scaling for the yield (Max Counts), type of yield
scale (LINEAR, SQRT or LOG), and the current linetype, symbol and npoint values.
¾
»
Plot device: AUTO
Size:
9.00 by
7.30
Offset:
0.50 by
0.00
Margin:
0.85 by
0.85
Hard copy not initialized
Shrink:
Pen:
Speed:
1.000
1 of max
18
Min-Max Channels:
100.0 600.0
Max Counts:
Scale is linear, normalized yield.
Linetype: 0
Symbol: 0
Npoints: 1
7
Autoscaled
Minor tick marks are disabled.
Current directory: C:\RUMP\EXAMPLES
Session SCRIPT file: r.cmd
½
¼
REGION
Syntax: REgion <lower-channel> <upper-channel>
Set the region of the lower axes in channel numbers. The region to be plotted is always specified
in terms of channels but plotting is actually performed in terms of energy. The specified channels
may be rounded off to close values to give nicer plot scales. See FORCEX and SGRAPH to disable the
roundoff and force the scales to cover a specified region.
FORCEX
Syntax: FOrcex [ON | off]
Normally, the channel numbers specified by the REGION command or by an EXPAND command are
“rounded out” to closest reasonable whole numbers. This roundoff feature can be disabled by setting
4p-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
FORCEX ON. Be sure though, when enabled, not to specify a zero length region. The extension of the
lower boundary of a REGION command to zero can also be disabled (or controlled) by setting the
ZFORCE variable using SGRAPH.
COUNTS
Syntax: COunts <max-yield-range>
The range for the YIELD axis is controlled by the COUNTS commands. The YIELD axis will always
begin at zero and extend to the specified maximum. If the COUNTS is specified as zero, RUMP will
perform autoranging of the axis so the entire plotted range of the ACTIVE buffer fits on screen. If
non-zero, the specified value is used without rounding. While the meaning of the numbers on the
yield axis depends on the mode of the axis (LINEAR, LOG, or SQRT), setting of COUNTS should
always be in terms of the maximum linear count. For example, in logarithmic mode 100,000 counts
for the upper limit is a COUNTS 10000 COUNTS 5. When switching between modes, if YIELD is
not in autoscale mode the current setting of COUNTS is “translated” to the the new mode. However,
COUNTS is translated when switching between normalized and raw mode; new values must be set
corresponding to the current setting.
LINEAR/LOG/SQRT
Syntax: LInear
Syntax: LOg
Syntax: SQrt
The LINEAR mode is the default mode for displaying the yield information. In this mode, peak
heights and areas appear visually correct and it is easy to estimate compositions or concentrations.
While the LINEAR is most common, the SQRT mode is statistically more accurate. In SQRT mode, the
value plotted is the square root of the number of counts in each channel. In this mode, noise due to
counting statistics is independent of the absolute yield magnitude and equal visual weight is given
to features of equal statistical significance. The LOG mode is seldom used in RBS but is useful for
spectra covering a wide dynamic range such as PIXE data. The common logarithm (base 10) of the
data is plotted and the lower range limit is fixed at -2 for normalized data and 0 for raw mode data.
RAW/NORMALIZE
Syntax: RAw
Syntax: NOrmaliz
The YIELD axis can be displayed as either the raw number of counts per channel or as a normalized
yield where experimental differences between data are eliminated by scaling. The commands RAW
and NORMAL switch between these two modes. In raw mode, the channel data is plotted exactly as
recorded by the Multi–Channel Analyzer (MCA). In normalized mode, the data is plotted based on
the normalization of
Y ield =
Counts ∗ Corr
Q ∗ dΩ ∗ ∆Echan
The units for normalization are beam dose Q in µCoulombs equivalents of He+ (measured charge for
He++ is divided by two), solid angles dΩ in milli–steradians, and the MCA channel width ∆Echan
4p-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
in keV. A fudge factor CORR allows for fine tuning of the beam charge to compensate for inaccuracies
during charge integration caused by inadequate secondary electron suppression.
In the normalized mode, yield curves should always be directly comparable between experiments if
the beam energy and scattering geometry are the same.
LABELS
Syntax: LABELS [ON | BRIEF | OFF]
The LABELS command sets the mode of axis labeling. On slow plotting terminals, its use can make
eliminate the time wasted putting up the coordinate labels on the screen. Alternatively, the labels
can be completely suppressed in a final output allowing a draftsperson (non–sexist) to label the plot
for publication. The default mode is on.
The three modes are:
ON
BRIEF
OFF
Full labels: the complete title of each axis is given, and each major tick
mark is labeled.
Partial labels: an abbreviated title of each axis is given, and the two end
major tick marks are labeled. This mode is recommended for routine use
on slow graphics devices as it is faster than the ON mode.
No labels: No text at all is drawn on the plot. This can be used if a draftsman is to complete the artwork.
In both the ON and BRIEF modes, labeling conforms to AIP standards for publication quality plots.
Minor tick marks are normally suppressed in publication plots and this is the default mode for
RUMP. Minor tick marks may be re–enabled using the SUBTICKS command.
4p-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
CONTROLLING PLOT LAYOUT AND LINETYPES
Most of the commands which control the plot layout and curve description (line type or symbol
type for curves) are essentially identical between GENPLOT and RUMP. The following table refers
to other sections of this manual where the corresponding commands are described. Commands
marked with † are implemented by the graphics support libraries and consequently are absolutely
identical to the GENPLOT equivalent. Other commands should behave in the same manner as
the GENPLOT documentation but are implemented by RUMP instead and may consequently show
subtle differences.
Section A — Device Control
CLS†
Clear the text screen
DEvice†
Select plotting device
SPeed†
Set the plotter pen speed
HCopy†
Save plot vectors – allows replay on hard copy device
Section B — Basic Plotting
AUtoids
Automatically use IDENT string as a legend
AUTOErase†
Set whether screen erased with PLOT
ERase†
Erase the screen or start a new page
IDs
Put the IDENT string of buffer in the legend
NPoints
Point plotting interval
TIMEStamp†
Put the date on the plot
Section D — Line Control
COLor†
Select the line color
LType
Select line type for subsequent drawing
LINEWidth†
Set line thickness on appropriate plotters
PEn†
Select the pen color
SYmbol
Select symbol used for plotting
VECsize†
Set the length of dashes in dashed lines
VISibili†
Set line visibility
Section E — Plot Appearance
CHARActer
Select character set
CHRset†
Select character set
SUBTIcks
Toggle subtick mark display
Section I — Labeling
ANNOTE†
Sub–process for annotating the plot
Section F — Size and Position
OFfset†
Controls plot offset
SHrink†
Scale entire plot to shrink
SIZe†
Set the paper size
MARGins†
Set the margins around the plot for labels
FLIPXY†
Flip the X and Y axes on the page
SUB Plot†
Adjust size/offset to create a plot within a plot
Section M — Miscellaneous
SGRAph†
Set various plot parameters
† Identical to GENPLOT command
4p-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
RUMP BUFFERS
BUFfers
REad
GET
RERead
SWALLOW
POintat
WRITE
REWrite
SAVE
WRASCII
EMpty
RECALcul
RELEASE
NEWall
Display current buffer status
Point at buffer with file or read RBS file into buffer 1
Point at buffer or read an RBS file into buffers
Force rereads current buffer into buffer 1
Load ASCII data into buffer as counts per channel
Point at a specific buffer by number
Writes current buffer to another file
Rewrites current buffer to a file with corrections
Rewrites current buffer to a file with corrections
Writes current buffer to an text file
Scrolls the data and leaves an empty buffer 1
Mark sample structure as modified to force recalculation
Release the ACTIVE buffer and scroll remaining up
Clear all buffers and zero all data
BUFFERS
Syntax: BUffers
Every PLOT, OVERLAY, or READ command either points to a spectrum in memory or reads a new file
into the temporary buffer space (see General Concepts at beginning of RUMP manual). Buffers
are referred to by number and the contents of the buffers can be determined using the BUFFERS
command. The BUFFERS command summarizes the current contents of each buffer. Special buffers
and any unused buffers are not listed by this command.
The BUFFERS command lists all non-empty files by buffer number. Following the buffer number are
two special flags described below. The last 20 characters of the entire pathname for the source file
are shown next followed by the identifier text for each buffer. The most recent buffer plotted or
otherwise acted upon is called the ACTIVE buffer. It is designated by the ‘*’ in the BUFFERS display
before the buffer number. You can explicitly make any buffer the ACTIVE buffer using the POINTAT
command. RUMP never points to the simulation buffer (0) unless you explicitly request so with the
POINTAT command.
Two other special markings used in the buffers listing indicate modifications to the buffer. The
‘@’ marking indicates files where the experimental parameters in the buffer have been modified
using commands such as MEV or CONV. Buffers marked with a ‘?’ indicate that the actual spectrum
data (counts per channel) in the buffer has been changed by a command such as the background
subtraction or the data smoothing. All WRITE commands will prompt for verification before writing
out buffers with modified data. No verification is necessary if only header information has been
modified.
¾
»
At your service! buf
* => Main
? => Dirty
=> Parameters changed
Main
1
c:\psmith\new\wb.rbs sput w, 300 sec in ar
Buffer 2 ? c:\psmith\new\wa.rbs sput w, 300 sec in n2
*Buffer 3
psmith\new\sputw.rbs sputtered w, as deposited
Buffer 4 @ psmith\new\qq 40.rbs WSi on Si in Ar for 5 minutes
Buffer 5
psmith\new\ii 40.rbs WSi on Si in N2
Buffer 6
ith\new\e1-w1-n2.rbs sample e1-w1, 300 sec in N2
Your wish?
½
4p-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
¼
Section P – RUMP
RUMP
READ
Syntax: REad <filename>
Synonym: GET
This command obtains a spectrum, from disk if necessary, and makes it the ACTIVE buffer. Either
a true filename, a buffer number, or one of the special names listed under the PLOT command may
be specified as the filename. If the filename already exists as one of the buffers, that buffer is simply
made active. Otherwise, READ scrolls the buffers creating a empty buffer 1 and reads the file into
buffer 1. Buffer 10 is lost in the process. The ACTIVE buffer is set to the buffer containing the file.
Each time a file is read, the filename and the ID of the file are echoed to the screen.
Wildcard filenames may also be specified to READ. In the case of wildcards, the process is repeated
for every file which matches the wildcard name. All RBS files could be read, for example, using
the command READ *.RBS. Each matching file is retrieved into a unique buffers. If more matches
occur than there are buffers, RUMP will stop reading once all the buffers have been filled by the
command. A warning message indicating that the maximum number have been read is displayed in
this event.
GET is the normal manner in which the ACTIVE buffer is changed. Specifying GET 3 or GET
aa 40.rbs will change the ACTIVE pointer to the appropriate buffer.
¾
»
I want a cookie!! /* Have an Oreo!
I want a cookie!! read \psmith\new\*.rbs
File: c:\psmith\new\aa 40.rbs
Id:
WSi on Si, control
File: c:\psmith\new\e-beam-i.rbs
Id:
e-beam w, as implanted
.........
File: c:\psmith\new\wb.rbs
Id:
sput w, 300 sec in ar
WARNING: Maximum number read - All buffers filled
Your wish? get aa 40
Yes master?
½
¼
REREAD
Syntax: RERead <filename>
Under normal conditions, RUMP will always return to the buffer already containing a given file if
it is requested again. Under some circumstances, such as after a failed background subtract, it is
necessary to bypass this and force RUMP to read the file off the disk. At other times, one may just
want to return to the original settings of the experimental parameters. REREAD performs this action
by changing the extension of the filename associated with the ACTIVE buffer to .OLD. The original
filename is then reread from disk into buffer 1. Note that the original buffer remains but has a new
name. The original buffer 10 is lost in the shuffle since a new file is added to the buffer stack. It is
difficult to reread a file if you originally gave the data file an .OLD extension. The ACTIVE buffer
points to the reread copy of the file after this command.
4p-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
¾
»
Next command: reread
/* ACTIVE was buffer 2
File: c:\psmith\new\wb.rbs
Id:
sput w, 300 sec in ar
Your wish? buf
* => Main
? => Dirty
=> Parameters changed
*Main
1
c:\psmith\new\wb.rbs sput w, 300 sec
Buffer 3
c:\psmith\new\wa.rbs sput w, 300 sec
Buffer 2
c:\psmith\new\wb.old sput w, 300 sec
Buffer 4
psmith\new\sputw.rbs sputtered w, as
You called?
½
in ar
in n2
in ar
deposited
¼
SWALLOW
Syntax: SWALLOW <channel data>
The SWALLOW command is primarily intended for macro files to load in non-RUMP format stored
ASCII channel data. It permits the reading of ASCII data directly into the counts array of the
ACTIVE buffer. Channel data is read from the command line (or the active macro) one element at
a time until a blank entry (or the default value) is entered. Multiple channels of data are allowed
on each line. The WRASCII command, which generates a macro file to reload data in a pure ASCII
format, uses the SWALLOW command. The following macro file will load in a spectrum segment using
the SWALLOW command. (Note the blank line used to terminate the swallow read.) The command
XEQ <file> would be used to actually load the segment.
¾
»
/* Open a blank buffer and start swallowing the data
empty swallow
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
2
29 223 485 786 1049
1373 1416 1504 1557 1567 1517 1539 1507 1553 1463 1516
1411 1478 1326 1417 1428 1375 1344 1306 1279 1238 1219
1246 1264 1192 1220 1212 1200 1166 1123 1142 1181 1137
1061 1065 1076 1042 1088 1110 1070 1086 1078 1017 1057
0
1231
1458
1289
1131
1062
/* After a blank line to terminate SWALLOW, set parameters
mev 3.02 charge 10 covers 4.95 1.6 theta 7 phi 9 omega 3.4
corr 1.0 fwhm 25 ident ’This is test swallow data’
½
See also: WRASCII
REWRITE
Syntax: REWrite
Synonym: SAVE
Rewrites current buffer to the current file with corrections. See Parameter Modifcation.
4p-14
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
¼
Section P – RUMP
RUMP
WRITE
Syntax: WRITE <filename>
Writes the current buffer to another file.
WRASCII
Syntax: WRASCII <filename>
Writes current buffer to a text file suitable for reading with SWALLOW.
See also: SWALLOW
POINTAT
Syntax: POintat <n>
POINTAT allows the ACTIVE pointer to be set to any buffer, including the simulation and temporary
buffers. Other than the requirement that it must point to a configured buffer, no check is made to
determine if the buffer is filled with valid data. POINTAT is the only command which will leave the
ACTIVE buffer pointing to the simulation or temporary buffer space.
EMPTY
Syntax: EMpty
EMPTY causes the current list of buffers to be scrolled with an empty buffer left as buffer 1. Buffer
10 is lost in the process. All parameters in buffer 1 are set to defaults, the data is set to all zero,
the number of points is to the maximum and the buffer is marked as ACTIVE. This command can
be used with the SWALLOW command below to read in ASCII data.
RECALCULATE
Syntax: RECALculate
Normally RUMP tracks the status of the theory buffer. It marks the buffer as being out of date
if either the sample structure is modified or if the experimental parameters are changed (such as
changing the ACTIVE buffer). However, it does not track modifications to the actual theory buffer
data (such as a BACKGROUND subtract) nor can it track modifications to sample parameters which
are linked to the function evaluator (such as in EQUATION USER). The RECALC command is a manual
override to the automatic feature and simply marks the theory buffer as being out of date. The next
reference to the theory buffer following this command will cause the simulation to be recalculated.
RELEASE
Syntax: RELease
Buffers can be intentionally released for general use by the RELEASE command. The data in the
buffer is forgotten and all parameters for the buffer are reset to default values. The remaining
buffers are unscrolled to fill in the space vacated by the released buffer. Releasing buffer 2 causes
buffer 3 to become 2, 4 to become 3 etc. It is not possible to retrieve the data in the buffer once it
is released. You must read the file back into memory directly. RELEASE is primarily used in macro
files to maintain control over which data files remain active.
NEWALL
4p-15
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
Syntax: NEWall
The NEWALL command “forgets” completely about the current buffers and resets all parameters in the
buffers to default values. It returns the buffer stack to the same state as when RUMP was initiated.
This command is commonly used with macros to clear all previous reads when it is necessary to
ensure the order of files in the buffers.
4p-16
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
LISTING AND MODIFYING SPECTRUM PARAMETERS
ACtive
BEAM
CHarge
CHOFF
CONVersi
CORrecti
CURRent
DATE
FILE
FWHM
GEOMetry
IDEntifi
MEV
OMEGA
PHI
PSI
THEta
List the parameters of the active buffer
Type of incident beam (He++ )
Measured beam dose in µC
Channel number of first data point
Channel to energy conversion constants
Minor fudge factor for normalization correction
Average beam current (pileup calculations)
Date of data collection
Spectrum file name
Detector resolution (keV)
Scattering geometry used
Description identifier of the spectrum
Beam energy
Detector solid angle
Supplement of the scattering angle
Angle of surface normal to detected beam
Sample tilt or angle of surface normal to incident beam
ACTIVE
Syntax: ACtive
Each buffer includes information on the experimental parameters used in the data collection process.
These parameters are also stored in the data files. The values for the parameters of the ACTIVE
buffer are listed to the screen using the ACTIVE command. This listing is organized so that related
parameters are listed together on the same line. The commands described below allow most of the
parameters to be modified.
¾
»
Ready if you are! buf
* => Main
? => Dirty
=> Parameters changed
Theory 0
temp.rbs
Simulation of Ni/Ni-Si/Si
*Main
1
rump\tests\examp.rbs Ni/NiSi/Si Annealed 90 min
Your wish? active
Filename:
c:\rump\tests\examp.rbs
Identifier: Ni/NiSi/Si Annealed 90 min
LTCT Text:
LT= 857 CT= 860
Date:
18-JUN-1985 12:33:48.48
Beam:
3.020 MeV
4He++
10.00 uCoul
8.0 nA
Geometry:
Cornell Theta:
7.0 Phi:
9.0 Psi:
0.0
MCA:
Econv: 4.950 1.600
First chan: 0.0
NPT: 1024
Detector:
FWHM: 35.0 keV
Omega: 3.400
Correction: 1.0041
Your wish?
½
¼
PARAMETER MODIFICATION
The following commands simply change the corresponding parameter in the ACTIVE buffer. The
use of each parameter within RUMP is listed in the notes below the table. In general, only commands
4p-17
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
which one should normally modify during a session have abbreviations. Commands which are, or
should be, solid experimental parameters require spelling out in full - this is to avoid later command
name conflicts.
Command
Parameter
Notes
Explanation
FILE
IDEntifi
DATE
MEV
CHarge
BEAM
CORrecti
GEOMetry
PHI
THEta
PSI
OMEGA
CONVersi
CHOFF
FWHM
CURRent
filename
’line of text’
’line of text’
MeV
µCoulombs
4He++
Value
CORNELL/IBM/GENERAL
degrees
degrees
degrees
msr
keV/ch keV(0)
channel
keV
nanoamps
4
2,3,7
1
1,2,3
1
2,3,6
2,3,6
2,3,6
2,3,6
1
1,5
5
3
3
File from whence it came
Description of buffer contents
Date of data collection
Incident beam energy
Integrated beam dose
Beam type (arbitrary)
Correction for beam dose
Scattering geometry
Supplement of scattering angle
Sample tilt angle (incident beam)
Sample exit angle (exit beam)
Detector solid angle
ADC channel to energy calibration
Channel # of first data point
Detector resolution
Beam current (for pileup)
1.
2.
3.
4.
5.
Used to normalize yield data
Parameters used by RBS analytical tools
Parameter used primarily by the simulation programs
The IDS command displays this text on the plot
The energy scale is determined by chan ∗ (kev/ch) + kev(0). CHOFF is channel number of
the first data point and is normally set to 0. Changing CHOFF shifts plot horizontally.
6. Scattering geometry — see description below.
7. Incident beam is specified as a specific isotope and charge state such as 4He++. Stopping
power data for the beam should have previously been loaded.
These commands change only parameters in the active buffer. The file remains unchanged until
a REWRITE command updates the information in the file. The REREAD command may be used to
restore the buffer to the state contained in the file.
SCATTERING GEOMETRY
A full description of the scattering geometry for RBS requires three angles, the scattering angle of
the particle, the entrance between the surface normal and the incident beam, and the exit angles
of the beam with respect to the surface normal. In the geometry GENERAL, these three angles are
independent and are set by the commands PHI, THETA and PSI respectively. Note, however, that
PHI is really the supplement of the scattering angle — direct backscattering is 0 degrees.
In many cases, the three angles are not completely independent. Given a single tilt axis on most
sample holders, only two of the angles need to be specified and the third can be determined from
knowledge of the geometry. Two “standard” geometries are defined, CORNELL and IBM. These are
purely historical designations having little to do anymore with the actual geometries at the two sites.
The angle PSI, again historically, is the derived quantity from THETA and PHI. The IBM geometry
refers to the scattering configuration where the incident beam, surface normal, and detected beam
are all coplanar. The exit angle PSI is set to PHI+THETA. In the CORNELL geometry, the tilt axis
lies in the plane defined by the incident and scattered beams, and the surface normal sweeps out a
perpendicular plane. The CORNELL geometry sets cos(psi) = cos(theta) ∗ cos(phi). If there are other
4p-18
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
common geometries in the world, there is only space for another 32,765 possibilities in the code —
get your request in early.
If the scattering geometry is set to GENERAL, all three angles must be defined and are used. Changing
the geometry to CORNELL or IBM will cause PSI to be ignored and its value may change.
4p-19
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
MANIPULATING AND MASSAGING DATA AND BUFFERS
ADD
BACKground
COPY
COMPRess
MOVE
DIVide
SMOoth
SUBTRact
Add two spectra
Background fit and subtraction
Copy one buffer to another
Compress channels to improve statistics
Exchange the data in two buffers
Calculate a χmin plot
Smooth the data
Subtract two spectra
MOVE
Syntax: MOve <source buffer #> <dest buffer #>
The MOVE command is really an exchange command. The source and destination buffers are exchanged, including all data and experimental parameters associated with the buffers. The ACTIVE
buffer remains pointing at the same data after this command; if either the source or destination
buffer was ACTIVE, the actual buffer number pointed to by ACTIVE will change. The buffers must
be specified by number for the MOVE command. In this command only, filenames are not allowed
but buffer -1 is accessible.
COPY
Syntax: COpy <source buffer> <dest buffer>
The COPY command directly copies all experimental parameters and data from the source buffer to
the destination buffer. After this command, both buffers are absolutely identical including name
and modification history. The original contents of the destination buffer are lost.
ADD
Syntax: ADd <source buffer> <dest buffer>
The ADD command works with a pair of buffers, adding the contents of the source buffer to the
destination buffer and saving the result in the destination buffer. The source and destination buffers
may be identified either by number or by the associated filename. ADD will attempt to read the file
into a buffer if it is not already in the buffer set. However, because of the buffers scrolling, specifying
a destination file which does not already exist in the buffer set may cause the wrong buffers to be
added. It is suggested that both files be read into buffers before executing the ADD command.
The result of the add is placed in the destination buffer. This buffer will be marked as dirty to
indicate that the data has been modified (? will be shown by the BUFFERS command). The ADD
command works slightly different depending on the setting of the RAW/NORMALIZE switch. In RAW
mode the add is performed literally — counts are counts, no questions asked. The charge of the
destination buffer is set to the sum of the charges of the source and and destination buffers.
In NORMALIZED mode, the addition is done as it appears visually on the graph. The charge and
correction factor of the destination buffer are not changed. The data is summed for the same energy
position (not same channel) with corrections for the width for the channels and for the beam current,
detector and correction factors. The resulting data is mapped onto the MCA structure of the original
destination buffer, retaining the CONV parameters.
4p-20
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
SUBTRACT
Syntax: SUBTRact <source buffer> <dest buffer>
The SUBTRACT command subtracts the data in the source buffer from the destination buffer and
places the results in the destination buffer. It is otherwise identical to the ADD command described
above and the same comments apply.
DIVIDE
Syntax: DIVide <source buffer> <dest buffer>
In the DIVIDE command, the contents of the destination buffer are divided channel by channel by
contents of the source buffer. Results are stored in the destination buffer which is marked as having
modified data. See notes in ADD for warnings on specifying filenames as buffers. This command is
commonly used to compute the ratio of a channeled spectrum to the reference random spectrum
and determine the minimum channeling yield χmin .
DIVIDE assumes that channel to energy conversion for the two spectra are identical, or identical
enough to be ignored. No check of the parameters is made. The data are divided on a channel
by channel basis after correcting for the starting channel number of each buffer. Anything divided
by zero is defined, as far as this command is concerned, to be zero. Only the region of overlap
between the two buffers is computed. In RAW mode, the absolute channel data are divided while the
NORMALIZE mode uses the scaled yield values. The correction factor, solid angle and charge of the
destination buffer are all set to unity following this command.
Independent of how the mode in which the division was performed, the result should always be
plotted in RAW mode since the normalized plots will be completely meaningless.
BACKGROUND
Syntax: BACKground <cursor entries> <order fit>
The BACKGROUND command attempts to extract an isolated peak from a large background by subtracting an estimate of the background from the data. Peaks extracted in this manner are then
often analyzed using the THICKNESS or INTEGRAL commands. The BACKGROUND is estimated by fitting a polynomial, of order <order fit>, through the spectral data on either side of the isolated
peak. (You must be able to identify regions from the background on both sides of the peak to use
this command.) Regions are normally entered using the cursor, but may also be entered from the
keyboard by pressing the <esc> key at the first cursor. Four channel values are requested and the
background fit will be done in the intervals between the lower two and upper two values.
A least squares polynomial fit is made to the data in these regions. The order of the polynomial
must not exceed 6. (Generally, anything above 2 is lying to yourself — if the data is not quadratic,
don’t try background subtract.) The polynomial fit is subtracted from the channel data over the
range of the fit, including the intervening channels. The polynomial fit and the resulting spectra
are then overlaid on the plot. This command modifies the data, so one normally copies the buffer of
interest into another buffer before using the BACKGROUND command.
The subtracted data is primarily suited to integrating. After a background subtract, the “gross”
integral results will give more reliable answers than the primitive background subtract used in the
“net” integration.
4p-21
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
COMPRESS
Syntax: COMPRess <nchan>
The statistical noise in a spectrum can be reduced by summing adjacent channels into a single
channel using the COMPRESS command. The resulting spectra has fewer data points, but each
channel is statistically less noisy. The alternative is to collect data for a longer period initially.
The parameter <nchan> is the number of channels which are to be combined in each step. Given
an <nchan> of 4, a spectrum with 1024 points will become a spectrum with 256 points. The energy
scales and the first channel number are modified to correspond to the compressed spectra. The
buffer is also marked as dirty to indicate modified data.
SMOOTH
Syntax: SMOoth [-SV | -CONV <ntimes> | -FFT <width>]
The smooths command reduces the noise in a spectra while attempting to retain statistically valid
features. There are several options available for smoothing:
SMOOTH
SMOOTH -SV
SMOOTH -CONV <ntimes>
SMOOTH -FFT <fwhm>
[-RANGE <cursor or entry>]
[-RANGE <cursor or entry>]
[-RANGE <cursor or entry>]
The three smoothing algorithms currently implemented are listed above, the Savitsy-Goulay smooth
(-SV), a convolution algorithm (-CONV) and an FFT smoothing algorithm (-FFT). If no algorithm
is selected, the Savitsy-Goulay algorithm will be used by default. The buffer is marked as dirty to
indicate modified data by this command.
The Savitsky–Goulay smooth is a simple 5 point smoothing algorithm. It works quickly and does a
surprisingly good job. It may be necessary to smooth several times to achieve the desired results.
Be sure to compare the smoothed spectra with the original before believing any results. The exact
formula is
−3 ∗ xn−2 + 12 ∗ xn−1 + 17 ∗ xn + 12 ∗ xn+1 − 3 ∗ xn+2
xn =
35
The convolution algorithm attempts to retain edges in the spectra while smoothing. This is a
iterative algorithm which convolutes and deconvolutes using the detector resolution on each iteration.
It will be executed the number of times specified by the <ntimes> value. Typical spectra require 5
iterations. Note that two smooths by this algorithm are not equivalent to one operation with twice
the number of iterations.
The FFT based smoothing algorithm is based loosely on the algorithm in Numerical Recipes, Press
et al., (Cambridge University Press, 1986). The degree of smoothing is controlled by the specified
<width>. The width is roughly the number of channels over which the data will be shared and should
be approximately equal to the detector resolution divided by the energy width of each channel.
Both the FFT and SV algorithms are implemented in a manner where the range of smoothing can
be limited to a subset of the entire buffer; the convolution however, always operates over the entire
spectra. The -RANGE option specifies a finite range, marked with cursors, over which the specified
smooth will be performed. Data outside the range will not be modified. This feature allows different
regions of the spectra to be smoothed to differing degrees.
PERT Warning: NEVER smooth data that PERT is to look at. The smooth functions give
pretty–looking lines for simplified viewing but are less than useless for quantitative work.
4p-22
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
P.S. If you are finding smooth extremely useful, you really should consider collecting data for a
longer period of time. SMOOTH should be used to direct further experiments, but results should not
be based on smoothed spectra. The COMPRESS command above is a statistically honest method of
improving the statistics in a spectrum.
RBS ANALYSIS
CALibrate
CURsor
ELement
INFo
INTegral
MATrix
THICkness
WHATisit
WIDth th
INTSET
DISPLAY
Calibrate CONV and MEV from spectra
Displays a cursor and returns energy/yield values
Indicates scattering energy for an element
Prints information about an element
Finds integral over a region
Plots energy and yield expected for a pure element
Calculates thickness from area integral
Identifies elements near a specified channel
Calculates thickness based on energy width
Sets integration modes for THICKNESS and INTEGRAL commands
Profiles the composition of the SIM sample structure
The commands in this section are designed for analysis of simple elemental RBS structures or for
identification of features within a spectrum. The command generally use surface or mean energy
scattering approximations. For more sophisticated analysis, the simulation capabilities described
later should be used.
Data for these commands is obtained from the ATOM3.DAT file containing atomic elemental information and stopping cross–section data. Scattering cross-sections are assumed to be purely Rutherford
and resonances are not treated by these commands. Thickness, as measured by RBS, is an areal
density rather than a distance. Conversion from the areal density of atoms/cm2 to thickness is
performed using the standard atomic density of the element. Corrections for differing densities must
be handled manually.
Many of these commands request input of marker positions from the cursor. At any point, the cursor
input mode can be escaped by pressing the <esc> key and input will be taken from the keyboard
instead. From the graph, the actual energy corresponding to the upper scale is obtained. However,
when responding to a cursor request by typing, channel numbers should be specified. These are
translated to the equivalent energy using the CONV parameters of the ACTIVE buffer. Inside macro
files, it may be necessary to use ENCURSOR NO to completely disable the cursor modes and allow
channel numbers to passed through the command line.
CURSOR
Syntax: CURsor
The CURSOR command displays a crosshair or hardware cursor on graphics so equipped. The coordinates of the crosshair are returned when any key or button is pressed and are listed to the screen
as channel number, energy and yield (or counts if in raw mode). If the key pressed was a 0 or <sp>,
the cursor mode is retained for another value. On any other key, the cursor mode exist and the
variables XCUR, YCUR, ECUR, and CCUR are linked to the resulting channel, yield, energy (in MeV)
and character pressed.
The energy value returned by CURSOR corresponds to the energy scale on the graph. However, the
channel number shown corresponds to the channel in the ACTIVE buffer which has the corresponding
energy. This may differ from the lower channel scale on the axes if CONV is different.
Ex: Channel:
338.4 Energy:
2.840 MeV Yield:
28.1132 /uC/keV/msr
4p-23
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
INFO
Syntax: INFo <element>
The INFO command prints a collection of information about the specified element, including the
isotopic makeup and scattering/stopping parameters. The scattering geometry for cross section and
stopping power evaluations is taken from the ACTIVE buffer. The first line after the parameters
gives the kinematic scattering factor and the channel and energy for scattering from an element on
the surface. The matrix scattering height is the yield expected from the pure element as a thick film
on the surface. The scattering cross section is evaluated at the incident energy and a scattering angle
of 180-phi. The stopping cross section [e] includes corrections for the incident and exit paths. The
stopping factor [S] is determined using the bulk elemental density.
¾
»
Your wish? info si
----------------------------------------------------Si Z: 14 Mass: 28.09 Density: 0.4978E+23 at/cc ( 2.32 g/cc)
Parameters: Energy 3.000 MeV
keV/channel 4.950
Theta 7.00
Phi
keV(0)
1.600
9.00
Surface Scattering:
0.5654 at 1.696 MeV (Channel: 342.3)
Matrix scattering height:
9.05 Counts/uC/keV/msr
Scattering cross section:
0.110 (1E-24 cm2/ster)
Stopping Factors: [e] = 76.3 (1E-15 eV-cm2)
[S] = 38.0 eV/A
Isotopes:
Mass:
Mass:
Mass:
29.97
28.98
27.98
Abundance: 0.03090
Abundance: 0.04700
Abundance: 0.92210
Ready if you are!
½
¼
ELEMENT
Syntax: ELement <element>
The ELEMENT command is used to identify on the graph the position where an element on the surface
would scatter. The kinematic factor, energy and channel for scattering are printed to the terminal.
If a graphic device is active, a marker is drawn on the channel axis at the scattering energy and is
labeled with the element. If an element name only is specified, the average atomic weight is used.
Isotopes may be specified and will be marked accordingly.
¾
»
Feed me! element si
el 28si
Si Z=14 Mass= 28.086 K(He)=0.5654
Si Z=14 Mass= 27.977 K(He)=0.5641
At your service!
½
Energy= 1.696 MeV
Energy= 1.692 MeV
Channel= 342.321
Channel= 341.550
¼
4p-24
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
WHATISIT
Syntax: WHATisit <cursor entry>
WHATISIT is, in one sense, the inverse of the ELEMENT command. Whereas ELEMENT is to mark a
known elemental point, WHATISIT is used to mark 5 elements around a given energy position. The
five closest elements to the marked point are displayed to the terminal and are drawn on the graph.
These markers thus indicate at least the range of atomic numbers corresponding to an unknown
peak. It is important to keep in mind that (1) elements may not be on the surface and (2) that
mass resolution is poor at high Z and the actual element may not be listed at all.
¾
»
Ready if you are! whatisit
Selected
Mg Mass
Al Mass
Si Mass
P Mass
S Mass
energy
24.3
27.0
28.1
31.0
32.1
was 1.694 MeV
expected at 1.550
expected at 1.656
expected at 1.696
expected at 1.790
expected at 1.822
MeV
MeV
MeV
MeV
MeV
(Channel
(Channel
(Channel
(Channel
(Channel
313)
334)
342)
361)
368)
MeV
MeV
MeV
MeV
MeV
(Channel
(Channel
(Channel
(Channel
(Channel
558)
558)
559)
560)
560)
Ready if you are! whatisit
Selected energy
Ir Mass 192.2
Pt Mass 195.1
Au Mass 197.0
Hg Mass 200.6
Tl Mass 204.4
was 2.769 MeV
expected at 2.762
expected at 2.765
expected at 2.767
expected at 2.771
expected at 2.775
At your service!
½
¼
MATRIX
Syntax: MATrix <element>
A surface thick film of any pure element has a well defined yield height determined by the stopping
power, cross section and channel energy width. This height is referred to as the matrix height
and is plotted and labeled on the graph using the MATRIX command. The height and edge for the
specified element are plotted as a cross on the graph with the element name (or isotope) just above.
The height of a substrate edge, such as Si, can be used to verify the normalization condition. The
scattering height and position are also displayed on the terminal. Matrix height is determined by
Y ield =
σ ∗ dΩ ∗ q ∗ ∆Echan
[²]
¾
»
Feed me! mat si
Si expected at 1.696 MeV ( 342.3) and height
At your service!
½
9.052
¼
4p-25
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
CALIBRATE
Syntax: CALibrate <cursor pt> <cursor pt> <el> <el> <energy> <cursor pt>
The settings of the channel–to–energy conversion and the absolute energy of the accelerator should
be well known quantities but are often not controlled well enough for an absolute setting. The CALIBRATE command determines the values for CONV and MEV of the ACTIVE buffer from the positions
of two surface element peaks and one absolute energy point. At Cornell, a 230 Th alpha source is
mounted near the detector to provide the absolute energy calibration in all spectra. If the beam
energy is accurately known, changes to the MEV setting can be skipped by setting the energy of the
known marker to zero. Only values for CONV will be modified in this case.
When CALIBRATE is executed, the cursor is enabled and two surface peaks should be identified,
either by a thin peak or the half height of a ledge. The elements corresponding to these points are
then entered (use the specific isotope for better calibration especially if a low Z element is one of
the calibration points). The absolute energy of a known marker (in keV) is then requested. The
default value is the 4684 keV major peak from 230 Th decay. If any positive non-zero marker energy
is input, the cursor is again displayed to obtain the position of the marker. To improve accuracy,
the position of the marker should have previously been determined using the REGION and CURSOR
commands. Escape out of cursor entry mode (using <esc>) and enter the absolute number from the
keyboard.
The command changes the MEV and CONV values of the current buffer to correspond to calculated
values. The accuracy should be tested using a third element peak and the ELEMENT command.
The following example calibrates using buffer 3 and then transfers the calibration to real spectra in
buffers 1 and 2.
¾
»
Your wish?
/* We first get the buffer and calibrate
Up periscope! /* The channel for 230Th is escaped and typed
Feed me!
get 3 calibrate
Identify two surface elements.
Element? (no change) ni si
Marker energy, keV (4684 for 230Th) ? 4684
Marker position? (pressed <esc> to abort cursor)
Marker position? 930
Energy= 3.223 MeV
Conversion:
4.7825 keV/ch
3.24 keV(0)
Feed me! for %f in (1 2) do get %f mev 3.223 econv 4.7825 3.24
Beam me up Scottie!
½
¼
INTEGRAL/THICKNESS
Syntax: INTegral <cursor low> <cursor high>
Syntax: THICkness <cursor low> <cursor high> <element>
Syntax: THICkness <cursor low> <cursor high> <element> <alpha val>
The INTEGRAL command determines the total integrated number of counts between two markers in
the ACTIVE buffer, either on a RAW or NORMALIZED basis. In the raw mode, the absolute counts in
each channel are summed. In normalized mode, this sum is then scaled by the charge, detector solid
4p-26
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
angle and correction factor (Q, OMEGA and CORR) to standard conditions. Two integrals, the “gross”
and the “net”, are reported. The gross integral is the complete sum while the net integral includes
only counts which lie above a straight line drawn between the region edges. The net integral thus
performs the simplest of background subtractions. However, the BACKGROUND command should be
used to extract the peak first if it lies on any substantial background signal.
There are two ways in which the INTEGRAL command can handle the channels at either end of
the integration region. The INTSET command is used to set the mode. In the default mode, the
boundaries of the integration are rounded to integers before summing the data (the rounding occurs
toward the center of the region). INTSET can switch the integration mode so that the partial channels
at the boundaries are also included in the integration. See the INTSET command for more details.
The THICKNESS command first does an INTEGRAL and then translates the measured total yield into
an equivalent thickness (atoms/cm2 ) of an element. To first order, the total number of scattering
centers (atoms) is related directly to the integrated yield through the beam dose and detector solid
dσ
angle, Y ≈ dΩ
∗ dΩ ∗ Q ∗ Nt / cos θin . Hence, the thickness determined by integration of a peak is
an absolute measurement assuming that dΩ and Q are known accurately. Since these quantities
are usually known only to within about 5%, the fudge factor CORR also enters into the equation.
Within these constraints, THICKNESS provides an absolute measurement of the number of atoms/cm2
present. This areal density is presented as a thickness using the bulk elemental density. Thickness
values are reported for both the gross and net integrals.
The INTSET command also controls the manner in which the thickness is calculated from the integral.
The default is to use the simple surface scattering approximation. Increasing accuracy is achieved by
allowing THICKNESS to estimate the correction required because the scattering cross section increases
as the particle slows down in the layer. The greatest accuracy is obtained if the user provides the
“alpha” energy loss ratio factor (after setting the mode with INTSET Q). Even in the compensated
modes, the thicknesses are valid primarily for pure elemental layers and SIM should be used for more
complex structures. See the INTSET command for additional details on compensated thickness.
The variables GROSS$, NET$, and THICK$ are linked by this command. GROSS$ and NET$ are real
numbers contain the corresponding integrals. THICK$ is a four element array containing the gross
and net thicknesses in Angstroms (entries 1 and 2) and areal thickness in atoms/cm2 in entries 3
and 4.
4p-27
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
¾
»
Your wish? thick ni
Identify region with cursor. Press any key.
Discrete integration on Buffer 1,
Ni/NiSi/Si Annealed 90 min
Region: 385.0 to 482.0 Gross:
5196.78 Net:
5164.94 (#/uC/msr)
Ni surface approximation with micro-density of 8.90 g/cc yields
(Gross) 0.1847E+19 Atoms/cm**2 ( 2023.4 Angstroms)
( Net ) 0.1835E+19 Atoms/cm**2 ( 2011.0 Angstroms)
Yes dear? intset interp thick ni intset round
Identify region with cursor. Press any key.
Interpolated integration on Buffer 1,
Ni/NiSi/Si Annealed 90 min
Region: 385.4 to 482.3 Gross:
5196.18 Net:
5158.00 (#/uC/msr)
Ni surface approximation with micro-density of 8.90 g/cc yields
(Gross) 0.1846E+19 Atoms/cm**2 ( 2023.2 Angstroms)
( Net ) 0.1833E+19 Atoms/cm**2 ( 2008.3 Angstroms)
At your service! intset estimate thick ni
Identify region with cursor. Press any key.
Discrete integration on Buffer 1,
Ni/NiSi/Si Annealed 90 min
Region: 385.0 to 482.0 Gross:
5196.78 Net:
5164.94 (#/uC/msr)
Ni surface approximation with micro-density of 8.90 g/cc yields
(Gross) 0.1847E+19 Atoms/cm**2 ( 2023.4 Angstroms)
( Net ) 0.1835E+19 Atoms/cm**2 ( 2011.0 Angstroms)
Compensated calculation (refer to Chu et.al. page 65)
For fixed alpha =
1.13703
(surface approx. for Ni)
(Gross) 0.1766E+19 Atoms/cm**2 ( 1934.8 Angstroms)
( Net ) 0.1755E+19 Atoms/cm**2 ( 1923.3 Angstroms)
Your wish?
½
¼
WIDTH THICK
Syntax: WIDth th <cursor low> <cursor high> <element>
As an alternate to THICKNESS, the width of a layer in energy can be related to its thickness through
the stopping factor [S]. The WIDTH THICK command determines the thickness based on a mean
energy approximation for the stopping factor. (See Chu et al. for a discussion of the mean energy
approximation.) WIDTH THICK is appropriate for almost pure elemental layers whose widths are
substantially greater than the detector resolution and form well defined flat top ledges. The cursor
is used to mark the half–height points on either side of the layer. The compensated stopping factors
and the calculated thickness are reported. The accuracy of this calculation is constrained by the
accuracy of the stopping power tables, usually about 5-10%. The final thickness (Å) and area
thickness are linked as the array THICK$.
4p-28
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
¾
»
Feed me! width th
Place cursor at half-height points.
Element? (no change) Ni
Stopping Factors:
[e] = 112.9 (1E-15 eV-cm2)
Width: 254.5 keV
0.2254E+19 Atoms/cm**2
Feed me! eval thick$(2)
Value:
2.254E+18
Yes Master?
½
[S] = 103.0 eV/A
2470.3 Angstroms
¼
INTSET
Syntax: INTSET [Round|Interp|Surf|Est|Query|?]
The INTSET command sets the internal mode used for calculating the INTEGRAL or the THICKNESS
commands. Integrals are evaluated in either of two modes. In the roundoff mode, channels are
rounded toward the center of the integration region. In the interpolate mode, each channel is
treated as having a triangular basis extending one channel to either side of center. The edges of
the region need not be integer channels and the integral will include an appropriate fraction of the
nearby edge channels. The default mode is rounding.
Three modes may be set for determining the thickness of an element over the region, surface,
estimate and query. The default is the surface approximation and no correction for the increase
of the cross section with depth is attempted. The other modes estimate and query are forms of
the mean energy approximation. The energy of the particle at the time of scattering is estimated
from the detected energy. Energy loss on the ingoing path is assumed to be a constant fraction of
the total energy loss and hence the scattering energy can be obtained from the overall energy loss.
In terms of stopping powers,
¡ dE ¢
Escat = E0 −
dx E0
cosΘin
∗·
∆E
¸
( dE
( dE
)
dx E
dx )
0
0
+ cos θKE
K cos θin
out
The parameter alpha is defined by the quantity
¡ dE ¢
cos θin
dx
alpha =
∗ ¡ dE ¢KE0
cos θout
dx E
0
and is sufficient to perform the above calculations. In the estimate mode, the thickness integrals
are performed correcting for cross section changes using this formulation of alpha. For repeated
measurements on a given sample type, alpha can be calibrated accurately and the query mode
allows for direct entry of a user value of alpha. Given accurate user values, THICKNESS will correctly
evaluate the areal density of elements even in compounds. See Chu et al. equations 3.21ff for
additional details.
The ? command provides a listing and short description of these modes as well as identifying which
modes are currently active.
4p-29
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
¾
»
Feed me! intset
[Round|Interp|Surf|Est|Query|?] ?
* current mode - Single letter command - Explanation of mode
* R - Integrals are rounded to nearest channel
I - Integrals are interpolated between channels
* S - Thickness calculation based on surface approximation only
E - Compensated thickness calculation with an estimated alpha
Q - Compensated thickness calculation with query for alpha
At your service! intset I intset E intset ?
* current mode - Single letter command - Explanation of mode
R - Integrals are rounded to nearest channel
* I - Integrals are interpolated between channels
S - Thickness calculation based on surface approximation only
* E - Compensated thickness calculation with an estimated alpha
Q - Compensated thickness calculation with query for alpha
At your service!
½
¼
PROFILE
Syntax: PROfile <element> <cursor region> <filename>
The PROFILE command (within RUMP — not SIM) estimaes the concentration versus depth for a
single element corresponding over a given region in the ACTIVE spectrum — usually an isolate peak.
The stopping factors which determine the non–linear conversion from energy to depth are calculated
using the current sample structure defined in the SIM module. A reasonable sample structure must
be defined prior to requesting PROFILE. For example, to profile As as a dopant in Si, the sample
structure need be defined only as pure Si since the As will not strongly affect the stopping powers.
Concentrations are reported in atomic fraction and the depth is measured in the only units appropriate to RBS, 1015 at/cm2 . PROFILE makes no attempt to deconvolute detector resolution, straggling,
isotope effects, or overlapping elements. Hence, it is most useful for heavy, isolated impurity peaks
or monoisotopic elements.
The concentration versus depth is plotted if a graphics device is available. After plotting, a filename
is requested and the data may be written as ASCII data pairs to the file. Stored data can be
subsequently massaged using GENPLOT or other analysis programs. If no filename (or a /) is
given, the data will not be stored. The last command in the example below might be used in a
macro file for automatically profiling Ni over a given range without saving the data. The ENCURSOR
command allows the range (in channel numbers) to be specified from the command line instead of
by the cursor (equivalent to escaping out of the cursor using <esc>).
4p-30
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
RUMP
¾
»
Yes Master? read \rump\examp
File: c:\rump\examp.rbs
Id:
Ni/NiSi/Si Annealed 90 min 295C
Up periscope! sim get \rump\examp return
Beam me up Scottie! profile
Element to be profiled? (abort) ni
Use cursor to define region to be profiled.
File name (if any) of saved data: niprof.dat
Your wish? encursor no profile ni 300 500 / encursor yes
Hey, man, what next?
½
¼
Profile will fail if no simulation sample has been defined. Also, the profile will fail with the message Simulation goes to zero in region of interest if you request a profile over a region
completely invalid for the element. Invalid experimental parameters will also generate an error.
Warnings are given if the profile is subject to some isotope effect or if absurd answers would be
expected because of the isotopic distribution (profiling B for example).
4p-31
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Section P – RUMP
OTHER COMMANDS
The following system utility commands are identical between GENPLOT and RUMP and are described in other sections of the manual as specified in the table below.
Section J – Function Evaluation
ALLOCate
Allocate a variable
DEALLocate
Deallocate a variable
DEClare
Allocate and set a STRING variable
DEFine
Define a user function
EValuate
Evaluate a general math expression
LET
Set a variable to a constant or expression
LISTVar
List all the defined variables
SAVEVars
Save variables to disk file
SETVar
Allocate and set a real variable
Section K – Command Macros
BASE MACRO
Specify a default macro directory
ECHO
Toggle the command display while a macro is running
FOR
Repeat command loop
MACRO
Collect commands in a macro file
GOTO
Continue execution at the given label
IF
Conditional execution of commands
QUERY
Prompt the user for input from the macro
SAVE MACRO
Save the commands from MACRO in a file
SLEEP
Delay for a given length of time
WAIT
Wait for user action before continuing
XEQ
Execute a macro file
CMDLIN
Execute the next token as a series of commands
&GETARG
Get the next argument from the macro command line
&QUERY
Get the next token from the user
&YESNO
Get a yes/no answer from the user
&ENCODE
Real number to string encoding
Section L — Operating System
CD
Change directory
DIr
Display directory
<disk>:
Change default disk
DOS
Send a command to the system to be executed
MEMory
Display unused RAM space
PAUSE
Temporarily pause GENPLOT and bring in the system
TYpe
Type a file on the screen
WHEre
Gives the pathname of the current directory
Section N — Editing
EMacs
Built in editor
4p-32
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
APPENDICES
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendices
APPENDIX A: TROUBLESHOOTING
HELP!
We hope to provide some quality customer service. The manual is the first step in that service. If
you have problems, first consult the section of the manual that deals with the commands or topics
that are being used. This frequently answers common questions. If you are unable to solve the
problem, please follow these steps:
1. Check the Installation section, Errors Appendix, Common Questions (below) and the Run-time
support appendix to see if any special procedures apply to your situation.
2. Check for a READ.ME file on the installation disk. (Use the DOS ’type’ command or your
favorite editor.)
3. If you still can’t solve the problem please see the support policy at the beginning of the manual.
If you qualify, try calling our support line. In any event, you can always mail us a letter or
send us electronic mail concerning your problem.
4. Call our support line at 607-277-4913 Registered Users Only between the hours of 9:00am
and 5:00pm (Eastern time). We are a small company. You may get our answering service and
we will have to call you back but before calling, please have the following information available.
1. Product Serial Number Very important – do not confuse with the revision number. The
serial number is a 12 character string that appears near the bottom of the first copyright
screen. Use the PAUSE key to halt the system and record this number. This serial number
identifies the minor revision level of your software.
2. As much information as possible describing the problem including specific steps required
to reproduce it. If any error messages occur, record the exact text and check with listing
in Appendix E.
3. DOS type and version (MS-DOS 3.00, PC-DOS 4.01). Use the VER command from the
DOS prompt.
4. Namess of any TSR (terminate and stay resident) programs which are concurrently running.
5. Access to your AUTOEXEC.BAT file.
6. Access to your CONFIG.SYS file.
7. Names and models of your computer, display adapter and/or printer if appropriate.
INSTALLATION TROUBLESHOOTING
See page 1–7 at the beginning of the manual.
A-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendices
COMMON QUESTIONS AND ANSWERS
Below is a list of some commonly asked questions and their answers. Please look through these when
you have problems.
? What is error 4001?
?
?
.
During initialization, GENPLOT tried, but failed, to find a math coprocessor (80x87 chip) in your machine. If you don’t have one, the standard
version of GENPLOT cannot run. If you really do have a coprocessor, check
your hardware configuration (those dusty old manuals that came with your
computer) to see if it is installed properly. If you do not have a coprocessor, a version of GENPLOT which emulates the math package can be
obtained by calling the CGS offices. Be aware that there is a substantial
speed penalty for running without the coprocessor.
.
(NOTE: On some early AT&T 6300’s, the BIOS fails to tell programs that
a processor exists; the fixbit program in \GENPLOT\UTIL will set the offending bit and allow GENPLOT to run.)
Although I have a 120 Mb hard disk, and 4 Mb of RAM installed in my
maching, GENPLOT stills runs out of memory when archiving multiple
curves. Why does GENPLOT not use the additional memory?
.
The problem is basic to the architecture of the 80x86 microprocessor chips.
DOS runs in what is called the real memory mode of the processors. In
this mode, there is only 640 kB of memory available for programs (another
384 kB used by ROM brings the total to 1 MB). Any additional RAM
that you install goes into either expanded or extended memory which is
not directly accessible to DOS programs. Although numerous kludges exist
for accessing this memory (LIMM, EEMS, disk swapping etc.), they are
nonetheless kludges and difficult to work with from FORTRAN. Because
we believe DOS’s life to be limited, we are not actively pursuing any of
these kludges.
.
That’s the bad news. The good news is that OS/2 is just around the corner
and solves all the memory problems we have in DOS. GENPLOT for OS/2
is currently under development and coming soon to your favorite theater.
How do I get GENPLOT to allow for more than 2048 points?
.
Buffers are allocated during initialization time using a command line option.
To allocate space for 5000 points use:
.
>>
GENPLOT -buffer 5000
A-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendices
Common Questions and Answers
?
Are there default file suffixes?
.
Of course, I hate typing.
.DAT
.MAC
.HCP
?
Can I read data files with multiple data columns?
.
?
This is actually straightforward. All of the fitting routines (within the FIT
subcommand), defines a function called FIT(X) The plot option PLOT -FIT
will automatically plot the function FIT(X) — exactly what you wanted to
do. Generally, you will want to use OV -FIT -LT 1 to overlay the fit as a
solid line.
How can I print out or change the value of an individual point?
.
?
Again, the -COLUMN option of the READ command will allow you to read a
single column. By default, column 0 is the point number within the X,Y
array. The command READ -COLUMN 0 1 will put the point number into X
and column 1 of the file into Y array. If you use this mode with the -APPEND
option, the actual point number in the array will be assigned to X, not the
position of the point within the data file. This difference only occurs with
the -APPEND option, otherwise the point number and the position within
the file are equivalent.
Once I have done a data fit, how can I plot that fit?
.
?
Multiple columns within data files are supported using either the -COLUMN
option or the -LIST option of read. The -COLUMN <xcol> <ycol> option
can be used to read any 2 columns of the file into the X and Y coordinates.
The -LIST option allows up to 40 columns to be read into a corresponding
list of arrays. Note however that the arrays must have been previously
allocated using ALLOC.
Can I read only one column of data into the Y variable and make the X
data be the point number?
.
?
Data files
Macro files
Hard Copy files
The command EVAL X(17) or EVAL Y(17) will print a single point out of
the data set. Using FOR REPEAT 37 TIMES DO EVAL X(%C) EVAL Y(%C)
will print out the first 37 elements of the array, unfortunately one per line.
Any single element may be modified using the LET command. LET X(17)
= 3.274*1.22.
Can I multiply one curve by another?
.
Since any archived curve is really a set of arrays, the function evaluator can
multiply curves in any manner you choose. The problem, of course, is that
everyone wants to multiply curves in a different manner, Y and X or just
Y or aligned X values followed by Y multiplied etc. etc. etc.
Consider multiplying the Y values of two curves where you want the X
points aligned. Not wanting to extrapolate data, we will confine both data
sets to the common region, assumed to have some overlap.
A-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendices
Common Questions and Answers
¾
»
GENPLOT:
.......
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
read file1 archive c1 read file2 archive c2
(some information text)
setv x1 = max(@min(c1:x),@min(c2:x))
/* Lower bound to use
setv x2 = min(@max(c1:x),@max(c2:x))
/* Upper bound to use
setv minpt = min(c1:npt,c2:npt)
retrieve c1 fixgrid -range x1 x2 -points minpt archive c1
retrieve c2 fixgrid -range x1 x2 -points minpt archive c2
let y = c1:y*c2:y
/* Done, X already there
¼
Of course, if you have the data sets aligned in X already, only the last line
of the commands is needed to multiply two archived curves.
?
When Annotating a graph, it would be easier for me to place labels based
on the axes coordinates rather than to use inches. Can this be done?
.
?
I set a label for the top axis but nothing came out, why?
.
?
Nothing is drawn on the top axis unless it is turned on. Unfortunately, it is
impossible to turn off the tick labels and still have the title come out. Use
ANNOTE to put a title up there if you don’t want the axis to be on. If you
really wanted the entire axis on, use the XTOP ON command.
When the text for TITLE and ANNOTATE are placed on the same
line as the command, GENPLOT reads only a single word as the label.
However, if the text is given to the prompt for text in the 2-line command
format, the entire line is used. Why?
.
?
The ANNOTE command COORMODE {user | inches} <xoff> <yoff> does
exactly that. In user mode, the same scales which would be used in an
OVERLAY command of GENPLOT will be used for specifying the location of
titles and lines. The <xoff> and <yoff> allow for an ADDITIONAL offset
to be added to the position. Normally, the offsets are set to 0,0. However,
offsets can be useful if you make macros which draw strange creatures (like
resistors) at a starting position 0,0 and then put them anywhere on the plot
using the offset capability.
This is fundamental to the way the command processor itself works. For
details, read the Appendix in the manual to understand exactly how GENPLOT reads command lines. In short, the TITLE and ANNOTE commands
first request a single token from the command line. This means a single
word unless the string is enclosed in quotes. Both commands, however,
know that a string is wanted when it prompts for information, hence the
entire string will used instead of a single token and no quotes are necessary
(or allowed).
If the size is specified as 5 by 5 inches for a plot, the actual box for the
plot ends up being only 3.3 by 3.2 inches. Why?
.
It is important to understand the interaction between size and margins in
the plot layout. The size is the total overall size of the plot. Margins are
A-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendices
Common Questions and Answers
specified on either side to allow for the labels to fit within the plot area.
The default margins are 0.85 in X and 0.75 in Y, with margins on both sides
of the plot. Hence, the area left for the interior of the plot is 5−2∗.85 = 3.3
in X and 5 − 2 ∗ .75 = 3.5 in Y. If you need to create a box of a specified
size, set MARGINS to be (0,0) and offset the plot on the screen to make
sure the labels fit.
?
Sometimes when I turn on the right axis the axis label disappears or gets
chopped off and sometimes it does not.
.
The axis label location is adjusted so that it will not run into the longest
tick mark label. If your ticks are labeled from 0.0 to 9.0 then the axis label
will be about 0.5 inches from the axis line. If your data causes the ticks
to be labeled from say, -10.0 to -100.0, GENPLOT will move the axis label
out to allow for the extra digits and the minus sign. This will cause the
label to be off the screen. You can use the OFFSET and MARGIN commands
to fix this.
A-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX D: DEVICE SUPPORT
PURPOSE
This appendix discusses interfacing external plotting devices with GENPLOT. Sections devoted to
each specific device driver follow a general discussion of how GENPLOT controls devices.
GENPLOT currently supports both hard copy devices such as pen plotters and laser printers, and
screen devices such as Tektronix 4015 terminals. This appendix discusses the information contained
in the user modifiable DEVICES.DAT file. This file contains the specifications for all devices which
GENPLOT will be able to access, associating a logical device name used by GENPLOT (see the
DEVICE command) with the actual plotting device characteristics. Sufficient detail is provided to
permit the user to modify the DEVICES.DAT file adding new devices and/or modifying the current
devices to match the hardware configuration at a particular site. While the file may be freely
modified, we recommend that a backup copy always be maintained in the event your editor corrupts
the file irretrievably. GENPLOT must be able to find and read DEVICES.DAT prior to any plotting.
Disclaimer
Because of the wide variety of plotting devices, the myriad of methods available for connecting them
to a PC, and the large number of ill–behaved software packages on the market (including possibly
GENPLOT), we cannot guarantee that any particular device will be successfully interfaced with
GENPLOT. The specific devices listed below have been used successfully on IBM PC–ATs running
only GENPLOT; successful implementation on clones is likely but not guaranteed. See the section
on software incompatibilities if any other commercial package is to share a plotting device.
Definitions:
Device Driver
I/O channel
ASYNC
XON/XOFF
ENQ/ACK
DTR/CTS
GPIB
A computer routine which takes general plotting commands and generates the particular sequence of of commands necessary to “drive” or
control a hardware device.
A routine which routes or “channels” the commands from the device
driver to the actual hardware plotting device.
Asynchronous communication. Also referred to as RS–232C. A Method
of transferring information between a computer and a device over a serial line. On the PC, these are COM1 and COM2.
A method of “handshaking” or controling the communications between
two devices. When a device can’t take anymore data it sends an XOFF
(control S) which tells the sending device to quit transmitting and later
an XON (control Q) reenables transmission.
Enquire/Acknowledge handshaking. Alternative to XON/XOFF where
the two devices utilize an “are you ready”/“yes I am ready” pair of signals (usually ASCII codes 05 and 06).
Data Terminal Ready/Clear to Send. A third alternative to XON/XOFF
handshaking using hardware wires for ready/not ready.
General Purpose Interface Bus - Also known as IEEE-488 or HPIB. A
parallel bus connecting devices (usually instruments) together.
D-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
CGA
Color Graphics Adapter. Early graphics board providing low resolution
(320x200) graphics.
Enhanced Graphics Adapter. Graphics board in computer providing
640x350 resolution color on an ECD or monochrome on an MD.
Enhanced Color Display. High resolution monitor used with an EGA to
provide 16 color high resolution graphics.
Hercules Graphics Adapters. Non-IBM alternative graphics hardware
providing high resolution graphics to a monochrome display.
Monochrome Display.
Monochrome Display Adapter. Hardware inside computer to provide
monochrome text only.
Video Graphics Array. Graphics board in computer providing 640x480
resolution on a multiscan or analog display.
EGA
ECD
HGA
MD
MDA
VGA
For brave souls
Additional devices may be added to GENPLOT simply by adding their names to the DEVICES.DAT
file. If you wish to ignore the details that follow in this appendix, you can simply edit the file and
mimic the structure of devices already present. In most cases, the format of the file is simple and
obvious. Be careful of the following during your edit session though.
•
The fields within the file have fixed column specifications.
•
There cannot be any <TAB> characters in the file.
•
At least scan the short self-documentation following the device list.
•
Refer to the specific device driver or I/O channel later in this appendix if you have
problems or add anything funny.
Immediately following this introduction are summaries of the device driver and the I/O channel
specifications. These are provided as reminders to the syntax and options only.
For more careful souls
In the remainder of this appendix, the philosophy and structure of device drivers within GENPLOT
will be described. Over many years, GENPLOT has gained drivers to support broad classes of
plotting devices, including the PC graphics screens, graphics terminals, pen plotters, dot–matrix
and laser printers. Internally, all devices are handled such that the user is insulated from the
particular device resolution and operating quirks.
•
IBM-PC and clone graphic CRT screens
.
Video Graphics Array (VGA) (recommended)
.
Enhanced Graphics Adapter (EGA)
.
Color Graphics Adapter (CGA)
.
Hercules Graphics Adapters (HGA)
.
IBM 8514
.
AT&T 6300 graphics screens
D-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
•
Pen plotters using Hewlett Packard’s HP-GL language (HP 7475/7550)
•
Laser printers using POSTSCRIPT page description language.
•
HP LaserJet/PaintJet/DeskJet printers.
•
IBM 4019 Personal Laser Printer.
•
QMS/Talaris laser printers using QUIC commands.
•
EPSON FX-80 and compatible dot-matrix printers
•
OkiData 92 and compatible dot-matrix printers
•
Tektronix 4014 and 4105 graphics terminals and work–alikes.
GENPLOT converts low level plotting commands (such as line draw) into device specific control
codes via a device driver. These control codes must then be directed to the actual hardware device,
which may, for instance, be connected to a parallel port, a serial port, or to a GPIB network. This
hardware connection is referred to as an Input/Output channel. GENPLOT supports numerous I/O
channels for moving the device specific plotting “codes” from the device driver to the actual device,
including
•
Parallel Printer Ports: PRN, LPT1, LTP2, LPT3
•
ASYNC ports: COM1 and COM2 Asynchronous Serial Communication Ports
•
GPIB Interface: IEEE-488 devices attached to a National Instruments GPIB Interface Board
or an IOtech GPIB Interface board.
•
DISK files: Direct output to disk files or to devices configured as files.
•
SPOOL output: External spool to mainframe computers through COM1 or COM2. User software must be written on the mainframe.
If you are familiar with UNIX concepts, plotter support within GENPLOT is implemented philosophically as a collection of filters and pipes. GENPLOT generates a stream of internal plot commands
which are piped to a device driver such as HP-GL. The device driver, as a filter, translates the plot
commands into device specific plotter control sequences. These sequences are then piped to an I/O
channel such as ASYNC, where the necessary flow control sequences are inserted and the bytes are
written to the physical hardware (could be a disk or a real plotter). Any device driver may be
connected to any I/O channel although only one of each may be active at any given time. Unlike
standard pipes, however, GENPLOT uses bi-directionality to retrieve status or position information
from a plotter also.
With this introduction, the discussion will now focus in detail first on the DEVICES.DAT file, then
the available device drivers, and finally to the I/O channels.
D-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
SUMMARY OF DEVICE DRIVERS AND CAPABILITIES
Display Devices (and terminals)
Driver
DEB
EGA-VGA
HERCULES
IBM8514
IBMBIOS
IBMCGA
IBMEGA
IBMHGA
TEKTRX
#
1
2
1
2
1
1
4-6
13-19
64-65
88-95
1
2
3
1
2
3
1
2
3
1
2
3
4
5
6
7
8
Description/Hardware Supported
dpi
I/O use
AT&T DEB board (color)
AT&T DEB board (b/w)
Enhanced Graphics Adapter (EGA)
Video Graphics Array (VGA)
Hercules Monochrome Adapter
IBM 8514/A display adapter
BIOS CGA screen graphics
BIOS EGA/VGA graphics
BIOS AT&T DEB graphics
BIOS extended VGA graphics
CGA graphics 640x200 B/W
CGA graphics 320x200 color
AT&T 6300 640x400 graphics
EGA graphics (use for 64kB EGA)
EGA graphics (use for 64kB EGA)
EGA graphics (use for 64kB EGA)
SuperVGA mode 88 – 800x600
SuperVGA mode 344 – 800x400
SuperVGA mode 100 – 800x600
Tektronix 4010
Tektronix 4104
Tektronix 4105
Selanar SG200 for VT100
VI550 Emulator/Retrographics
HiRez 100
DEC TAB terminal
VT 340/Tek terminal
63x52
63x52
63x45
63x63
71x45
100x100?
options
options
options
options
?
?
63x52
?
63x26
32x26
63x52
63x45
63x26
32x26
79x77
52x52
79x77
100x100
100x100
100x100
100x100
100x100
100x100
100x100
100x100
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
? Various resolutions are available on the device.
Device Drivers for Graphics Exchange and Debuging
Driver
DEBUG
NULDRV
TIFF
WPDRV
#
1
1
1
1
Description/Hardware Supported
dpi
I/O use
Debug driver
Null driver (do nothing)
TIFF graphics exchange format
Word Perfect graphics format
1000x1000
1000x1000
300x300?
1200x1200
Byte Stream
Byte Stream
FILE only
? Various resolutions are available on the device.
Table I: List of the graphics device drivers available in GENPLOT. All physically distinct subdevices are shown with the generic hardware supported. See the description of the particular device driver for further information.
D-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
Printers, Plotters and Other Hard Copy Devices
Driver
COMREX
DESKJET
DRVQUIC
HP-GL
HPRASTER
IBM4019
LASERJET
PAINTJET
POSTDRV
RASTER
SST
#
1
1
1
1
2
3
4
5
6
7
1
1
0
1
2
3
1
2
1
2
3
4
5
6
7
1
Description/Hardware Supported
dpi
I/O use
Comrex pen plotter
HP DeskJet Printer
QMS/Talaris Laser Printer (QUIC)
HP 9872S pen plotter
HP 7220A/C pen plotter
HP 7220S/T pen plotter
HP 7225A pen plotter
HP 7475A pen plotter
HP 7550A pen plotter
HP 7440A ColorPro pen plotter
OBSOLETE – see individual drivers
IBM 4019 LaserPrinter E (PPDS)
HP LaserJet Laser Printer
HP PaintJet Color Inkjet Printer
(3 colors)
(7 colors)
(15 colors)
Postscript printers (landscape)
Postscript printers (protrait)
HP LaserJet printers (OBSOLETE)
Epson MX-80 compatible printers
Okidata dot matrix printer
EPSON LQ-500 24 pin printer
GEMINI 10-x printer
NEC P2200XE 24 pin printer
IBM X24E 24 pin printer
HP LaserJet with SST card
254x254
300x300?
300x300?
1016x1016
1016x1016
1016x1016
1016x1016
1016x1016
1016x1016
1016x1016
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
300x300?
300x300
180x180?
180x180?
180x180?
180x180?
1000x1000
1000x1000
300x300?
72x60?
72x72
216x60?
72x60?
180x60?
180x60?
300x300
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Byte
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
Stream
? Various resolutions are available on the device.
Table I: (cont) List of the graphics device drivers available in GENPLOT. All physically distinct
sub-devices are shown with the generic hardware supported. See the description of the
particular device driver for further information.
D-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
Plotting
Device
IBM 8514 Display Board (†)
Video Graphics Array (†)
Enhanced Graphics Adapter (†)
Color Graphics Adapter
Color Graphics in BW
AT&T 6300
AT&T 6300 DEB board
AT&T 6300 DEB board mono
Hercules
Ill-behaved CGA boards
Ill-behaved EGA boards
HP 7220A pen plotter
HP 7225A 2 pen plotter
HP 7475A 6 pen plotter
HP 7550A 8 pen plotter
HP 7440A 8 pen plotter
Apple LaserWriter
Talaris/QMS Laser Printer
HP LaserJet Printer
HP PaintJet Printer
HP DeskJet Printer
MX-80 dot matrix printer
OkiData dot matrix
Tektronix 4014
Tektronix 4105 color
HiRez Tektronix emulator
null driver
Supplied
Name
Device
Driver
none
VGA
EGA
CGA
BW
6300
DEB
DEB
HERC
BIOSCGA
BIOSEGA
HP7220
HP7225
HP7475
HP7550
COLORPRO
POSTSCRI
QUIC
HP300
PAINTJET
DESKJET
MX-80
OKIDATA
TEK4014
TEK4105
HRZ
NULL
IBM8514
EGA-VGA
EGA-VGA
IBMCGA
IBMCGA
IBMCGA
DEB
DEB
HERCULES
IBMBIOS
IBMBIOS
HP–GL
HP–GL
HP–GL
HP–GL
HP–GL
POSTDRV
DRVQMS
LASERJET
PAINTJET
DESKJET
RASTER
RASTER
TEKTRX
TEKTRX
TEKTRX
NULDRV
Subdev/
Option
1
2
1
1
2
3
1
2
1
4
16
2
4
5
6
7
1
1
1
2
1
2
3
2
3
6
1
0
-2
-2
0
0
0
0
0
0
0
0
1
1
1
1
1
1
0
0
0
0
2
0
1
0
0
0
Use of
Options
color map
color map
flop mode
flop mode
flop mode
flop mode
page size
page size
page size
page size
page size
page size
page size
options
options
options
resolution
delay rate
(†) I/O Channel controls display options – see driver descriptions.
Table II: Table gives examples of supported devices and plotters, and suggested names for each.
The device driver, sub-device and secondary options values are typical for each device.
The last column indicates the general effect of changing the secondary option in each case.
See the description of the particular device driver for further information.
D-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
SUMMARY OF I/O CHANNEL SPECIFICATIONS
I/O Specification = [<pre opts>*]<io channel>*<sub channel>*<channel opts>
<io channel>
FILE
ASYNC
SPOOL
GPIB
GPIB2
SCREEN
<sub channel>
DEFAULT
QUERY
CMDLINE
<name>
CON
PRN
LPT1, LPT2, LPT3
COM1, COM2
COM1
COM2
Description
COM1
COM2
<devname>
<devname>
none
Mainframe spool
(see note below)
PC-2A GPIB
IOtech GPIB
Screen devices
T$xxxx.PLT files
Request at run time
Read at run time
Specific filename
Console
Default printer
Specific printer
Don’t USE!!
RS-232 on COM1
RS-232 on COM2
<channel opts>
none
XON
ENQ
DTR
initialization
strings
none
none
none
Table III: An overview of the I/O channel specification is provided. This is meant only to serve for
syntax, not as a full description. See the individual I/O channels for further information.
Notes: The SPOOL channel supports output of plot commands to a mainframe computer connected
through the COM1 or COM2 port using the XON/XOFF protocol. The user must write appropriate
software on the mainframe computer to handle receipt of the plotting commands and direction to
the appropriate spool queue. The protocol of the transfer is described further in the SPOOL channel
below.
Examples:
FILE*PRN
FILE*CON
XON*FILE*E:TEMP.PLT
FILE*F:\SPOOLER\Q1.OUT
LEN=100*FILE*QUERY
DTR*FILE*CMDLINE
FILE*DEFAULT
ASYNC*COM1*XON
ASYNC*COM2*ENQ
GPIB*HPPLOT
GPIB2*HPPLOT
SPOOL*COM1*hp file
Direct output to the printer
Direct output to the console
Direct to a temporary file on the E: disk
Another file output
Query at execution time for filename (from user)
Query for filename from command stream
Accept GENPLOT default T$xxxx.PLT files
Standard RS-232 output to COM1
Same with ENQ/ACK protocol
Use device HPPLOT on National GPIB
Use device HPPLOT on IOtech GPIB
Send to mainframe and run “hp file”
D-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
THE DEVICES.DAT FILE
Within GENPLOT, all plotting devices are referred to by simple (and hopefully meaningful) logical
names such as EGA, HP150 or POSTSCRIPT (see the DEVICE command). The purpose of the
DEVICES.DAT file is to provide, for each logical name, two major specifications: a device driver
which specifies the class of the device (eg. IBMEGA or HP-GL) and an I/O channel which specifies the
disposition of the graphics output to the physical plotter (eg. diskfile or COM1). As an example, an
HP pen plotter will always use the HP–GL graphics driver, but might specify either ASYNC*COM1 or
GPIB*LAB HP as the I/O channel. Along with the device driver and the I/O channel, the DEVICES.DAT
file also provides further information on the capabilities of the device, such as the number of pens
or colors available or the size of paper being used.
The DEVICES.DAT file is required for any graphics output. This file must be found in the C:GENPLOT
directory unless the environment variable DEVICES.DAT has been set (see Appendix R or V to redirect
this file). Users are encouraged to modify DEVICES.DAT for their specific site, after having read this
section. A full screen editor is recommended for modifying the file. No special formating characters
can be inserted in this file and the column spacing is important.
A subset of a DEVICES.DAT file is shown below. The actual file includes many more device specifications along with internal documentation following the device list.
¾
»
/* IBM-PC
/*
EGA
MYHP
HPDISK
QMS
HP300
TEK4105
/*
SPECIAL
DEBUG
NULL
/*
@END
½
¼
devices
EGA-VGA
HP-GL
HP-GL
DRVQMS
LASERJET
TEKTRX
01
05
06
01
02
03
-2
01
01
00
00
00
SPECIAL
DEBUG
NULDRV
00 00
02 00
01 00
x x x
x x
x
x x x
15
06
06
08
01
07
x x x x 15
x x 08
x x 08
SCREEN
ASYNC*COM1*ENQ
FILE*DEFAULT
SPOOL*COM1*TAL
FILE*PRN
ASYNC*COM2*XON
640x350 EGA
HP7475 on COM1
HP7550 to file
Spooled QMS
300 DPI LaserJet
TEK4105 on COM2
UNKNOWN
FILE*CON
FILE*CON
Special request
Debug device
Null device
This would be a typical device listing for a computer with the following hardware:
EGA adapter and ECD screen
HP–7475 pen plotter on port COM1 (using ENQ/ACK protocol)
File output for spooling to an HP7550 pen plotter
Mainframe also connected to COM1 for spooling QMS files
Tektronix 4105 color terminal on port COM2
HP LaserJet printer on PRN
DEVICES.DAT need contain lines only for the devices that you will actually be using, although there
is no penalty for having additional devices defined. Only the executable code for the currently active
device is loaded into memory; device drivers for any other plotters remain on disk until needed. Each
non–blank, non–comment line (comments lines begin with /* as in the first two lines above) in the
file defines a logical device with the name given in the first column.
D-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
WARNING: The file consists of fixed length fields — the pretty columns must remain in their
exact locations.
The file may be logically ended with a single @END (case sensitive) token in the first column of a
line. Modifying DEVICES.DAT generally requires only editing the file and changing the parameters
for a given device. A new device can be added by copying one of the existing lines and changing the
fields to correspond to the new device. Be careful to keep the items in the proper column though.
Consider one device from the DEVICES.DAT file above.
MYHP
HP-GL
05 01
x x
06
ASYNC*COM1*ENQ
HP7475 on COM1
The first string MYHP is the logical name by which GENPLOT refers to the device. The second
string HP-GL specifies the device driver and the following two numbers select a specific device from
the driver and a specific set of options (05 ⇒ HP7475 pen plotter and 01 ⇒ size A paper). The
two x’s inform GENPLOT that this device has a cursor and the 06 specifies that MYHP has 6 pens
available for plotting. Finally, the string ASYNC*COM1*ENQ is the I/O channel, specifying output to
the asynchronous communication port COM1, using an enquire/acknowledge handshaking protocol.
The remainder of the line is only a comment to remind oneself what the device really is.
The device drivers and I/O channels available within GENPLOT will be described in detail later in
this appendix.
Below is a formal list of the fields and the format for each column in the DEVICES.DAT file. It is
a fixed field format and entries must maintain the proper column alignment. Since the FORTRAN
compiler treats tabs as a single character, tabs are not allowed in DEVICES.DAT. All fields, with the
exception of the I/O channel, should be uppercase only.
Field Description
Format
Columns
Blanks
Logical device name
Device driver routine name
Device type (see driver listings)
Secondary parameter (see drivers)
Device characteristics - bits
Number of pens available (<16)
I/O Channel (see note below)
Description (see note)
(A8,2X)
(A8,2X)
(I2,1X)
(I2,2X)
4(A1,1X)
(I2,2X)
(A40)
Remainder
1-8
11-18
21-22
24-25
28-34
36-37
40-xx
xx-80
9-10
19-20
23
26-27
29-35
38-39
NOTE: The I/O channel field can be up to 40 characters in length. A single blank character
terminates the I/O string and the remainder of the line may be used for a descriptor comment.
Each time a DEVICE command is executed in GENPLOT (or implicitly executed as in HCOPY), the
DEVICES.DAT file is loaded and the requested device name is compared with the list of logical device
names. Once a match is found, the real device is initialized using the specified device driver, the
I/O channel and the parameters.
The logical device name, the first field, must be at least 2 characters long. When selecting a device,
the device name may be abbreviated to 2 characters; however, the first device to match the request
is loaded. Specifying DEV HP or DEV HPD would both select the HPDISK device, while DEVICE HP3
is the minimum abbreviation required to get the HP300 device. This field MUST appear in upper
case only.
D-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
The second field specifies the device driver routine name, corresponding to a particular class of
devices. The device driver executable code is dynamically loaded from the c:genplot directory,
using the driver name with a .DRV extension as the filename. The sub–device and the secondary
parameter (numbers) are passed to this driver to select a particular device and select options on that
device. The specific sub–devices and secondary parameters for each device driver are given later in
this appendix.
The next 4 positions are logical bits which describe cursor capabilities of the device. From left to
right, these are
1.
2.
3.
4.
Device
Device
Device
Device
has a cursor
may have a cursor
is a video terminal type device (overwritable)
is a tablet for digitization (don’t use for normal devices)
If the first bit is set, the second bit must also be set. The converse is not true however since some
devices have optional cursors (perhaps mice). ’May have cursor’ causes GENPLOT to proceed
with caution when requesting input from a cursor. You can also choose to disable the cursor on some
devices despite the hardware capability. The HP pen plotters above could, for instance, be caused to
return No cursor by replacing the first two x’s with blanks. The video bit indicates to GENPLOT
whether the device looks more like a soft copy (CRT) or a hard copy device (pen plotters). CRT
capability is used for overwriting. The fourth bit is reserved for future use and is currently ignored.
The next field is an integer that indicates the number of pens or colors available on that device. The
EGA has 15 pens (plus black) available while the HP7475 has only 6 real pens. This information
is fed back to GENPLOT for use by the auto–pen change software (see PEN -1 command). If you
commonly execute macros or HCOPY files on the EGA and then on the HP7475, it may be desirable
to limit the selection of colors on the EGA to 6 to match the HP 7475.
The last field, starting in column 40, is the I/O channel string. This string consists of several
sub–fields separated by the * character. The entire string is passed to the I/O channel processor
for interpreting — see the section below on the I/O channel. Not all devices use the I/O channel
information. Devices which implement the output as a byte stream to physical plotters (eg. LASERJET) utilize the I/O channel information to direct their output. However, many screen drivers (eg.
EGA-VGA) also utilize this field to pass control information to the driver. Generally, devices which
may be attached to a PC in a variety of ways will be byte–stream and use the I/O channel. Each
device driver described in the next section specifies whether it is a byte–stream device. For future
compatibility, we recommend using SCREEN as the I/O channel for any screen devices which do not
specifically use the information, and UNKNOWN as the I/O channel for all other devices (as in the
SPECIAL device above).
The I/O channel string terminates with the first blank character. The remainder of each line is a
comment field, and should provide some reminder of what each device actually is.
Special devices
Besides real devices, three special devices are defined: DEBUG, NULL and SPECIAL. NULL does
exactly what it says, nothing. All plotting commands are accepted but nothing comes out anywhere.
Obviously, the I/O channel is irrelevant. The DEBUG device generates a line of text each time the
device driver is called, indicating the operation and the passed parameters. This is an interesting,
albeit verbose, way of seeing what plotting commands occur in GENPLOT. The SPECIAL device is
a reserved device name which prompts at initialization time for the actual device driver, sub–device,
secondary parameter and I/O channel. Its primary use is to select a strange device which is not
D-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
defined presently defined in the DEVICES.DAT file. We strongly recommend that these three devices
be included in all DEVICES.DAT files you write.
WARNING AGAIN: The strongest warning is that this file requires correct spacing and that
GENPLOT treats <tabs> as single spaces. It gets very upset at files which are neatly formatted
into columns through the use of tabs, but in reality do not have the proper spacing. If your editor
allows tabs, be sure to remove them before saving the file to disk. I can guarantee that GENPLOT
will not plot if this file is corrupted.
D-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
DEVICE DRIVERS
Device drivers have been written to support numerous devices. The bold characters below are the
names of the device drivers which support the specified devices. Some drivers are obsolete but are
included for compatibility with old DEVICES.DAT files.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
COMREX – Comrex pen plotters.
DEB – AT&T 6300 color graphics DEB adapter.
DEBUG – Debug device driver. Includes debugging capabilities.
DESKJET – HP DeskJet personal inkjet printer
DRVQUIC – QMS/Talaris laser printers using QUIC commands.
EGA-VGA – EGA (Enhanced Graphics Adapter) and VGA (Video Graphics Array)
HERCULES – Hercules monochrome graphics adapter.
HP–GL – Pen plotters using HP–GL language (all HP pen plotters).
HPRASTER – HP LaserJet/DeskJet/PaintJet (OBSOLETE – use individual drivers)
IBM4019 – IBM Personal laser printer IBM 4019
IBM8514 – IBM 8514 high resolution display adapter
IBMBIOS – Generic BIOS compatibility for ill-behaved graphics devices.
IBMCGA – COLOR, BW on Color Graphics Adapters. AT&T 6300 graphics.
IBMEGA – Enhanced Graphics Adapter (OBSOLETE – use EGA-VGA)
IBMHGA – Some super-VGA modes
LASERJET – HP LaserJet printer (or clone such as IBM 4019)
NULDRV – Null device driver. Does nothing.
PAINTJET – HP PaintJet color ink printer
POSTDRV – Laser printers using Postscript page description language, such as the Apple
LaserWriter.
RASTER – Raster output for most dot-matrix printers including
.
.
•
•
•
•
Dot matrix printers such as EPSON FX–80, OkiData 92 and Gemini.
24 pin dot matrix printers
TEKTRX – Tektronix 4014, 4105 and compatible type terminals.
TIFF – Produces a TIFF compatible plot file
WPDRV – Produces a graphics file compatible with WordPerfect 5.0.
?????? – Any other device you are willing to write the driver for.
Each of these device drivers covers a general class of plotting devices; normally each driver supports
several sub–devices. For example, the RASTER device driver supports as sub–devices the EPSON FX–
80 dot matrix printer and the OkiData dot matrix printer. Although these printers are physically
different, the structure of the plotting commands are similar enough that they are treated together
as a single class of device. Each sub–device within a driver class may also have several operating
modes. Again, as an example, the HP LaserJet printer may be operated at 300, 150 or 75 DPI
resolution by specifying a secondary parameter for the sub–device.
Example
To specify an HP LaserJet printer in raster mode at 150 DPI.
device driver
LASERJET
specifies LASERJET output devices
D-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
sub–device
secondary parm
2
2
selects the 150 DPI mode from LASERJET
suppresses page eject at end of plots
D-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
General Device Information
Special notes on drivers – EGA-VGA, IBMCGA, HERCULES
As a general rule, I have assumed that all users want graphics at the maximum possible resolution
and at the fastest possible drawing speed. While the PC screen drivers contain specifications and
code to handle almost all screen resolutions and modes, the drivers are optimized for running in
dual screen mode on PC–AT type systems (ie. 80286 processor, slow video channels). In dual
screen mode, all interactive text with GENPLOT appears on the monochrome screen with graphics
appearing separately on the graphics screen. The fastest drawing and the highest resolution occurs
for a VGA or EGA adapter (hardware version, not software emulation) connected to an appropriate
color monitor and a MDA connected to a monochrome monitor.
However, the inventors of PCs did not always foresee the strange modes we would run them in
and failed to provide complete information in the BIOS about what equipment was available; only
the display adapter currently active could be checked. This problem was fixed with release of the
EGA BIOS which provided an “existence” byte. Hence, to run in the dual screen mode, GENPLOT
must be started with the non–graphics screen currently active (so GENPLOT can know that it is
there). This will require a MODE MONO or MODE CO80 DOS command to select the non–EGA or non–
graphics device. The same comments apply when running with a CGA and MDA adapter, though
for somewhat different reasons.
If the graphics screen is active when GENPLOT is initialized (actually when the plotting device is
initialized), or only a single monitor is used, GENPLOT will assume a single screen configuration
and try to do the best it can. This involves time–sharing the screen between graphics and text.
(As a personal note, I hate graphics and text on the same screen — my graph is my graph and
all the commands needed to get it up there are separate.) The screen time–sharing is done by
constantly calling BIOS to switch the screen modes, storing and restoring the graphics and text
memory, and keeping track of where the graphics and text material actually is at any given instant.
The compromise for this single screen operation is a noticeable flicker (or worse) in the screen during
the switch.
The EGA–VGA driver can handle single screen graphics and text without the flicker by staying in
graphics mode and scrolling between the two views. Text is slow in this mode but there is no screen
flashing.
Finally, if you happen to disagree with me and you want the text to overwrite the graphics, you can
force true single screen operation with some effort. GENPLOT will not enter screen flopping mode
if the graphics monitor is currently active and is in the correct BIOS mode for the selected graphics.
If you do not know how to force a screen to any BIOS mode, write me with your reasons for liking
true single screen operation, and we’ll send you an appropriate .COM file for switching.
And terminally, we cannot fully guarantee that GENPLOT will work with all graphics screens if
being shared with other software packages, nor will the other package necessarily work after running
GENPLOT. GENPLOT must make some assumptions concerning the graphics card status, and
then configure the graphics board to GENPLOT’s own requirements. I have been careful to return
the monitor to a “nice” mode when GENPLOT exits, but I cannot necessarily return it to the same
state it was received in.
D-14
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP DeskJet Printer
DESKJET.DRV
Brief
1.
2.
3.
Byte Stream
Cursor support
Linewidth
Fully implemented
Not implemented
Fully implemented
Sub–devices
01
02
03
04
Secondary parms
Summed key (bit settings) for control of various options
+01 =⇒ Single dot mode for LT 0 SYM 0
+02 =⇒ Suppress page eject on last plot
+04 =⇒ Suppress reset sequence on open/close
+08 =⇒ Suppress linewidth capability
+16 =⇒ Suppress data compression
+32 =⇒ Suppress blank lines at top of scan
+64 =⇒ Eject current plot before next starts
Related drivers
LASERJET, PAINTJET
=⇒
=⇒
=⇒
=⇒
300 dpi resolution
150 dpi resolution
100 dpi resolution
75 dpi resolution
Notes:
Secondary parameter +08 is currently not implemented
Use secondary parameter +64 to force plots out before further drawing
To incorporate plots into documents (such as TeX), use secondary parameter +6 or +38 to
disable page eject, reset sequences, and optionally blank lines.
General Description
The DESKJET driver generates compressed raster mode output for the HP DeskJet. The DeskJet is
capable of printing at the 75, 100, 150 or 300 dpi resolutions of the LaserJet. Plots at 300 dpi plots
are generally suitable for publication. The 150 dpi resolution is reasonable for draft work and can
be used on slower machines. The 100 and 75 dpi resolutions are comparable to screen dumps and
can be used for very rough draft work, but otherwise should be avoided.
As a raster device, images generate a large amount of output and the I/O channel should be configured to send data directly to the printer if at all possible. Without compression, a 75 dpi image
requires 56 kB while a 300 dpi image requires almost 860 kB. Although processing time scales
quadratically with the linear resolution, this code has been optimized for speed and transfer of the
image to the printer is the rate limiting step. The DeskJet accepts RLL compressed data (which
the LaserJet lacks) dramatically reducing the actual amount of data which must be transferred.
However, because of the printhead speed, several minutes are required just to draw a full 300 dpi
graph. Unless absolutely necessary, always leave the compression enabled since it requires negligible
computing time and gives dramatic improvements in speed.
Note: This driver is identical to the LASERJET in all details except for the compression algorithm.
Line and dots drawing characteristics
All vectors are drawn in a variable linewidth mode with rounded corners. This mode generates
publication quality output (at 300 and 150 dpi) at the expense of some processing time. At 100
and 75 dpi, the linewidth control begins to appear ragged due to the low resolution. The linewidth
D-15
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP DeskJet Printer
mode currently cannot be disabled. Single dots, such as generated by the mode LT 0 SYM 0, are
drawn as a cross of 5 pixels instead of a single pixel (single pixels are often lost when printing). This
conversion can be disabled, resulting in single points drawn as single pixels, by setting +1 in the
secondary parameter.
Incorporating plots in other software
Many word processing programs (including some versions of TeX) allow insertion of raster plots into
documents. This driver generates all draw commands as relative motions from the current position,
permitting insertion at any position in the document. However, it is almost always necessary to
disable the commands for page feed and resets in the driver by setting +6 in the secondary parameter.
Compression should be left enabled if possible.
Plots for wordprocessing are commonly drawn in the FLIPXY YES mode to get the correct orientation
with text. However, since the plot defaults to the bottom of the page in this mode, an OFFSET is
required to place the plot at the top of page for correction positioning. If this is not done, the plot
may fall off the “bottom” of the page and not be printed. As an alternative to the OFFSET command,
+32 can be added to the secondary parameter. This eliminate all blank scan lines from the top of
the plot and causes the first non-blank scan to be positioned at the top. While the position of the
plot may shift if additional drawing is done above the axis, this method is usually easier than the
trial and error method of determining the correct offset.
Why plots do not come out immediately
In operation, raster drivers are very different from vector oriented drivers such as EGAVGA. For vector
devices, each line segment can be drawn on the physical page as it is generated. However, since
the entire page must be output at once to the DeskJet, the plot must be drawn in memory. Since
there is seldom a free megabyte of RAM to hold the image, plotting is actually done in two phases.
The first phases simply collects vectors into a temporary file. Once all vectors have been generated,
a vector-to-raster conversion process begins, working in thin bands until the full image is output.
Note, the computer cannot read your mind and the conversion can never start until you explicitely
“end” the graph by doing an erase or starting a new plot.
Since I don’t like waiting for the vector-to-raster conversion between every plot, multiple plots are
normally collected and the conversion process is started only after the device is closed. This can be
modified so plots are output after every page by setting the secondary parameter +64. Alternatively,
reinitialize the device with another DEVICE command when you want the output process started.
During plot generation, the driver stores a list of vectors in a T$xxxx.PLT temporary file, created in
either the directory pointed to by the TMP environment variable or in the current directory. The I/O
channel specifies where the final plot goes, not this temporary file. Once all vectors are collected, the
vector to raster conversion begins. The vector file is sorted and raster conversion occurs in bands,
each typically 8-24 pixel lines on the output page. Scan conversion statistics are output to the screen
during processing. After each page, a form feed is sent to the printer and the next graph is started.
Output from the scan conversion is directed to the I/O channel as specified in DEVICES.DAT.
Speeding up the printing process
Best suggestion for increasing the output speed is to buy a faster computer. It’s amazing how fast
a 486 processes even the most complex graphs. Short of this, there are several steps to improve the
speed on 286 and 386 machines. Since the conversion process uses the disk as swap space, dramatic
D-16
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP DeskJet Printer
improvements can be realized by shifting temporary files to a RAM disk or by installing a disk cache.
Useful speed (i.e. time to keyboard response) can be further improved by use of a print cache.
1. To redirect temporary files, set the environment variable TMP to point to a directory (or root)
of the RAM disk. The temporary vector files are seldom larger than 200kB/graph even for
complex drawings so even small RAM disk (not in conventional memory please!) are useful.
2. If a hard disk must be used for swap space, install a disk caching program to improve the read
after write speed. Approximately 10 kB are being swapped in and out at any single instant.
3. Finally, use a print cache program (such as PCACHE from Hewlett Packard) to allow GENPLOT
to complete the vector conversion process without waiting for the printer. You can then
continue on with your work while the graph is slowly and painfully transferred to the printer
itself.
WARNING: There is not enough conventional memory below 640 kB for programs as is. Never waste
any space for resident programs unless the payoff is phenomenal. RAM disks and/or disk caches in
conventional memory are useless and should instead only use extended or expanded memory. Also,
always disable the memory wasteful, albeit pretty, TSR control modes of the print cache programs.
Memory constraints
Since raster drivers must do the vector to raster conversion, they require considerably more memory
(18 kB) than display devices. Consequently, although a graph may be drawn to the screen, an
attempt to make the same plot on a DeskJet may fail because of insufficient memory to load the
DESKJET driver. It may be necessary to free memory by deallocating some modules before the driver
will load (see DEALLOC). There are no longer any limits on the number of active vectors allowed,
although the total number of vectors is still limited to approximately 200,000.
Sample DEVICES.DAT file entries:
¾
DESKJET
DJ150
DJNOW
DJASYNC
TEXDJ
½
»
DESKJET
DESKJET
DESKJET
DESKJET
DESKJET
01
02
01
01
01
00
32
64
00
38
01
01
01
01
01
DISK*PRN
300 DPI HP DeskJet
DISK*PRN
150 DPI HP DeskJet
DISK*PRN
DeskJet w/ immediate output
ASYNC*COM1*BAUD=9600 300 DPI DeskJet
DISK*TEX.HP 300 DPI DJ for TeX special
¼
D-17
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
EGA and VGA screen drivers
EGA–VGA.DRV
Byte Stream
Cursor support
not implemented
Fully implemented
Sub-devices
01 =⇒EGA 640x350 16/4 colors (mode 10/0F)
02 =⇒VGA 640x480 16 colors (mode 12)
Secondary parms
I/O channel
Select color map
0 =⇒normal IBM color scheme
-1 =⇒White/nice colors on black background
-2 =⇒White/nice colors on blue background
-3 =⇒Black/colors on White background
-4 =⇒Black/colors on Grey background
+n =⇒Normal IBM colors on background color N
Opt1*Opt2*Opt3*. . . – Selects options.
Related drivers
IBMCGA, IBMBIOS
Device Options
SCREEN
SWAP
SCROLL
No operation, use defaults
Screen initialized in swapping mode (default)
Screen initialized for scrolling mode
LARGE
TINY
BOTTOm
TOP
Initialize SCROLL mode with large text
Initialize SCROLL mode with tiny text (default)
Show bottom of graph in SCROLL mode (default)
Show top of graph in SCROLL mode
KEY
TEXT
GRAPH
NOKEY/NOTEXT/NOGRAP
Switch to text view when key pressed
Switch to text view if text printed
Switch to graph view if vector drawn
Disable corresponding mode
KEY=ec
L=n
DELAY=n
Specify screen toggle key – extended code (default 68=[F10])
Number of text lines initialized in SCROLL mode (default 25)
Time delay for switching from graph view (default 3 ticks)
LW
NOLW
Enable linewidth control on device
Disable linewidth control on device (default)
MOUSE
Robust initialization of mouse hardware (see text)
This driver supports the Video Graphics Array (VGA) connected to a high resolution monitor and
the Enhanced Graphics Adapter (EGA) connected to an enhanced color display or monochrome
display. Use the IBMCGA driver for either of these display cards if they are attached to a normal
color display. For EGA systems with less than 256 kB of memory, buy a new card. This code is
optimized for driving full function VGA and EGA systems and utilizes direct writes to the onboard
registers. Only fully register level compatible VGA and EGA cards will work with this driver. The
driver checks for existence of the appropriate hardware and BIOS during initialization.
There are only two subdevices in this driver; 01 selects the 640x350 resolution compatible with
the EGA; 02 selects the full VGA resolution of 640x480 pixels in 16 colors. Sub–device 01 must
be selected for EGA devices and will automatically switch to handle either monochrome or color
screens. The screen size of this driver is chosen to match the HP7475 pen plotter; plots which fit on
the screen should also fit on a HP7475 output.
D-18
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
EGA and VGA screen drivers
The secondary parameter selects a color map for the sixteen pens. The colors on all maps correspond
closely to standard pen colors specifications. A value of 0 retains the normal IBM color scheme with
a black background. Negative numbers select predefined alternate color maps. Map -2 is probably
the best for normal graphics with white on IBM blue. Positive values select the standard IBM colors
sets but change the background to the specified color (between 1 and 255).
This driver supports both dual and single screen configurations. In dual screen configurations,
graphics is directed to the EGA/VGA screen and text is output to the monochrome display adapter
(MDA). The MDA must be the active screen when the device is initialized in order to be recognized.
Independent of any of the I/O channel specifications, the dual screen operating mode will always be
selected if the MDA is active
If an MDA is not active when the device initializes, one of the single screen modes, swapping or
scrolling, will be entered. In the SWAP mode, text is output to a video mode optimized for text
output (normal screen modes) and graphics are drawn in the high resolution graphics mode. The
two screens are maintained in separate areas of the VGA/EGA memory with only one screen display
at any time. The display mode is toggled between the two using the F10 key (or the key specified
with the KEY= option). There may be considerable gnashing of teeth in the monitor (and an annoying
flash) as the screen switches since the monitor must readjust to a new scan frequency. This minor
distraction is normally overshadowed by the advantages of dealing with the text in a normal text
mode (fast, lots of colors, coherent cursor, etc.). If the flash is annoying, however, the screen may
be operated in the scrolling mode.
In the SCROLL mode, both text and graphics are handled in the graphics mode of the video card.
There is sufficient memory on both the EGA and VGA cards that the text and graphics can share
the memory space without interference (though with some limitations as discussed below). The
display screen toggles between graphics and text simply by changing a pointer to the hardware
output chip. Since both text and graphics use the same modes, there is no flash associated with
the text/graphics switch. There are disadvantages to this mode. (a) Drawing text characters in a
graphics mode is painfully slow and scrolling of the screen is even slower. (b) The cursor is handled
by software emulation and may disappear during some operations. (c) On the VGA, there is not
sufficient memory to display 25 lines of text with normal size characters. (d) Pausing out to a DOS
shell with ANSI.SYS installed may give strange results because of color mismatches or if the number
of lines is not 25. A 25 line display is achieved by shrinking the size of the characters from the normal
8x14 (or 8x16) cell to an 8x8 cell (the 43/60 line mode of the EGA/VGA). With small characters, 25
lines does not require the entire screen and the remainder of the screen is used to display a portion
of the graphics window (see BOTTOM/TOP option below). There are numerous options which select
the interaction between the graphics and text areas as described below.
Mice, Rodents, Mouses and other pointing devices
Rodents (also known as mice) are supported for graphics cursor operations. The EGA-VGA driver
recognizes the BIOS configured mouse of the PS/2 so there is no need to install a Microsoft compatible mouse driver for these. The MOUSE option is irrelevent when using the PS/2 mouse. To
utilize the rodent on computers without the PS/2 BIOS supported type mouse, a Microsoft 6.x
(or compatible) mouse driver (MOUSE.COM) must be loaded prior to running GENPLOT (normally
done in your AUTOEXEC.BAT file). Once installed, the mouse will be automatically recognized and
configured during graphics initialization. The MOUSE option is not necessary for this standard use of
the rodent.
In some configurations initializing the driver software is not sufficient to initialize the mouse; the
hardware must be reset and reinitialized each time. The option MOUSE causes the EGA-VGA driver
to robustly initialize the mouse and hardware. This reset may require a few seconds to complete
D-19
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
EGA and VGA screen drivers
and should only be used if the mouse does not always successfully initialize without it. (Note: The
mouse will always work properly during the first invocation of GENPLOT; it is during subsequent
invocations that the mouse will appear disabled.)
Both the rodent and the cursor keys may be used for movements. The left mouse button returns a
zero (equivalent to space) and the right returns the character 1. In CURSOR -TRACK, holding down
the left button enters search mode and returns the equivalent of F. For the box cursor, pressing
the left button quickly will shift the attached corner. Holding the left button down will allow rigid
movement of the box.
DEVICES.DAT Entry Examples:
VGA
EGA
EGA-VGA
EGA-VGA
02 -2
01 -2
x x x
x x x
15
15
SCROLL*KEY*GRAPH VGA 640x480
SWAP*KEY*GRAPH
EGA 640x350
I/O Channel Specifications of Options
The I/O channel is used in the EGA-VGA driver to select additional options.
Defaults: SWAP*TINY*BOTTOM*L=25*KEY=68*DELAY=3*NOKEY*NOTEXT*NOGRAPH*NOLW
SCREEN — This option does nothing but is provided for consistency with the overall I/O channel
concept for other drivers. Default options are used.
SCROLL/swap — SWAP causes the driver to initialize separate text and graphics modes in the
single screen configuration. See discussion above. The text/graphics view are toggled between using
the F10 key (normally). This switch generally causes flicker on most monitors, the exact degree
depending on your monitor and adapter combination. In SCROLL mode, only one graphics mode is
used for both text and graphics and eliminates the flicker problem. The toggle key F10 still switches
between graphics and text views, although a portion of the graphics view normally remains visible
on the screen.
LARGE/tiny — This option selects the LARGE (8x14 pixel) text in SCROLL mode only. Default is
to use TINY (8x8) text. The smaller text is normally used since it allows 25 lines of text in the VGA
mode. The small character correspond to a screen with 43/60 lines on EGA/VGA systems; however,
not all of the lines can be used in GENPLOT because of memory conflicts with the graphics area.
For the small characters, a maximum of 43/27 lines are possible on the EGA/VGA screen and for
the large characters, a maximum of 25/18 lines. See the L= option below. Since the text lines do not
utilize the entire screen, a portion of the graph is also displayed on the screen. See the BOTTOM/TOP
option to select the portion to be displayed.
L=n — Sets the number of text lines to be displayed in the SCROLL mode. Normally, the number
of lines should be left at 25 as the editor and help routines assume this size. Since memory is
shared with the graphics screen, there is a maximum number of lines which can be specified. For the
EGA/VGA, TINY characters allow 43/27 lines and the LARGE characters allow 18/25 lines. Although
there is no lower limit, fewer than 10 lines becomes impractical. See warning under technical notes
below.
BOTTOM/top — Any extra space on the display in the text view in SCROLL mode (tiny characters
at L=25 for instance) is used to display a section of the plot. This command specifies either the
BOTTOM or TOP to be displayed in the extra area. If BOTTOM is specified, it is possible to use the
SHRINK command on the plot and get an entire plot within the extra area. Reducing the number of
lines below 25 increases the area available for this “single page” plot.
D-20
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
EGA and VGA screen drivers
KEY=ec — The KEY command changes the toggle key from F10 to any other extended code key.
(Note: Normal ASCII key sequences may also be used by specifying 256+ASCII value.) Extended
codes include the function keys, function keys modified with <ALT>, <CTRL> or <SHIFT> and all the
<ALT> keys. A full listing of the extended codes are given in an Appendix of the BASIC manual
and in the Technical Reference Manual section on the keyboard BIOS interface. Some PC values
are given below.
Code
Alpha Keys
Code
Function Keys
16–25
30–38
44–50
ALT top row (Q,W,E,R,T,Y,U,I,O,P)
ALT middle row (A,S,D,F,G,H,J,K,L)
ALT lower row (Z,X,C,V,B,N,M)
59-68
84-93
94–103
104–113
F1-F10
SHIFT F1–F10
CTRL F1–F10
ALT F1–F10
TEXT/GRAPH/KEY
Context switches from graphics to text screen can occur (or not occur) for four conditions. The
toggle key (default is <F10>) will always initiate a context switch from the current screen mode to
the other mode. If the option GRAPH is enabled, any graphics draw commands will automatically
switch to the graphics view. Likewise, if TEXT or KEY is enabled, any text output or any keystroke
will switch to text mode. The recommended mode is KEY*GRAPH. The switch from graphics view to
the text view is delayed slightly to avoid continuous context switches. The default delay is 3 ticks
(1 tick = 1/18.2 seconds) or the value specified by the DELAY= option. If a graph context switch
is requested within 3 ticks of a text request, the text request is cancelled. This avoids the flashing
associated with typing and drawing at the same time.
DELAY=n — Sets the time delay between receipt of text context switch request and the actual
context switch. See discussion in section above.
LW/nolw — The EGA-VGA driver will emulate linewidths by drawing multiple pixel lines. This
feature is enabled by specifying LW with the I/O channel. One pixel, by definition, is 1/150 of an
inch. Linewidth 2 is drawn as two pixels side by side. The default is NOLW for speed and highest
screen resolution. LW may be specified to verify proper settings of the axis linewidth parameters.
VGA I/O Channel Examples
Since the I/O channel of the EGA–VGA driver is a bit more complex than any of the others, here
are a few examples.
SWAP*KEY=67*KEY*GRAPH
25 lines in text mode. Changes mode to get
graphics. Toggle key set to F9 instead of F10.
SCROLL*BOTTOM*KEY*GRAPH*LW
25 lines of text, jump view scrolling with hold,
no flicker, good VGA or EGA mode
25 lines of large text, jump view scrolling with
hold, no flicker. Separate graphics/text. Good
EGA mode
SCROLL*LARGE*TEXT*GRAPH
Technical notes: ANSI.SYS and BIOS modes
ANSI.SYS This VGA driver is known to have several problems when used with the standard DOS
supplied ANSI.SYS device driver. In particular, ANSI.SYS was written back in the days before anyone
thought screens would have anything other than 25 lines of text; it handles changes in the number
of columns but will not handle other than 25 lines. GENPLOT completely bypasses ANSI.SYS itself.
D-21
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
EGA and VGA screen drivers
However, if you PAUSE to a DOS shell, the text attributes may be wrong and strange things may
result, such as not being able to see any output. If problems occur, the options are 1) If it hurts when
you do that, don’t do that (translated, suffer with 25 lines of text in whatever size is necessary), or
2) Eliminate ANSI.SYS from your CONFIG.SYS file.
BIOS modes: There is one additional possibility for EGA–VGA initialization that occurs if the
VGA/EGA card is already in the specified BIOS graphics mode. In this case, the driver will enter
a true single screen operation where the text and graphics appear on a single frame. When the text
scrolls, so does the graph. Getting into this mode is normally difficult; if it happens unintentionally,
type DEV NUL DOS MODE CO80 or DEV NUL DOS MODE MONO from within GENPLOT and re-select
the EGA/VGA graphics device.
WARNING: Some GENPLOT commands, such as HELP, assume 25 lines and may not work properly if fewer lines exist on the screen. Pausing to DOS may also fail since most versions of ANSI.SYS
do not recognize the BIOS variable for number of lines.
D-22
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP-GL Pen Plotters
HP-GL.DRV
Byte Stream
Cursor support
Sub–devices
Secondary parms
Related drivers
Fully implemented
Cross–hair only. No box mode.
See discussion for digitizing below.
01 =⇒ HP 9872S
02 =⇒ HP 7220A or C
03 =⇒ HP 7220S or T
04 =⇒ HP 7225A
05 =⇒ HP 7475A
06 =⇒ HP 7550A
07 =⇒ HP 7440A ColorPro
-x =⇒ Disable initialization of communication protocol
00 =⇒ input paper size from user
01 =⇒ using A size paper (8.5x11 inches)
02 =⇒ using B size paper (11 x17 inches)
03 =⇒ using A4 size paper (210x297 mm)
04 =⇒ using A3 size paper (297x420 mm)
none
The HP-GL driver supports pen plotters which understand the HP–GL graphics plotting language,
ie. essentially all HP pen plotters. HP plotters other than those specifically listed will generally run
under one of the above categories. The entire family of HP plotters differ primarily only in (1) the
number of pixels on a given size of paper (2) the ability to do a paper check and (3) the ability to
automatically feed new paper. The HP7550 (device 6) is capable of computer paper feed and should
be specified only for similarly equipped plotters. Likewise, both the HP7475 and HP7550 (devices
5 and 6) implement a paper check algorithm which may fail with other, especially older, plotters.
Page sizes differences between plotters are a secondary effect which can be safely ignored when using
unusual HP plotters.
Many plotters from other companies (IBM comes to mind here) are really HP plotters in disquise.
If the documentation indicates that it supports the HP–GL language, you can probably expect one
of the above devices will work. The most “restrictive” device (which should work for all plotters) is
the HP7440A (ColorPro). For unknown HP compatible plotters, it is best to start with that device
and work through in progression to the HP7475 and finally the HP7550.
I/O Channel information
The HP-GL driver fully implements all I/O channel capabilities including GPIB support. For any RS232 implementation of the plotter (including through file output or spooled devices), the I/O channel
should contain a specific handshaking protocol. The HP-GL driver uses the specified handshaking
protocol to configure the internal buffers and communication port of the plotter appropriately.
Failure to configure the plotter properly will generally result either in no plot, or a plot which starts
correctly but fails midstream. Plotter buffer configuration is unnecessary for GPIB I/O channels or
if the plot will be incorporated into other software (such as WordPerfect).
RS-232 connections
HP plotters, and this driver, support all three “handshaking” protocols of the RS-232 communication
line; XON/XOFF, DTR and ENQ/ACK. See the discussion under the ASYNC I/O channel for a
description of these terms.
For RS–232 output through COM1 or COM2, the plotter will be properly configured by the software
for either XON/XOFF handshaking, ENQ/ACK handshaking or DTR hardware handshaking (see
D-23
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP-GL Pen Plotters
I/O channel information). The DTR hardware handshaking is the most robust since it cannot be
locked up by software. However, it requires that DTR line from the plotter be connected to the
CTS line of the COM port; other modem control lines can be ignored. The XON/XOFF protocol is
the next most robust. This mode requires connection between only the transmit/receive lines of the
plotter and COM port. ENQ/ACK also requires only transmit/receive lines but may get lost if the
plotter is accidently disconnected during plotting. ENQ/ACK is also generally slower than either of
the other modes and should only be used if the plotter is being driven directly by this software. If
in doubt, specify XON/XOFF.
In addition to agreeing on the handshaking protocol, the plotter and your computer must agree on
the baud rate and number of data bits. These parameters are set by switches on the plotter (see
your manual) and by the DOS command MODE (see your DOS operating system manual – do you
remember where it is?).
WARNING: Be sure that the RS–232 cables are properly configured before selecting the DTR handshaking mode. A breakout box is almost necessary to establish the proper connections. See the
ASYNC I/O channel description for further information.
File output and/or spooled devices
If the output from the HP-GL driver is to be saved on disk, or passed to a spooled output device,
it may still be necessary to include a protocol specified. For FILE and SPOOL I/O channels,
ENQ/ACK should not be used unless the spooling software specifically requests this mode; either
XON/XOFF or DTR however may be specified depending on the final output mode. Since FILE
and SPOOL do not recognize these options, the protocol specifier must be specified as a pre-channel
options (ie. XON*DISK*E:HPGL.TMP). For spooled plotters, such as mainframes or networked plotters,
the handshaking protocol should correspond to the mode the file will later be spooled with to the
hardware device (usually XON/XOFF). For networked plotters and spoolers, both XON/XOFF
and DTR are commonly used; check with your system administrator to determine your specific
requirements. In the event spooler handling on your plotter is more complex, you may choose to
disable all communication initialization in this device by giving a negative sub-device value. Specific
commands can be added by the spooler as necessary.
Most software packages which can incorporate HP–GL files will ignore all communication protocol
specifiers. In these cases, the specifier can be left blank and the driver will default to XON/XOFF.
Digitizer usage and notes
The cursor is marginally implemented as a cross–hair. While it is generally not useful for ANNOTE
or data analysis, it can be used very successfully to digitize data using the bull’s eye pen available
from Hewlett Packard and the READ %DIGITIZE command. The cursor position is “entered” by
pressing the ENTER key on the front panel of the plotter. If the pen is down when ENTER is pressed,
GENPLOT treats the cursor entry as if a “0” had been pressed from the keyboard (equivalent to
an Add during digitize operations). If the pen is up, a “3” character is returned (equivalent to Quit
when digitizing). For the CURSOR command, the pen down will print the value and return to the
cursor immediately while pen up will exit the CURSOR command. See the READ %DIGITIZE command
for additional information on digitizing using the cursor.
GENPLOT does not support setting pen speeds for individual pens; all pens are set to the same
velocity. The driver will not support more than 8 pens and the color is always modulo 8 if GENPLOT
has not previously truncated the value. To avoid unnecessary pen changes, actual pen selection is
deferred until the pen is required for a real vector stroke; ie. PEN 7 will not immediately grab pen 7.
D-24
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP-GL Pen Plotters
At the end of the plot, all pens are replaced in the pen holders and the paper is moved to the lower
left corner, ready for unloading. The P1 and P2 grid rescaling functions are currently disabled.
Testing HP plotter hardware configuration
GENPLOT will not be able to output directly to an HP plotter until the hardware connection is
properly established. This connection is outside the realm of GENPLOT and must be established
under DOS by referring to the DOS manual (MODE command) and the hardware reference for your
plotter. The MODE command should be placed in your AUTOEXEC.BAT since it must be executed every
time your computer is rebooted. After establishing the connection and setting the communication
parameters with the MODE command, insert a sheet of paper and initialize the plotter. The operation
of the plotter can be tested as follows (replace COM1 with COM2 as necessary):
C:> copy con com1:
PD;PU;
∧Z
(the <ctrl>Z character)
C:>
PU and PD are pen up and pen down instructions. If the hardware is properly configured, you
should see the pen move down and up. If not, recheck your manuals to establish correct baud rates,
number of data bits, parity, etc.
Example DEVICE.DAT entries for HP-GL devices
HP7475
HP7550
COLORPRO
HPDISK
HP-GL
HP-GL
HP-GL
HP-GL
05
05
07
06
01
01
01
01
x
x
x
x
x
x
x
x
06
06
06
06
ASYNC*COM1*XON
HP 7475 on COM1
ASYNC*COM2*DTR*BAUD=9600,7,n,1
ASYNC*COM1*XON
HP ColorPro on COM1
XON*DISK*QUERY
HP 7550 disk output
D-25
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP LaserJet devices
HPRASTER.DRV
Byte Stream
Cursor support
Linewidth
Sub–devices
Fully implemented
Not implemented
Fully implemented
00 =⇒ low resolution debugger
01 =⇒ HP LaserJet II printers
02 =⇒ HP PaintJet
03 =⇒ HP DeskJet
none
RASTER
Secondary parms
Related drivers
YOU HAD BETTER READ ME! The HPRASTER driver is now obsolete. It has been replaced
with the individual drivers LASERJET, PAINTJET, DESKJET and IBM4019 to save memory and to
expand the capabilities. Some of the limitation mentioned in this section no longer apply to the
newer drivers. This section is included only for backward compatibility.
Device
Sub–device
Secondary
Debug
LaserJet
0
1
PaintJet
2
–
1
2
3
4
0
10x10 DPI
300x300
150x150
100x100
75x 75
180x180 1 color
(white,black)
180x180 3 color
(white,black,red,green)
180x180 7 color
(white,black,red,green,yellow,blue,magenta,cyan)
180x180 15 color
(white,black,red,green,yellow,blue,magenta,cyan)
device 3 has only 7 unique colors.
90x90 1 color
(white,black)
90x90 3 color
(white,black,red,green)
90x90 7 color
(white,black,red,green,yellow,blue,magenta,cyan)
90x90 15 color
(white,black,red,green,yellow,blue,magenta,cyan)
(?)
300x300
150x150
100x100
75x 75
1
2
3
4
5
6
7
DeskJet
3
Resolution
1
2
3
4
HPRASTER generates output for raster mode HP devices with square pixels (same horizontal and
vertical resolution), including the HP LaserJet I/II, HP DeskJet, HP PaintJet. Other raster devices
(such as dot matrix printers) are supported by RASTER.
D-26
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP LaserJet devices
Linewidth control is enabled on all devices in this driver. The linewidth mode allows varying
linewidths and a more professional quality output at the expense of processing time. The linewidth
mode looks poor below 100 dpi and the RASTER is suggested for the low resolution modes.
In actual operation, the HPRASTER driver is very different from vector oriented drivers such as EGAVGA.
In vector oriented drivers, each vector is drawn on the physical page as it is generated. Raster devices,
however, must internally buffer all of the vectors and, and output the page only after the entire plot
is complete. A entire bit mapped image of the plot must be generated and dumped to the device
at the specified resolution; it is not possible to output partial plots. There is insufficient memory
to hold the entire bit–map so the driver operates in two passes, a vector collection pass followed by
a vector to raster conversion pass. No plots are generated until the vector collection pass has been
terminated when the device is closed down.
Actually plotting only occurs after all plots to the device have been generated and the device has
been closed down. During plot generation, the driver simply stores a list of the vectors in a temporary
file with a name of the form T$xxxx.PLT. This name cannot be changed and will either be created
in the directory pointed to by the TMP environment variable or in the current directory. The I/O
channel specifies where the final plot is sent, not this temporary file. Vector collection continues
until the device is completely shut down by either quitting GENPLOT or by changing devices.
IMPORTANT NOTE: This indeed means that physical plotting does not occur at the end of
each plot but only when the device is changed. (Hint: If you want to force the output immediately,
simply reinitialize the device using the DEVICE command.)
When the raster device is closed, it enters the second phase of operation, the vector to raster
conversion. The vector file is sorted and conversion to a raster image occurs in bands, each band
typically representing either 8 or 24 pixel lines on the output page. During the scan conversion,
the driver outputs statistics on the number of vectors active in the band, the number of vectors
processed and the total number of vectors on the plot. After each page, a form feed is sent to the
printer and the next stored graph is begun. The output from the scan conversion is directed to the
I/O channel specified in DEVICES.DAT.
Raster images are extremely large and a 300 DPI plot requires almost 1 Megabyte for a full page.
Such images should be directed immediately to the printer if at all possible. While RAM disks can
easily hold the unsorted vector list (T$xxxx.PLT above), they are unlikely to be able to hold many
300 DPI raster images. Raster processing time scales quadratically with the linear resolution, but
the code has been optimized for speed and actual transfer of the image to the printer turns out to
be the rate limiting step in all cases. Each subdevice supports different levels of data compression;
the “best” compression for each device is implemented.
WARNING: Although the DESKJET and PAINTJET supports all LASERJET commands sequences, the optimization for the LASERJET becomes extremely slow on the DESKJET and PAINTJET. Use the appropriate subdriver instead. Someday HP will implement an intelligent optimization
for the LASERJET as well.
Sample DEVICES.DAT file entries:
¾
HP300
HP150
PJ180
PJ90
½
»
HPRASTER
HPRASTER
HPRASTER
HPRASTER
01
01
02
02
01
02
02
07
01
01
07
15
DISK*PRN
DISK*PRN
DISK*PRN
DISK*PRN
300
150
180
90
DPI
DPI
DPI
DPI
HP LaserJet
HP LaserJet
with 7 colors
with 15 colors
¼
D-27
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP LaserJet devices
HP LaserJet printers
The HP LaserJet can operate at either 75, 100, 150 or 300 dpi resolutions. A 75 dpi image looks
similar to an EGA screen dump, generates only 56 kB of raster information and prints reasonably
fast. The 150 dpi is reasonable, generating 220 kB of raster information while 300 dpi generates 860
kB. The 150 dpi resolution is compatible with full page plotting on all HP LaserJet printers while
the 300 dpi may require additional memory to utilize the full page. At 300 dpi with HP’s dippy
uncompressible data format, several minutes are required just to transfer the raster information
to the LaserJet itself. Have fun waiting for nice looking 300 dpi resolution. The compression
implemented in this driver is a real hack job and, while outputting at least twice as fast on a
LASEREJET, drives the PAINTJET and DESKJET crazy.
Plots at 300 dpi plots are very similar in quality to POSTSCRIPT output and are easily of publication
quality.
Memory constraints: HPRASTER.DRV
There is no equivalent of VSORT (see RASTER) for this driver. The limits are 67,032 total vectors with
no more than 504 vectors active within any band. Normally, the limits are reached only if the plot
has been flipped (FLIPXY) and there are a large number of vectors at a constant X value (like lots
of zeros). RASTER2 can be used for LASERJET output if these limits are exceeded.
D-28
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP LaserJet devices
HP LaserJet at 75 Dots Per Inch
HP LaserJet at 150 Dots Per Inch
HP LaserJet at 300 Dots Per Inch
D-29
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
IBM4019 Laser Printer
IBM4019.DRV
Brief
1.
2.
3.
Byte Stream
Cursor support
Linewidth
Fully implemented
Not implemented
Fully implemented
Sub–devices
01
02
03
04
Secondary parms
Summed key (bit settings) for control of various options
+01 =⇒ Single dot mode for LT 0 SYM 0
+02 =⇒ Suppress page eject on last plot
+04 =⇒ Suppress reset sequence on open/close
+08 =⇒ Suppress linewidth capability
+16 =⇒ Suppress data compression
+32 =⇒ Suppress blank lines at top of scan
+64 =⇒ Eject current plot before next starts
Related drivers
LASERJET
=⇒
=⇒
=⇒
=⇒
300 dpi resolution
150 dpi resolution
100 dpi resolution
75 dpi resolution
Notes:
Secondary parameter +08 is currently not implemented
Use secondary parameter +64 to force plots out before further drawing
To incorporate plots into documents (such as TeX), use secondary parameter +6 or +38 to
disable page eject, reset sequences, and optionally blank lines.
General Description
The IBM4019 driver generates raster mode output for the IBM 4019 LaserPrinter (also known as
the IBM LaserPrinter E). Since the IBM 4019 can emulate an HP LaserJet, this driver is essentially
identical to the LASERJET driver and generates similar output. The only difference between the
drivers is the output of an escape sequence to switch the IBM 4019 from whatever mode is currently
operating to HP LaserJet emulation mode (mode 2) at initialization, and a sequence to return the
printer to native PPDS mode (mode 1) when the plot is complete. If you normally operate your
printer in HP emulation mode, use the LASERJET driver instead to avoid the return to PPDS mode.
The LaserJet family is capable of printing at 75, 100, 150 or 300 dpi resolutions. Full page graphics
at 75, 100 and 150 dpi are supported on all models, while a 1 megabyte memory upgrade may be
required for complex graphics at 300 dpi (but not necessarily). Plots at 300 dpi plots are generally
suitable for publication. The 150 dpi resolution is reasonable for draft work and can be used on
slower machines, or on printers without memory expansion. The 100 and 75 dpi resolutions are
comparable to screen dumps and, unless you have a painfully slow machine, should be avoided.
As a raster device, images generate a large amount of output and the I/O channel should be configured to send data directly to the printer if at all possible. Without compression, a 75 dpi image
requires 56 kB while a 300 dpi image requires almost 860 kB. Although processing time scales
quadratically with the linear resolution, this code has been optimized for speed and transfer of the
image to the printer is the rate limiting step. There is no formal data compression implemented in
the printer and several minutes may be required just to transfer a full 300 dpi graph to the printer.
(Have a nice day waiting!). A real hack job data compression algorithm is implemented in this driver
to reduce the time (and size) by approximately a factor of 2.
D-30
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
IBM4019 Laser Printer
Line and dots drawing characteristics
All vectors are drawn in a variable linewidth mode with rounded corners. This mode generates
publication quality output (at 300 and 150 dpi) at the expense of some processing time. At 100
and 75 dpi, the linewidth control begins to appear ragged due to the low resolution. The linewidth
mode currently cannot be disabled. Single dots, such as generated by the mode LT 0 SYM 0, are
drawn as a cross of 5 pixels instead of a single pixel (single pixels are often lost when printing). This
conversion can be disabled, resulting in single points drawn as single pixels, by setting +1 in the
secondary parameter.
Incorporating plots in other software
Many word processing programs (including some versions of TeX) allow insertion of raster plots into
documents. This driver generates all draw commands as relative motions from the current position,
permitting insertion at any position in the document. However, it is almost always necessary to
disable the commands for page feed and resets in the driver by setting +6 in the secondary parameter.
Note that the switch from PPDS to HP emulation is also disabled by disabling the reset sequences.
Compression should be left enabled if possible.
Plots for wordprocessing are commonly drawn in the FLIPXY YES mode to get the correct orientation
with text. However, since the plot defaults to the bottom of the page in this mode, an OFFSET is
required to place the plot at the top of page for correction positioning. If this is not done, the plot
may fall off the “bottom” of the page and not be printed. As an alternative to the OFFSET command,
+32 can be added to the secondary parameter. This eliminate all blank scan lines from the top of
the plot and causes the first non-blank scan to be positioned at the top. While the position of the
plot may shift if additional drawing is done above the axis, this method is usually easier than the
trial and error method of determining the correct offset.
Why plots do not come out immediately
In operation, raster drivers are very different from vector oriented drivers such as EGAVGA. For vector
devices, each line segment can be drawn on the physical page as it is generated. However, since
the entire page must be output at once to the printer, the plot must be drawn in memory. Since
there is seldom a free megabyte of RAM to hold the image, plotting is actually done in two phases.
The first phases simply collects vectors into a temporary file. Once all vectors have been generated,
a vector-to-raster conversion process begins, working in thin bands until the full image is output.
Note, the computer cannot read your mind and the conversion can never start until you explicitely
“end” the graph by doing an erase or starting a new plot.
Since I don’t like waiting for the vector-to-raster conversion between every plot, multiple plots are
normally collected and the conversion process is started only after the device is closed. This can be
modified so plots are output after every page by setting the secondary parameter +64. Alternatively,
reinitialize the device with another DEVICE command when you want the output process started.
During plot generation, the driver stores a list of vectors in a T$xxxx.PLT temporary file, created in
either the directory pointed to by the TMP environment variable or in the current directory. The I/O
channel specifies where the final plot goes, not this temporary file. Once all vectors are collected, the
vector to raster conversion begins. The vector file is sorted and raster conversion occurs in bands,
each typically 8-24 pixel lines on the output page. Scan conversion statistics are output to the screen
during processing. After each page, a form feed is sent to the printer and the next graph is started.
Output from the scan conversion is directed to the I/O channel as specified in DEVICES.DAT.
D-31
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
IBM4019 Laser Printer
Speeding up the printing process
Best suggestion for increasing the output speed is to buy a faster computer. It’s amazing how fast
a 486 processes even the most complex graphs. Short of this, there are several steps to improve the
speed on 286 and 386 machines. Since the conversion process uses the disk as swap space, dramatic
improvements can be realized by shifting temporary files to a RAM disk or by installing a disk cache.
Useful speed (i.e. time to keyboard response) can be further improved by use of a print cache.
1. To redirect temporary files, set the environment variable TMP to point to a directory (or root)
of the RAM disk. The temporary vector files are seldom larger than 200kB/graph even for
complex drawings so even small RAM disk (not in conventional memory please!) are useful.
2. If a hard disk must be used for swap space, install a disk caching program to improve the read
after write speed. Approximately 10 kB are being swapped in and out at any single instant.
3. Finally, use a print cache program (such as PCACHE from Hewlett Packard) to allow GENPLOT
to complete the vector conversion process without waiting for the printer. You can then
continue on with your work while the graph is slowly and painfully transferred to the printer
itself.
WARNING: There is not enough conventional memory below 640 kB for programs as is. Never waste
any space for resident programs unless the payoff is phenomenal. RAM disks and/or disk caches in
conventional memory are useless and should instead only use extended or expanded memory. Also,
always disable the memory wasteful, albeit pretty, TSR control modes of the print cache programs.
Memory constraints
Since raster drivers must do the vector to raster conversion, they require considerably more memory
(18 kB) than display devices. Consequently, although a graph may be drawn to the screen, an
attempt to make the same plot on an IBM 4019 may fail because of insufficient memory to load the
IBM4019 driver. It may be necessary to free memory by deallocating some modules before the driver
will load (see DEALLOC). There are no longer any limits on the number of active vectors allowed,
although the total number of vectors is still limited to approximately 200,000.
If space is critical, the IBM 4019 can also emulate a pen plotter when manually switched to mode 3.
The printer then appears as an HP7475 plotter. Use the HP-GL driver to generate the appropriate
output. The flow control should be set to DTR although it is mostly ignored. Drawing is limited to
150 dpi and no linewidth control is possible. However, the size is comparable to screen drivers and
can almost always be used.
Sample DEVICES.DAT file entries:
¾
IBM4019
IBM150
IBMOW
½
»
IBM4019
IBM4019
IBM4019
01 00
02 00
01 64
01
01
01
DISK*PRN
DISK*PRN
DISK*PRN
300 DPI LaserPrinter E
150 DPI LaserPrinter E
LaserPrinter w/ immediate output
¼
D-32
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP LaserJet Printer
LASERJET.DRV
Brief
1.
2.
3.
Byte Stream
Cursor support
Linewidth
Fully implemented
Not implemented
Fully implemented
Sub–devices
01
02
03
04
Secondary parms
Summed key (bit settings) for control of various options
+01 =⇒ Single dot mode for LT 0 SYM 0
+02 =⇒ Suppress page eject on last plot
+04 =⇒ Suppress reset sequence on open/close
+08 =⇒ Suppress linewidth capability
+16 =⇒ Suppress data compression
+32 =⇒ Suppress blank lines at top of scan
+64 =⇒ Eject current plot before next starts
Related drivers
PAINTJET, DESKJET
=⇒
=⇒
=⇒
=⇒
300 dpi resolution
150 dpi resolution
100 dpi resolution
75 dpi resolution
Notes:
Secondary parameter +08 is currently not implemented
Use secondary parameter +64 to force plots out before further drawing
To incorporate plots into documents (such as TeX), use secondary parameter +6 or +38 to
disable page eject, reset sequences, and optionally blank lines.
General Description
The LASERJET driver generates raster mode output for all HP LaserJet models and compatible
clones (including IBM LaserPrinter E). The family is capable of printing at 75, 100, 150 or 300
dpi resolutions. Full page graphics at 75, 100 and 150 dpi are supported on all models, while a
1 megabyte memory upgrade may be required for complex graphics at 300 dpi. Plots at 300 dpi
plots are generally suitable for publication. The 150 dpi resolution is reasonable for draft work and
can be used on slower machines, or on LaserJets without memory expansion. The 100 and 75 dpi
resolutions are comparable to screen dumps and, unless you have a painfully slow machine, should
be avoided.
As a raster device, images generate a large amount of output and the I/O channel should be configured to send data directly to the printer if at all possible. Without compression, a 75 dpi image
requires 56 kB while a 300 dpi image requires almost 860 kB. Although processing time scales
quadratically with the linear resolution, this code has been optimized for speed and transfer of the
image to the printer is the rate limiting step. HP did not include any formal data compression into
the LaserJet II printer and several minutes may be required just to transfer a full 300 dpi graph to
the printer. (Have a nice day waiting!). A real hack job data compression algorithm is implemented
in this driver to reduce the time (and size) by approximately a factor of 2.
WARNING: Do not use this driver for the PaintJet or DeskJet since the compression algorithm is
handled very poorly by those devices.
Line and dots drawing characteristics
D-33
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP LaserJet Printer
All vectors are drawn in a variable linewidth mode with rounded corners. This mode generates
publication quality output (at 300 and 150 dpi) at the expense of some processing time. At 100
and 75 dpi, the linewidth control begins to appear ragged due to the low resolution. The linewidth
mode currently cannot be disabled. Single dots, such as generated by the mode LT 0 SYM 0, are
drawn as a cross of 5 pixels instead of a single pixel (single pixels are often lost when printing). This
conversion can be disabled, resulting in single points drawn as single pixels, by setting +1 in the
secondary parameter.
Incorporating plots in other software
Many word processing programs (including some versions of TeX) allow insertion of raster plots into
documents. This driver generates all draw commands as relative motions from the current position,
permitting insertion at any position in the document. However, it is almost always necessary to
disable the commands for page feed and resets in the driver by setting +6 in the secondary parameter.
Compression should be left enabled if possible.
Plots for wordprocessing are commonly drawn in the FLIPXY YES mode to get the correct orientation
with text. However, since the plot defaults to the bottom of the page in this mode, an OFFSET is
required to place the plot at the top of page for correction positioning. If this is not done, the plot
may fall off the “bottom” of the page and not be printed. As an alternative to the OFFSET command,
+32 can be added to the secondary parameter. This eliminate all blank scan lines from the top of
the plot and causes the first non-blank scan to be positioned at the top. While the position of the
plot may shift if additional drawing is done above the axis, this method is usually easier than the
trial and error method of determining the correct offset.
Why plots do not come out immediately
In operation, raster drivers are very different from vector oriented drivers such as EGAVGA. For vector
devices, each line segment can be drawn on the physical page as it is generated. However, since
the entire page must be output at once to the LaserJet, the plot must be drawn in memory. Since
there is seldom a free megabyte of RAM to hold the image, plotting is actually done in two phases.
The first phases simply collects vectors into a temporary file. Once all vectors have been generated,
a vector-to-raster conversion process begins, working in thin bands until the full image is output.
Note, the computer cannot read your mind and the conversion can never start until you explicitely
“end” the graph by doing an erase or starting a new plot.
Since I don’t like waiting for the vector-to-raster conversion between every plot, multiple plots are
normally collected and the conversion process is started only after the device is closed. This can be
modified so plots are output after every page by setting the secondary parameter +64. Alternatively,
reinitialize the device with another DEVICE command when you want the output process started.
During plot generation, the driver stores a list of vectors in a T$xxxx.PLT temporary file, created in
either the directory pointed to by the TMP environment variable or in the current directory. The I/O
channel specifies where the final plot goes, not this temporary file. Once all vectors are collected, the
vector to raster conversion begins. The vector file is sorted and raster conversion occurs in bands,
each typically 8-24 pixel lines on the output page. Scan conversion statistics are output to the screen
during processing. After each page, a form feed is sent to the printer and the next graph is started.
Output from the scan conversion is directed to the I/O channel as specified in DEVICES.DAT.
D-34
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP LaserJet Printer
Speeding up the printing process
Best suggestion for increasing the output speed is to buy a faster computer. It’s amazing how fast
a 486 processes even the most complex graphs. Short of this, there are several steps to improve the
speed on 286 and 386 machines. Since the conversion process uses the disk as swap space, dramatic
improvements can be realized by shifting temporary files to a RAM disk or by installing a disk cache.
Useful speed (i.e. time to keyboard response) can be further improved by use of a print cache.
1. To redirect temporary files, set the environment variable TMP to point to a directory (or root)
of the RAM disk. The temporary vector files are seldom larger than 200kB/graph even for
complex drawings so even small RAM disk (not in conventional memory please!) are useful.
2. If a hard disk must be used for swap space, install a disk caching program to improve the read
after write speed. Approximately 10 kB are being swapped in and out at any single instant.
3. Finally, use a print cache program (such as PCACHE from Hewlett Packard) to allow GENPLOT
to complete the vector conversion process without waiting for the printer. You can then
continue on with your work while the graph is slowly and painfully transferred to the printer
itself.
WARNING: There is not enough conventional memory below 640 kB for programs as is. Never waste
any space for resident programs unless the payoff is phenomenal. RAM disks and/or disk caches in
conventional memory are useless and should instead only use extended or expanded memory. Also,
always disable the memory wasteful, albeit pretty, TSR control modes of the print cache programs.
Memory constraints
Since raster drivers must do the vector to raster conversion, they require considerably more memory
(18 kB) than display devices. Consequently, although a graph may be drawn to the screen, an
attempt to make the same plot on a LaserJet may fail because of insufficient memory to load the
LASERJET driver. It may be necessary to free memory by deallocating some modules before the driver
will load (see DEALLOC). There are no longer any limits on the number of active vectors allowed,
although the total number of vectors is still limited to approximately 200,000.
Sample DEVICES.DAT file entries:
¾
LASERJET
HP300
HP150
HPNOW
HPASYNC
TEXHP
½
»
LASERJET
LASERJET
LASERJET
LASERJET
LASERJET
LASERJET
01
01
02
01
01
01
00
00
32
64
00
38
01
01
01
01
01
01
DISK*PRN
300 DPI HP LaserJet
DISK*PRN
300 DPI HP LaserJet
DISK*PRN
150 DPI HP LaserJet
DISK*PRN
LaserJet w/ immediate output
ASYNC*COM1*BAUD=9600 300 DPI LaserJet
DISK*TEX.HP 300 DPI HP for TeX special
¼
D-35
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Null driver
NULDRV.DRV
Byte Stream
Cursor support
Sub–devices
Secondary parms
Related drivers
Ignored
none
none
none
none
The NULDRV is an absolute null driver. Everything goes in but nothing comes out. No error
messages, no returns of useful parameters.
DEBUG.DRV
Byte Stream
Cursor support
Sub–devices
Secondary parms
Related drivers
Fully implemented
Fully implemented (as text input)
01 =⇒ Debugging driver (list everything)
none
none
The DEBUG driver is useful as a debugging tool. In drv DEBUG mode, the device is initialized
with a 1000 dpi resolution. Any operation requested of a device driver is printed out to the I/O
channel with the appropriate parameters in human readable form. While it is extremely useful to
the programmer to have an audit trail of all plot commands, it is also fun for the novice to see what
actually transpires in a plotting session. Be forewarned, the file can get extremely large if complex
plots are generated.
Cursor inputs are requested from the terminal and should be avoided if at all possible.
Example:
DEBUG
DEBUG
01 00
x x 08
DISK*CON
Debug device
NULL
NULDRV
01 00
x x 08
CON
Null device
D-36
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP PaintJet Color Printer
PAINTJET.DRV
Byte Stream
Cursor support
Linewidth
Fully implemented
Not implemented
Fully implemented
Sub–devices
00
01
02
03
04
05
06
07
Secondary parms
Summed key (bit settings) for control of various options
+01 =⇒ Single dot mode for LT 0 SYM 0
+02 =⇒ Suppress page eject on last plot
+04 =⇒ Suppress reset sequence on open/close
+08 =⇒ Suppress linewidth capability
+16 =⇒ Suppress data compression
+32 =⇒ Suppress blank lines at top of scan
+64 =⇒ Eject current plot before next starts
Related drivers
LASERJET, DESKJET
=⇒
=⇒
=⇒
=⇒
=⇒
=⇒
=⇒
=⇒
180
180
180
180
90
90
90
90
dpi 1 color
dpi 3 colors
dpi 7 colors
dpi 15 colors (see Note 4)
dpi 1 color
dpi 3 colors
dpi 7 colors
dpi 15 colors
Brief
1.
2.
3.
Notes:
Secondary parameters +08 and +16 are currently not implemented
Use secondary parameter +64 to force plots out before further drawing
To incorporate plots into documents (such as TeX), use secondary parameter +6 or +38 to
disable page eject, reset sequences, and optionally blank lines.
4. Although device 3 supports 15 colors, only the first 7 are unique.
Color Mapping
Pen
Color
0
white
1
black
2
red
3
green
4
blue
5
magenta
6
yellow
7
cyan
NTSC RGB
(90,88,85)
(04,04,06)
(53,08,14)
(03,26,22)
(03,26,22)
(03,26,22)
(03,26,22)
(03,26,22)
Pen
8
9
10
11
12
13
14
15
Color
orange
purple
brown
dark gray
light gray
pink
light blue
light yellow
NTSC RGB
(72,41,13)
(12,06,24)
(12,08,10)
(15,16,18)
(43,43,45)
(52,06,19)
(03,10,46)
(89,87,31)
General Description
The PAINTJET driver generates raster mode output for the HP PaintJet color printer. The PaintJet
can print at either 90 or 180 dpi resolutions with up to 15 colors (at 90 dpi) or 7 colors (at 180 dpi).
Plots at 180 dpi look reasonable while the 90 dpi is comparable to a screen dumps. Unless you need
the colors or speed, the 180 dpi modes are recommended.
As a color raster device, images consume a large amount of output and the I/O channel should be
configured to send data directly to the printer if at all possible. Without compression, a 180 dpi
D-37
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP PaintJet Color Printer
image with 7 colors would require over 1 MB. Because of the size, compression is always enabled in
this driver and is implemented via the run-length encoding algorithm (mode 1). With compression, a
complex plot will require only 150 kB which, while still large, is reasonable to save on disk if necessary.
Although processing time scales quadratically with the linear resolution and logarithmically with
number of pens, this code has been optimized for speed and printing of the image to the printer is
the rate limiting step.
Line and dots drawing characteristics
All vectors are drawn in a variable linewidth mode with rounded corners. This mode generates
publication quality output (at 180 dpi) at the expense of some processing time. At 90 dpi, the
linewidth control begins to appear ragged due to the low resolution. The linewidth mode currently
cannot be disabled. Single dots, such as generated by the mode LT 0 SYM 0, are drawn as a cross of
5 pixels instead of a single pixel (single pixels are often lost when printing). This conversion can be
disabled, resulting in single points drawn as single pixels, by setting +1 in the secondary parameter.
Incorporating plots in other software
Many word processing programs (including some versions of TeX) allow insertion of raster plots into
documents. This driver generates all draw commands as relative motions from the current position,
permitting insertion at any position in the document. However, it is almost always necessary to
disable the commands for page feed and resets in the driver by setting +6 in the secondary parameter.
Compression should be left enabled if possible.
Plots for wordprocessing are commonly drawn in the FLIPXY YES mode to get the correct orientation
with text. However, since the plot defaults to the bottom of the page in this mode, an OFFSET is
required to place the plot at the top of page for correction positioning. If this is not done, the plot
may fall off the “bottom” of the page and not be printed. As an alternative to the OFFSET command,
+32 can be added to the secondary parameter. This eliminate all blank scan lines from the top of
the plot and causes the first non-blank scan to be positioned at the top. While the position of the
plot may shift if additional drawing is done above the axis, this method is usually easier than the
trial and error method of determining the correct offset.
Why plots do not come out immediately
In operation, raster drivers are very different from vector oriented drivers such as EGAVGA. For vector
devices, each line segment can be drawn on the physical page as it is generated. However, since
the entire page must be output at once to the PaintJet, the plot must be drawn in memory. Since
there is seldom a free megabyte of RAM to hold the image, plotting is actually done in two phases.
The first phases simply collects vectors into a temporary file. Once all vectors have been generated,
a vector-to-raster conversion process begins, working in thin bands until the full image is output.
Note, the computer cannot read your mind and the conversion can never start until you explicitely
“end” the graph by doing an erase or starting a new plot.
Since I don’t like waiting for the vector-to-raster conversion between every plot, multiple plots are
normally collected and the conversion process is started only after the device is closed. This can be
modified so plots are output after every page by setting the secondary parameter +64. Alternatively,
reinitialize the device with another DEVICE command when you want the output process started.
During plot generation, the driver stores a list of vectors in a T$xxxx.PLT temporary file, created in
either the directory pointed to by the TMP environment variable or in the current directory. The I/O
D-38
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
HP PaintJet Color Printer
channel specifies where the final plot goes, not this temporary file. Once all vectors are collected, the
vector to raster conversion begins. The vector file is sorted and raster conversion occurs in bands,
each typically 8-24 pixel lines on the output page. Scan conversion statistics are output to the screen
during processing. After each page, a form feed is sent to the printer and the next graph is started.
Output from the scan conversion is directed to the I/O channel as specified in DEVICES.DAT.
Speeding up the printing process
Best suggestion for increasing the output speed is to buy a faster computer. It’s amazing how fast
a 486 processes even the most complex graphs. Short of this, there are several steps to improve the
speed on 286 and 386 machines. Since the conversion process uses the disk as swap space, dramatic
improvements can be realized by shifting temporary files to a RAM disk or by installing a disk cache.
Useful speed (i.e. time to keyboard response) can be further improved by use of a print cache.
1. To redirect temporary files, set the environment variable TMP to point to a directory (or root)
of the RAM disk. The temporary vector files are seldom larger than 200kB/graph even for
complex drawings so even small RAM disk (not in conventional memory please!) are useful.
2. If a hard disk must be used for swap space, install a disk caching program to improve the read
after write speed. Approximately 10 kB are being swapped in and out at any single instant.
3. Finally, use a print cache program (such as PCACHE from Hewlett Packard) to allow GENPLOT
to complete the vector conversion process without waiting for the printer. You can then
continue on with your work while the graph is slowly and painfully transferred to the printer
itself.
WARNING: There is not enough conventional memory below 640 kB for programs as is. Never waste
any space for resident programs unless the payoff is phenomenal. RAM disks and/or disk caches in
conventional memory are useless and should instead only use extended or expanded memory. Also,
always disable the memory wasteful, albeit pretty, TSR control modes of the print cache programs.
Memory constraints
Since raster drivers must do the vector to raster conversion, they require considerably more memory
(18 kB) than display devices. Consequently, although a graph may be drawn to the screen, an
attempt to make the same plot on a PaintJet may fail because of insufficient memory to load the
PAINTJET driver. It may be necessary to free memory by deallocating some modules before the driver
will load (see DEALLOC). There are no longer any limits on the number of active vectors allowed,
although the total number of vectors is still limited to approximately 200,000.
Sample DEVICES.DAT file entries:
¾
PAINTJET
PJBW
PJ90
PJNOW
TEXPJ
½
»
PAINTJET
PAINTJET
PAINTJET
PAINTJET
PAINTJET
02
00
07
02
02
00
00
32
64
38
07
01
15
07
07
DISK*PRN
DISK*PRN
DISK*PRN
DISK*PRN
DISK*TEX.PJ
7 colors PaintJet
B/W PaintJet
15 colors at 90 dpi
PaintJet w/ immediate output
300 DPI HP for TeX special
¼
D-39
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Postscript
POSTDRV.DRV
Byte Stream
Cursor support
Sub–devices
Secondary parms
Related drivers
Fully implemented
not implemented
01 =⇒ Landscape mode (X axis long)
02 =⇒ Portrait mode (Y axis long)
01 =⇒ 8.5x11 paper (10.5x8.0 plot)
02 =⇒ 8.5x14 paper (13.5x8.0 plot)
03 =⇒ 11x17 paper (16.5x10.5 plot)
DRVQUIC
Postscript is a powerful page description language commonly claimed to be the wave of the future,
despite its hefty price tag and relative slow speed. Devices supporting Postscript hide their internal
resolution one step further from GENPLOT, allowing for an extremely simple driver (though the
human readable commands cause files to be quite large).
Output for Postscript may be directed to any of the I/O channels implemented. Commonly, it is
redirected to a disk file for later spooling since the printers are not known for their speed. All
Postscript drawing is done assuming a resolution of 1000 DPI, which should be adequate for at least
a few more generations of laser printers. The driver assumes that the capabilities of the laser printer
is at least as good as the Apple LaserWriter printer.
Drawing on the page can be done in either landscape or portrait orientation. In landscape mode,
the X axis is aligned along the long side of the paper while in portrait mode it is along the short
edge. Default setting of the laser printer corresponds to the portrait mode; to obtain the landscape
mode, the Postscript coordinate system is rotated by -90 degrees and translated up the page. If the
output from the POSTDRV driver is to be used in another program, the portrait orientation should
be chosen. Note that FLIPXY command also reverses the mode of portrait and landscape, but it is
implemented in software and the resulting data stream is difficult to insert into other programs.
Visibility and linewidth are actually implemented. Linewidth 1 corresponds to 7/1000 of an inch (approximately 1/150). Lines are currently drawn using squared off line segments, Postscript command
“2 SETLINECAP”. A default 0.25 inch border is left on all sides of the plot.
Including Postscript output files in TeX or other typesetting languages
The Postscript files generated by GENPLOT fully conform to the Adobe 1.0 standard and may
be inserted into other text processing programs to include plots in reports. The specific method,
however, depends strongly on the word processing program. In general, though, you should use the
PORTRAIT orientation (sub–device 2) if you are creating such files (as opposed to using FLIPXY).
Note also that GENPLOT inserts a default 0.25 inch border around all plots to cover the un-plottable
area of most laser printers. It may be necessary to take this offset into account when placing figures
from GENPLOT into the text. POSTDRV behaves itself, as much as is possible, by saving the status
of Postscript plotter before drawing and restoring the status when complete.
If the output from POSTDRV does not work immediately, the output file can be edited and the
initialization/termination strings modified as necessary.
Example:
POSTSCRIP POSTDRV
01 01
01
DISK*QUERY
Postscript device
LPR
01 01
01
PRN
Printer attached
POSTDRV
D-40
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Dot Matrix Printers
RASTER.DRV
RASTER2.DRV
Byte Stream
Cursor support
Linewidth
Sub–devices
Secondary parms
Related drivers
Sub–device
0
1
2
3
4
5
6
Fully implemented
not implemented
Fully implemented
00 =⇒ low resolution debugger
01 =⇒ HP LaserJet II
02 =⇒ Epson MX 80 and compatibles
03 =⇒ Okidata 92 and compatibles
04 =⇒ Epson LQ300 24 pin and compatibles
05 =⇒ Gemini class Epson work–alikes
06 =⇒ NEC 2200, Epson LQ800 and compatibles
Negative =⇒ Disable linewidth ability - absolute value sets Sub-device
Negative =⇒ Compress output if possible
Absolute value =⇒ Set resolution according to table below
HPRASTER
Option
1
2
3
1
2
3
1
2
3
1
2
3
1
2
3
Device Supported
Debug
HP LaserJet
(see also HPLASER.DRV)
Epson MX-80
Okidata
Epson LQ-300
(24 pin)
Gemini
Epson LQ-800
(24 pin)
Resolution
10x10 DPI
300x300
150x150
75x75
72x60
72x120
216x120
72x72
216x60
216x120
216x180
72x60
72x120
144x120
180x60
180x120
180x180
RASTER.DRV generates output for many raster scanned devices including HP, Epson, Okidata and
other compatible printers. The newer driver HPRASTER should be used for any HP raster oriented
printers including the LaserJet and DeskJet. RASTER2.DRV is identical to RASTER.DRV except that
the final vector to raster conversion operation must be performed outside of GENPLOT using the
VSORT utility which allows a much larger number of vectors to be drawn (see Memory Constraints
below). The drivers support two different drawing modes, a mode where the linewidth may be varied
and a single pixel drawing mode. In the single pixel mode, all vectors are drawn exactly 1 pixel
in size. The linewidth mode allows varying linewidths and a more professional quality output at
the expense of processing time. The single pixel mode is selected if the sub-device is specified as a
negative integer, or if the resolution differential between X and Y is greater than about 20%.
In actual operation, the RASTER driver is quite different from most other vector oriented drivers.
In vector oriented drivers such as pen plotters, each vector is drawn on the physical page as it is
D-41
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Dot Matrix Printers
generated. Raster devices, however, must internally buffer all of the vectors and, once the page
is complete, send the entire bit–mapped image of the plotting area at full resolution. There is
insufficient memory on a normal PC to directly hold the bit–map so the driver operates in two
passes, a vector collection pass followed by a vector to raster conversion pass.
Actually plotting only occurs after all plots to the device have been generated and the device has
been closed down. During plot generation, the driver simply stores a list of the vectors in a temporary
file with a name of the form T$xxxx.PLT. This name cannot be changed and will either be created
in the directory pointed to by the TMP environment variable or in the current directory. The I/O
channel specifies where the final plot is sent, not this temporary file. Vector collection continues
until the device is completely shut down by either quitting GENPLOT or by changing devices.
IMPORTANT NOTE: This indeed means that physical plotting does not occur at the end of
each plot but only when the device is changed. (Hint: If you want to force the output immediately,
simply reinitialize the device using the DEVICE command.)
When the raster device is instructed to shut down, it enters the second phase of operation, the
vector to raster conversion. The vector file is sorted and conversion to a raster image occurs in
bands, each band typically representing either 8 or 24 pixel lines on the output page. During the
scan conversion, the driver outputs statistics on the number of vectors active in the band, the number
of vectors processed and the total number of vectors on the plot. After each page, a form feed is sent
to the printer and the next stored graph is begun. The output from the scan conversion is directed
to the I/O channel specified in DEVICES.DAT.
Raster images are extremely large and a 300 DPI plot requires almost 1 Megabyte for a full page.
Such images should be directed immediately to the printer if at all possible. While RAM disks can
easily hold the unsorted vector list (T$xxxx.PLT above), they are unlikely to be able to hold many
300 DPI raster images. Raster processing time scales quadratically with the linear resolution, but
the code has been optimized for speed and actual transfer of the image to the printer turns out to
be the rate limiting step in all cases.
Examples:
EPSON
RASTER
02 02
01
PRN
EPSON printer
OKIDATA
RASTER
03 01
01
PRN
Okidata printer
Memory constraints: RASTER.DRV, RASTER2.DRV and VSORT.EXE
The RASTER driver requires more memory than any other drivers (≈ 40 kBytes) because of the raster
to vector conversion code and memory. This size itself represents a tradeoff between the memory
utilization and limitations on the number of vectors which can be plotted. In RASTER, a maximum
of approximately 67,000 vectors may be plotted. However, no more than 504 vectors can be active
in any of the output bands (usually 24 pixels wide). This limit is not particularly difficult to exceed.
Rather than waste more memory in enlarging RASTER, a second driver, RASTER2 exists where the
vector collection and rastering processes are separated. RASTER2 only performs the collection phase
and the vector to raster conversion is done “off-line” using a utility VSORT after GENPLOT has
been exited.
You should consider switching from RASTER to RASTER2 under in two cases; (1) the message Too
many active vectors occurs during the vector to raster conversion phase or, (2) there is insufficient
memory to load the RASTER module. RASTER2 is one of the smallest drivers and should load in the
same memory space where a screen driver was loaded previously.
D-42
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Dot Matrix Printers
RASTER2 generates the temporary file T$xxxx.PLT with the number of vectors limited only to the
available disk space. When the device is closed, it outputs a message indicating that the file needs to
be sorted. To generate the raster output, use the utility VSORT.EXE in the \GENPLOT\UTIL directory.
In VSORT.EXE, the maximum number of vectors and number active in each band are limited to 1
million and 32,000 respectively. The vector conversion time normally becomes unacceptable before
these limits are reached.
The format of VSORT is:
VSORT [[-INFILE] <infile>] [[-OUTIFLE] <I/O channel>]
[-KEEP -DEBUG -COMPRESS -HELP]
If not specified, <infile> defaults to T$0000.PLT and <I/O channel> defaults to the I/O channel
specified when the device was initialized. The --COMPRESS is the only really useful switch and causes
raster image compression on LaserJet output. The --KEEP switch causes the input file to be retained
after sorting (somewhat useless), and the --DEBUG switch sends the output to the terminal screen.
The --HELP option will print a brief help on the format of the command.
The following illustrates the use of RASTER2 to generate a plot at 300 DPI to a LaserJet connected
to the PRN port.
¾
»
GENPLOT: dev sp
Enter primary device driver name: raster2
Enter minor dev # and sub-mode: 1 1
Enter I/O channel information:
DISK*PRN
GENPLOT: axis quit
VSORT required on: T$0000.PLT
C> VSORT T$0000.PLT
Plot file opened as: PRN
Merging
3 chains ...
Band: 109
Active:
38 (
Execution terminated : 0
C>
½
67)
Processed:
507 (
507)
¼
HP LaserJet printers
The HP LaserJet can operate at either 75, 150 or 300 dpi resolutions. The newer driver HPRASTER
supports the entire family of raster devices in a consistent manner and should be used, if possible,
instead of RASTER. A 75 DPI image looks similar to an EGA screen dump, generates only 56 kB of
raster information and prints reasonably fast. The 150 dpi is reasonable, generating 220 kB of raster
information while 300 dpi generates 860 kB. The 150 DPI resolution is compatible with full page
plotting on all HP LaserJet printers while the 300 DPI may require additional memory to utilize the
full page. At 300 DPI with HP’s dippy uncompressible data format, several minutes are required
just to transfer the raster information to the LaserJet itself. Have fun waiting if you really want 300
DPI resolution.
D-43
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Dot Matrix Printers
In single pixel mode, the 150 DPI mode looks better than the 300 DPI. Examples of the three possible
resolutions are shown below (real size). With linewidth enabled, 300 DPI plots looks similar to the
POSTSCRIPT output and are of publication quality.
Occasionally, it is nice to save the plot images to disk. Rather than fill disks with mostly blank raster
files, a compression algorithm for HP images is built into the driver; setting the secondary parameter
to a negative value will enable compression. Since compression factors of 100 are normal, compression
is essential if you want keep images around on disk. While the compression was easy, HP’s engineers
did not implement de-compression in the LaserJet logic and the file must be re-expanded before
being sent to the printer. A filter, HPPLOT.COM, is included for expanding compressed files to full HP
format. If IMAGE1.HP is a compressed LaserJet file, the command HPPLOT <IMAGE1.HP >PRN will
cause the uncompressed file to be sent to the printer. HPPLOT.COM is located in the \GENPLOT\UTIL
directory.
MX–80, Okidata, Gemini and LQ-300 dot-matrix printers
The MX–80, Okidata and Gemini graphics printers provide adequate output for a modest investment
(especially since almost everyone has one anyway). The speed, though, leaves much to be desired.
The LQ–300 and compatible 24 pin printers produce plots rivaling the output of a laser printer,
though still limited in speed. Each of these devices, except the Okidata, support various resolution
models as described below. The Okidata supports only a single resolution of 72x72 pixels.
The MX-80 and Gemini printers are very similar, differing only in minimum possible line spacing.
The Epson compatibles provide a 1/216 of an inch minimum spacing while the Gemini class printers
only provide 1/144 of an inch. To determine which compatible you have, check the manual under
the <ESC>J command and determine the units of the line spacing. The 72x60 resolution in both
cases is reasonably fast and suitable for simple graphs and analysis. The second mode uses double
density printing to achieve good “across page” resolution while still limited to the same “down
page” resolution. The third third mode enters the ridiculous resolution mode; the X axis resolution
is 1/3 (1/2 for Gemini class) of a dot wire width! The plots become increasingly sharp, but time
to plot increases proportionately. A complete plot at the highest resolution requires several minutes
to print. Example plots of the three resolutions for an Epson MX–80 are shown below. No data
compression is implemented for any of the dot-matrix printers.
The LQ–300 printer has three times as many wires in the same sized print head. This automatically gives the printer the 216 pixels/inch “down page” resolution. The three resolutions available
correspond to double and triple dot density across the page during printing. Note that the MX–80
modes will also work with the LQ–300 although they waste the available resolution.
Debugging Mode
The debugging mode, sub–device 0, is for fun only. Specify FILE*CON as the I/O channel and see
how poor a 10x10 DPI plot looks.
D-44
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Dot Matrix Printers
Epson MX–80 at 72x60 Dots Per Inch
Epson MX–80 at 72x120 Dots Per Inch
Epson MX–80 at 216x120 Dots Per Inch
D-45
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Tektronix 40xx
TEKTRX.DRV
Byte Stream
Cursor support
Sub–devices
Secondary parms
Related drivers
Fully implemented
Cross–hair only. No box mode.
01 =⇒ Tektronix 4010 (1023x767 pixels, no FS mode)
02 =⇒ Tektronix 4014 (1023x782 pixels, FS mode)
03 =⇒ Tektronix 4105 and equivalents
04 =⇒ Selanar SG200 for VT100 terminals
05 =⇒ VI550 Emulator – Retrographics
06 =⇒ HiReZ 100
07 =⇒ Digital Engineering TAB terminal
08 =⇒ VT 340/Tek (Kermit) terminals
Set to 9600/baud for actual “real” 401x terminals (see below)
none
The TEKTKX supports almost anything that looks like a Tektronix 4010, 4014, 4105 or 4205 device,
including innumerable clone terminals. However, all of the clones require strange and different
escape sequences to enter and leave the graphics modes and hence trying to run another emulator
may require modification of the driver source code.
You may ask, why put a Tektronix terminal on a PC? The 4105 is a very fast, high resolution color
screen which complements the PC. Running at 19200 baud, it rivals the drawing speed of an EGA.
Likewise, the TEK 4014 is an extremely high resolution screen capable of extremely fast drawing
rates. If you don’t want a dual monitor on your PC, a Tektronix terminal attached to a COM port
is almost as attractive.
However, the early 4010 and 4014 were not perfect. When busy, such as erasing the screen, they
ignore incoming characters, leading to the ugly kludge of sending SYN characters during such times.
The secondary parameter indicates to the driver the number of SYN characters which it must send,
based on the actual operating baud rate. A 0 secondary parameter indicates that NO SYN characters
are necessary (such as on emulators). One is defined as the number required at 9600 baud value,
while 2 specifies the number at 4800 baud etc. In order to run at 19,200 baud, it is necessary to
hardware modify the PC communication card and run with an external clock; poor documentation
on doing this is available.
Notes on the TEK 4105: The 4105 must be configured with <ctrl>G (07) as the bypass cancel
character.
Examples:
L1TEK
TEKTRX
01 00
x x x
07
ASYNC*COM1*XON
Fast TEK4010 on COM1
L2TEK
TEKTRX
01 01
x x x
07
ASYNC*COM2*XON
Slow TEK4010 on COM2
D-46
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
TIFF interchange format
TIFF.DRV
Byte Stream
Cursor support
Linewidth
Sub–devices
Secondary parms
Related drivers
Fully implemented
Not implemented
Fully implemented
1 =⇒ 10.6”x8.0” at 226 dpi resolution
2 =⇒ 8.0”x10.6” at 300 dpi resolution
3 =⇒ 8.0”x8.0” at 300 dpi resolution
0 =⇒ Compressed output. Full defined area.
1 =⇒ Compressed output. Limit area to written.
16 =⇒ Uncompressed output. Full defined area.
17 =⇒ Uncompressed output. Limit area to written.
RASTER
Quick description of new TIFF driver. It is a TIFF 5.0 implementation writing TIFF B compatible
files. This is a “restricted” output format to conform to the TIFF class X standards for Standard
TIFF Black-and-White Scanned Images. Since TIFF files are exclusively for inclusion in desktop
publishing systems, the output is in portrait mode rather than the normal landscape modes.
Compression is standard TIFF/B packbits structure. This is extremely efficient for the graphics
based output. Specifying 16 or 17 disables the compression and outputs as straight bit-mapped text
for unconforming readers. Secondary parms 1 and 17 specify the output as extending only as far as
the data is written. Parms 0 and 16 will always mark the TIFF file as being the full defined size.
Parms 1 and 17 TIFF file size will depend on the extent of the data.
Device is a RASTER type device and limited by the constraints similar to the RASTER driver. No
VSORT exists.
D-47
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Word Perfect
WPDRV.DRV
Byte Stream
Cursor support
Sub–devices
Secondary parms
Related drivers
Disk channel only emulated
None
None
None
None
GENPLOT plots can be directly incorporated in WordPerfect 5.0 documents using the WPDRV.DRV
driver. The WPDRV.DRV driver outputs the graphics commands in the native WordPerfect 5.0 graphics
format (WPG). Figures generated from by this driver can be incorporated directly into your text
files using the Graphics Command <Alt>F9 and can be previewed using the Print/View commands
(<shift>F7). WordPerfect itself provides facilities for scaling the plot to any desired size. The driver
supports multiple colors and continuously variable linewidths.
The driver supports no sub-devices or secoundary parameters. The maximum plotting area is arbitrarily set at 11x11 inches allowing either landscape or portrait orientation. The default orientation
(FLIPXY NO) is portrait mode which is appropriate for inclusion into text. The WPG format does
not handle multiple pages in a single file and hence only the last plotted page remains when the
driver is closed. The I/O channel must point to a valid DISK* option and all files are given a .WPG
default extension. Examples of valid I/O channels are:
disk*query
disk*cmdline
Query at run time for the filename
query at run time for the filename but take it from the
current command line if possible.
Generates a file of the form T$xxxx.WPG
Output to the given file name.
disk*default
disk*<name>
Recommended I/O channels are disk*query and disk*cmdline. A sample line for the DEVICES.DAT
file is:
WP50
WPDRV
01 01
15
DISK*QUERY
WordPerfect 5.0
D-48
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O Channels
I/O CHANNELS SUPPORTED
Many of the above device drivers (main exception being the screen drivers) act as a byte stream
of information destined for the plotter. In these cases, the I/O channel directs the byte stream to
the specific port on the PC where the plotter is physically connected. Just as easily, the bytes may
be directed to a file for later spooling to the plotter. Several classes of I/O channels are currently
implemented including, FILE, ASYNC, GPIB and SPOOL. They are described below with most of their
possible forms.
Not all device drivers use the I/O channel. Only devices which connect via various parallel and serial
ports can make practical use of the I/O channel. Screen drivers, for example, make sense outputting
only to the screen. Their I/O channels may be used for other purposes. See the above sections to
determine if a device is a byte-stream driver that utilizes the I/O channel.
The I/O channel specification consists of a character string with at least two subfields separated by
the ’*’ character. The general format is:
[<pre opts>*]<io channel>*[<sub channel>*<channel opts>]
The <pre opts> section optionally specifies default initialization parameters for all I/O channels.
See the ASYNC I/O driver section for information on the default handshaking protocols. Multiple
pre-options may be given. Valid pre-options are
• LEN=nnn Sets maximum output buffer size to nnn characters
• DTR Default to DTR handshaking protocol
• XON Default to XON/XOFF handshaking protocol
• ENQ Default to ENQ/ACK handshaking protocol
The first sub-field not recognized as a <pre opt> is taken as the name of an I/O channel. If no
sub channel is found, the entire string is instead assumed to be the sub channel of the FILE I/O
channel. Hence, I/O channel specifications of CON and FILE*CON are equivalent.
The final sub-field, <channel opts>, may consist of any number of parameters depending on the
complexity of the I/O channel. An extremely simple I/O channel would be specified by FILE*CON,
where FILE is the <io channel> and CON is the <sub channel> (actually this directs output to the
console). The <io channel> must correspond to one of the I/O channels in the C:GENPLOT directory,
such as FILE, ASYNC, GPIB or SPOOL. The choices for <sub channel> and <channel opts> depend
on the specific I/O driver selected.
D-49
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O Channels
The possible drivers and an overview of their modes are shown below.
<io channel>
FILE
ASYNC
SPOOL
GPIB
GPIB2
NOVELL
SCREEN
<sub channel>
DEFAULT
QUERY
CMDLINE
<name>
CON
PRN
LPT1,LPT2,LPT3
COM1,COM2
COM1
COM2
Description
COM1
COM2
<devname>
<devname>
<username>
none
Mainframe spool
(see note below)
PC-2A GPIB
IOtech GPIB
NOVELL spooled printers
Screen devices
T$xxxx.PLT files
Request at run time
Read at run time
Specific filename
Console
Default printer
Specific printer
Don’t USE!!
RS-232 on COM1
RS-232 on COM2
<channel opts>
none
XON
ENQ
DTR
initialization
strings
none
none
none
none
Some examples of valid I/O channels are:
• PRN Output via FILE I/O channel to printer
• FILE*QUERY Output via FILE I/O channel but query for filename
• LEN=80*FILE*E:TEST Output via FILE I/O channel to e:test file but limit output buffer to 80
characters.
• DTR*ASYNC*COM1 Output to COM1 port via ASYNC I/O channel using DTR handshaking by default.
• DTR*FILE*E:TEST Output to file e:test but initialize the device driver for DTR handshaking
(pre opt).
• NOVELL* Output to default printer of Novell netwrok
Notes: The SPOOL channel supports output of plot commands to a mainframe computer connected
through the COM1 or COM2 port using the XON/XOFF protocol. The user must write appropriate
software on the mainframe computer to handle receipt of the plotting commands and direction to the
appropriate spool queue. The protocol of the transfer is described further under the SPOOL channel.
D-50
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O to disk file
FILE I/O channel:
The FILE I/O channel supports output to the parallel printer ports, the console (for debugging),
as well as to disk files. On a PC, the console, parallel printer ports and the serial communication
ports are all implemented as files (see sidelight below). However, because of the lack of flow control
on the serial communication ports (COM1 and COM2) in DOS, these are implemented separately as
the ASYNC channel. The FILE I/O channel is also used to direct the plot commands into a file
which can be spooled later to a device. Alternatively, these files could be sent to a remote system
for output to plotters attached to a mini or mainframe computer.
Sidelight: On a PC, almost all input/output devices are treated as generalized file (also
called device drivers). These “device files” include the console, the printer and serial lines.
Consequently, a file opened on a PC can be either a real file or a device (and it is somewhat
difficult to tell the difference). Devices included in standard DOS are PRN, LPT1, LPT2, LPT3,
CON, COM1, COM2, and NUL referring to the printer, parallel line printer ports 1–3 (one of which
is commonly directed to PRN), the console, the communication ports and the null device. Once
you understand this usage of generalized devices, the DOS command COPY <file> CON will be
seen to be synonymous with TYPE <file>.
The <sub channel> parameter to the FILE channel is essentially the filename (or device name)
which is to be opened. If the DEFAULT file is specified, the channel will create a filename of the
form T$xxxx.PLT where xxxx is a the first number which generates a unique unused filename. If the
environment variable TMP exists, this temporary file will be created in the directory pointed by the
variable. Typically, TMP will be set to a directory on a RAM disk for improved speed. Files should
only be directed to the RAM disk if they are to be printed immediately.
If the <sub channel> is specified as QUERY or CMDLINE, GENPLOT will prompt at execution time
for the filename to use. The inputted filename can be DEFAULT or any other legal pathname or
device. QUERY and CMDLINE differ only in how the name is requested. QUERY always queries from the
user directly through a fortran read statement. CMDLINE, alternatively, reads the filename from the
current command stream (as other GENPLOT commands), allowing a single command line such as
dev <device> myfile.out to output to a myfile.out file.
Files are always opened in binary mode, since a ∧Z in DOS marks the logical end of a file. Copies
of the file to other devices should also use the binary flag of DOS to guarantee transfer of the entire
file (see DOS COPY command).
The EXAMPLES
•
FILE*PRN – output to currently configured printer output. This may be redirected
to a COM port via the MODE command.
•
FILE*LPT1 – direct output to specific parallel printer ports.
•
FILE*CON – direct output to the console (user screen – always fun!).
•
FILE*DEFAULT – Default disk output using filenames of the form T$nnnn.PLT.
•
FILE*e:junk – Disk output to the file e:junk.
•
FILE*QUERY – Filename for output is queried from user.
•
FILE*CMDLINE – Filename read from current command line of user.
•
FILE*NUL – Output to never never land.
D-51
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O to COMx port
ASYNC I/O channel:
The ASYNC I/O channel supports output through COM1 and COM2 to devices connected via RS–232
interfaces. Officially, the COM ports are supported by DOS as disk files, but DOS does not handle
any flow control to prevent devices from losing data. The ASYNC channel reconfigures the COM1 or
COM2 port as an interrupt driven asynchronous port and supports three type of flow control: XON–
XOFF, ENQUIRE–ACKNOWLEDGE, and DTR–CTS control. The specifics of the flow control
modes are discussed later.
The ASYNC channel does not normally set the baud rate or transfer characteristics of the COM
line, although these may be specified by a <channel opt>. The characteristics of the line should
normally be set using the DOS MODE command before entering GENPLOT; GENPLOT will then
not have to diddle with any of the chip parameters. Most devices can be configured for 9600 baud
with a typical setting of MODE COM1:9600,n,8,1. These parameters set the baud rate to 9600, no
parity, 8 data bits and 1 stop bit. The device being communicated with must have its communication
parameters set to the same values. See the DOS MODE command for details. Once configured, the
device should be tested in something simple like BASIC before entering GENPLOT.
The <sub channel> parameter to ASYNC must be either COM1 or COM2 indicating the appropriate
output port. The <channel opts> field is optional and, if present, specifies the flow control to be
used and the setting of the baud rate. Valid flow control specifies are XON, ENQ or DTR corresponding
to the XON/XOFF, ENQ/ACK or DTR/CTS protocols. If no flow control option is selected, the
default passed from the <pre opts> is used or XON/XOFF defaults. Some device drivers, however,
may request a preferred flow control, such as ENQ/ACK, if the user has no preference.
The baud rate and line parameters may also be set by the <channel opt>. The parameters of the
BAUD channel option are identical to the corresponding DOS MODE command. To set output to
COM1 using DTR handshaking protocol with the port configured at 9600 baud, no parity, 8 data bits
and 1 stop bit, ASYNC*COM1*DTR*BAUD=9600,n,8,1.
When the ASYNC I/O channel is initialized, resident code is loaded for an interrupt driven RS-232
driver. XON/XOFF and DTR/CTS flow control is implemented directly in the interrupt driver.
Both input and output are buffered from the RS-232 serial line with a buffer size of 256 bytes each.
Upon receipt of an XOFF character (∧S), the interrupt routine will cease transferring within 2
characters (assuming XON/XOFF protocol). Transmission will continue upon receipt of the XON
character (∧Q). The interrupt driver will also send a ∧S automatically when the buffer is within 80
characters of full. ∧Q is transmitted to restart transmissions from the device when 160 characters
are available in the buffer again. In XON/XOFF and ENQ/ACK modes, the DTR and RTS modem
control lines always held true and the incoming modem control lines are ignored.
If the DTR/CTS protocol is enabled, GENPLOT will monitor the incoming CTS line from the
device. Upon initialization, DTR (Data terminal ready) and RTS (request to send) are brought
true, indicating that the PC (a terminal) is ready to start transmitting and receiving data. As long
as CTS (clear to send) is true, data transmission will occur. If CTS goes false, however, transmissions
is halted until the line returns to true state. Other modem control lines are ignored. Transmission
of data to the PC is allowed without handshaking; the PC will never drop DTR or RTS.
Cabling RS-232 devices
Connecting RS–232 plotters to the PC is, and always will be, a problem. The first step is to refer to
the manual which may explicitly explain how the connection needs to be made, sometimes involving
the fabrication of a special interface cable. The difficulties arise for two reasons. First, (and in
a sense fortunately), very few devices implement the entire RS–232 handshaking protocol. Hence
D-52
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O to COMx port
one is not sure what any particular device will require to operate properly. Secondly, there are
two types of devices in the world, DTE’s (data terminal equipment) and DCE’s (data connection
equipment). A DTE is meant to be connected to a DCE, with the hardware handshaking and data
communication handled between them.
Unfortunately, both the PC and most plotters are configured as DTE’s and hence do not know how
to talk with each other. When this occurs, both the PC and plotter talk on the same wire as the
other, and both listen to the same wire; hence nothing can ever be transmitted. The solution is
a “null” modem, a cable which exchanges the talk/listen wires (pins 2 and 3 of a 25 pin RS-232
connector - pin 7 is the signal ground) as it goes from the PC to the plotter. Both DTE’s are also
waiting for signals from a DCE telling them that it is ok to transmit data, signals which will never
be received. The normal fix is to let each DTE tell itself that it is ready; this is done by jumpering
pins on the 25 pin connector at either end, tying RTS to CTS (pin 4 to pin 5), and DTR to DSR
and LI (pins 6,8 and 20). This must be done on both connectors, but no wires are run from one
device to the other.
Transmit
Transmit
Receive
Receive
GND
GND
CTS
RTS
CTS
RTS
DTR
DSR
LI
DTR
DSR
LI
This jumpering works fine for XON/XOFF and ENQ/ACK protocols but bypasses all hardware
handshaking making DTR/CTS impossible. A solution for HP plotters is to route the DTR line
from the plotter to the PC and connect it to the CTS line of the PC. At the plotter, RTS/CTS and
DTR/DSR/LI should be jumpered. At the PC, only DTR/DSR/LI need to be jumpered; CTS is
connected to the plotter and RTS is ignored. Without getting deeply involved in the cabling process,
I suggest the judicious use of a RS-232 breakout box to determine exactly which connections are
required to complete the circuit.
EXAMPLES:
•
ASYNC*COM1*XON – Output to COM port 1 with XON–XOFF protocol
•
ASYNC*COM2*BAUD=1200 – Output to COM port 2 with default XON–XOFF protocol
•
ASYNC*COM1*ENQ – Output to COM port 1 with ENQ–ACK protocol
•
ASYNC*COM2*DTR*BAUD=9600,p,7,1 – Output to COM port 1 using hardware handshaking
D-53
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O to GPIB card
GPIB I/O Channel:
The GPIB (General Purpose Instrument Bus) I/O channels support input and output to plotting
devices connected to an IEEE–488/GPIB interface card. Unfortunately each GPIB interface card
manufacturer uses a slightly different protocol for communicating with user programs. Each variety
of GPIB cards requires a different I/O driver. We currently support two manufacturer’s GPIB cards:
the PCII/PIIA/PCMC/PCAT cards from National Instruments and the GP488A/B/2 cards from
IOTech. The National Instruments boards use the GPIB driver and the IOTech cards the GPIB2
driver. (Note: Several other manufacturers also sell the National Instruments board under their
own name.)
I/O Channel Examples:
•
GPIB*HPPLOT – Open a device called HPPLOT on the GPIB network using the
National Instruments device driver.
•
GPIB2*HPPLOT – Open a device called HPPLOT on the GPIB network using the
IOTech device driver.
GPIB – National Instruments
This driver is compatible with the National Instruments PCII, PCIIA, PCMC and PCAT boards.
Software access is provided through a DOS device driver loaded by the command DEVICE=GPIB.COM
in CONFIG.SYS. The National Instruments utility IBCONF configures GPIB.COM with specific information about each device. The logical name, GPIB address, timeout, and terminator attributes of
each device are configured with IBCONF. The I/O channel accesses devices by their logical name
only. The utility IBIC, provided to test devices manually, should be used to verify the configuration before attempting to access the device from GENPLOT. (If your GPIB software includes these
utilities and driver, it is probably compatible with this I/O channel.)
The <sub channel> specifies the logical name (see IBCONF above) of the device. Internally the
subroutine IBFIND is used to open the device, followed by device reset via IBCLR. The GPIB card
and the bus itself are not reset. When the I/O channel is closed, the device is returned to the local
state and taken off-line by IBLOC and IBONL.
Commands are output to the device using IBWRT. A <NULL> terminator (ascii 00) is appended to all
writes. IBCONF should be set to assert EOI with the last byte of the write. EOS should not be
set to <NULL>. (WARNING: The string <CR><LF> is not appended to strings and cannot be used as
the terminator. If your plotter does not utilize the EOI line, it cannot be accessed by GENPLOT.)
Data is input from the device using IBRD. Reads must be terminated by either EOI only or by the
sequence <CR><LF>. If <CR><LF> is used, IBCONF should be configured with <LF> as the EOS byte
and set to terminate reads on EOS. Other terminating sequence may not be properly handled by
GENPLOT.
On errors, the GPIB I/O driver will report the value of IBSTA and IBERR. The symbolic names
correspond to those in the National Instruments documentation. See your manual for further information.
D-54
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O to GPIB card
Configuration Example for National Instruments
The following setup properly configures an HP-7475 plotter as the device HPPLOT. The plotter is
assumed to be set for primary address 05.
Device:
Primary GPIB Address:
Timeout Setting:
Terminate Read on EOS:
Set EOI with EOS on write:
HPPLOT
05
T10s
yes
no
Secondary GPIB Address:
EOS Byte:
Type of compare on EOS:
Set EOI w/last byte of write:
NONE
10H
7-bit
yes
GPIB2 – IOtech
The GPIB2 I/O driver is compatible with the IOtech Personal488 GPIB card. Under the IOtech
software, GPIB devices appear as DOS devices similar to PRN or LPT1. The IOtech driver (DRVR488)
is normally loaded by a command in the AUTOEXEC.BAT file such as
DRVR488 /i0 /d /A&H02E1 /B21 /F8 /TCRLFEOI /ECRLF /SC <\IEEE488\DEVCONF1.DAT
Device specific information is contained in the DEVCONF1.DAT file. Commands in this file assign
logical names to each device and specify the GPIB address and read/write terminators for each.
The INSTALL utility provided by IOtech handles creation and modification of this file. For further
information, refer to the sections on INSTALL and on using Named Devices in the IOtech manual.
(WARNING: The assigned logical names and the names IEEE, IEEEIN, IEEEOUT must not conflict
with any names on your disk.)
The GPIB2 I/O channel accesses devices which have been assigned a logical name as discussed
above, specified by <sub channel>. During initialization, the driver IEEE is opened and reset by an
IOCTL BREAK. This clears the board and may terminate pending GPIB operations. The driver is
closed and the <sub channel> is opened. The device is subsequently handled as a DOS file.
Strings written to the device are terminated with the string <CR><LF>. Reads must be terminated
by <CR><LF> or by EOI only. Other terminating strings may not be handled properly and should
not be used.
Errors which occur during initialization are handled internally by GPIB2 while errors during read
and write operations are handled by DOS. Errors during initialization are either IO-TECH GPIB
device driver not installed if the device IEEE could not be found or Unable to open GPIB
device: Device invalid? if the device <sub device> could not be opened.
For errors during read or write operation (commonly timeout), an error message is printed. ERROR:
TIME OUT OR BUS ERROR ON WRITE if the device is off and ERROR: TIME OUT ERROR ON DATA READ
are common messages. The familiar Abort, Fail, Retry, Ignore?
prompt will follow the
message. Retry will reattempt the I/O operation. Ignore proceeds as if the operation had completed
(dangerous). Fail (available only for some DOS revisions) will fail the operation and return to
the driver. The driver will then print either Unable to write GPIB device: Not on-line? or
Unable to read from GPIB device: Not on-line? and proceed. The abort response should
never be given since it will immediately abort back to DOS.
Configuration Example
The following setup properly configures an HP-7475 plotter as the device HPPLOT. The plotter is
assumed to be set for primary address 05.
Name of IEEE 488 Device to Create ................... HPPLOT
D-55
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O to GPIB card
IEEE 488 Bus Input Terminators
................... CR
IEEE 488 Bus Output Terminators
................... CR
IEEE 488 Bus Address (00 to 30, 0000 to 3031) ....... 05
LF
LF
EOI
EOI
The terminators are the defaults values supplied by IOtech. It is only necessary to add the name
and the Bus Address. After adding this device, the file DEVCONF1.DAT will contain a line
CONFIG /TCRLFEOI /NPLOTTER 05
D-56
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O spooled to mainframe
SPOOL I/O channel:
The SPOOL I/O channel directs the output from a device driver through the COM1 or COM2 ports
to a mainframe computer. The mainframe computer must have a program running (or initialize
a program when so requested) to receive the plot sequences. Output to the mainframe utilizes a
ACKNOWLEDGE only protocol from the mainframe with XON–XOFF handshaking on the actual RS-232 communication port. The program on the mainframe is the user’s responsibility; its
requirements are described below.
The <sub channel> must specify either COM1 or COM2 communication port. The <channel opts> is
a character string which is transmitted automatically to the mainframe to indicate the disposition
of the file (see below).
EXAMPLES:
•
SPOOL*COM1*HPPLOT – Output spool commands to COM1. The string HPPLOT will be
transmitted to the mainframe for initialization.
Mainframe Program
The SPOOL channel provides for rudimentary transfer of plot information from the PC to a mainframe computer connected to either the COM1 or COM2 RS-232 port. When the channel is initialized,
the string remote plot <channel opts> <CR> is transmitted to the mainframe to initialize a remote plotting package (lower case is transmitted, <CR> is ascii 13). The remote plotting program
must acknowledge that it is initialized and running by transmitting an <ACK> character (ascii 6).
If no <ACK> is received, the channel will generate the message Remote PLOTTER did not respond
and return with an error. The remote plotting program should read the remainder of the command
line and decide how to dispose of the incoming information.
Each subsequent buffer of information from the I/O driver will have the following format:
@025xxxxxxxxxxxxxxxxxxxxxxxxx<CR>
The first four characters @025 consist of the @ identifier followed by the ASCII decimal number of
characters in the plot buffer which immediately follows (represented by the x’s). The entire string
is terminated with a <CR> character. Upon receiving the buffer, the remote program must respond
with another <ACK> character (all other characters are ignored). If the <ACK> is not received, the
I/O channel will issue the message No ACK on buffer send.
The buffer itself is sent exactly as the device driver generated it, no translation of characters occurs.
If only normal ASCII character codes are expected (such as from the HP-GL, POSTDRV or DRVQUIC
drivers), the incoming line can be read as a standard text line terminated by the <CR>. The first
four characters are stripped and the remainder is output directly to the plotter. However, if the
driver generates control codes (such as a raster driver), the remote plotting program must configure
its RS-232 receive line for 8 bit transparent character receiving and no echo. The exact number of
characters must be read prior to acknowledging the receipt of the buffer (one of the buffer characters
could be a <CR>. Handling this problem is completely machine dependent and requires a reasonably
good hacker to implement.
The I/O channel indicates it is finished by sending the line @END<CR>. No buffer count is transmitted
first, only the 4 characters and the terminating <CR>. The program should acknowledge this final
line as well; the driver will respond with No ACK to end remote SPOOL otherwise.
•
Initialize and acknowledge start of the remote program
D-57
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
I/O spooled to mainframe
•
Read options from the command line and determine disposition of the plot
.
Read a buffer of text to the terminating <CR> character
.
Acknowledge receipt of the buffer
.
Check for the @END terminator - exit if present
.
Strip the buffer count and output buffer to the plotter
.
Return to read another buffer
D-58
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX E: ERROR MESSAGES
WARNING MESSAGES
0000 expression errors occurred. All .FALSE. - HA HA
During a CULL operation with a FOR range, the expression failed in several cases. On failure,
CULL assumes a default .FALSE. value and continues. This warning message gives the number
of times the default was used.
Arrow aborted - zero length
An arrow was requested with zero length. Drawing is aborted
Check new YPLOT call sequence
This internal error indicates that the old calling sequence of YPLOT has been used. Should not
normally occur.
CMDLIN string will be truncated
A subroutine call to CMDLIN contained a string which was longer than the command processor
buffer.The string has been truncated.
Could not deallocate specified variable
Attempt to deallocate a variable failed. Most probable cause is because the variable does not
exist. No action is taken.
CPLTX3 common block may be different
The versions of the HCOPY file and the current plotting software are substantially different.
The internal common blocks of the plotting code may have changed (though they should not).
Plotting continues and we hope for the best.
Curve full - Extra points ignored
During read of an ASCII data file, the file contained more points than the current curve could
hold. The remaining points are ignored.
Error in vector write (RASTER)
An error may have occured while writing the temporary vector block. Usual cause is a disk full
condition.
Even if you are the Boss, deconvolution is extremely ill-advised
A TRANSFORM DECONVOLUTION was requested. Because we believe this to be dangerous
in all cases, a warning message is issued.
FLAMBDA out of range - Strange function!
During the NSLFIT calculation, the data set behaved in an unexpected, though not necessarily
wrong, manner. This warning often occurs for non-linear fits and generally can be ignored. You
should always though check the validity of the fit by eye before accepting the values returned
from NLSFIT.
HCOPY plot aborted from keyboard.
A HCOPY PLOT command was aborted prematurely by typing ∧C at the keyboard. It may be
necessary to reinitialize the device.
Illegal expression:
Assume .FALSE.
E-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
During a CULL operation with a FOR range, the expression failed to evaluate properly. CULL
assumes a default .FALSE. value and continues. This message is given on only the first such
error. Total number of defaults used is given after the CULL is complete.
Illegal expressions are set = 0
In TRANSFORM FILTER, an error occured during evaluation of the specified filter function.
This warning is issued only on the first such error. The filter value is set to 0 on each error.
Invalid range or too few points (FIX GRID)
Invalid parameters were specified in the FIX GRID command. Error occurs if number of points
in the curve is less than 2, if less than 2 points are requested for the resulting curve (-POINTS)
or if the range specified (-RANGE -FROM -TO) does not overlap at all with the curve data.
ITYPE out of bounds (AXIS)
This internal error indicates that a parameter to the AXIS drawing routine is invalid. Should
not normally occur.
No active SCRIPT file - comments lost
A LOGIT command occured with no SCRIPT file open. The comments will be written to the
bit dump (ie. out the power cord - be sure to notify your neighbors of unattached bits floating
around).
No plot device active. Please select one using the DEVICE command
A control command to a plotting device was issued (such as ERASE) before any device was
initialized. Before plotting, use the DEVICE command to select and initialize the appropriate
device.
No response to ACK on COMx: line
The asynchronous I/O channel is operating in ENQ/ACK mode on one of the COM ports.
An ACK (acknowledge) was never received from the plotter in response to the computer ENQ
(enquire). The buffer output is aborted but processing continues. Check to make sure the plotter
is on-line.
No SCRIPT session active
At attempt to PAUSE a script session failed because none was active.
Non-integer expression. Nearest integer returned
A integer number or expression was expected. However, the value was not within 0.1 of an
integer. The nearest integer value will be used.
Not all points will be retrieved
During a RETRIEVE operation, there was insufficient space in the curve to contain all the
additional data. As many points as possible are retrieved.
Points colinear - Line only drawn
An arc was requested but the three points defining the arc were colinear. The line between the
end points was drawn.
Previous definition of this variable has been deleted
A variable allocating command has redefined an existing variable. The previous definition is lost.
Example: If F is currently a real number, the command ”DEFINE F(X) = X” redefines F as a
string.
Rename of temporary macro failed
SAVE MACRO attempted to rename the temporary macro file to a new name. This attempt
failed, probably because the new name already exists. The file remains saved under the temporary
name.
E-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
Set LTYPE = 0 for point
A symbol type was specified while the line type was non-zero. Symbols are only drawn when
lines are disabled by with LTYPE = 0. The message can be avoided by setting LTYPE to zero
before changing the symbol type.
So sorry Charlie, possible data error (FIX GRID)
During FIX GRID, the initial data is moved to the end of the curve and new data (on a fixed
grid) is created starting at the beginning of the curve. This WARNING occurs if the new data
overruns the pointer for the old data. Since the new data may be corrupted, proceed with
caution.
Specified variable was not found
The name specified to the REMOVE command in NLSFIT is not currenlty on the list to be
varied.
Too few columns or illegal data value
A line of data from an ASCII file during read contained fewer columns than required by the
-COLUMN or -LIST specification (or fewer than 2 columns if neither option specified), or an
entry in the column could not be evaluated.
Too fine an increment chosen. NPTMAX used
During CREATE, a DX value was specified which would have required more points than fit in
the curve. CREATE modifies the request to use the minimum possible DX given the curve size
and the specified range.
Too many smoothing iterations during SPLINE
SPLINE -SMOOTH is handled by iterating the fitting process until the specified SMOOTH value
is achieved. The current data set is so poor that the SPLINE did not converge after 50 iterations.
The SPLINE is set to the current guess after 50 iterations.
Unable to determine filename (GPTH$F)
The program was unable to ascertain the name of a currently opened file. While generally not
an error, whatever caused this warning will probably generate an error soon.
Unable to determine length of CPLTX3
HCOPY processor was unable to determine the length of an internal common block. This internal
warning should not occur. Processing continues with a default value anyway.
Unable to reopen old macro
The MACRO command normally reuses the previous temporary filename. The command was
unable to reopen this old file. Possible causes are the file in use, insufficient rights, or previously
deleted. use or has been deleted.
Unknown command (SVPLOT):
An internal command byte in a HCOPY file is unrecognized. This should only occur if the file
has been corrupted (by an editor for instance). HCOPY plotting continues ignoring the unknown
command byte but don’t expect miracles.
Variable redefined as type REAL
The variable in a SETVAR command already exists but is not of type REAL. The variable has
be redefined to be REAL. Previous definition is lost.
You’re the boss but spacing of ordinates differ. Zero pts aligned.
A correlation operation was requested in TRANSFORM between two curves whose X ordinates
are not equally spaced. GENPLOT proceeds under the assumption that you know what you are
doing. The data sets are aligned so the zero points overlap.
E-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
ERROR MESSAGES
Abort repeat process (YES|no)?
An error condition has interrupted the processing of a FOR %F or a REPEAT command sequence.
The repetative operation may either be cancelled at this point, or execution allowed to continue
with the next valid entry.
Access denied
DOS function error. An operation was requested which the user does not have priveleges to
perform. This includes deleting a non-empty directory or overwriting a read-only file.
Ambiguous CREATE option
Ambiguous or unrecognized option was specified in the CREATE command.
Array dimension too large
Expression evaluator error. An array was requested with a dimension too large to fit in a single
65kB memory segment. No more than 16380 real numbers may exist in any single array.
ASCII file read failure
During read, an attempt to read a line from an ASCII formatted file failed. Check the file for
valid ASCII format.
ASYNC IO definition error
The I/O channel options specified for the ASYNC channel are invalid. See the I/O channel
documentation for valid listing.
Attempt to remove current directory
DOS function error. RMDIR attempts to remove the directory you are currently attached to.
DOS does not like you doing this.
Attempt to set the BIOS video mode failed
An attempt to set video mode via low level BIOS routines failed. The requested graphics mode
is not supported on your hardware. For example, specifying the AT&T mode 40h on an IBM
PC will generate this error.
Bad address request x(nnn)
Expression evaluator error. The last 5 bytes of a segment cannot be read by the math coprocessor.
Unfortunately, some variable had an address in this range.
Bad buffer length specified
The LEN=xxxx value specified with the I/O channel could not be interpreted as a number. xxxx
must be a decimal integer.
Bad definition of BOTTOM TO TOP(X) or TOP TO BOTTOM(X), or Y equivalents
The functions BOTTOM TO TOP and TOP TO BOTTOM or LEFT TO RIGHT
and RIGHT TO LEFT for drawing non-linear axes generated errors during evaluation. Check
that the functions are properly defined and that they are valid over the necessary range.
Bad key (JSTR$U)
Bad key passed to subroutine JSTR$U
Bad key (SYSTEM)
Bad key passed to subroutine SYSTEM
Bad key (WILD$U)
Bad key passed to subroutine WILD$U
Bad name or insufficient memory
E-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
An attempt to allocate memory for a string, array or curve failed. If the name was valid, you must
delete old variables to create space for new ones. Use MEM to determine the largest memory
block remaining.
Bad name, no memory or unable to set
An attempt to allocate memory and set the value of a string variable failed. The string may
have been successfully allocated but the value will not be properly set.
Bad rows range (SCRL$)
The rows specified for a scrolling region are invalid.
Bad sub device
A invalid sub device was specified. Check documentation on valid sub devices for each driver
class.
Bad variable type
Expression evaluator error. An invalid variable type was specified by a subroutine call. This is
an internal error - report to CGS.
BIOS mode not supported by this driver
The BIOS mode required by the selected device is not supported by the low level driver. This is
an internal error which should not occur under normal situations.
Box cursor not implemented on this device
The BOX range was specified for a CULL operation, but the current device does not support
the BOX cursor. The CULL is aborted.
Buffer modified. Confirm exit (y/N):
Not wanting you to lose your edits, the editor requires confirmation when exiting with a modified
file in the buffer window. Confirm exit without saving by typing Y. To save the file, type N and
then save the file using ∧X∧S.
Can’t do power estimate on CBUF$R/I pair (FFT)
The FFT power estimator is only valid for real data sets. The request for spectral power estimation on the complex buffer pair is ignored.
Cannot add points w/ tracking cursor
During EDIT DATA, a request to add a point failed because the tracking cursor was active.
Points may only be added with a free cursor.
Cannot create unique temporary filename (GTMP$F)
Attempt to generate a temporary name of the form T$xxxx failed. Either (1) the character
string passed to GTMP$F is too short for the the character name, (2) the default path does not
exist (check TMP variable) or (3) all 10000 possible temporary filenames are in use (AARGH!)
Cannot find the .HLB help file
The help information is stored in a xxxx.hlb file where xxxx is the program name. This file could
not be located in the default GENPLOT directory. HELP aborts.
Cannot locate COMMAND.COM (CP$)
CP$ attempted to spawn a second copy of the DOS command processor in response to a DOS,
OK or PAUSE command. The shell program COMMAND.COM could not be found however.
The environment variable COMSPEC, normally set by DOS at machine boot time, must point
to this program.
Cannot locate your interrupt driver
Device driver [1.4] not installed - Use RS232DRV
E-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
The output routines utilizing the COMx: ports rely on an interrupt routine RS232DRV. The
initialization routine for COMx: could not find one already in memory nor could it allocate one.
RS232DRV may be force loaded into memory via the .COM file in \GENPLOT\UTIL.
CBUF$R/I pair are invalid or non-existent (FFT)
An inverse or forward FFT was specified on the CBUF$R/CBUF$I complex data pair. However,
the variables do not exist as valid arrays.
COME ON - GIVE ME A BREAK! At least log into the network before printing.
The I/O Novell channel was specified but you are not logged into a 2.1x Novell network. Login
and reattempt the device.
Command line aborted by user ∧C
User pressed ∧C during execution. The remainder of the command line has been flushed and
will not be executed.
Command line flushed
An error condition or a ∧C typed by the user caused the current command line to be terminated.
The indicated text, remaining on the command line, has been flushed and will not be executed.
Condition is not a legal math expression
The FOR range was specified for a CULL operation, but the expression given is invalid. The
CULL is aborted.
-- Console input error -An end of file condition was detected from terminal input (perhaps due to typing of a ∧Z
character). If 1000 of these occur (probably because of the end of an input file), execution is
terminated with the STOP message “FATAL ERROR ON INPUT DEVICE”
CREATE aborted because of multiple errors
During CREATE, a maximum of 10 errors are allowed in the expression evaluation (tolerating
occasional divide by zero, etc). More than 10 occurred however and CREATE aborts assuming
the function is bad.
CRITICAL ERROR: Press any key to continue
A critical error occurred during execution. The failure is sufficiently severe that processing is
halted until the user presses any key. One example is the failure of a HCOPY DEV command.
Curve does not exist
The curve specified to be RETRIEVE’d does not exist.
Data not strictly sorted for SPLINE
The curve passed for a spline fit must be sorted and cannot have any equal abscissas. Use the
command SORT -STRICT to sort and delete any duplicate data points.
Denormalization exception
80287 math coprocessor error. Error is masked and should not occur.
Derivative failed to parse
The analytic derivative for one of the variables in a non-linear least squares fit failed to parse.
Check for a valid function definition.
Device definition file missing
The file DEVICES.DAT (or equivalent environment variable name) could not be found in the
current or default directory. This file specifies the device driver and parameters associated with
each device and is required. The original may be reloaded from the distribution diskettes.
Device does not exist or cannot digitize
E-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
If no -TABLET was specified to READ %DIGITIZE, then the current device does not have a
cursor and cannot be used to digitize. If the -TABLET option was specified, the tablet is invalid
or could not initialize.
Directory not found
CD (change directory) was requested to a non-existent path
Divide by zero
80287 math coprocessor error. Attempt to divide by zero.
DUMMY ROUTINE CALLED! (xxxx)
A routine has called an unexpected procedure, which is not loaded in the DYNT module. Please
note the conditions of this error and the report the error to CGS.
DYNT ERROR NOTES:
The dynamic loader handles allocation of memory and loading of sub-sections of the graphics
code. The internal format bypasses certain limitations of simple overlay loaders. However, it
requires that all components of the code agree as to format and structure of the dynamic header.
During an attempt to load a dynamic module, several errors may occur as listed below. Dynt
modules are identified by either a .DRV or a .OVL extension.
The .OVL and .DRV files between minor updates of the code are incompatible. In general,
revision 1.11 .DRV files will work with a revision 1.12 main procedure. The reverse is seldom
true. 1.12 .DRV files may require routines not found in the 1.11 headers. The entire ordering
of the routines will change between minor revisions such as 1.14 to 1.20. The drivers cannot be
exchangable between these revision levels.
A DYNT 108 error indicates that you have mixed .OVL, .DRV and .EXE files from multiple
revision levels. To eliminate the error, reload the executable files from the latest distribution
disks. Be sure to replace and .EXE in your path with the newer versions.
For programmers, the ordering of the DYNT header is loaded in the ALL.EPF object file. DYNT
108 error indicates that the current link does not have the recent list in the header. You must
relink using the ALL.EPF corresponding to the current ALL DYN.OVL file.
DYNT ERR 100: Not DOS 3.x
You probably need to be running DOS 3.0 or above.
DYNT ERR 101: ID code mismatch
Different version of DYNT were detected. See note below.
DYNT ERR 102: Multiple call to loader
A second request for loading the main dynamic module has occurred. This is an internal error
which should not occur.
DYNT ERR 103: Unable to access module Most common error. The program requested a dynamic module but the module could not be
found. The pathname of the unfound module is given following the error. This is often caused
either by missing files in the \GENPLOT directory or by the wrong spelling of a device driver
in the DEVICES.DAT file. Check the spelling and make sure the file exists in the specified
directory.
DYNT ERR 104: No space for requested DYNAMIC module
DOS could not locate sufficient free, contiguous memory to load the requested module. DOS
only knows about 640K no matter how much memory your computer actually has. Currently we
do not support either expanded or extended memory. The solution to this problem is to free up
some memory. Most of GENPLOT’s major functions and all the device drivers are loaded into
E-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
memory as needed so this error presumably occured when you tried to do or change something.
Check the notes below.
1. Try using the MEM command within GENPLOT just after you start and at different points
before the problem arises to see how much memory you actually have free. There is also
a /GENPLOT/UTIL/MEM.COM program you can use to check memory outside of GENPLOT.
Check your AUTOEXEC.BAT and CONFIG.SYS files for resident routines such as Sidekick. Some
network programs also take up a large chunk of memory.
2. Try DEALLOCATing some modules that may have been loaded. LISTV -H will display all current
variables. Those preceeded by a “M ” represent dynamic modules and you can deallocate them
to free up some memory. Start from the bottom, MEM only recognizes free memory from the
last loaded module. Don’t deallocate M GENPLOT that’s what you are using!
Printing Device drivers will unload themselves when you change devices. Most of the printer drivers,
like RASTER or HPRASTER, use about 40K of memory while screen drivers use about 13K.
Something that works with the screen may not work with the printer. Your options are:
1. See the RASTER driver section of Appendix D concerning memory constraints. (This doesn’t
work for the DeskJet or PaintJet.)
2. Create an HCOPY file of your plot and save it. Quit and restart GENPLOT, and try printing
the HCOPY file with device whatever hcopy plot file.
DYNT ERR 105: Module not .EXE file
The requested module is not EXE format - probably corrupted.
DYNT ERR 106: XKsegment wrong version
Different version of DYNT were detected. See note below.
DYNT ERR 107: EXE module wrong version
Different version of DYNT were detected. See note below.
DYNT ERR 108: CRC value of EXE and EPF mismatch
This error indicates that the modules disagree on the specific list of routines in the DYNT header.
A CRC checksum verifies that routine list is the same for the calling and called modules. If this
error occurs outside of user written code, it indicates use of incompatible versions of GENPLOT.
See note below. For user written routines and device drivers, this error indicates that the routines
need to be relinked using the new copy of ALL.EPF.
DYNT ERROR 200: Unable to access module Same as DYNT error 103. See comments above.
DYNT ERROR 201: No space for requested DYNAMIC module
Same as DYNT error 104. See comments above.
DYNT ERROR 205: Module not .EXE file
Same as DYNT error 104. See comments above.
DYNT2 module LOAD EXE not implemented in fully linked executable code
A fully linked executable program (such as HCPLOT or VSORT) attempted to load a dynamic
module such as a screen driver or the editor. This error should not occur in normal use of
distribution programs. If it occurs in user written programs, use dynamic linking.
EDIT DATA requires cursor capable device
The EDIT DATA command only works with devices implementing a cursor.
Either COM1 or COM2 must be specified for SPOOL output
E-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
The I/O spool channel must use either COM1 or COM2. Any other specification is considered
invalid input. See the I/O channel documentation.
Equation failed to parse
The equation for an NLSFIT failed to parse, indicating either a variable or definition problem.
Check the equation definition.
Equation name truncated
The equation name given to NLSFIT was too long. The name has been truncated as indicated.
Not that variables names can only be 32 characters in length.
***** ERROR: Failure on session SCRIPT file. *****
***** Press any key to continue *****
An error occurred while writing to the SCRIPT file. The file either has been closed elsewhere or
the disk is full. SCRIPT will be disabled when execution continues.
EXCLUDE curve cannot be located
An exclusion curve was specified in PLOT or OVERALY. However, GENPLOT does not find
the curve currently defined. The plot is aborted.
Execution error
An error occured during processing of the specified token, The command and the remainder of
the command line are aborted.
Expected IN command not received (SV$RCM)
Internal error. HCOPY expected an IN (initialize) command in the HCOPY file at this point
but received something else. This normally indicates a corrupted HCOPY file.
Expecting mathematical operation
Expression evaluator error. A point was reached in the expression where a mathematical operator
(+-*/) should have been. Expression can not be parsed.
Failure outputting plotting buffer (PLOUT)
The output of a block of plotting information to the I/O channel failed. Processing continues
with only the warning. Possible causes are device off-line or disk full.
FATAL ERROR ON INPUT DEVICE
The input device appears to have been closed or is at permanent end of file. Execution is halted.
FATAL ERROR: The .EPF library loaded with a dynamic module does not
match the .EPF previously loaded. This is a fatal error which
means you are using incompatible versions of drivers and executable
code. There is no way I can recover therefore I quit!
This error indicates that the modules disagree on the specific list of routines in the DYNT header.
The CRC checksum verifying the routine order failed. However, the code is already running and
there is no way to abort gracefully. A CRITICAL ERROR ABORT is executed.
If this error occurs outside of user written code, it indicates use of incompatible versions of
GENPLOT. See note below. For user written routines and device drivers, this error indicates
that the routines need to be relinked using the new copy of ALL.EPF.
File does not exist
Attempt to read data from a file which does not exist.
File failed to open
The filename specified as the I/O channel to the Word Perfect driver could not be opened. Check
the name for valid format.
File incompatible with -LIST or -COLUMN
E-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
The binary file specified in a READ command is of an older format. This format has only two
columns.
File not found
DOS function error. A low level file operation through DOS failed to find the specified file.
File SAVE.F77:
Bad key in call (SVSET) SAVE
Internal error. Bad key to internal subroutine.
File too large
The editor, by choice, limits file edits to 64kB. The specified file was too large to fit in the editor.
Function evaluator errors. (NLSFIT)
During NLSFIT, too many errors occured in the function evaluator suggesting a problem with
the equation or derivatives. NLSFIT aborts without setting parameters.
Function name or specification invalid
An attempt to define a function F(X,Y) = ... failed for any of numerous reasons. Most common
is an invalid F(X,Y) name or function declaration. May also occur for insufficient memory.
General file open failure
An attempt to open a file failed. Probable cause is either file does not exist, is in use, or you
have insufficient rights. The fortran compiler requires RW rights on all files.
General READ error
General failure to read the specified file
General WRITE error
A general error occurred during writing of the buffer to the file. This error occurs for invalid
filenames or disk errors. The contents of the buffer are retained but the disk file will not be
properly written.
Hardware for requested COM port does not exist
No hardware could be located for the specified asychronous port. Check that the port is installed
and jumpers are set properly for the specified COM port. Note that the I/O ASYNC channel is
interrupt driven and must be able to take over interrupts 3 (COM2) or 4 (COM1).
Header information never terminated
During read of a ASCII structured data file, the end of file was reached before the header
terminating character was found. Check the file format.
I/O channel initialize failed on RASTER output
The I/O channel specified could not be initialized again after plotting was complete. Check
output devices.
Illegal exponentiation (a**b)
Expression evaluator error. A request was made for 0**0 or for a negative number to be raised
to a real power (-1**.5).
Illegal expression for error bars
The expression for the X or Y error bars in PLOT -ERRX failed to parse. Check for existence
of the curve or validity of the expression. The request data plot is aborted.
Illegal integer value.
A integer number or expression was expected. However, the value entered was outside the range
of a valid integer.
Illegal label origin specified
E-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
The token specified for label origin type was invalid. Allowed formats are two letters using
[L—C—R] and [B—C—T].
Illegal option
An unrecognized or option was specified.
Illegal option
The specified option was not recognized by the command
Illegal option for AXCTRL
An illegal or unrecognized option was given to the AXCTRL command.
Illegal response. Answer YES or NO
A response other than YES or NO was returned when expecting YES or NO. Type in a valid
response.
Illegal response. Expecting xxxx or yyyy
Command processor was expecting a simple xxxx/yyyy (YES/NO) or (ON/OFF) response but
read something else. Retype a valid answer.
Illegal RS-232 port specified. 1 < COMx < 4
A invalid asynchronous communication port has been specified. The PC fully defines only COM1
and COM2. Some compatibles may have COM3 and COM4 defined. All other values are invalid.
Illegal weighting function
The specified weighting function could not be parsed as a legal function. Check the definition of
all constants.
Initialization of SST hardware failed
The SST hardware was specified as the device channel. GENPLOT was unable to initialize the
hardware either for port address conflicts or because the board is not installed. Check you SST
installation documentation to resolve address conflicts.
Insufficient memory
Expression evaluator error. Could not allocate sufficient memory for a requested CURVE, ARRAY or STRING.
Insufficient memory
DOS function error. There is insufficient memory for the requested operation. Commonly happens with PAUSE command when memory is fully utilized by curves.
Insufficient memory or unable to load EDITOR
Attempt to load EM editor failed because either (1) insufficient free memory remained or (2)
MOTMACS.OVL could not be found.
Insufficient memory to allocate X,Y arrays
At initialization, GENPLOT could not allocate sufficient memory for the default X,Y curves.
Specify a smaller number of points or remove memory resident utilities.
Insufficient memory to expand buffer
As a file expands, the editor attempts to allocate space to accomdate the new next. This error
indicates that it is not possible to expand the buffer further.
Insufficient memory
Editor could not allocate sufficient memory for the requested file
Internal HELP$ error (001)
Internal pointer error on HELP file. Report conditions of this error to CGS.
Invalid access code
E-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
DOS function error. Never seen this one.
Invalid COMx: request
A request was made for output to be directed to a communication port which does not exist.
Check the I/O channel of the specified plotting device and make sure the specified COMx: port
exists.
Invalid data
DOS function error. Never seen this one.
Invalid DOS or critical error
The DOS version was invalid or an unexpected critical error occured while initializing the editor.
The editor is aborted.
Invalid drive specified
DOS function error. A drive was specified which does not exist.
Invalid environment
DOS function error. The environment is corrupted. Who knows why.
Invalid expression for either XMIN or XMAX
In the CREATE command, the XMIN and XMAX specifiers are stored as strings for evaluation
each time. When CREATE tried to evaluate the strings, an expression error occurred.
Invalid format
DOS function error. Never seen this one.
Invalid function number
DOS function error. An invalid function was requested from DOS. This indicates an internal
error which should be reported to CGS.
Invalid GAMMA argument
Expression evaluator error. Gamma function is not defined at the negative integers.
Invalid handle
A read or write was specified to a file handle (unit) which is not currently connected to a real
file.
Invalid memory block address
DOS function error. Attempt to modify an invalid memory block. See Memory Control Block
Destroyed information.
Invalid numerical expression
A real or integer expression was expected but the parsed expression was invalid. Check the
expression and reenter.
Invalid operation or stack overflow
80287 math coprocessor error. An undefined operation was requested, such as the square root of
a negative number.
Invalid SCRIPT open option
An option following the SCRIPT open command is invalid.
Invalid SUB PLOT option
An invalid option was specified to the SUB PLOT command. Check the command format and
try again.
Illegal VECSIZE value
A negative or zero vector repeat length for dot-dashed lines was specified. The repeat spacing
should be a real number on the order of 0.003 inches.
E-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
Invalid syntax (FOR %f IN (*.asm a.f77) DO some %C and %F)
A FOR repeat command was given with an invalid syntax. The structure ”FOR %F IN (xxxxxxx)
DO” is required where xxxxxx is a list of wild or items. The terminating DO must be given
before the command expression.
Invalid TRIG function argument
Expression evaluator error, sin(-2) for example.
IO-TECH GPIB device driver not installed
A GPIB2 I/O device driver was requested. However, the IO-TECH device driver for the IEEE488 board has not been installed. See your IO-TECH documentation for details on installing the
device driver.
Kill buffer full
The editor has a limited 4096 byte kill buffer for cut and paste operations (this isn’t an editor it’s a plotting program). The kill operations have overflowed the buffer. The first 4096 bytes are
retained for a paste operation if desired.
Less than 3 points. LSQFIT not possible
The least square fit was requested with fewer than 3 points.
-LIST incompatible with -APPEND
During a READ, both -LIST and -APPEND were specified. It is not possible to APPEND data
to the end of an array.
LSQFIT matrix was singular
The matrix used in solving the least squares fit was singular. This will occur if the data is perfectly
random in space, but may also occur if the data is poorly normalized (such as extending from
300001 to 300002).
Macro file does not exist
The macro file requested via XEQ or CALL does not exist.
Macro file failed to open
The macro file requested could not be opened for reading. File may be protected or in use by
another user.
Memory control blocks destroyed
DOS function error. You better watch out, you better not cry, your machine is about to die,
memory walking has occurred. Someone overwrote one of DOS’s memory control blocks. DOS
seldom recovers from this error without a reboot. If you want to crash, this error is trivial to
obtain. ”ALLOC M ARRAY 16 LET M(17) = 8”
Minimum fractional change allowed = 1E-7
The fractional change criteria for stopping the NLSFIT search cannot be specified smaller than
the precision of REAL*4 numbers, approximately 7 digits.
Mouse driver not installed or unable to initialize.
The rodent driver was selected but the mouse driver has not previously been loaded. Only the
MICROSOFT of 100% compatible mice are supported and MOUSE.COM v. 6.0 or above must
be loaded before the device is initialized. See your mouse documentation to load MOUSE.COM.
Network spool error: CLOSE
A network error occurred while attempting to close the NOVELL spool file. Cause unknown.
Network spool error: OPTIONS
A network error occurred while attempting to set the spooler options to the NOVELL server.
Cause unknown.
E-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
Network spool error: WRITE
A network error occurred while attempting to write to the NOVELL spooler. Cause unknown.
No <ACK> on buffer send
The I/O spool channel failed to receive the expected <ACK> after a buffer of text. This indicates
a probable error on the host side of the spool connection. See the I/O channel documentation.
No <ACK> received at end of remote SPOOL
The I/O spool channel failed to receive the expected <ACK> at the end of the spool session.
This indicates a probable error on the host side of the spool connection. See the I/O channel
documentation.
No active file for saving! (SVON)
Internal error. HCOPY tried to initialize or restart a HCOPY file but found no currently active
file to reset.
No active unit (SV$RCM)
Internal error. HCOPY thinks a file is open for reading but fails to find an active unit. HCOPY
aborts.
No active unit. (SVSET)
Internal error. Program attempted to truncate a HCOPY file but did not find one open.
No command implemented here
A command was given which executed a NOP operation. Please record the command which gave
this error and submit to CGS.
No cursor on current device dummy
A CURSOR was requested on a device which does not support the cursor.
No data columns specified for READ
During a READ, either the -LIST or the -COLUMN specification failed to specify a valid column
of data. Columns start with 1 in data file.
No default allowed. Type YES or NO
A blank response was made to a YES/NO answer but the program does not permit a default.
You must select either YES or NO.
No Display Enhanced Adapter (DEB) found
The device selected requires the Display Enhancement Board but a check of system resources
did not indicate that one was present.
No Enhanced Graphics Adapter (EGA) found
The device selected requires an Enhanced Graphics Adapter but a check of system resources did
not indicate that one was present.
No file currently enabled! (SVCOM)
Internal error. HCOPY tried to write initialize code to a HCOPY file but found no currently
active file.
No file units available (GUNT$F)
All 234 FORTRAN file units are currently in use. Boy are you ever in trouble.
No Hercules Graphics Adapter (HGA) found
The device selected requires a Hercules Graphics board but a check of system resources did not
indicate that one was present.
No more files
DOS function error. Root directory cannot hold any more files.
E-14
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
No plotting device is active - Sorry
A plotting or graphics operation was requested before a graphics device has been initialized. The
command and the remainder of the command line are aborted.
No point within reasonable distance
During EDIT DATA, a request to delete a point failed because no point was within a reasonable
distance of the cursor.
No room to add points to curve
During EDIT DATA, a request to add a point failed because of no space.
No size - Draw aborted
The sample structure requested had zero length. Drawing aborted.
No space to append data
During a RETRIEVE -APPEND, there was no space in the curve for additional data. No data
retrieved.
No space to append digitized data
The curve was already full but -APPEND was specified in READ %DIGITIZE
No temporary macro defined
The command XEQ NOW was attempted before a temporary macro was defined with the
MACRO command. The names N, NO and NOW are reserved to refer to the temporary macro.
No temporary macro file to save
A SAVE MACRO command to save the temporary macro failed because no temporary file exists.
MACRO must be used first to create the file.
No tracking cursor available
During EDIT DATA, an attempt to use a tracking cursor failed because the current device did not
support a tracking cursor.
No unit enabled (SVSET)
Internal error. Program attempted to truncate an HCOPY file but did not find one open.
No variable specified in QUERY
The QUERY command requires the string variable to store the result to be given on the same
command line as the QUERY command. The command parser failed to find any token on the
command line.
No Video Graphics Adapter (VGA) found
The device selected requires the Video Graphics Adapter but a check of system resources did not
indicate that one was present.
Non-existant I/O channel
The I/O channel specified for plotting output (via DEVICES.DAT) does not appear to exist.
Check for the appropriate IO xxxx.DRV driver file in the default directory or see documentation
on I/O drivers.
Not same device
DOS function error. Attempt to rename a file from one disk to another. Copy must be used to
move files across disks.
Only single argument allowed to SPLINE
Expression evaluator error. The SPLINE function cannot take more than one argument, but
several were given.
Overflow condition
E-15
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
80287 math coprocessor error. Overflow occurred either during a calculation or when the value
was saved to memory. Temporary values should not exceed 10**37.
Parenthesis mismatch
Expression evaluator error. The number of open and close parenthesis (or braces) do not match.
Recheck the expression.
Path not found
DOS function error. An invalid path was specified for either a change directory command or a
file creation/opening.
Plotter not enabled - no title
A title command attempted to plot to a device which has not been initialized. Sorry - no plotting
to the bit bucket.
Points colinear(?) - try again
During a READ %DIGITIZE, the three calibration points were too close to colinear to determine
the axes properly.
Precision exception
80287 math coprocessor error. Error is masked and should not occur.
PSP segment not found. Switch to DOS 3.x
An attempt to find the PSP address after program execution began has failed. This error only
occurs under DOS 2.x which you shouldn’t be using anyway.
REDICULOUS # OF VECTORS - PLOT REFUSED!
The number of vectors in the file is greater than the program is willing to tolerate. Since the
limit is 67,000 vectors, you would be in for a long wait anyway.
Reduction factor of 0? Are you on drugs?
A shrink factor of zero or negative was specified. Be reasonable.
Remote plot does not respond: Failed to initialized
The I/O spool channel attempted to initialize the remote host but never received the expected
acknowledge. The initialization fails and the channel is aborted. See the I/O channel documentation.
Requested file failed to open
Requested file to the file I/O channel failed. Check that the name specified is valid.
Requested mode incompatible with attached monitor
The device selected requires that a specific monitor be attached to the graphics adapter board
but a check of system resources did not indicate the appropriate hardware. For example, the
high resolution EGA modes require that an enhanced color display be attached to the board.
Resolution model not supported
Resolution model specified for an EPSON class printer is not available on the specified sub device.
Check DEVICES.DAT specifications with the device driver documentation.
Specified DEFAULT name is not a curve
The curve specified for use as the DEFAULT curve in all GENPLOT operations does not exist.
The current default curve remains in force.
Specified DERIV is not a function
The function specified as the analytic derivative does not exist as a function. If you don’t want
to compute the derivative analytically, specify / as the derivative to let GENPLOT handle the
derivative.
E-16
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
Specified DX requires too many bins - ABORT
During a TRANSFORM BIN or CENTER, the specified bin width would create too many points
for the curve. The BIN operation is aborted.
Specified equation not a function
The equation name given to NLSFIT is not a defined function. Check the definition. The
equation must be of a single variable giving Y(X).
Specified name is not a REAL variable
The variable specified for VARY does not appear to be a type REAL variable. Check that the
variable has been allocated as a real (using SETVAR for example).
Specified variable is not array
During a READ -LIST specification, a variable was specified which did not exist or was not
recognized as an array. -LIST can only read data into arrays. Note that C1:X refers to the X
array of the C1 curve.
SPLINE array SPL$DATA not defined
Expression evaluator error. The SPLINE function was called before the SPL$DATA array had
been defined. Use FIT SPLINE to create a SPL$DATA array.
STACK NUM error
Expression evaluator error. The quasi-stack of the 80287 ended a calculation with other than 1
value. This is an internal error - please report the conditions to CGS.
SVCMD$ undetermined read error.
Internal error. An unknown read error occured during HCOPY PLOT or HCOPY DEV replay
of a vector save file. The command is aborted.
SYSTEM failure?
Internal error. SYSTEM should have executed the command.
Tablet definition file not found
The file TABLETS.DAT (or equivalent environment variable name) could not be found in the
current or default directory. This file specifies the device driver and parameters associated with
each tablet.
Tablet failed to intialize
The tablet specified in a -TABLET option did not respond as expected for initialization. Check
that the tablet is attached to the computer as specified in the TABLET.DAT file.
Tablet not found
The device specified in a -TABLET option was not found in the TABLET.DAT file.
Too few COLUMNS in data file
The binary file specified in a READ command contained fewer columns than required by the
-LIST or -COLUMN options.
Too few points for LSQFIT determination
A least square fit is ill defined for less than 3 points. Current data set violates this requirement.
Too few points for SPLINE fit
A spline fit was requested on a data curve with less than 3 points. Give the program a chance
to work with real data - okay?
Too few points to create a curve
CREATE refuses to make a curve with 1 or fewer points. Specify a reasonable number of points
in CREATE command via the -POINTS option.
E-17
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
Too many active vectors
Too many vectors were drawn across the current raster band. Any more vectors in the same
band will be ignored. See device driver documentation for further details.
Too many nested macro files
User has attempted to nest a macro request (CALL or XEQ) beyond 5 levels. Macro may be
nested only 5 deep. Often caused by a macro calling itself.
Too many open files
DOS function error. Too many files are currently open. DOS limits the number of open files at
any one time. See the CONFIG.SYS command FILES=xx to increase the number available.
Too many parameters for number of data points
In NLSFIT, more parameters are being varied than there are points in the current data set. As
they say, give me enough parameters and I’ll fit an elephant. Number of free parameters must
be less than the number of data points.
Too many points for buffer
The binary file specified in a READ command contained more points than fit in the current
curve. No data is read. Restart GENPLOT with a larger buffer using GENPLOT -BUF <nptmax>
to avoid this error.
Too many points. Y unmodified (FFT)
During FFT operations, the result of the FFT operation will not fit into the current CURVE.
The Y data will not be changed but the FFT operation will proceed if possible.
Too many search parameters specified
The number of parameters to be varied exceeds the capability of the NLSFIT processor. Reduce
the number to something reasonable.
Tracking CURSOR not available
CURSOR -TRACK was requested on a device which does not support it.
Unable to &ENCODE value
The value passed to the inline &ENCODE function could not be evaluated because of an invalid
format specifier. Recheck format.
Unable to allocate CBUF$I/R (FFT)
During FFT operations with -DEFINE specified, a GENPLOT attempt to allocate space for the
arrays CBUF$R and CBUF$I failed, probably for insufficient memory. The operation is aborted.
Unable to allocate space for CREATE function
During a CREATE operation, temporary space for the curve could not be allocated. All memory
is in use by various curves and modules.
Unable to allocate work space. (NLSFIT)
NLSFIT must allocate temporary working storage for the fit procedure but none was available.
Deallocate unused curves and try again.
Unable to allocate working space for SPLINE
Spline attempted to allocate an array workspace of 5*NPT real points but failed. First, NPT
must be less than 3,200 points. Second, check that sufficient memory is still free using the MEM
command.
Unable to allocate workspace (WILD$U)
The routine WILD$U attempted to allocate temporary space for a wildcard filename search. No
more memory was available.
Unable to decode HP response
E-18
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
A cursor command to a HP plotter returned an undecodable string. Program expected a simple
series of numbers.
Unable to find GPIB device
The device specified for the National Instruments GPIB interface has not been defined by IBCONF or the GPIB driver has not been loaded. Check the documentation on the National
Instruments GPIB to properly define devices on the bus.
Unable to fit data - matrix singular
The solution to the polynomial best fit for the current data yielded a singular matrix. Either
the data is very poorly posed (x ranging from 1.00001 to 1.00002) or doesn’t fit any curve well.
Try a lower order fit.
Unable to initialize device
The specified device driver and I/O channel could not be initialized. A particular error should
already be listed.
Unable to initialize the I/O channel
The device driver was unable to initialize the requested I/O channel. Possible errors are directory
not found or no printer on specified LPT port.
Unable to intepret plotter status
The status word returned from an HP plotter could not be interpreted. The word was exptected
to be a series of numeric digits.
Unable to link frequency variable F$
During a TRANSFORM FILTER operation, the variable F$ is linked as the frequency (to be
used in the filter function). This error indicates that GENPLOT was unable to link the variable.
The filter operation is aborted.
Unable to make default definitions
The functions BOTTOM TO TOP and TOP TO BOTTOM or LEFT TO RIGHT and RIGHT TO LEFT for nonlinear axes do not exist. Attempts to define default transformations failed.
Unable to open file
Editor was unable to open the file - probably because it does not exist or the name was bad.
The filename is retained and, if it did not exist when opened, it will be created if possible when
writing the file.
Unable to open GPIB device: Device invalid?
The device specified as a IO-TECH GBIB device could not be opened. Check that the device is
properly configured with IO-TECH software.
Unable to open unique filename (TEMP$F)
An attempt to open a unique temporary file failed. Possible causes are non-existent path specified
by TMP variable, full disk or insufficient rights.
Unable to open vector file
The raster devices maintain a temporary file for storing vectors until the vector to raster conversion process is started. This error occurs if it is unable to open the temporary file. Make sure
that the TMP environment variable points ot a valid directory if it is defined.
VSORT required
The vector to raster conversion process could not be started. The file needs to be sorted and
printer off-line using VSORT.
Unable to open/continue SCRIPT session file
E-19
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
General failure of the SCRIPT open/continue commands. The specified filename was either
invalid, could not be found, was protected or otherwise unavailable.
Unable to parse filter expression
During a TRANSFORM FILTER operation, the expression for the filter function appears to be
invalid. The filter operation is aborted.
Unable to read from GPIB device: Not on-line?
An error occurred while reading from an IO-TECH GPIB device. Check that the device is on-line.
Also, check your IO-TECH documentation to confirm that the device is correctly configured.
Unable to read HCOPY buffer (SV$RCM)
Internal error. HCOPY was unable to read a buffer from the HCOPY file. HCOPY aborts.
Unable to read vector sort file (VSORT)
During the vector to raster conversion, the temporary vector file could not be found. Did the
disk disappear?
Unable to set SGRAPH value
The SGRAPH variable specified could not be set. Be sure the variable is correctly spelled and
loaded. (Note: ANNOTE variables are not available to SGRAPH until ANNOTE has been
entered at least once).
Unable to write GPIB device: Not on-line?
An error occurred while writing to an IO-TECH GPIB device. Check that the device is on-line.
Also, check your IO-TECH documentation to confirm that the device is correctly configured.
Undecipherable syntax
Expression evaluator error. The parsing routine cannot understand the syntax at this point.
Check that any variable or function actually exists.
Underflow condition
80287 math coprocessor error. An underflow occurred either during a calculation or when the
value was saved to memory. Set to zero.
Unexecuted command
The command specified at the GENPLOT prompt was not understood and not executed. The
remainder of the current command line is flushed on the error.
Unexpected error finding EOF (GEND$F)
Attempt to read to the end of a file failed unexpectedly.
Unexpected READ error on help file
An attempt to read the HELP file failed. The xxxx.hlb may be corrupted. HELP aborts.
Unformatted read failure (VERSION 3.1/4.0)
Unformatted read error. The binary data file is corrupted.
Unformatted read failure VERSION 4.0
Unformatted read error. The binary data file is corrupted.
Unit not connected for unformatted (SVSET)
Internal error. HCOPY was initializing (or restarting) a HCOPY file but found the expected file
was not connected for UNFORMATTED writes.
Unit not connected sequential (SVSET)
Internal error. HCOPY was initializing (or restarting) a HCOPY file but found the expected file
was not connected for SEQUENTIAL write.
Unit not open (SVPLOT)
E-20
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
Internal error. An HCOPY PLOT or HCOPY DEV command requested replaying of the saved
vector commands in a file unit. However, the unit was not open when plotting was to start.
Unit not open (SVSET)
Internal error. HCOPY was initializing (or restarting) a HCOPY file but found the expected file
unit closed.
Unknown error (?)
80287 math coprocessor error. Catch all for unexpected errors.
Unknown error code
DOS function error. Unknown errors. Advanced DOS errors no longer pass through this routine
and should not appear as unknown messages.
Unknown failure during write (full disk?)
An error occurred while trying to write out the data file. Caused generally by either a full disk
or insufficient access rights on disk.
Unknown NLSFIT command
NLSFIT is a “sticky” sub-processor. Once entered, only commands recognized by NLSFIT are
processed. To return to GENPLOT, use RETURN or try ? for a listing of known commands.
Unrecognized AUTOX mode - unchanged
The mode specified for the autoscaling of the X axis was not recognized. Valid modes are BOTH,
TOP, BOTTOM or OFF.
Unrecognized AUTOY mode - unchanged
The mode specified for the autoscaling of the Y axis was not recognized. Valid modes are BOTH,
TOP, BOTTOM or OFF.
Unrecognized CULL mode
An unrecognized CULL mode was specified. Options are KEEP, DELETE, ZERO or WINDOW.
Unrecognized CULL range
The range specifier for CULL is invalid. Allowed range specifications are RANGE, XRANGE,
YRANGE, CURSOR, BOX or FOR.
Unrecognized CURSOR option
An unrecognized option was specified to the CURSOR command.
Unrecognized device
The device specified in a DEVICE command was not found in the DEVICES.DAT file. See the
appendix on devices in the manual to add new devices to the file.
Unrecognized DIGITIZE option
An unrecognized option was specified to the READ %DIGITIZE command.
Unrecognized driver
The driver specified in TABLET.DAT for the logical tablet name is not recognized.
Unrecognized FFT option
An unrecognized option was specified to the FFT tranformation.
Unable to define X,Y data set as a CURVE
The X,Y arrays passed to the subroutine GENPLOT could not be linked to the function evaluator
as the curve PLOT. The call to the GENPLOT processor is aborted. (Only occurs in user written
programs.)
Unrecognized FFT option
E-21
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
An unrecognized option was specified to the TRANSFORM FFT command.
Unrecognized GRID option
An unrecognized option was specified to the GRID command.
Unrecognized mode for XTOP/YRIGHT
An unrecognized mode was specified after an XLEFT or YRIGHT command. Valid modes are
OFF, ON, BOTTOM, LEFT, YOUDRAW, or NONLINEAR.
Unrecognized option
An unrecognized I/O option was specified. Check the I/O channel with the device driver documentation.
Unrecognized PLOT option
An unrecognized option was specified to the PLOT or OVERLAY commands.
Unrecognized READ option
An unrecognized option was specified to the READ command.
Unrecognized region
An unrecognized region was specified for either the SET, REGION, LABEL, AXCTRL or LOGARITH commands. Valid regions are BOTTOM, LEFT, TOP and RIGHT.
Unrecognized RETRIEVE option
An unrecognized option was specified to the RETRIEVE command.
Unrecognized side specified
The closure side in SQUIGG command CLOSE was not RIGHT or LEFT.
Unrecognized SORT option
An unrecognized option was specified to the SORT command.
Unrecognized TRANSFORM operation
An unrecognized option was specified to the TRANSFORM command.
Unrecognized WRITE option
An unrecognized option was specified to the WRITE command.
Unsupported data file format
The format of the file specified in a READ statement could not be recognized. There are some
old incompatible formats which are no longer read by GENPLOT. See the appendix on data file
formats.
Unsupported plot input mode attempted
A plotting device requested input through an I/O channel which does not support the input
mode. Example is cursor input from a file I/O channel.
Unsupported video mode
The editor only supports pure text video modes. If you are using a graphics device in graphics
mode, you must specify “DEVICE NUL” before running the editor to return to a normal text
screen mode.
Variable does not exist
The variable specified in a LET command does not exist. The variable name must be ALLOCATE
first, or use SETVAR to define and set the value.
Variable exists - cannnot overwrite
Expression evaluator error. The variable already exists and cannot be replaced with a new
definition.
E-22
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix E: Error Messages
Vertical baseline?
The baseline specified in the TRANSFORM BASELINE operation appears to be vertical. Subtraction of the baseline is very difficult under such conditions. Operation is aborted.
Write failure (SVOUT) - disk full?
Internal error. A buffered block of vector commands was to be written to the currently open
HCOPY disk file. An unknown error occurred normally indicating either a full disk or network
access failure.
xxxx.xxx active. Terminate (YES|no)?
An error condition has caused the current macro file xxxx.xxx to be interrupted. You may
choose to continue execution at the next valid line or to terminate the macro.
You are ON DRUGS! Too few points! (FFT)
The FFT processor is optimized for speed and space. It will not handle less than 8 points besides, you should do that small a buffer by hand.
You must specify at least one parameter to vary
The FIT command in NLSFIT was requested without specifying any parameters to be varied. It
is tough to get the best fit if nothing can be changed. Use VARY <name> to specify at least one
variable.
You TWIT! Use QUIT to exit GENPLOT, not RETURN
The command QUIT must be used to exit GENPLOT. An inadvertant RETURN brought GENPLOT back to the initialization shell which simply returns back to GENPLOT command level.
ZOOM not implemented for this device
ZOOM was requested on a graphics device which does not support the box cursor. The range must
be specified directly.
E-23
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX F: DATA FILES
There are two broadly categories of data files within GENPLOT. Referred to as ASCII and BINARY
formats. Within each category are several subdivisions differing in the amount of additional information which is incorporated with the data. Each of these will be discussed separately below. In
general, ASCII files contain human readable data points which may have been created by an editor
or by another program. The format is extremely relaxed and almost any set of X,Y data pairs may
be read in the ASCII format, which is its greatest benefit. The penalty to be paid for this flexibility
is the fact that ASCII files are slow to be read since each line must be interpreted into a number
the computer can understand.
BINARY files are stored on the disk in a machine readable (binary) format, bits and bytes only
the computer can understand. The internal format of the file is rigid and must conform to specific
data structures and lengths. The advantage is almost instantaneous reading of large data structures
along with reduced disk space requirements. Disadvantages include the inability to read (visually) or
modify values in the data set and the difficulty of writing the data in the first place. BINARY files,
however, may be written by GENPLOT to save data read in from an ASCII source. Direct generation
of BINARY files should be done by reliable, robust and often used data collection programs.
ASCII FORMAT
At its simplest level, the ASCII format is simply a list of X,Y data pairs. Additional scaling
information or textual information may be incorporated in the file for other ASCII versions. The
simplest data file consists of only X,Y pairs, one pair per line, with the X and Y values separated
by either spaces or a comma. The following example shows a somewhat more complicated data file
(though still conceptually obvious).
The lines are numbered for the discussion, the ’c’ of lines 1–4 are in column one.
¾
1
2
3
4
5
6
7
8
9
10
11
12
½
»
c first number is degrees C
c second number is related to speg rate
c
divide 1.68e8 gets cm/sec
c john got 1.68eV for activation energy
18
28
31
4
7
480
,
554
828-273
579
,
604
0.055
1.1
0.75 <- he doesn’t like this one
2.3
6.0
c End of Data - hope you like it
¼
The first 5 lines are comments indicated by a ’C’ in the first column (or a blank line). Subsequent
lines contain three columns of data separated by spaces or commas. Straight reading of this file
F-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix F: Data Files
would load in the first and second columns of data as X and Y. Use of the -COLUMN option in read
allows the other columns to be accessed. Notice that as long as the 4th column is never specified in
READ, the comment on line 8 will not generate an error. Line 8 also shows that data may be algebraic
expressions as well as numeric constants. Any data entry will be evaluated using the current values
of constants in the function evaluator.
A second ASCII version is illustrated below, obsoleted by the expression evaluator and inline comment capability. This format is useful for data sets where either X or Y (or both) need to be scaled
by constants or additional comments are to be included in the file. This version consists of a header
which precedes the data (the data has the same format as above).
¾
1
2
3
4
5
6
7
8
9
10
11
12
13
½
»
VERSION GENPLOT 1.1
These are lines of arbitrary text
As many as you choose. It will be printed when file is read.
Ended by a line consisting of a control A (∧A) character column 1
∧A
These are additional sub-text lines. This information is not printed
when read and may contain more information about an experiment.
∧A
3.8 1.0 2.8 0.0
128
1.0
1.2
...
128.0 1.8
¼
The “VERSION GENPLOT 1.1” on line 1 identifies the file as a special format. The next three lines
consist of textual information printed out during file read. This section may be any number of lines
and is terminated by a ∧A (control A) character in the first column. A second “sub–text” header
follows this header. The information is simply skipped until another ∧A is found in column 1 (note
that both the text and sub–text may be 0 lines in length). Following these text fields is a line (9)
containing scaling information for X and Y in the form XFACT XOFF YFACT YOFF. After the data is
read, a scaling transform is applied to the data. X = X*XFACT+XOFF and Y = Y*YFACT+YOFF. (In
this example, XFACT is 3.8) and XOFF is 1.0). The following line indicates the number of points in
the data file. The actual number may vary from this value without error. The program reads the
maximum of NPT or the number of points which are actually available.
VERSION GENPLOT 1.1 also accepts multiple columns and in–file comments within the data region.
The one anomaly, however, is that the X and Y factor/offset values are not affected by the -COLUMN
operation. The value of X read from the file (whichever column it is) is scaled by XFACT and XOFF.
BINARY FILES
BINARY files are considerably more compact and very fast to load compared to corresponding
ASCII files. The current version allows for storage and reading of multiple columns from a BINARY
file. GENPLOT, however, can only write two column data files using the WRITE command.
In the following table, FACTOR, OFFSET refer to transformation values where
ACTUAL = READ∗FACTOR+OFFSET
F-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix F: Data Files
NPT is the number of data points and NCOL is the number of columns of data stored. The left column
numbers refer to the type and number of variables in that record. A–80 indicates an 80 character
ASCII string field. R–1024 is a 1024 length real array. The data is stored in 1024 element (4096
byte) chunks up to the required number of elements. All real numbers are REAL∗4 and integers are
INTEGER∗2.
¾
Bytes
80
80
80
80
4
80
8
4096
4096
4-4096
80
4
4096
4096
4-4096
½
»
Type
A-80:
A-80:
A-80:
A-80:
I-2:
A-80:
R-2:
R-1024:
R-1024:
R-MOD(NPT,1024)
A-80:
R-2:
R-1024:
R-1024:
R-MOD(NPT,1024)
Description
VERSION GENPLT 4.0
text
text
∧A
NPT,NCOL
column description
FACTOR,OFFSET
data(1...1024)
data(1025,2048)
data(2049,NPT)
column description
FACTOR,OFFSET
data(1...1024)
data(1025,2048)
data(2049,NPT)
|
|
| Repeat NCOL times
|
|
¼
GENPLOT uses Ryan–McFarland/IBM Professional Fortran binary records. They are stored on
disk as
>> <record length><data...data><record length>
The record length is a 4 byte integer giving the total byte length of the record including the 8 bytes
used by the record length itself. All data is stored in byte reversed, least significant first, (Intel)
order and real numbers are in IEEE floating point format. The record corresponding to NPT = 100,
NCOL = 2 would be (in hexadecimal, spaces are added for clarity):
>> 0C 00 00 00 64 00 02 00 0C 00 00 00
Example routines for writing GENPLOT binary files from FORTRAN, C and Pascal are given at
the end of this appendix.
PITFALLS AND PROBLEMS: (OR COMMON ERRORS)
1. The last line of an ASCII file will not be read unless it ends with a <CR><LF>. We suggest always
leaving an extra blank line at the end of ASCII files to avoid this FORTRAN “feature”.
2. Expressions given in an ASCII file are evaluated using currently defined constants. Be sure to
declare such constants before reading the file. Also remember that expressions cannot contain
space since spaces are the column delimiters.
3. The ASCII fields in BINARY files MUST be 80 characters in length. The correct usage is
TOK80 = ’Hi there’
WRITE(UNIT) TOK80
F-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix F: Data Files
but the following is wrong
WRITE (UNIT) ’Hi there’
4. By definition, BINARY files are machine and compiler specific. Do not try to use files
generated by other than IBM PROFESSIONAL or Ryan–McFarland FORTRAN unless you follow
the examples below.
Writing Binary Files From Other Languages
These subroutines will store an X,Y,Z array in GENPLOT binary format. The column description
will someday be accessible within GENPLOT for such usage as
LET TITLE BOTTOM = DESCRIPTION X
Plan for such capability when writing save subroutines.
SAMPLE SOURCE CODE
Sample source code for writing GENPLOT compatible binary files from various languages comes
with the distribution in \GENPLOT\ EXAMPLES. This currently includes Ryan–McFarland FORTRAN,
Microsoft FORTRAN, Turbo Pascal and Turbo C.
F-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX G: GENPLOT FILES
Below is a descriptions of the files contained with the GENPLOT distribution. Your distribution
diskettes may contain more or fewer files (depending on the whims of the day).
GINSTALL.BAT
Run Files
GENPLOT.EXE
GENPLT.OVL
ALL DYN.OVL
ANNOTE.OVL
FIT$.OVL
SPLINE$.OVL
HELP$.OVL
MOTMACS.OVL
USER$.OVL
Genplot installation batch file
3D PLT.OVL
PKUNZIP.EXE
Minimal shell GENPLOT executable file, loads overlays
Main GENPLOT overlay
Support overlay with almost everything but the kitchen sink
Annotate overlay (the kitchen sink)
Overlay for fit routines
Spline fit overlay
Online help overlay
Editor overlay
Dynamic overlay file containing calls to the user supplied subroutines in USER$.FOR.
3–D overlay
Program to uncompress distribution files (.ZIP)
Internal Data Files
DEVICES.DAT
GENPLT.HLB
HDATA.CHR
HDATA4.CHR
Device description file
Genplot online help file
Character set description file for 9 sets
Character set description file for 4 set
Device Drivers
COMREX.DRV
DEB.DRV
DEBUG.DRV
DESKJET.DRV
DRVQUIC.DRV
EGA–VGA.DRV
HERCULES.DRV
HP–GL.DRV
HPRASTER.DRV
IBM4019.DRV
IBM8514.DRV
IBMBIOS.DRV
IBMCGA.DRV
IBMEGA.DRV
IBMHGA.DRV
IO ASYNC.DRV
IO FILE.DRV
IO GPIB.DRV
IO GPIB2.DRV
IO NOVELL.DRV
IO SPOOL.DRV
LASERJET.DRV
Comrex plotter driver
AT&T Display Enhanced Board
Debugging driver (for those bugger problems)
HP DeskJet driver
QMS/Talaris QUIC driver
New EGA/VGA driver
Hercules driver
HP plotter driver
HP printer driver
IBM LaserPrinter E driver
IBM 8514 1024x768 display board
BIOS driver
CGA driver
EGA driver (superceeded by EGA–VGA)
Super-VGA modes
I/O driver to RS-232 communication ports
I/O driver to files
I/O driver to National Instruments GPIB
I/O driver to IOTech GPIB
I/O driver for Novell Networks
I/O driver to mainframe spooling programs
HP LaserJet (II/III) driver
G-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix G: GENPLOT Files
NULDRV.DRV
PAINTJET.DRV
POSTDRV.DRV
RASTER.DRV
RASTER2.DRV
RS232DRV.OVL
SST.DRV
SUMMA.DRV
TEK4957.DRV
TEKTRX.DRV
TIFF.DRV
WPDRV.DRV
Null device driver
HP PaintJet driver
PostScript driver
Epson, OkiData, etc. driver
Raster driver with sort routine
RS-232 COM port driver (used by I/O above)
SST Enhancement board for HP LaserPrinter II
Tablet driver for Summagraphics tablets
Tablet driver for Tektronix 4957 digitizing tablet
Tektronix 4014 driver
Driver for TIFF interchange format
WordPerfect 5.0 driver
Utilities
19200.COM
GRHP.COM
GREPSON.COM
FIXBIT.COM
\GENPLOT\UTIL
Sets com port to 19200 baud
TSR program allowing EGA PrintScreen to HP LaserPrinter
TSR program allowing EGA PrintScreen to Epson printer
Sets coprocessor bit in equipment flag (for early AT&T 6300’s)
MEM.COM
RS232DRV.COM
SCRNSAVE.COM
STATUS.COM
VSORT.EXE
WATCH.COM
Shows memory and disk usage
Serial device driver (obsolete)
Blanks video display when not in use
Shows RS232 status
Vector sort routine to use with RASTER2
Watches memory allocation
Examples
README
AUTOEXEC.BAT
COVER
TITLE
LORENTZ
\GENPLOT\EXAMPLES
Guess
Sample autoexec.bat file
Macro and data for the plot on the manual cover
Macro and data for the plot on the manual title page
User routine and data implementing complex LORENTZ fit
algorithm
Writing a GENPLOT binary in TurboC
Writing a GENPLOT binary in TurboC
Writing a GENPLOT binary in Ryan-McFarland FORTRAN
Writing a GENPLOT binary in MicroSoft FORTRAN
Writing a GENPLOT binary in Turbo Pascal (Not for real
programmers)
Writing a GENPLOT binary in Quick Basic (Not for real
programmers)
BINPTRTC.C
BINARYTC.C
BINRM.FOR
BINMS.FOR
BINTP.PAS
BINQUICK.BAS
Tutorial
T1.DAT
T2.DAT
T3.DAT
TEST.DAT
\GENPLOT\TUTORIAL
Tutorial data files
Library
README
USER$RUN.ASM
USER$RUN OBJ
\GENPLOT\LIB
Guess
Assembly language links between USER$ and GENPLOTuser
Object of same
G-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix G: GENPLOT Files
ALL.EPF
DYNT.OBJ
DYNT2.OBJ
FIX UP.OBJ
MAIN$.OBJ
F77STRIP.COM
ALLDRV.INF
ALLDRV.OBJ
EXAMPLE.F77
EXAMPLE.LNK
EXAMPLE.BAT
DRIVER.F77
DRIVER.BAT
TABLET.F77
TABLET.BAT
USER$.F77
USER$.BAT
RUMP.F77
RUMP.BAT
RDASM.OBJ
LASER.F77
LASER.BAT
Object file with dynamic links
Routine for loading dynamic modules
Routine for secondary loading dynamic modules
Module for resolving dynamic links
Main program initializing dynamic modules
Program to strip comments from .F77 source files
Information on calling sequence for general I/O channel usage
General I/O channel library
Example main procedure for calling GENPLOT directly
Link file for EXAMPLE
Batch file to compile and link EXAMPLE.F77
Specification of call sequence for graphics device drivers
Batch file to compile and link DRIVER.F77
Specification and example for a digitizing tablet driver
Batch file to compile and link TABLET.F77
Example default USER$ routine
Batch file to compile and link USER$.F77
Example USER$ (linked as .USR) for reading RUMP data
files
Batch file to compile and link RUMP.F77
Assembly code called by RUMP.F77
Example USER$ (linked as .USR) extending function evaluator
Batch file to compile and link LASER.F77
G-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX R: RUN TIME SUPPORT
GENPLOT requires several run-time loadable files to operate properly (or in some cases at all).
By default, the program assumes that it can find these files in the c:\GENPLOT directory on your
system. This default may be modified on either a file–by–file basis or for certain groups of files. The
purpose of each file will be described below along with the specifics for overriding the default name.
These files include information necessary for the following:
•
Dynamically linked executable codes
•
Graphic device driver overlay files (executable code)
•
I/O channel overlay files (executable code)
•
Dynamic loaded command overlay files (such as ANNOTE)
•
Names, types and capabilities of the plotters available
•
Graphic character descriptions
DYNAMICALLY LOADED OVERLAY FILES
The first four groups of files listed above are referred to generically as DYNT modules, which roughly
abbreviates for dynamic loaded files. These are internal concepts to Thompson kludgeware and are
not tied to any other commercial package. Currently, a dynamic file may be identified by the .OVL or
.DRV extension although this is only a convention which may not be adhered to in the future. Overlay
files contain sections of code which are loaded only as required and which may or may not remain
resident in the computer memory. Although internally quite complex, they allow additional features
to be added and dynamically loaded without regenerating the entire program. In particular, the
specific drivers for each graphic device is an DYNT module which is swapped in only when necessary.
Additional drivers may be written at any time and included in the DEVICES.DAT file below to add
new plotters to GENPLOT.
DYNT modules include ALL DYN.OVL, GENPLOT.OVL, ANNOTE.OVL and FIT$.OVL. These are command
and general utility overlays. The second group of overlay files, EGA-VGA.DRV, POSTDRV.DRV, etc. are
graphic drivers. See Appendix D for additional details on these drivers. The files in \GENPLOT\LIB
are provided for making additional DYNT modules.
All of the .OVL files should lie in a single subdirectory which defaults to c:\GENPLOT. This default
directory may be overridden by setting an environment variable DYNT LIB before executing GENPLOT. Alternatively, any single .OVL file may be redirected by setting an environment variable of
the same name. The DOS command
SET DYNT LIB=D:\MOT\GENPLOT
causes default GENPLOT files to be loaded from the directory d:\mot\genplot.
WARNING: When setting environment variables, spaces should not be used on either side of the
= sign since DOS takes blanks to be significant (GENPLOT will ignore them however). Secondly, it
is not possible to change environment variables once inside GENPLOT as DOS maintains separate
R-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix R: Run Time Support
copies of the environment for each process. Consequently, all setting of environment variables must
be done before entering GENPLOT.
CHARACTER SET DATA
The actual pen movements required to draw the text in the graphics mode is loaded at run time
from a file called HDATA.CHR. The distributed version of HDATA.CHR contains specifications for 9
HERSHEY based character sets. These are currently assigned as
0. Special Symbols
1.
Normal Roman
2.
Normal Greek
3.
Fancy Roman
4.
Fancy Greek
5.
Old English
6.
Normal Greek (modified order)
7.
Fancy Greek (modified order)
8.
Script
Your distribution may also include files HDATA4.CHR and HDATA2.CHR which contain only the first
0-4 and the first 0-2 sets respectively. Since memory is allocated for the character sets at run time,
memory may be saved by using one of the smaller character files. To change which block of character
sets is loaded, the name HDATA.CHR must be point to one of the other files. A permanent change
may be effected by renaming either HDATA2.CHR or HDATA4.CHR to HDATA.CHR. It is recommended
that the default HDATA.CHR be copied to HDATA9.CHR before it is lost.
A second way to temporarily change the character set file is to set the ENVIRONMENT variable
HDATA.CHR to point to some other filename. If the DOS command
SET HDATA.CHR=C:\GENPLOT\HDATA4.CHR
is executed BEFORE running GENPLOT, the 4 character data set will be loaded. See the warning
on setting environment variables from within GENPLOT below. This method is preferred if you
only wish to delete character sets for a particular problem which requires a large memory block.
I apologize, but because of the order of code execution, it is not possible to gracefully recover from
a failed character set load (such as insufficient memory). The program will request a new pathname
for the character data (to which you might respond HDATA2.CHR) and will fatally terminate if unable
to load. If this becomes an annoying problem, include the command CHRSET 1 in your default
GENPLOT.INI file. This will force a character set load immediately and allocate memory early in the
plotting sequence.
DEVICE DESCRIPTION FILE
One of the most important files included in \GENPLOT is the DEVICES.DAT file which describes the
graphic devices recognized by GENPLOT. The file comes configured for a number of devices with
default names which have evolved over the years. Devices within GENPLOT are identified by a
unique character name (although longer names are allowed, only the first eight are checked for
identifying a driver).
R-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix R: Run Time Support
DEVICES.DAT is described in detail in the APPENDIX concerning graphic devices supported. At
this point, only the method for redirecting the file is discussed. Redirection occurs in the similar
manner as for HDATA.CHR. The environment variable DEVICES.DAT can be set to point to another
file. For instance, the DOS command
SET DEVICES.DAT=B:DEVICES.DAT
will take device information from the B: disk rather than from the default c:\GENPLOT\DEVICES.DAT
file.
MOVING THE ENTIRE DEFAULT GENPLOT DIRECTORY
All files required for run-time of GENPLOT can be moved with a single environment variable. The
dynt lib variable determines where GENPLOT finds the .OVL, .DRV, HDATA.CHR, DEVICES.DAT and
GENPLOT.HLB files.
set dynt lib=d:\MYPLOT
Remember, however, that GENPLOT.EXE must be placed in a directory within the scope of your
current command search path.
RUNNING GENPLOT ON FLOPPY DISK BASED SYSTEMS
First, have you head examined for sanity. While it is possible to run GENPLOT from floppies, it is
not terribly efficient. All of GENPLOT will not fit on a single 360 kB floppy, although most of it
will go on a 1.2 Mbyte floppy disk. If you have a 1.2 Mb drive, simply redirect the default directory
to the A: disk as discussed above.
On a real 360 kB system (or 720 kB hard disk floppies), it will be necessary to split the overlay files
among two disks. The simplest method is to place ALL DYN.OVL, GENPLOT.OVL and GENPLOT.EXE
on one disk; these routines always remain resident once loaded. They can be redirected individually
with the remaining files on the A: or B: drive.
Disk 1: System BOOT disk with the \GENPLOT directory. \GENPLOT should have all the files HDATA.CHR,
DEVICES.DAT, all .OVL files except GENPLOT.OVL and ALL DYN.OVL, and any necessary .DRV
files. I’d leave off GENPLOT.HLB as well since it is quite large.
Disk 2: GENPLOT.OVL, ALL DYN.OVL and GENPLOT.EXE only.
• set genplot.ovl=b:genplot.ovl
• set all dyn.ovl=b:all dyn.ovl
• set dynt lib=a:\genplot
To run, place disk 1 in drive A: and disk 2 in drive B:. Type B:\GENPLOT to initialize GENPLOT.
After initialization, disk 2 may be removed and the drive used for data diskettes.
R-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX S: GENPLOT AS A SUBROUTINE
If you intend to write subroutines, please first look carefully at the examples in the lib directory.
These are working examples which show the correct syntax for subroutine calls and the necessary
linking sequences.
Although the standalone version of GENPLOT is powerful, it is impossible to foresee the needs of
every user in every case. Hence, we provide several levels of interface between GENPLOT and user
written subroutines and programs. The easiest interface with GENPLOT is through hooks written
into the code and accessed via the USER$ functions; these hooks include the command USER which
executes a user written subroutine (or loads a new set of user routines), and the -USER options of
the READ and WRITE commands. These routines are loaded from either the USER$.OVL file or any
.USR file which may be written as necessary. With these hooks, the following GENPLOT commands
actually call and execute user written subroutines.
USER
READ -USER
WRITE -USER
Invokes the user written subroutine USER$
Invokes the user written subroutine USER$RD
Invokes the user written subroutine USER$WR
The second level of support for user entensibility dates from the original purpose of GENPLOT, that
of a subroutine callable from any user written FORTRAN program. In both the USER hook mode and
the subroutine call mode, GENPLOT is not actually linked to the user written routines, but rather
dummy linked through the dynamic load modules. This provides for rapid linking with the main
program, avoids the need to distribute source or object level code, and includes FORTRAN library
links in the dynamic modules. Consequently, the use of compatible compilers is essential.
The following section discusses compilers and linkers known to be compatible with GENPLOT.
FORTRAN Compilers:
1. Ryan-McFarland F77: Ryan-McFarland FORTRAN 77 Rev 2.42. This is the compiler we
currently use in generating the GENPLOT object code. The compiler still has some troublesome
and annoying bugs, but all can be programmed around. (Note, we recommend use of the /Z1 or
/Z option at all times because of problems with the RM implementation of the SAVE statement.)
Be sure to obtain revision 2.42. Rev. 2.40 is littered with bugs and programming is almost
impossible unless you love assembly code debugging. We never managed to obtain a working
GENPLOT from compilers prior to 2.40 (but after the split from PROFORT).
Note: The /I option must be used to force all integers to be short, 16 bit, words. This guarantees
compatibility with GENPLOT, improve execution speed and reduce memory requirements. If
the switch is not used, all integer variables passed to GENPLOT routines must be declared
INTEGER*2.
2. IBM Professional F77: The IBM Professional FORTRAN at revision level 1.14 is mostly
compatible with GENPLOT and the new RMFORT compiler. However, no guarantees are made.
The IBM Professional FORTRAN compiler actually got worse as it got older, with unacceptable
bugs introduced at rev 1.19. If you have later versions of this compiler, they may work but we
have never tried them. We recommend that you either upgrade to Ryan-McFarland 2.42 or find
an old copy of PROFORT 1.14. (PS, while your at it, you might add a letter of complaint to
IBM directly) See the note above concerning the /I switch. WARNING: The IBM Professional
S-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
FORTRAN is not the same as the standard IBM FORTRAN; the original IBM FORTRAN is
an absolute disaster and is best used for warmth in a fireplace.
3. Microsoft F77: We receive numerous requests for Microsoft FORTRAN support. As soon as
Microsoft releases a compiler which is even close to bug free (which has not happened yet and
we’re been through Rev. 2.x, 3.x and now 4.0), we may provide support as an option. Until then,
Microsoft FORTRAN cannot be supported in any way. Furthermore, the increasing complexity
of Microsoft FORTRAN necessary to maintain compatibility with other Microsoft compilers
makes support extremely difficult even if we had a good compiler. Any release of GENPLOT
under Microsoft FORTRAN will only be possible in one of the memory models, and the various
language interface supports may have to be eliminated.
• Microsoft 5.0 FORTRAN looked initially to be a healthy and refreshing change from their earlier
compilers. However, it is incompatible with itself, and has numerous serious failures with respect
to the ANSI FORTRAN standard. We are no longer considering it for anything more than a
doorstop. Sorry. Wait for the C version in UNIX or OS2.
Other Languages:
1. Calling Sequence: GENPLOT is compatible with other languages in as far as the calling
sequence can be emulated by the specific compiler. Ryan-McFarland FORTRAN uses an unusual
frame pointer structure for argument passing, using ES:BX to point to the frame. In contrast,
most other compilers place the arguments on the stack. Assembly language interludes can be
used to establish the alternate frame pointer for interlanguage calls.
2. Memory Constraints: GENPLOT is a memory hog. However, it includes most, if not all, of
the FORTRAN libraries. Relatively complex routines can be written in FORTRAN and linked
with no major increase in size. However, if another compiler requires a comparably sized library
to be loaded, memory will quickly limit the programs which can be run.
3. I/O system: As a rule, any time multiple compilers are used in a single run-time module,
only one should be allowed to interface with the file system. Each compiler sets up its own disk
transfer areas and handles file opening/closing in a different manner. Mixing these interfaces is
bound to cause trouble.
4. Disclaimer: We make no claims that GENPLOT can be successfully interfaced to any compiler.
Responsibility for code generation and testing lies entirely with the programmer foolish enough
to embark on such an escapade.
Macro Assembler and Linker
1. MICROSOFT Macro Assembler Rev. 4.0. Unlike FORTRAN, the macro assembler is almost
stable and reasonably free from problems. Versions from 2.0 to 5.0 seem to work equally well.
2. MICROSOFT Linker 3.61. Most linkers should work although we recommend staying away from
the /EXEPACK switch in early versions. Earlier versions of the linker lack the /NODEF switch. If
/NODEF is unrecognized by your linker, simply insert an explicit reference to the RMFORT.LIB in
its place.
S-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
USER$ AND .USR INTERFACE
The most common need for user written routines is in reading and writing data from other proprietry
formats, manipulating data in strange manners, and adding functions to the function evaluator. The
USER$ interface provides this functionality without major programming efforts through the USER
command and the -USER option to the READ and WRITE commands.
The overlay file USER$.OVL contains the default entry point for calls from GENPLOT at several
levels. These calls occur at command level with the USER command, and within READ and WRITE
with the -USER option. The first time any USER option is requested, GENPLOT loads USER$.OVL
from disk. Program control is then transferred to the appropriate routine in the module. Any named
module (normally .USR routines) can be loaded in place of USER$.OVL by specifying the -LOAD option
in the USER command. Note that the READ and WRITE commands cannot similarly request a different
module, only USER has the ability to load and reload modules.
By substituting your routine for the distribution USER$.OVL or writing .USR modules, you can have
GENPLOT execute any function you need. However, using any of these routines requires you to
define specific subroutine names, and to link the module in a specific manner, as described in detail
below.
An example GENPLOT\LIB\USER$.FOR program is provided as a template for writing your own versions. Four routines must be provided in all USER modules; USER$ for the USER command, USER$RD
for the READ -USER command, USER$WR for WRITE -USER and USER$CM for future extensions. All four
routines are logical functions which return .TRUE. when successful and .FALSE. when unsuccessful.
The curve data is passed to each routine and each may modify the data and number of points as
necessary.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
========================================================================
Usage: LOGICAL = USER$(xbuf,ybuf,npt,nptmax)
|
LOGICAL = USER$RD(file,xbuf,ybuf,npt,nptmax)
|
LOGICAL = USER$WR(file,xbuf,ybuf,npt)
|
LOGICAL = USER$CM(cmd,xbuf,ybuf,npt,nptmax)
|
|
Inputs: xbuf (real*4 array)
- Array of X data points
|
ybuf (real*4 array)
- Array of Y data points
|
npt (int*2 variable) - Current number of valid points
|
nptmax (int*2 constant) - Maximum number of points allowed
|
file (char*(*) var)
- filename for reading or writing
|
cmd (char*(*) var)
- command to try and execute
|
|
Output: xbuf,ybuf,npt - New curve and valid number of points
|
file
- May be modified w/ extension added
|
USER$
- .TRUE. => operation defined and successful
|
USER$RD
.FALSE. => bad operation. Command line is
|
USER$WR
terminated w/ error handling
|
|
USER$CM
.TRUE. => command was recognized
|
.FALSE. => command was not recognized
|
|
Note: Any undefined function (do nothing) should return false.
|
========================================================================
S-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
Again, all four of these functions should be present in any .USR routines you write. If they are
just do nothing functions, .FALSE. should return immediately. Each user written .USR routine (or
a revised USER$.FOR) must be linked with the dynamic support modules as specified below. The
routine USER$RUN.OBJ from the \GENPLOT\LIB directory must be the first routine linked in every
case. This module handles the calls from GENPLOT and patches them to the appropriate user
written subroutines USER$, USER$WR, USER$RD and USER$CM. We recommend using /liez options
to the RMFORT compiler although only /i is necessary.
¾
»
C:\MYDIR> rmfort user$ /liez
RM/FORTRAN Compiler
Version 2.42
(c)Copyright Ryan-McFarland Corp 1984, 1987
Compiling USER$
0 Errors,
0 Warnings.
Compiling USER$RD
0 Errors,
0 Warnings.
Compiling USER$WR
0 Errors,
0 Warnings.
Compiling USER$CM
0 Errors,
0 Warnings.
Compilation Complete:
0 Errors,
0 Warnings.
C:\MYDIR> link
Microsoft (R) Overlay Linker Version 3.55
Copyright (C) Microsoft Corp 1984, 1985, 1986.
Object Modules [.OBJ]:
Object Modules [.OBJ]:
Run File [USER$RUN.EXE]:
List File [NUL.MAP]:
Libraries [.LIB]:
All rights reserved.
\genplot\lib\user$run+user$+
\genplot\lib\all.epf+\genplot\lib\fix up
\genplot\rdaux.usr
/nodef/stack:1
C:\MYDIR>
½
¼
The /exepack option must not be used when generating dynamic load files. The option /stack:1
minimizes the stack since one already exists in the main program. If /nodef does not fly with your
linker, it may be replaced by an explicit reference to the FORTRAN library RMFORT (nothing
will be loaded from RMFORT though). In this example, the file has been saved as the RDAUX.USR
module.
During execution, the file RDAUX.USR would not be loaded until the command USER -LOAD RDAUX
was given. If no -LOAD module is specified on the first USER invocation, or if READ -USER or WRITE
-USER are executed before running USER, the default USER$.OVL would have been loaded. If the
system hangs in the USER$ loading, the fault is likely that the link did not exactly follow the above
sequence. Remember also that integers must be passed as short integers.
S-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
PRACTICAL USAGE OF USER$
1. User routines which only implement the read and write routines must define the USER$ routine as
well. Modules of alternate names can only be loaded from the USER command and hence USER$
will be exectued at least once. On entry, USER$ should indicate what this module implements.
The example program RUMP.FOR in the \GENPLOT\LIB contains code for reading RBS data files.
2. The other major use for USER is extending the capabilities of the function evaluator or implementing unusual functions. The example program LASER.FOR in the \GENPLOT\LIB does not
implement any of the USER$ subroutines in reality, but rather only links into the function evaluator several useful transformations. See the routines below GV$LINKE.
3. The third major use of USER is controlling instruments for data collection with immediate analysis
capabilities. Numerous modules can be written, each for a different instrument, and each designed
to collect data in very different manners.
NOTES AND COMMON PROBLEMS WITH USER$
1. READ and WRITE check their options sequentially. If a -USER option is found, parsing immediately
terminates and USER$RD is called. Any options previously read are lost, and any subsequent
options must be interpreted by the user reading (or writing) routines. The user routines may
choose to parse tokens as necessary. Any tokens left on the line will be read by GENPLOT as
commands upon return.
¾
»
GENPLOT: read file1 -user -col 1
/* ’-col 1’ should be read by the user routine, if not, GENPLOT will
/* generate an error when it is read as a command upon return
GENPLOT: read file2 -user plot
/* The user routine may use ’plot’ as an option.
/* happy to execute it upon return.
However, GENPLOT will be
GENPLOT: user -load rdaux read file3 -col 3 -user
/* ’-col 3’ will be lost
½
¼
2. With our “let the programmer beware”, no checking is done on valid modifications of xbuf, ybuf,
npt or nptmax. You may change these at will in the USER$ procedures and take the consequences
if you cause a memory write to an unknown location. Worst you can do is overwrite the disk
FAT table or overwrite the system configuration data (don’t say you’ve never been warned —
I’ve done it). Best bet is to make sure no data is written beyond nptmax and that nptmax is
not changed, unless you know exactly what you are doing! (For example, you may know that
XBUF and YBUF are really much larger than GENPLOT thinks and hence you can safely write
beyond NPTMAX.)
3. All of the parsing and processing subroutines are available within USER$. See the section following
’Calling GENPLOT as a Subroutine’ for a description of the more useful of these.
S-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
CALLING GENPLOT AS A SUBROUTINE
GENPLOT is callable as a subroutine from any user written FORTRAN program, assuming you
follow the link procedure specified below exactly. As an example, consider a simple program which
calls GENPLOT directly. The calling sequence for GENPLOT is
|
|
|
|
|
|
|
|
|
|
|
|
|
========================================================================
GENPLT2: Subroutine to pass an X,Y,NPT curve to the GENPLOT processor |
and enter command mode in GENPLOT.
|
|
Usage:
CALL GENPLT2(xbuf, ybuf, npt, nptmax)
|
|
Inputs: xbuf (real*4 array)
- Array of X data points of main curve |
ybuf (real*4 array)
- Array of Y data points of main curve |
npt (int*2 variable) - Current number of points in curve
|
nptmax (int*2 constant) - Defined size of XBUF and YBUF
|
|
Outputs: xbuf - modified curve data
|
ybuf - modified curve data
|
npt - number of points now valid
|
========================================================================
(The call to GENPLOT is to the subroutine GENPLT2.) When GENPLOT is called, it respond
the first time with a message giving the current revision date, and the number of data points available. GENPLOT returns from this subroutine call via the RETURN command. The QUIT command
exits completely without ever returing to the calling routine. The following program, stored as
TEST.FOR, calls GENPLOT with a 1000 point, uninitialized buffer.
¾
»
subroutine main(cmline,ircode)
character*(*) cmline
integer ircode
/* Subroutine main header
real xbuf(1000),ybuf(1000)
integer npt
external genplt2,genoff
/* Allocate X,Y buffers
/* Integer number points
/* Declare external routines
npt = 1
call genplt2(xbuf,ybuf,npt,1000)
/* No points valid, start
/* Enter GENPLOT
call genoff
ircode = 0
return
end
/* Gracefully exit
/* Return code is 0
c
c
c
½
¼
This example could easily have included some data analysis or collection prior to calling GENPLOT.
In such cases, GENPLOT would be transferred valid data for immediate plotting as desired. This
program is almost equivalent to the stand alone GENPLOT version with a 1000 point buffer.
Several important points must be made on the program above. First, the main user level program
must be a SUBROUTINE MAIN and not a program module. The only program allowed is PROGRAM MAIN$
which is provided in the c:\genplot\lib directory. MAIN$ is a program that handles initialization
S-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
processes related to the dynamic load modules, and then transfers control via a subroutine call to
subroutine MAIN. Hence, where you previously defined a PROGRAM module (or the main module), you
must now rename it as SUBROUTINE MAIN.
When MAIN$ transfers control to MAIN, the remainder of the command line typed after the program
name is placed in the character string CMLINE, and is available for program usage. For example,
<program> Hi there would place the string Hi there into the variable CMLINE. IRCODE is a return
variable which is passed to DOS as the return code after execution. This may be tested using the
ERRORLEVEL command in batch processing or through other programs. If IRCODE is non-zero,
the termination message Execution terminated: nnn will be printed at exit time.
The call to GENOFF causes all GENPLOT related processes to be terminated gracefully, including
closing down the plotter, HCOPY files and temporary macros. Finally, note that a RETURN is done
from the subroutine back to MAIN$. You may choose to do a STOP instead, however IRCODE will
not be passed to DOS as the termination value. A subroutine EXIT is also provided for exiting and
passing a return parameter to DOS. CALL EXIT(int*2) will cause execution to terminate with the
specified return value.
• All variables passed to GENPLOT must be 4 byte reals or 2 byte integers. The compiler switch /I
should be used to force all integers to be short words. This guarantees compatibility with GENPLOT,
improves speed performance and reduces the memory requirements. If the switch is not used, all
integers variables passed to GENPLOT routines must be short integers; integer constants are allowed
as long as they do not exceed the range of a short integer, ±32767.
LOAD SEQUENCE
Linking the above program requires the files \GENPLOT\LIB\ALL.EPF, \GENPLOT\LIB\DYNT and
\GENPLOT\LIB\MAIN$ as well as the user routines. The FORTRAN library is not required since
it already exists within the dynamic modules. (A license for RMFORT, however, is required.) The
following example assumes the Ryan-McFarland 2.42 compiler and the Microsoft 3.55 linker.
S-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
¾
»
C:\MYDIR> rmfort test /liez
RM/FORTRAN Compiler
Version 2.42
(c)Copyright Ryan-McFarland Corp 1984, 1987
Compiling MAIN
0 Errors,
0 Warnings.
Compilation Complete:
0 Errors,
0 Warnings.
C:\MYDIR> link
Microsoft (R) Overlay Linker Version 3.55
Copyright (C) Microsoft Corp 1984, 1985, 1986.
Object Modules [.OBJ]:
Object Modules [.OBJ]:
Run File [TEST.EXE]:
List File [NUL.MAP]:
Libraries [.LIB]:
All rights reserved.
test+\genplot\lib\dynt+
\genplot\lib\main$+\genplot\lib\all.epf
test
/nodef/exepack
C:\MYDIR>
½
¼
The /nodef switch tells the linker not to include default libraries in the load. If this switch does
not work on your linker revision level, simply include the appropriate library, RMFORT, in the
library list. Only RMFORT should be bypassed; if you are using C or another language interface,
its library should be fully linked. The /exepack causes the program module to have redundant
strings compressed. This switch has been known to fail in early linker versions.
If the link succeeds, you should have an executable program on the order of 4900 bytes in length. Do
not be deceived, the actual executable size will be substantially larger once GENPLOT is dynamically
loaded. Notice, however, how rapidly the link goes with the dynamic linking. Try running TEST.EXE
and hope that it works.
Many subroutine and function calls are accessible to the programmer in GENPLOT. Some of the
common routines are listed later in this appendix.
NOTES AND COMMON PROBLEMS WITH CALLING GENPLOT
1. Due to the segmented architecture of the PC, the largest real*4 array which may be passed to
GENPLOT is 16380 elements. GENPLOT may painfully wrap if a larger array is passed.
2. I have no idea what GENPLOT will do if you pass a negative argument to NPT or NPTMAX.
That question is left for experimentation.
3. You call GENPLT2, not GENPLOT.
S-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
USEFUL SUBROUTINES AVAILABLE TO THE PROGRAMMER
The following routines are considered to be the more “useful” of the hundreds available within the
GENPLOT program. The headers printed below provide a brief description of each subroutine and
the formal syntax for each. All real parameters are expected as REAL∗4, integers are INTEGER∗2,
and characters are generally assumed to be arbitrary length. Logical variables are 4 bytes, but only
the low order byte is written. Functions returning integers must be declared INTEGER∗2, although
functions returning real numbers may be declared as REAL∗4 or REAL∗8. Use of the ’/I’ switch
with the compiler automatically makes all variables compatible.
The routines are divided into two sections, those related to executing GENPLOT and terminating
from a program, and those related to parsing of command lines within user programs.
GENPLT2
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
========================================================================
GENPLT2: Subroutine to pass an X,Y,NPT curve to the GENPLOT processor |
and enter command mode in GENPLOT.
|
|
Usage:
CALL GENPLT2(xbuf, ybuf, npt, nptmax)
|
CALL GENPLT (xbuf, ybuf, npt)
|
|
Inputs: xbuf (real*4 array)
- Array of X data points of main curve |
ybuf (real*4 array)
- Array of Y data points of main curve |
npt (int*2 variable) - Current number of points in curve
|
nptmax (int*2 constant) - Defined size of XBUF and YBUF
|
|
Outputs: xbuf - modified curve data
|
ybuf - modified curve data
|
npt - number of points now valid
|
|
Note: The GENPLT and GENPLT2 versions of this call are identical
|
with the exception that NPTMAX is assumed to be equal to NPT in |
the GENPLT call. GENPLT is included for backward compatibility |
and its continued use is discouraged.
|
========================================================================
The buffers X,Y may initially contain either valid data or may be dummy arrays into which data
will be read via GENPLOT commands. Control is returned to the calling program via execution of
a RETURN command.
S-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
GENOFF
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
========================================================================
GENOFF: Subroutine to clean up and close all temporary processes in
|
GENPLOT prior to a final exit to the operating system. This
|
routine closes down the current device, closes and disposes of |
any HCOPY file currently open, and terminates any temporary
|
macro file opened during GENPLOT. This subroutine should be
|
called prior to final exit or when plotting is complete.
|
|
Usage:
CALL GENOFF
|
|
Inputs: none
|
|
Output: none
|
|
Note: This sequence is also done by the command "QUIT" in GENPLOT. An |
alternate exit sequence from program control is the two commands |
CALL CMDLIN(’QUIT’)
|
CALL GENPLT2(X,Y,npt,nptmax)
|
========================================================================
|
|
|
|
|
|
|
|
|
|
|
|
|
|
========================================================================
EXIT: Subroutine to exit a program to the operating system. This is
|
almost equivalent to the FORTRAN stop command except that the
|
return code to DOS may be a variable instead of constant as in
|
the STOP command.
|
|
Usage:
CALL EXIT(icode)
|
|
Inputs: icode (INT*2 variable) - Return code to DOS on exit
|
|
Output: none
|
|
Note: This is a permanent exit to DOS. All allocated memory is
|
released, and control is returned to DOS. Device drivers and
|
temporary files are not closed down by this command.
|
========================================================================
EXIT
S-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
CMDLIN
========================================================================
| CMDLIN: Subroutine to place a character string into the current
|
|
command line. This effectively prepends the string to any
|
|
text the user has already typed. Use of this command is
|
|
common to preset an operation before entering GENPLOT.
|
|
|
| Usage:
CALL CMDLIN(string)
|
|
|
| Inputs: string (CHAR*(*) variable) - String to be prepended to
|
|
command line buffer.
|
|
|
| Output: none
|
|
|
| Limitations: The remainder of the user’s string and the new string
|
|
fit into the current 132 character command line. The
|
|
string will be truncated otherwise.
|
========================================================================
This is an extremely useful command for passing commands to GENPLOT from within program
control. Typical program sequence might be as follows:
¾
»
subroutine main(cmline,rcode)
character*(*) cmline
integer*2 rcode
integer NPTMAX
parameter (NPTMAX=1000)
real x(NPTMAX), y(NPTMAX)
integer*2 i, npt
external cmdlin, genplt2
...
...
i = 1
call cmdlin(’TITLE BOTTOM ’’Time (ns)’’ RETURN’)
call genplt2(x, y, i, NPTMAX)
call cmdlin(’TITLE LEFT ’’Voltage (V)’’ RETURN’)
call genplt2(x, y, i, NPTMAX)
call cmdlin(cmline)
call cmdlin(’PLOT -LT 1 -PEN 3’)
call genplt2(x, y, npt, NPTMAX)
...
½
¼
The titles are automatically set by the prepended command line and the RETURN command guarantees that program control returns immediately to the users routine. The reason one would use ’i’
in the first two calls rather than ’npt’ is that GENPLOT does a min/max determination on the data
S-11
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
on every entry. Setting i = 1 minimizes the time needed to do this. (And I like things to go fast).
Before entering GENPLOT with the real data, the command line type when invoking the program,
CMLINE, is passed to the command parser. And finally, an initial plot command is prepended to
everything. GENPLOT2 is called and one is off and running.
LEXFIL
========================================================================
| LEXFIL: Logical function to open a file, and cause subsequent command |
|
lines to be read from this file. The file will be opened on |
|
any available file unit and subsequent command lines will be |
|
taken from this file instead of the console (or currently
|
|
active file). LEXFIL calls may be nested to a maximum depth |
|
of 5. The file is automatically closed and control passed
|
|
to the next lower command file upon reaching the end of file. |
|
|
| Usage:
LOGICAL = LEXFIL(filename)
|
|
|
| Inputs: filename (char*(*) variable) - File name to be opened for
|
|
reading subsequent command lines. File must exist
|
|
with the name exactly as passed.
|
|
|
|
Special filenames: -TTY
==> Close all files and return to
|
|
console input level.
|
|
-RETURN ==> Close current level of file and |
|
return to next lowest.
|
|
null
==> Blank filename same as -TTY
|
|
|
| Output: LEXFIL - .TRUE. => success opening the file
|
|
.FALSE. => failure. File does not exist or too many |
|
levels have been requested.
|
|
|
| Note: The remainder of the current command line will be executed
|
|
before any commands are read from the specified file.
|
========================================================================
The GENPLOT command XEQ is implemented essentially as a call to this subroutine, after handling
the BASE MACRO directory problem. Subroutine opens a disk file and takes subsequent requests
for commands from the disk file rather than the user. When the end of file is reached, the disk is
closed and commands are taken from the interactive user again.
¾
»
if (exst$f(\exper\init’) then
if (lexfil(\exper\init’))
+
call tcou(’Initialization file started’)
endif
call genplt2(x,y,npt,nptmax)
½
¼
S-12
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
PARSING TOKENS
========================================================================
| Series of routines to return tokens from the current command line (and |
| possible prompt for a new command line). These provide a standard
|
| interface with the rest of GENPLOT
|
|
|
| Usage:
REAL
= rdarg(default,prompt)
Read a real number
|
|
INTEGER = nrdarg(idefault,prompt) Read an integer
|
|
LOGICAL = gettok(token)
Return next string token
|
|
LOGICAL = getto1(token,prompt)
Return/prompt for token
|
|
LOGICAL = getexp(token)
Return string expression
|
|
LOGICAL = getexp1(token,prompt)
Return/prompt for expression|
|
LOGICAL = getfile(token)
Return next filename
|
|
LOGICAL = getfile1(token,prompt) Return/prompt next filename |
|
|
| Inputs: default - real default value
REAL*4
|
|
idefault - integer default value
INTEGER*2
|
|
prompt
- prompt to use if not token available
CHAR*(*)
|
|
|
| Output: token
- string token returned
CHAR*(*)
|
========================================================================
S-13
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix S: GENPLOT as a Subroutine
FUNCTION EVALUATOR SUBROUTINES
========================================================================
| Series of routines to link with the function evaluator. These routines|
| link user variables and functions into the function evaluator for
|
| use by any user expression or modification.
|
|
|
| Usage:
LOGICAL = gv$linkr(name,var,1,1)
Link a real variable
|
|
LOGICAL = gv$linki(name,ivar,2,1)
Link a real variable
|
|
LOGICAL = gv$linka(name,array,3,len) Link an array
|
|
LOGICAL = gv$links(name,var,4,1)
Link a string variable |
|
LOGICAL = gv$linke(name,routine,6,1) Link an external routine|
|
LOGICAL = gv$curve(name,x,y,npt,nptmax,ids) Link a curve
|
|
| Inputs: name
- name of the variable (uppercase)
CHAR*(*)
|
|
var
- actual variable to be linked
REAL*4
|
|
ivar
- actual variable to be linked
INTEGER*2
|
|
array
- actual variable to be linked
REAL*4(len)
|
|
len
- length of the array
INTEGER*2
|
|
routine - actual routine to be linked
EXTERNAL
|
|
x,y
- x,y arrays of defined curve
REAL*4(nptmax)|
|
npt
- variable w/ number of points
INTEGER*2
|
|
nptmax
- dimensioned size of X and Y
INTEGER*2
|
|
ids
- character string for curve IDS
CHAR*(*)
|
|
|
| Output: gv$linkx - success of the link
|
========================================================================
S-14
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX T: TOKEN PROCESSING
After a line of text is typed in response to a prompt from GENPLOT, it goes into a special processing
buffer. From this buffer, it is parsed into a series of tokens which are interpreted as either commands
or arguments to commands. To make GENPLOT work properly, it is important to understand
exactly how GENPLOT does this command interpreting. As mentioned, each typed line is internally
parsed into a series of tokens.
A token is defined as either
1) A contiguous series of alphanumeric characters (usually converted to upper case)
2) A literal text string enclosed in single quotes.
3) An expression marked by matching pairs of parenthesis or braces (when expected)
Tokens on a line are separated by the occurrance of a blank, comma or a semicolon character (see
exceptions below). Note that this immediately implies that the only way to include spaces in a token
is to enclose it in quotes. All (well almost all) commands and arguments within GENPLOT pass
through this token interface.
During execution, GENPLOT requests a token from this token processor as the next command.
Anytime additional commands or arguments are needed, another request for a token is made. If a
token is available on the current command line, it is returned to the calling program. If no token is
available, the user is prompted for a new command line. Every time the program requests a token,
it also passes to the token processor its own prompt to be used in the event no token is available
on the current line. This prompt gives the user at least a hint as to what type of information is
expected next by the program as well as some form of default value. If a token is available on the
previous command line, the prompt is simply ignored eliminating boring and redundant typing for
the experienced user. Hence the beginning user can be prompted for all information necessary while
an experienced user can bypass all such queries by providing all of the command information on
a single command line. (See exceptions below for situations where the normal token processing is
bypassed.)
There are three types of queries for tokens; normal text, mathematical expressions, and filenames.
The following exceptions hold. Filenames are not case converted but are passed case sensitive. Mathematical expressions suspend all delimiters while a parenthesis, brace or bracket is open. Delimiters
are searched for only when all parenthesis are matched. Knowing when GENPLOT is reading text,
mathematical expressions, or a filename is only possible if you have written the code. However, in
most cases it is clear the type of expression expected by GENPLOT at any time.
Consider first a simple command SET which sets the lower and upper range for a plot axis. The
format of SET is SET [LEFT|RIGHT|BOTTOM|TOP] <rmin> <rmax>. Typing SET LEFT 0 100 causes
the left hand Y axis to have a range from 0 to 100. Note that there are four tokens on this command
line. The first is the SET which is interpreted as a command, followed by three arguments in the
specific order of specifying which axis and then the values. The same result may be obtained by
typing each token on a separate command line resulting in the following dialogue with GENPLOT.
T-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix T: Token Processing
¾
»
GENPLOT: SET
[Bottom Left Top Right]: LEFT
Lower range limit (unchanged): 0
Upper range (unchanged): 100
GENPLOT:
½
¼
Most prompts actually obtain a new command line each time. Hence, the remainder of the information may be given at anytime. The following sequence also performs the same operation.
¾
»
GENPLOT: SET
[Bottom Left Top Right]: LEFT 0 100
GENPLOT:
½
¼
Consider a specific example of the CREATE command which provides for both required and optional
arguments to the command. GENPLOT requests a token and receives the token “CREATE” the
token processor. CREATE is an interesting command which creates a curve from a user specified
equation. Since this command requires additional arguments, the arguments will be taken from the
command line if they are present, or a new line will be read in from the user. Once the command
has been processed, GENPLOT starts over again reading another token. Thus, multiple commands
may be typed on a single command line. The command
>> create y = sin(x) label left ’sin(x)’ plot
creates data for SIN(X) in the DEFAULT curve, specifies a label for left axis and plots the data,
all with a single command line. Note that the label sin(x) was quoted to prevent it from being
uppercased by the token processor. New users are encouraged to type only a single token on each
command line and allow GENPLOT to prompt each time for the necessary information. This allows
one to learn the order of parameter input for each command as well as to learn the default values for
each command (more on defaults later). GENPLOT will always (almost) prompt for the information
it requires.
Most commands in GENPLOT have required and/or expected tokens. For example, the CREATE
command expects the tokens Y and = to immediately follow the CREATE token, followed then by
an EQUATION token (which will allow commas for functions). Any other format will either be
reported as an error or executed with predictable, but not desired, results. The following examples
show 2 legal usages of the CREATE command (to illustrate the token concept). The third string will
generate an error from CREATE because of invalid tokens while the fourth will create a SIN(X) curve
and then stop when it tries to execute the + sign as a new command. Try to understand why and
how the number of tokens is determined.
¾
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
GENPLOT:
½
»
create
create
create
create
create
y = sin(x)+cos(x)
y = ’sin(x) + cos(x)’
y=sin(x)+cos(x)
y = (sin(x) + cos(x))
y = sin(x) + cos(x)
/*
/*
/*
/*
/*
Legal Legal Illegal
Legal Illegal
4
4
4
-
tokens
tokens
only 2 tokens
tokens
6 token
¼
T-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix T: Token Processing
REQUIRED AND OPTIONAL ARGUMENTS
Any given command may have both required arguments and optional arguments. The required
arguments must be given first and the program will prompt the user for them if a token is not
available on the current command line. After obtaining all required arguments, GENPLOT checks
only the current command line for optional arguments. Actually, it looks for the next token and
checks it against its list of allowed optional arguments. If the token is not recognized, it throws
the token back on the command line and proceeds as if there are no more optional arguments.
This means your typing errors may turn out to be executed commands in GENPLOT. Again, the
CREATE command provides a specific example. CREATE has three optional arguments, FROM, TO
and POINTS. The command CREATE Y = SIN(X) -FROM -10 -TO 10 works fine. However, CREATE
Y = SIN(X) FORM --10 TO 10 will happily create SIN(X), then complain about the FORM token as
an illegal command. Remember, only the current command line is parsed for optional arguments —
there is never a prompt for these options.
DEFAULTS
Finally, the problem of defaults. GENPLOT is built in with default values for any numeric input
(such as lower and upper limits of a create command). Most text commands also have a default
which often is abort. If you simply press return to a prompt, GENPLOT will use the default value
or reprompt you for the information. You can also take the default value by typing a “/” on a
command line. For example, REGION LEFT / 100 will leave the lower left region limit unchanged
(the default in this case) and set the upper to 100. The default value is often given in a prompt,
but sometimes only the author knows the defaults.
ESCAPE
Some command processors recognize <ESC> as an abort operation command and return immediately
to command level.
EXCEPTIONS
Under special circumstances, the comma and semicolon are taken to be part of a token (such as in
equations), but the space is always a token separator.
In a few special cases (such as axis labels), prompting the user for information will bypass token
processing and return to the program the entire string as typed. This generally happens only when
the program is expecting a literal string which would be normally be expected to have spaces, special
characters and case sensitive information (such as an axis label).
The following are equivalent:
¾
»
GENPLOT: label left ’sin(x) normalized’
and
GENPLOT: label left
Label: sin(x) normalized
GENPLOT:
½
¼
T-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
APPENDIX V: INTERNAL VARIABLES
This appendix lists two sets of important variables. The first are DOS environment variables recognized by GENPLOT. The second is a list of the known (or at least admitted to) variables which
are linked to the expression evaluator for use within GENPLOT.
ENVIRONMENT VARIABLES
There are several DOS environment variables which will GENPLOT recognize if present. Most of
them are used to modify the default directory and filename of required run–time files, although some
specify the operating environment for GENPLOT. See Appendix R on run–time support for more
detailed information on file redirection and the use of the environment variables. Generally, these
environment variables would be set in your AUTOEXEC.BAT file. All environment variables are set
using the DOS SET command.
WARNING: While spaces on either side of the = sign are ignored by GENPLOT, the DOS SET
command considers them significant. For this reason do not put spaces in when setting environment
variables.
Example: set gterm=ega.
Any individual file from the \GENPLOT directory may be redirected to another directory or filename
by creating an environment variable of the same name. As an example, EGA-VGA.DRV, POSTDRV.DRV,
and HP--GL.DRV might be commonly used drivers which could be put on a RAM disk. The following
set commands redirect loading of these files to the ram disk.
set ega-vga.drv=e:ega-vga.drv
set postdrv.drv=e:postdrv.drv
set hp-gl.drv=e:hp-gl.drv
Other variables define parameters, special directories or rediredted directories. These are listed
below.
Variable
Description
GTERM
Default graphics device (terminal). If a plot command is given before a dev <gd> command, GENPLOT searches for the GTERM environment variable and initializes that device if found. This should
be set to the device you most commonly use.
DYNT LIB
Redirects search for all dynamically loaded files (including HDATA.CHR,
DEVICES.DAT, *.OVL, *.DRV and *.HLB files) from the C:\GENPLOT
directory to the specified directory. Example: set DYNT LIB=F:\GENPLOT
switches to the F: disk.
GENPLOT.INI
Specifies an initialization file which is executed when GENPLOT
starts. This file normally establishes the GENPLOT environment
as you like it (plot size, offsets etc.).
V-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix V: Internal Variables
Variable
Description
GENPLOT
Specifies any run time options that might normally be specified on
the DOS command line. Any options actually given on the command line will override the environment values. For example, to
increase the default buffer size every time use: set genplot=bufsize 4096.
HDATA.CHR
Points to the file containing character set data. Used for redirecting the file from the default directory and name.
DEVICES.DAT
Points to the file containing plot devices and descriptions. Used
for redirecting the file from the default directory and name.
TMP
Points to a temporary directory used for saving temporary files.
Generally this should point to a RAM drive for speed. Any time
a temporary file is opened, it will be opened in the TMP directory
if possible. Temporary files include all HCOPY files, PLOT files, and
internal buffering files. If TMP is not defined, those files are opened
in the current directory.
NOTE: DOS normally has a very limited environment space. The error of OUT OF ENVIRONMENT
SPACE is common. At DOS 3.2, the method to increase the size of the environment is
documented. Add the line shell command.com c:\ /p/e:400 to your CONFIG.SYS file.
The /e:400 specifies the size of the environment space in bytes. Although undocumented
at DOS 3.1, the same CONFIG.SYS command works except that the environment size is
specified in paragraphs rather than bytes (16 bytes/paragraph).
GENPLOT VARIABLES
The expression evaluator has several internal variables associated with GENPLOT. The variables
may be used, and in some cases set, using the LET and EVAL commands. Do not use SETV though
since the user definitions will override these definitions resulting in loss of access to the specific
variable.
Variable
Description
X
PLOT:X
Y
PLOT:Y
Z
PLOT:Z
NPT
PLOT:NPT
IDS
X array of main curve
X array of main curve
Y array of main curve
Y array of main curve
Z Reserved for 3–D
Z Reserved for 3–D
Number of points in main curve
Number of points in main curve
Identifier string for main curve
XCUR or CURX
YCUR or CURY
X value of a cursor from GENPLOT or ANNOTE
Y value of a cursor from GENPLOT or ANNOTE
$XMIN
Minimum value of X which can be plotted. Tied to the REGION.
V-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix V: Internal Variables
Variable
Description
$XMAX
$XMIN
$YMAX
Maximum value of X which can be plotted. Tied to the REGION.
Minimum value of Y which can be plotted. Tied to the REGION.
Maximum value of Y which can be plotted. Tied to the REGION.
$I
Index to the value where @MIN or @MAX find their result.
CBUF$R
Real component of the complex FFT defined or evaluated in the
TRANSFORM FFT command
Imaginary component of the complex FFT (see CBUF$I)
The spatial frequency for defining the filter function in TRANSFORM
FILTER
Real array, starting at CF$(0), containing the coefficients of linear
and polynomial fits.
CBUF$I
F$
CF$
EX$RADIUS
EX$NPT
EXCL$
SIGMA$
CHISQR$
VARIANCE$
RESULT$
Radius around each point for which plotting is excluded in the
PLOT -EXCLUDE command. If this value is negative, it will be set
to a multiple of the current symbol size. Otherwise, the specified
value will be excluded around each point in the exclusion curve.
Number of points currently being excluded. This should generally
not be changed by the user.
Curve which is actually excluded. Normally, this is set by the
PLOT command, but you are free to archive data to this curve
and then set EX$NPT and EX$RADIUS manually.
Estimated sigma of the parameters in the LINEAR and NLS fits.
χ2 from NLS fit.
Variance from NLS fit.
Gets general result from various commands, like summation
The following variables require SGRAPH to be executed before access
$ARWLEN
Arrow head length for arrow commands
$ARWANG
Opening angle for arrow head drawing
$AXCOLR(1)
Pen color used for axes lines
$AXCOLR(2)
Pen color used for major tick marks
$AXCOLR(3)
Pen color used for minor tick marks
$AXCOLR(4)
Pen color used for axis labels
$AXCOLR(5)
Pen color used for axis title characters
$AXWIDTH(1)
Width of major axis line
$AXWIDTH(2)
Width of major tick marks
$AXWIDTH(3)
Width of minor tick marks
$AXWIDTH(4)
Width of axis labels
$AXWIDTH(5)
Width of axis title characters
$CSMIN
Minimum character size allowed for labeling axis numbers
$CSMAX
Maximum character size which will be used for axis labeling
$IDLSKP
Distance from left axis line to start of IDS labels
$IDTSKP
Distance from top axis to start of IDS labels
$IDSIZE
Size of IDS labels
$IDSPAC
Spacing between IDS labels (character sizes)
$IDLSIZ
Size of example line for IDS description
$SUSIZ
Subscript/superscript size as a fraction of current symbol size
$SUBOFF
Offset of subscripts as fraction of current size
$SUPOFF
Offset of superscripts as fraction of current size
V-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Appendix D: Device Support
Appendix V: Internal Variables
Variable
Description
$SYMSIZ
$TICK
$TICK2
$TSIZE
$TSTAMP(1)
$TSTAMP(2)
$TSTAMP(3)
$TBOFF
$TTOFF
$TLOFF
$TROFF
$ZFORCE
Default symbol size
Length in inches of the major tick marks
Length in inches of the minor tick marks
Size of titles on axis
Time stamp X position
Time stamp Y position
Size of time stamp
Offset of title on bottom axis
Offset of title on top axis
Offset of title on left axis
Offset of title on right axis
Force ratio for lower axis limit being set to 1. If lower/upper <
ZFORCE, then lower is set to 0.0
V-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
INDEX
Sample, 4i-6
Annotate, 4i-5
Archive, 4c-1
ARCHIVE, 4c-8
Archive, 4c-9, 4o-6
3–D, 4o-5
Expressions, 4c-8, 4o-5
ARCHIVED curves, 4j-4
Arguments, T-3
Arrow style, 4m-4
Annotate, 4i-5
Arrows, 4i-4
ASCII files, 4c-1
ASCII Files, F-1
ASCII, 4c-5
ASYNC, D-1, D-62
AT&T 6300 color, D-16
AT&T 6300, D-42
Autoaxis, 4b-1
AUTOAXIS, 4e-2
Autoerase, 4b-1
AUTOERASE, 4b-9
Autoerase, 4e-2
AUTOEXEC.BAT, 1-5
Autoids, 4b-11
AUTOX, 4e-6
AUTOY, 4e-6
AUX, 4e-6
AUY, 4e-6
Available memory, 4l-3
Average, 2-21
AXCOLR, 4e-2
AXCTRL, 4e-12
DX, 4e-14
DX2, 4e-14
GRID, 4e-15
INTICKS, 4e-14
JUSTIFY, 4e-13
LABEL, 4e-13
∼, 4i-3
∧, 4i-3
/, 4k-11
?, 4m-1
&Encode, 4k-7
&GETARG, 4k-5
&QUERY, 4k-6
&YesNo, 4k-7
A
ALLOCATE, 4j-8
Angle, 4i-4
Annotate, 4i-4
Annotate Circle, 2-19
Annotate Rectangle, 2-17
Annotate, 2-16, 4i-1
Angle, 4i-4
Arc, 4i-5
Arrow, 4i-5
Circle, 4i-5
Connect, 4i-5
Coordinates, 4i-2
Cursor, 4i-6
Draw, 4i-6
Help, 4i-6
Label, 4i-2
Line, 4i-5
Orgmode, 4i-4
Parameter, 4i-4
Parc, 4i-5
Parms, 4i-4
Place, 4i-2
Rectangle, 4i-5
Reset, 4i-6
Return, 4i-6
Size, 4i-4
Spacing, 4i-4
Index-1
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
LENGTH, 4e-15
MX, 4e-14
OFF, 4e-13
ON, 4e-13
ROTATE, 4e-13
SPECLOG, 4e-14
SUBTICK, 4e-14
TICKS, 4e-14
XSTART, 4e-15
YSTART, 4e-15
BRIEF, 4e-13
Axes, 4e-1
Axis color, 4m-4
Axis control, 4e-12
Axis labeling, 4e-12
Axis Labels, 2-13
Axis labels, 4e-13
Right, 2-13
Top, 2-13
Axis numbering, 4e-13
Axis scale, 4b-10
Axis size, 4e-15
Axis title offsets, 4m-4
AXIS, 4e-1
Axis, 4e-1–3
3–D, 4o-3
Auto drawing, 4e-2
Data, 4e-6–7
Flip, 4f-6
Intersection, 4e-3
Label, 4e-7
Labeling, 4e-3, 4e-8, 4e-10
Log labels, 4e-14
Log, 4e-10
off, 4e-13
On, 4e-13
Right, 4e-10
Scale, 4e-4–6
Tick Marks, 4e-8
Title, 4e-7
Top, 4e-8
Color, 4e-2
Drawing, 4e-1
Nonlinear, 4e-8
Width, 4e-2
AXWIDTH, 4e-2
B
Backspace, 4i-3
Bargraph, 4b-4
Plot, 4b-4
Base Macro, 4k-2
Binary files, 4c-1
Binary Files, F-2
BIOS, D-41
Bottom to top, 4e-8
Box, 1-14, 3-3
Annotate, 4i-5
Cursor, 1-14, 3-3
Mode, 1-14, 3-3
BOXMODE, 4e-3
Buffer size, 1-12, 3-1–2
C
Cabling, D-62
Call GENPLOT, S-6
CALL, 4k-1
CD, 4l-1
CGA, D-14, D-42
Character Set Selection, 4e-11
Character Set, 1-15, 3-4, 4i-3
CHARACTER, 4e-11
CHRSET, 4e-11
Circle, 2-19
Annotate, 4i-5
CLS, 4a-3
CMDLIN, 4k-4
Color, 4b-3
COLOR, 4d-4
Multiple, A-3
Single, A-3
COM, D-62
Command List, 4m-1
Command Processing, T-1
Comments, 4k-11
Logging, 4m-3
Compilers, 1-3, S-1
Compiling, S-7
GENPLOT2, S-7
USER$, S-4
Comrex, D-15
Constants, 4j-2
Index-2
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
Contour, 4o-3
3–D, 4o-3
Coordinates, 4i-2
Annotate, 4i-2
Coormode, 4i-2
Create, 2-3
CREATE, 4h-7
Cull Data, 2-22
CULL DATA, 4h-5
Cursor Movement, 2-16
Cursor, 1-14, 2-16, 3-3–4
CURSOR, 4g-1
Annotate, 4i-6
Box, 1-14, 3-3
Enable, 4a-4
Nonlinear, 4e-9
Curve fitting, 4h-16
3–D NLSFIT, 4o-8
Linear, 4h-17
Polynomial, 4h-18
NLSFIT, 4h-19
Curve, 1-11
Expressions, 4c-8, 4o-5
Curves, 4b-8, 4j-2
Multiple, 4b-8
Customer service, A-1
Hcopy, 4a-7
Null, 4a-2
Selection, 4a-1
Special, 4a-2
Stock, 4a-3
Devices, 1-2, 4a-1–2
AT&T 6300, D-16, D-42
BIOS, D-41
CGA, D-42
Comrex, D-15
Configuration, D-8
DEB, D-16
DEBUG, D-46
Drivers, D-12
Epson, D-51
File, D-8
Gemini, D-51
Hercules, D-26
HP–GL, D-27
IBMCGA, D-42
NULL, D-46
NULLDRV, D-46
Okidata, D-51
Postscript, D-50
QMS, D-20
Quic, D-20
RASTER, D-51
Special, D-10
Talaris, D-20
Tektronix, D-56
TEKTRX, D-56
WordPerfect, D-58
WPDRV, D-58
8514, D-37
DESKJET, D-17
EGA, D-21
EGA–VGA, D-21
HP DeskJet, D-17, D-30
HP LaserJet, D-30, D-43
HP PaintJet, D-30, D-47
HPRASTER, D-30
IBM LaserPrinter E, D-34
IBM4019, D-34
IBM8514, D-37
LASERJET, D-43
PAINTJET, D-47
D
Data files, 2-1
Data Files, 4c-1
ASCII, 2-1
Data range, 2-22
Data Reading, 4c-2
Data selection, 2-22
DEALLOCATE, 4j-8
Debug device, 4a-2
DEBUG Device, D-46
DECLARE, 4j-7
Default Disk, 4l-1
Defaults, T-3
DEFINE, 4j-7
Derivative, 4h-10
DeskJet, D-17, D-30
Device, 2-2
DEVICE, 4a-1
Debug, 4a-2
Index-3
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
Summary, D-4
TIFF, D-57
VGA, D-21
Devices.dat, 4d-4
DEVICES.DAT, D-8, R-2
DIGITIZE, 4c-2
DIR, 4l-2
Directories, 4l-1–2
Directory, 4l-1
Changing, 4l-1
Current, 4l-1
Listing, 4l-2
Disk, 4l-1
Default, 4l-1
Display points, 4c-7, 4g-1, 4g-4, A-3
DOS commands, 4l-2–3
DOS, 4l-2
Annotate, 4i-6
DTR/CTS, D-1
Execution options, 1-12, 3-1
Expression Evaluation, 4j-5
Expressions, 4c-8, 4j-1–2, 4o-5
Curves in, 4c-8, 4o-5
F
File ID, 4b-11
FILE, D-61
ASCII, 4c-1, 4c-5
Binary, 4c-1
List, 4l-2
Read, 4c-2
Write, 4c-5
Files, 4c-1
ASCII, F-1
Binary, F-2
FILL, 4b-9
Fit, 4h-15
FIT, 4h-16
LINEAR, 4h-17
NLSFIT, 4h-19
Plot, 4b-3
Plot, 4h-16
Plot, A-3
POLYNOMIAL, 4h-18
SPLINE, 4h-19
LSQfit, 4h-15
FIX GRID, 4h-4
FLIPXY, 4f-6
Flow control, 4k-8–9
Font, 1-15, 3-4, 4i-3
Fonts, 4e-11
FOR, 4k-7–8
Force, 4e-2
FORCE, 4e-5
FORTRAN, S-1
Function evaluation, 4j-1
Function, 4b-2, 4o-4
3–D, 4o-4
Plot, 4b-2
Functions, 4j-10
E
ECD, D-2
Echo, 4k-3
Data, 4h-5
Data, 4h-6
Editing, 4n-1
Editor, 4n-1
EDIT DATA, 4h-6
EGA, D-14, D-21
EGA–VGA, D-21
ENCURSOR, 4a-4
ENQ/ACK, D-1
Entering Data, 4c-3
Environment Variables, V-1
Epson driver, D-51
Epson, D-51
Equation evaluation, 4j-5
ERASE, 4a-3
Error bars, 4b-6
Errx, 4b-6
Plot, 4b-6
Erry, 4b-6
Plot, 4b-6
Escape, T-3
EVALUATE, 4j-5
EXCHANGE, 4h-3
G
Gemini driver, D-51
Gemini, D-51
GENPLOT Subroutine, S-6
GENPLOT, 4m-1
Index-4
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
Subroutine, S-1
GET, 4c-2
GOTO, 4k-9
GPIB, D-1, D-64
Graphics page, 4a-4
Grid markers, 4e-15
GRID, 4b-9
Grid, 4h-4, 4o-2
3–D, 4o-2
GRPAGE, 4a-4
GRPRINT, 4a-3
Gterm, 2-2
HP–GL, D-27
HPIB, D-64
I
I/O Channels, D-3, D-10, D-59, D-62
ASYNC, D-62
FILE, D-61
GPIB, D-64
SPOOL, D-67
Summary, D-7
IBM 4019 LaserPrinter, D-34
IBM LaserPrinter E, D-34
Identify, 4b-4
IDENTIFY, 4b-11
IDS parameters, 4m-4
IDS, 4b-4, 4b-11
IEEE–488, D-64
IF, 4k-8
Initialization, 1-12, 3-1
Integral, 4h-9
Internal Variables, V-2
INTICKS, 4e-8
H
Hardcopy, 4a-4
hcopy, 2-2
HCOPY, 4a-4
APPEND, 4a-7
Backspace, 4a-8
BACKUP, 4a-8
DEVICE, 4a-7
END, 4a-6
File, 4a-7
HELP, 4a-5
LABEL, 4a-8
LIST, 4a-9
MARK, 4a-8
OFF, 4a-6
ON, 4a-5
PLOT, 4a-7
RESET, 4a-9
SAVE, 4a-7
STATUS, 4a-9
UNDO, 4a-6
Help, 4a-5, 4m-1
3–D, 4o-4
Hcopy, 4a-5
Hercules, D-14, D-26
Hidden lines, 4o-4
3–D, 4o-4
Histogram, 4b-5, 4h-11
Plot, 4b-5
HP DeskJet, D-17, D-30
HP LaserJet, D-30, D-43
HP PaintJet, D-30, D-47
HP Plotter, D-27
L
Label processing, A-4
LABEL, 4e-7
Label, 4o-5
3–D, 4o-5
Angles, 4i-4
Annotate, 4i-2
Chopped, 4e-7, A-5
Hcopy, 4a-8
Line Spacing, 4i-4
Missing, 4e-7, A-5
Origin, 4i-4
Paragraphs, 4i-3
Size, 4i-4
Top, A-4
Labeling, 4i-1
Annotate, 4i-2
Labels, 2-16
Coordinates, A-4
Uppercase, 2-16
LaserJet, D-30, D-43
LaserPrinters, D-34, D-43, D-47
Legend location, 4m-4
Legend parameters, 4m-4
Index-5
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
Legend, 4b-11
LET, 4j-5
Line type, 4d-3
Dash Length, 4d-3
Vector length, 4d-3
Line width, 4d-4
Line, 4d-1
Annotate, 4i-5
Symbol, 4d-1
Type, 4d-1
Linear Fit, 4h-17
Lines and Symbols, 2-20, 4b-3
Lines, 4b-3–4
Linewidth, 4b-4
LINEWIDTH, 4d-4
Linker, S-2
Linking, S-7
GENPLOT2, S-7
USER$, S-4
LISTVARS, 4j-9
Log axis labels, 4e-14
LOGARITHM, 4e-10
Logfile, 4m-2
Logit, 4m-3
LS, 4l-2
LSQFIT, 4h-15
Ltype, 4b-3
LTYPE, 4d-1
Plot, 4b-3
Input, 4k-4, 4k-6–7
XEQ, 4k-1
&Encode, 4k-7
&Getarg, 4k-5
&Query, 4k-6
&YesNo, 4k-7
Mainframe, D-67
Margin, 4f-1
MARGIN, 4f-4
Mark, 4a-8
Hcopy, 4a-8
MD, D-2
Memory Limiatations, A-2
Memory, 4l-3
Mesh, 4o-3
3–D, 4o-3
Mice, 1-6, D-22, D-38
Mouse, 1-6, D-21–22, D-37–38
Multi–line Labels, 4i-3
Same page, 4a-5
Multiple Plots, 2-10, 2-20
Same page, 4b-9, 4e-2–3
Multiplying curves, A-3
N
NEC, D-51
NLSFIT, 4h-19, 4o-8
3–D, 4o-8
ACCURACY, 4h-24
Algorithm, 4h-28
Convergence, 4h-24
FIT, 4h-22
FUNCTION, 4h-20
HELP, 4h-23
INFORMATION, 4h-23
MAX ITER, 4h-24
MODES, 4h-25
RELEASE, 4h-21
REMOVE, 4h-21
Reset, 4h-23
RETURN, 4h-23
STATUS, 4h-23
UNVARY, 4h-21
Variables, 4h-21
VARY, 4h-21
VERBOSE, 4h-25
M
Macro, 4k-3
Suffix, A-3
Editing, 4n-1
Macros, 4k-1
Comment, 4k-11
Delay, 4k-10
Directory, 4k-2
Echo, 4k-3
Save, 4k-3
Arguments, 4k-5
Call, 4k-1
Execution, 4k-1
For, 4k-7–8
Goto, 4k-9
If, 4k-8
Index-6
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
VERBOSITY, 4h-25
Non-linear least squares (see NLSFIT), 4h28
Non-linear least squares, 4h-19, 4o-8
NONLINEAR, 4e-8
Cursor, 4e-9
NPOINT, 4b-9
NPT, 1-10
NPTMAX, 1-10
Null device, 4a-2
NULL Device, D-46
O
Offset, 4e-2, 4f-1
OFFSET, 4f-3
OK;, 4l-2
Okidata driver, D-51
Okidata, D-51
Operators, 4j-10
Precedence, 4j-10
Annotate, 4i-4
Origin, 4f-1
OVERLAY, 4b-8
3–D, 4o-3
P
PaintJet, D-30, D-47
Paragraph Labels, 4i-3
PARAMETER, 4g-4
Annotate, 4i-4
Label, 4i-4
Annotate, 4i-5
Parms, 2-15
PARMS, 4g-4
Pause, 4l-3
FORTRAN, 4k-10
Pen, 4a-4, 4b-3
PEN, 4d-4
Plot, 4b-3
Speed, 4a-4
Perspective, 4o-6
3–D, 4o-6
Place, 4i-2
Plot area, 4f-1
Plot parameters, 4m-4, 4m-6
Plot, 2-2, 4a-1
PLOT, 4b-1
3–D, 4o-2
Archive, 4b-2
Bargraph, 4b-4
Color, 4b-3
Device, 4a-1
Errx, 4b-6
Erry, 4b-6
Fit, 4b-3
Fit, 4h-16
Fit, A-3
Function, 4b-2
Hcopy, 4a-7
Histogram, 4b-5
Identify, 4b-4
IDS, 4b-4
Labeling, 4e-3
Linewidth, 4b-4
Ltype, 4b-3
Overlaying, 4b-1, 4b-8
Parameters, 4e-3–4
Pen, 4b-3
Position, 4f-3–4
Pt label, 4b-2
Size, 4f-3, 4f-5, A-4
Symbol, 4b-3
Symbols, 4d-2
Symsize, 4b-4
Plotting, 4b-1, 4b-8
PLX, 4e-6
PLY, 4e-7
Points, 1-12, 3-1–2
Maximum, 1-12, 3-1–2
Polynomial Fit, 4h-18
Postscript, D-50
Print points, A-3
Print, 4a-3
Graphics, 4a-3
PS/2, D-37
Pt label, 4b-2
Plot, 4b-2
PWD, 4l-1
Q
QMS, D-20
QUERY, 4k-4
Questions, A-2
Index-7
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
Quic, D-20
Quit, 4m-2, 4o-6
3–D, 4o-6
Quote, 4i-3
R
Range, 4e-4, 4e-6
3–D, 4o-6
Automatic, 4e-6
Raster Device, D-17, D-30, D-34, D-43, D47, D-51, D-57
Raster, D-51
Read, 2-2, 4c-1
READ, 4c-2
3–D, 4o-2
Digitize, 4c-3
List, 4c-4
User, S-3
Data entry, 4c-3
Real to String, 4k-7
Rectangle, 2-17
Annotate, 4i-5
Region, 4b-10, 4e-2
REGION, 4e-4
Region, 4e-6
Automatic, 4e-6
Force, 4e-5
Unzoom, 4b-10
Zoom, 4b-10
Repeat commands, 4k-7–8
Reset, 4m-2
3–D, 4o-7
Retrieve, 4c-1, 4c-8
RETRIEVE, 4c-9
Retrieve, 4o-5
3–D, 4o-6
Return, 4m-2
Rotate, 4o-7
3–D, 4o-7
RS–232, D-62
S
s, 2-22, E-8
Sample, 4i-6
SAVEVAR, 4j-9
SAVE MACRO, 4k-3
Scale, 4e-4, 4e-6
Automatic, 4e-6
Force, 4e-5
Screen, 4a-3
Clear, 4a-3
Erase, 4a-3
Erase, 4b-9
Script, 4m-2
Selecting data, 2-22
Serial, D-62
Cabling, D-62
Logging, 4m-2
SET, 4e-4
Setup, 2-4
SETUP, 4e-3
SETVAR, 4j-6
SGRAPH, 4m-4
SHOW, 4c-7, 4g-4
Show surface, 4o-7
3–D, 4o-7
SHRINK, 4f-5
Single screen, 1-2, 1-6
Size, 4f-1
SIZE, 4f-3
Annotate, 4i-4
SLEEP, 4k-10
SORT, 4h-2
Annotate, 4i-4
Special device, 4a-2
SPEED, 4a-4
SPLINE, 4h-19
SPOOL, D-67
Starting GENPLOT, 1-12, 3-1
Status, 2-15, 4c-1
STATUS, 4c-6, 4g-3
3–D, 4o-7
Stereo, 4o-8
3–D, 4o-8
Stock device, 4a-3
Subroutine, 1-11, S-1
GENOFF, S-7
GENPLOT, S-6
MAIN, S-6
USER$, S-3
USER$CM, S-3
USER$RD, S-3
USER$WR, S-3
Index-8
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
CMDLIN, S-11
EXIT, S-10
function evaluator, S-14
GENOFF, S-10
GENPLT2, S-9
LEXFIL, S-12
token parsing, S-13
user callable, S-9
Subscript parameters, 4m-4
Subscripts, 1-15, 3-4, 4i-3
Subtick marks, 4e-14
SUBTICKS, 4e-8
SUB PLOT, 4f-5
Superscript parameters, 4m-4
Superscripts, 1-15, 3-4, 4i-3
Support, A-1
Surface, 4o-3
3–D, 4o-3
Symbol size, 4b-4
Symbol, 4b-3
SYMBOL, 4d-2
Plot, 4b-3
Size, 4d-3
Symbols, 4b-3
Symsize, 4b-4
SYMSIZE, 4d-3
System commands, 4l-2–3
Top to bottom, 4e-8
TRANSFORM, 4h-7
ABORT, 4h-9
BASELINE, 4h-11
COMPRESS, 4h-10
DEPHase, 4h-12
DIFference, 4h-9
DY/DX, 4h-10
FFT, 4h-13
INTEGRAL, 4h-9
List, 4h-8
ROLL, 4h-10
SMOOTH, 4h-11
SMOOTH FFT, 4h-11
SQUISH, 4h-10
SUM, 4h-9
ZERO pad, 4h-11
Autocorrelation, 4h-14
BIN, 4h-11
CBIN, 4h-11
CENTERBIN, 4h-11
CONVolution, 4h-14
CORRelation, 4h-14
DECONVoluti, 4h-14
FILTER fft, 4h-15
HISTOGRAM, 4h-11
TYPE, 4l-2
U
T
UNZOOM, 4b-10
User Subroutines, S-3
User support, A-1
USER, 4h-2
Talaris, D-20
Tektronix driver, D-56
TEKTRX, D-56
Tick mark size, 4m-4
Tick Marks, 4e-8
Tick marks, 4e-14
Direction, 4e-8
Direction, 4e-14
Spacing, 4e-14
Subtick, 4e-8
Tilt, 4o-9
3–D, 4o-9
Timer, 4k-11
TIMESTAMP, 4m-6
Title, 4b-12
Tokens, T-1
Labels, A-4
V
VARIABLES, 4j-2
Variables, V-1
Environment, V-1
Internal, V-2
VECSIZE, 4d-3
VGA, D-14, D-21, D-37
VISIBILITY, 4d-5
W
WAIT, 4k-10
Where, 4l-1
WordPerfect driver, D-58
Index-9
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-
Index
WPDRV, D-58
Write, 4c-1
WRITE, 4c-5
User, S-3
Function, 4o-4
Grid, 4o-2
Help, 4o-4
Hidden lines, 4o-4
Label, 4o-5
Mesh, 4o-3
NLSFIT, 4o-8
Overlay, 4o-3
Perspective, 4o-6
Plot, 4o-2
Quit, 4o-6
Range, 4o-6
Read, 4o-2
Resolution, 4o-7
Retrieve, 4o-5–6
Rotate, 4o-7
Show surface, 4o-7
Status, 4o-7
Stereo, 4o-8
Surface, 4o-3
Tilt, 4o-9
Z Search, 4o-9
X
XEQ, 4k-1
XON/XOFF, D-1
XTOP, 4e-8
Y
YRIGHT, 4e-10
Z
ZOOM, 4b-10
Z Search, 4o-9
3–D, 4o-9
3–D
3–D, 4o-1–2
Archive, 4o-5
Axis, 4o-3
Contour, 4o-3
Index-10
c
-Computer Graphic Service, Ltd. °1988-2007
June 5, 2007-