home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
17 Bit Software 1: Collection A
/
17Bit_Collection_A.iso
/
files
/
134.dms
/
134.adf
/
Icon
/
amiga.doc
< prev
next >
Wrap
Text File
|
1988-07-25
|
22KB
|
576 lines
Version 6.0 of Icon for the Amiga
Scott Ballantyne
1. Introduction
Version 6 of Icon for the Amiga should run on any Amiga with
at least 512k of memory and running Kickstart Version 1.2
Due to the intense memory requirements of Icon, more memory is
recommended, however, with few exceptions, you should be able to
handle most programming tasks on a 512k box.
The Amiga implementation of Icon is the work of Scott Ballantyne
and Gary Sarf, and may be freely distributed on the usual 'use
at your own risk' basis. It is based on the public domain version
of Icon from the University of Arizona.
The University of Arizona has released an upgraded version of
Icon (V6.3), which fixes a few bugs in Version 6.0. We hope to
make this available on the Amiga in a few months. We will also
be releasing the source code for Amiga Icon at that time.
Meanwhile, 6.0 is very usable as it is. Version 6.3 for the Amiga
will also be using the arp.library, and so should be somewhat smaller.
If you encounter any bugs or problems I would like to hear
about them:
BIX: SDB
CIS: 70066,603
And elsewhere...
2. Documentation
The basic reference for the Icon programming language is the
book
The Icon Programming Language, Ralph E. Griswold and Madge
T. Griswold, Prentice-Hall, Inc., Englewood Cliffs, New Jer-
sey, 1983. 313 pages. ISBN 0-13-449777-5. $25.95.
This book is available in many college bookstores or can be
ordered through any bookstore that handles special orders or by
telephone directly from Prentice-Hall: (201) 767-9520.
A brief overview of Icon is contained in technical report TR
83-3 [1] (overview.doc on the distribution diskette). Features
that have been added to Icon since the book was written are
described in TR 86-10b [2] (version6.doc on the distribution
diskette). These technical reports, together with this document
(Amiga.doc on this diskette), provide enough information to write
simple Icon programs, but persons who are going to use Icon seri-
ously will need the book.
3. Installing Amiga Icon
There are five executable binary files needed to run Icon:
Icont command processor
Itran translator
Ilink linker
Iconx run-time system
ixhdr start-up code
Icont should be located on a place in your Path specification, while
the remaining files may be placed wherever you like, however, you
need to tell Icon where they are by making the following Assigns:
Assign ICONX: location of Iconx
Assign ICONT: location of Icont
Assign ILINK: location of Ilink
Assign ITRAN: location of Itran
Assign HEAD: location of ixhdr
If you start to get requesters which say, for example, "Please Insert
Volume ICONX: in any drive", it is because you forgot to make these
Assigns. The easiest way to do this is to use a batchfile, or the
startup-sequence file if you boot to an Icon disk.
You will also need the Set program, which is included on this diskette,
and is the work of Thomas Rokicki of Radical Eye Software. The MANX Set
may also be used, but the two versions of Set (the Rokicki Set and the
MANX set) should not be mixed. If you are intending to use floating
point math, then you will also need the mathieeedoubbas.library (as
supplied on 1.2 Workbench disks) in the LIBS: directory.
4. Running Amiga Icon - Basic Information
Files containing Icon programs must have the extension .icn.
Such files should be plain text files (without line numbers or
other extraneous information). The command processor icont runs
itran and ilink to produce an ``icode'' file that can be executed
by iconx. For example, an Icon program in the file prog.icn is
translated and linked by
1> icont prog.icn
The result is an icode file with the name prog (with the exten-
sion removed). This file can be run by simply typing it's name,
as though it were a binary machine code file, or by providing it
as an argument to the icon runtime system as:
1> prog
or
1> iconx prog
Alternatively, icont can be instructed to execute the program
after linking and translating by appending a -x to the command
line, as in
icont prog.icn -x
In this case the file prog also is left and can be run subse-
quently simply by typing it's name at the CLI prompt.
If you find you are having difficulty due to memory constraints,
there are various environment variables used by Icon which you may
use to ''fine-tune'' your version. Section 6 has more information
about other aspects of running Icon.
5. Testing the Installation
There are a few programs on the distribution diskette that may
be used for testing the installation and getting a feel for run-
ning Icon:
hello.icn This program prints the Icon version number, time,
and date. Run this test as
1> icont hello.icn
1> hello
Note that this can be done in one step with
1> icont hello.icn -x
cross.icn This program prints all the ways that two words
intersect in a common character. The file cross.dat
contains typical data. Run this test as
1> icont cross.icn
1> cross <cross.dat
meander.icn This program prints the ``meandering strings'' that
contain all subsequences of a specified length from a
given set of characters. Run this test as
1> icont meander.icn
1> meander <meander.dat
roman.icn This program converts Arabic numerals to Roman
numerals. Run this test as
1> icont roman.icn -x
and provide some Arabic numbers from your console. Hit
CNTRL-\ when you want to terminate.
wordcnt.icn This program tabulates the number of occurrences of
each word from the input file. Run this test as
1> icont wordcnt.icn
1> wordcnt <file
where file contains some text of interest. Caution:
the tabulation is kept in memory; do not try to pro-
cess a large file - unless you have a lot of memory!
If these tests work, your installation is probably correct and
you should have a running version of Icon. If you want to save
the output from any of these programs, you may redirect the output
as well, for example:
1> wordcnt <file >outfile
If there are other examples included, have fun with them!
6. More on Running Icon
For simple applications, the instructions for running Icon
given in Section 4 may be adequate. The icont command processor
supports a variety of options that may be useful in special
situations. There also are several aspects of execution that can
be controlled with environment variables. These are listed here.
Persons who are new to Icon may wish to skip this section on the
first reading but come back to it if they find the need for more
control over the translation and execution of Icon programs.
6.1 Arguments
Arguments can be passed to the Icon program by appending them
to the command line. Such arguments are passed to the main pro-
cedure as a list of strings. For example,
1> prog text.dat log.dat
runs the icode file prog, passing its main procedure a list of
two strings, "text.dat" and "log.dat". The program also can be
translated, linked, and run with these arguments with a single
command line by putting the arguments after the -x:
1> icont prog.icn -x text.dat log.dat
These arguments might be the names of files that prog1.icn reads
from and writes to. The main procedure might begin as follows:
procedure main(a)
in := open(a[1]) | stop("cannot open input file")
out := open(a[2],"w") | stop("cannot open output file")
.
.
.
See also the information about the processing of command-line
arguments given in Section 6.4.
6.2 The Command Processor
The command processor icont can accept several input files at
one time. When several files are given, they are translated and
combined into a single icode file whose name is derived from the
name of the first file. For example,
icont prog1.icn prog2.icn
translates and links the files prog1.icn and prog2.icn and pro-
duces one icode file, prog1.
A name other than the default one for the icode file produced
by the Icon linker can be specified by using the -o option, fol-
lowed by the desired name. For example,
icont -o probe prog.icn
produces the icode file named probe rather than prog.
If the -c option is given to icont, only translation is per-
formed and intermediate ``ucode'' files with the extensions .u1
and .u2 are kept. For example,
icont -c prog1.icn
leaves prog1.u1 and prog1.u2, instead of linking them to produce
prog1. (The ucode files are deleted unless the -c option is
used.) These ucode files can be used in a subsequent icont com-
mand by using the .u1 name. This avoids having to translate the
.icn file again. For example,
icont prog2.icn prog1.u1
translates prog2.icn and links the result with the ucode files
from a previous translation of prog1.icn. Note that only the .u1
name is given. Ucode files also can be added to a program when it
is linked by using the link declaration in an Icon source program
as described in [2].
It is worth noting that icont only controls the execution of
the other components of the Icon system. For example,
icont prog.icn -x
is equivalent to
itran prog.icn
ilink prog.u1
iconx prog
The Amiga version of Icont has a -v option, which will display the
command lines it is executing. This can be useful if you are
curious about exactly what information Icont is sending the various
subsystems.
Icon source programs may be read from standard input. The
argument - signifies the use of standard input as a source file.
In this case, the ucode files are named stdin.u1 and stdin.u2 and
the icode file is named stdin. You indicate that you are finished
with the text entry by typing CNTRL-\ (the Amiga standard EOF indicator).
The informative messages from the translator and linker can be
suppressed by using the -s option. Normally, both informative
messages and error messages are sent to standard error output.
The -t option causes &trace to have an initial value of -1
when the program is executed. Normally, &trace has an initial
value of 0.
The option -u causes warning messages to be issued for unde-
clared identifiers in the program. The warnings are issued dur-
ing the linking phase.
Icon has several tables related to the translation and linking
of programs. These tables are large enough for most programs,
but translation or linking is terminated with an error message,
indicating the offending table, if there is not enough room. If
this happens, larger table sizes can be specified by using the -S
option. This option has the form -S[cfgilrstCL]n, where the
letter following the S specifies the table and n is the number of
storage units to allocate for the table.
c constant table 100
f field table 100
g global symbol table 200
i identifier table 500
l local symbol table 100
r record table 100
s string space 15,000
t tree space 15,000
C code buffer 20,000
L labels 500
The units depend on the table involved, but the default values
can be used as guides for appropriate settings of -S options
without knowing the units. For example,
icont -Sc200 -Sg600 prog.icn
translates and links prog.icn with twice the constant table space
and three times the global symbol table space that ordinarily
would be provided.
6.3 Environment Variables
When an Icon program is executed, several environment vari-
ables are examined to determine certain execution parameters.
You establish the values of environment variables by using Set,
which should be included with the Amiga Icon distribution
package. Syntax is
set STRING=VALUE
VALUE can be anything, numeric or string data, that is required
by Icon. Generally, the Icon environment variables require numbers.
When setting a numeric environment variable do not include commas
or other formatting characters - digits only.
If you type Set, by itself, with no arguments, then it will display
a list of all currently defined environment variables, along with their
values.
Finally, to remove an environment variable from memory, just type
Set STRING=
With nothing following the '=' sign, and this variable will be removed.
Environment variables are particularly useful in adjusting
Icon's storage requirements. This may be necessary if your com-
puter does not have enough memory to run Icon as configured or for programs
that have unusual demands for a particular kind of data. Partic-
ular care should be taken when changing default sizes: unreason-
able values may cause Icon to malfunction.
The variables that affect the execution of Icon are:
TRACE initializes the value of &trace. If this variable has a
value, it overrides the translation-time -t option.
NBUFS determines the number of i/o buffers used for files.
When a file is opened, it is assigned an i/o buffer if one is
available and the file is not the console. If no buffer is
available, the file is not buffered. &input, &output, and
&errout are buffered if buffers are available. The defualt for
the Amiga implementation is 10.
If NOERRBUF is set, &errout is not buffered.
STRSIZE determines the initial size of the string space, in
bytes. The string space grows if necessary, but it never
shrinks. For the Amiga implementation of Icon, the default
value of STRSIZE is 51,200. If the amount of memory available for
running the Icon is small, the initial size of the string space
can be set to a smaller value, such as 10,000.
HEAPSIZE determines the initial size of the allocated block
region, in bytes. The heap grows if necessary, but it never
shrinks. The default value of HEAPSIZE is 51,200. If the amount
of memory available for running Icon is small, the initial size of
the allocated block region can be set to a smaller value, such as 10,000.
COEXPSIZE determines the size, in words, of each co-expression
block. The default value of COEXPSIZE is 2,000.
MSTKSIZE determines the size, in words, of the main inter-
preter stack. The default value of MSTKSIZE is 10,000.
The size of the main interpreter stack can be set to a smaller
value, such as 5,000. If the main interpreter stack is not large
enough, excessive recursion may lead to program termination with
a run-time error message.
STATSIZE determines the size, in bytes, of the static region
in which co-expression blocks are allocated. The default value of
STATSIZE is 20,480.
If the amount of memory available for running Iconis small,
the size of the static region can be set to a small value, such
as 100, provided that co-expressions are not used.
STATINCR determines the size of the increment used when the
static region is expanded. The default increment is one-fourth
of the initial size of the static region.
Icon on the Amiga allocates all it's memory from one big
heap. Initially, Icon will attempt to grab the largest section
of contiguos memory it can find. If you wish to limit the amount
of memory Icon will ask for, then you can set the the maximum amount
of memory Icon will ask for with the MAXMEM environment variable.
This variable should specify a value in Kbytes, thus MAXMEM=300
will limit the amount of memory Icon will request to 300k bytes.
Note that you may not get all the memory you ask for - Icon will
attempt to get the amount of memory you asked for, but if it is
not available, will ask for less. You will not get an out of memory
error if this occurs. Out of memory errors will occur only when
an Icon program needs more memory than Icon has available, and this
is determined as the program runs its course, not during the icon
system initialization.
You can use the environment variable UFILES to establish where
icont will place the temporary .u? files. By setting UFILES=RAM:,
these will be placed in the ram disk, greatly speeding up the linking
and translating phases of the process.
Amiga Icon supports all the features of Version 6 of Icon,
with the following exceptions and additions:
o Pipes are not supported. A file cannot be opened with the
``p'' option.
o The PATH environment variable is not used on the Amiga, instead,
the CLI path is searched, as set by the Path command.
o The IPATH environment string used by the Icon linker, is
supported as described in [2]. The separator between
paths is the bang ('!'). The current directory is always
searched. You should specify a ':' in volume names,
but you should not add a trailing '/' to path names.
For example:
set IPATH=df1:!df1:Iconstuff!df1:icontstuff/bookstuff
will cause the linker to examine the current directory for
linkable files, then the root directory of df1:, then Df1:Iconstuff,
then df1:iconstuff/bookstuff.
o All of the AmigaDOS logical devices can be used as files,
this provides a simple means to output to a window, by opening
a CON: or RAW: window.
o Trace output is sent to STDERR.
The following functions have been added to Icon only for the Amiga version,
and should not be expected to be found on other versions:
o Translate(string) -- returns translated string, try:
Write(Translate("Hello big boy"))
o Narrate(string, rate, pitch, mode, sex, volume, sampfreq, side)
You can simply do Narrate(Translate(string)) if you want
to accept the defaults, or you can set specific parameters:
rate - rate of speaking -- 40 to 400, default is 150
pitch - pitch of voice -- 65 to 320. default is 110
mode - may be "natural" or "robotic", or you may use 0 or 1.
default is natural (0).
sex - may be "male" or "female", or you may use 0 or 1
default is male (0)
volume - loudness of voice -- 0 (silence) to 64, default is 64
sampref - sample frequency. 5000 to 28000, default is 22200
side - may be "both", "right" or "left", to set the speaker from
which the voice will come, default is "both".
NOTE: You will have to use MAXMEM to limit the amount of
memory initially grabbed by icon, or there will not be
enough room in memory for the translator and narrator when
you call these functions!
o Delay(timeout) - wait timeout ticks, 50 per second, returns #seconds
Delayed, defaults to 1 second. You should use this
if you want a delay, instead of busy waiting.
o DeleteFile(file) -- Delete a file.
o Rename(old, new) -- Rename files
o SetComment(file, string) -- Set a comment for file
All of these functions use the Icon conventions as much as possible.
The following functions are also extensions to Icon, but are common
enough across implementations that you can somewhat depend on them:
MATH:
exp(x)
log(x)
log10(x)
sqrt(x)
TRIG:
sin(x)
cos(x)
tan(x)
acos(x)
asin(x)
atan(x)
atan2(x, y)
dtor(x) # Convert degrees to radians
rtod(x) # Radians to degrees
FILES:
seek(file, offset, start) - aka C's fseek.
GETENV:
getenv(s) - return contents of environment variable s
6.4 Further details about running Icon programs.
Icon does not actually produce machine code executable files.
What actually happens is that the linker (Ilink) writes an executable
file header (the program ixhdr, located in assigned directory HEAD:)
which then loads and runs Iconx (the run time system) passing itself
as an argument. This appears complex, but is actually the way Icon
is handled on most systems - Icon compilers do not actually increase
execution speed by very much, but they do increase program size a
considerble amount.
You may run Icon programs without taking advantage of this feature,
by simply passing the icon program name to Iconx. Here are some examples:
1> prog
can also be run as
1> Iconx prog
1> prog arg1 arg2 arg3
can also be run as
1> Iconx prog arg1 arg2 arg3
1> prog <infile >outfile arg1 arg2 arg3
can also be run as
1> Iconx <infile >outfile prog arg1 arg2 arg3
(Note that order of the arguments in this last one!).
Of course, in this case, Iconx must be in your search path, and the icon
program must have it's full name specified - the CLI path will not be
searched.
Icon programs may be interrupted by using CNTRL-C. However, the Icon
system will only check for the CNTRL-C when it is doing I/O, so if you
are stuck in an non I/O bound loop, well, it is time to reboot.
________________________________________________
1. R. E. Griswold, An Overview of the Icon Programming
Language, The Univ. of Arizona Tech. Rep. 83-3c, 1983,
Revised 1986.
2. R. E. Griswold, W. H. Mitchell and J. O'Bagy, Version 6 of
Icon, The Univ. of Arizona Tech. Rep. 86-10b, 1986.