Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 089.lha / Icon / Doc / amiga.doc < prev next >

Wrap

Text File | 1986-11-20 | 22.0 KB | 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.