home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ICONV8.ZIP / DOCS.ZIP / IPD131.DOC next >
Text File  |  1990-04-05  |  18KB  |  661 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                    Version 8 of Icon for OS/2
  8.  
  9.                         Ralph E. Griswold
  10.     Department of Computer Science, The University of Arizona
  11.  
  12.  
  13.  
  14. 1.__Introduction
  15.  
  16.    Version 8 of Icon for OS/2 should run on any computer that
  17. runs OS/2.  Icon for OS/2 is a large-memory model program. Its
  18. data regions are limited to 65K and are fixed in size once execu-
  19. tion begins.  Math coprocessors are supported and used if
  20. present; otherwise software emulation is used.
  21.  
  22.    Version 8 of Icon for OS/2 is distributed on a 3.5" or 5.25"
  23. diskette. It includes executable binary files, a few test pro-
  24. grams, and documentation in machine-readable form. Printed docu-
  25. ments are included with diskettes distributed by the Icon Project
  26. at the University of Arizona.
  27.  
  28.    This implementation of Icon is in the public domain and may be
  29. copied and used without restriction.  The Icon Project makes no
  30. warranties of any kind as to the correctness of this material or
  31. its suitability for any application.  The responsibility for the
  32. use of Icon lies entirely with the user.
  33.  
  34.  
  35. 2.__Documentation
  36.  
  37.    The basic reference for the Icon programming language is the
  38. book
  39.  
  40.      The Icon Programming Language, second edition, Ralph E.
  41.      Griswold and Madge T. Griswold, Prentice-Hall, Inc., Engle-
  42.      wood Cliffs, New Jersey, 1990. 365 pages. ISBN 0-13-447889-
  43.      4. $29.95.
  44.  
  45. This book is available from the Icon Project at the University of
  46. Arizona. It also can be ordered through any bookstore that han-
  47. dles special orders or by telephone directly from Prentice-Hall:
  48. (201) 767-9520.
  49.  
  50.    Note that the first edition of this book, published in 1983,
  51. describes an older version of Icon and does not contain informa-
  52. tion about many of the features of Version 8.
  53.  
  54.    A brief overview of Icon is contained in technical report TR
  55. 90-6 [1] (tr90-6.doc on the distribution diskette). Features that
  56. have been added to Icon since the first edition of the book was
  57. written are described in TR 90-1 [2] (tr90-1.doc on the distribu-
  58. tion diskette).  These technical reports, together with this
  59. document (ipd131.doc on this diskette), provide enough informa-
  60. tion to write and run simple Icon programs, but persons who
  61.  
  62.  
  63.  
  64. IPD131a                       - 1 -                 April 5, 1990
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. intend to use Icon extensively will need the book.
  74.  
  75.  
  76. 3.__Installing_OS/2_Icon
  77.  
  78.    Two executable binary files are needed to run Icon:
  79.  
  80.         icont.exe   translator
  81.         iconx.exe   executor
  82.  
  83. These files should be located at a place on your PATH specifica-
  84. tion.
  85.  
  86.    The distribution is contained in several files in ARC format.
  87. A copy of arc.exe is included for dearchiving. The distribution
  88. files are:
  89.  
  90.         arc.exe      archiving utility
  91.         icon.arc     executable binary files [302KB]
  92.         samples.arc  Icon programs and data [3KB]
  93.         docs.arc     documents [90KB]
  94.         readme       installation overview and recent notes
  95.  
  96. The figures in brackets give the approximate amount of disk space
  97. needed when the files are extracted from their archives.
  98.  
  99.    To install the .exe files, set your current directory to the
  100. desired place, place the distribution diskette in drive A, and
  101. dearchive the files there using arc.exe on the distribution
  102. diskette:
  103.  
  104.         a:arc x a:icon.arc
  105.  
  106.  
  107.  
  108. 4.__Running_OS/2_Icon_-_Basic_Information
  109.  
  110.    Files containing Icon programs must have the extension .icn.
  111. Such files should be plain text files (without line numbers or
  112. other extraneous information).  The icont translator produces an
  113. ``icode'' file that can be executed by iconx.  For example, an
  114. Icon program in the file prog.icn is translated by
  115.  
  116.         icont prog.icn
  117.  
  118. The result is an icode file with the name prog.icx.  This file
  119. can be run by
  120.  
  121.         iconx prog.icx
  122.  
  123. Alternatively, icont can be instructed to execute the icode file
  124. after translation by appending a -x to the command line, as in
  125.  
  126.  
  127.  
  128.  
  129.  
  130. IPD131a                       - 2 -                 April 5, 1990
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.         icont prog.icn -x
  140.  
  141.  
  142.    If icont is run with the -x option, the file prog.icx is left
  143. and can be run subsequently using iconx as described above.
  144.  
  145.    The extensions .icn and .icx are optional. For example, it is
  146. sufficient to use
  147.  
  148.         icont prog
  149.  
  150. and
  151.  
  152.         iconx prog
  153.  
  154.  
  155.  
  156.  
  157. 5.__Testing_the_Installation
  158.  
  159.    There are a few programs on the distribution diskette that can
  160. be used for testing the installation and getting a feel for run-
  161. ning Icon:
  162.  
  163.      hello.icn   This program prints the Icon version number,
  164.                  time, and date. Run this test as
  165.  
  166.                          icont hello
  167.                          iconx hello
  168.  
  169.                  Note that this can be done in one step with
  170.  
  171.                          icont hello -x
  172.  
  173.  
  174.      cross.icn   This program prints all the ways that two words
  175.                  intersect in a common character. The file
  176.                  cross.dat contains typical data. Run this test
  177.                  as
  178.  
  179.                          icont cross -x <cross.dat
  180.  
  181.  
  182.      meander.icn This program prints the ``meandering strings''
  183.                  that contain all subsequences of a specified
  184.                  length from a given set of characters. Run this
  185.                  test as
  186.  
  187.                          icont meander -x <meander.dat
  188.  
  189.  
  190.      roman.icn   This program converts Arabic numerals to Roman
  191.                  numerals. Run this test as
  192.  
  193.  
  194.  
  195.  
  196. IPD131a                       - 3 -                 April 5, 1990
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.                          icont roman -x
  206.  
  207.                  and provide some Arabic numbers from your con-
  208.                  sole.
  209.  
  210. If these tests work, your installation is probably correct and
  211. you should have a running version of Icon.
  212.  
  213.  
  214. 6.__More_on_Running_Icon
  215.  
  216.    For simple applications, the instructions for running Icon
  217. given in Section 4 may be adequate. The icont translator supports
  218. a variety of options that may be useful in special situations.
  219. There also are several aspects of execution that can be con-
  220. trolled with environment variables.  These are listed here. If
  221. you are new to Icon, you may wish to skip this section on the
  222. first reading but come back to it if you find the need for more
  223. control over the translation and execution of Icon programs.
  224.  
  225. 6.1__Arguments
  226.  
  227.    Arguments can be passed to the Icon program by appending them
  228. to the command line.  Such arguments are passed to the main pro-
  229. cedure as a list of strings.  For example,
  230.  
  231.         iconx prog text.dat log.dat
  232.  
  233. runs the icode file prog.icx, passing its main procedure a list
  234. of two strings, "text.dat" and "log.dat".  The program also can
  235. be translated and run with these arguments with a single command
  236. line by putting the arguments after the -x:
  237.  
  238.         icont prog -x text.dat log.dat
  239.  
  240. These arguments might be the names of files that prog.icn reads
  241. from and writes to. For example, the main procedure might begin
  242. as follows:
  243.  
  244.         procedure main(a)
  245.            in := open(a[1]) | stop("cannot open input file")
  246.            out := open(a[2],"w") | stop("cannot open output file")
  247.                        .
  248.                        .
  249.                        .
  250.  
  251. See also the information about the processing of command-line
  252. arguments given in Section 6.4.
  253.  
  254. 6.2__The_Translator
  255.  
  256.    The icont translator can accept several Icon source files at
  257. one time.  When several files are given, they are translated and
  258. combined into a single icode file whose name is derived from the
  259.  
  260.  
  261.  
  262. IPD131a                       - 4 -                 April 5, 1990
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. name of the first file.  For example,
  272.  
  273.         icont prog1 prog2
  274.  
  275. translates the files prog1.icn and prog2.icn and produces one
  276. icode file, prog1.icx.
  277.  
  278.    A name other than the default one for the icode file produced
  279. by icont can be specified by using the -o option, followed by the
  280. desired name. For example,
  281.  
  282.         icont -o probe.icx prog
  283.  
  284. produces the icode file named probe.icx rather than prog.icx.
  285.  
  286.    If the -c option is given to icont, the translator stops
  287. before producing an icode file and intermediate ``ucode'' files
  288. with the extensions .u1 and .u2 are left for future use (normally
  289. they are deleted).  For example,
  290.  
  291.         icont -c prog1
  292.  
  293. leaves prog1.u1 and prog1.u2, instead of producing prog1.icx.
  294. These ucode files can be used in a subsequent icont command by
  295. using the .u1 name. This saves translation time when the program
  296. is used again.  For example,
  297.  
  298.         icont prog2 prog1.u1
  299.  
  300. translates prog2.icn and combines the result with the ucode files
  301. from a previous translation of prog1.icn. Note that only the .u1
  302. name is given. The extension can be abbreviated to .u, as in
  303.  
  304.         icont prog2 prog1.u
  305.  
  306. Ucode files also can be added to a program using the link
  307. declaration in an Icon source program as described in [2].
  308.  
  309.    Icon source programs may be read from standard input.  The
  310. argument - signifies the use of standard input as a source file.
  311. In this case, the ucode files are named stdin.u1 and stdin.u2 and
  312. the icode file is named stdin.icx.
  313.  
  314.    The informative messages from the translator can be suppressed
  315. by using the -s option.  Normally, both informative messages and
  316. error messages are sent to standard error output.
  317.  
  318.    The -t option causes &trace to have an initial value of -1
  319. when the icode file is executed.  Normally, &trace has an initial
  320. value of 0.
  321.  
  322.    The option -u causes warning messages to be issued for unde-
  323. clared identifiers in the program.
  324.  
  325.  
  326.  
  327.  
  328. IPD131a                       - 5 -                 April 5, 1990
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.    Icon has several tables related to the translation of pro-
  338. grams.  These tables are large enough for most programs, but
  339. translation is terminated with an error message, indicating the
  340. offending table, if there is not enough room.  If this happens,
  341. larger table sizes can be specified by using the -S option. This
  342. option has the form -S[cfgilnrstCFL]n, where the letter following
  343. the S specifies the table and n is the number of storage units to
  344. allocate for the table.
  345.  
  346.      c  constant table          100
  347.      f  field table             100
  348.      g  global symbol table     200
  349.      i  identifier table        500
  350.      l  local symbol table      100
  351.      n  line number table      1000
  352.      r  record table            100
  353.      s  string space          20000
  354.      t  tree space            15000
  355.      C  code buffer           15000
  356.      F  file names               10
  357.      L  labels                  500
  358.  
  359. The units depend on the table involved, but the default values
  360. can be used as guides for appropriate settings of -S options
  361. without knowing the units.  For example,
  362.  
  363.         icont -Sc200 -Sg600 prog
  364.  
  365. translates prog.icn with twice the constant table space and three
  366. times the global symbol table space that ordinarily would be pro-
  367. vided.
  368.  
  369. 6.3__Environment_Variables
  370.  
  371.    When an icode file is executed, several environment variables
  372. are examined to determine execution parameters.  The values
  373. assigned to these variables should be numbers.
  374.  
  375.    Environment variables are particularly useful in adjusting
  376. Icon's storage requirements. This may be necessary if your com-
  377. puter does not have enough memory to run programs that require an
  378. unusually large amount of data.  Particular care should be taken
  379. when changing default sizes: unreasonable values may cause Icon
  380. to malfunction.
  381.  
  382.    The following environment variables can be set to affect
  383. Icon's execution parameters. Their default values are listed in
  384. parentheses after the environment variable name:
  385.  
  386.         TRACE (undefined).  This variable initializes the value
  387.      of &trace.  If this variable has a value, it overrides the
  388.      translation-time -t option.
  389.  
  390.         NOERRBUF (undefined).  If this variable is set, &errout
  391.  
  392.  
  393.  
  394. IPD131a                       - 6 -                 April 5, 1990
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.      is not buffered.
  404.  
  405.         STRSIZE (65000). This variable determines the size, in
  406.      bytes, of the region in which strings are stored.
  407.  
  408.         HEAPSIZE (65000).  This variable determines the size, in
  409.      bytes, of the region in which Icon allocates lists, tables,
  410.      and other objects.
  411.  
  412.         COEXPSIZE (2000). This variable determines the size, in
  413.      32-bit words, of each co-expression block.
  414.  
  415.         MSTKSIZE (10000). This variable determines the size, in
  416.      words, of the main interpreter stack.
  417.  
  418.         QLSIZE (5000). This variable determines the size, in
  419.      bytes, of the region used by the garbage collector for
  420.      pointers to strings.
  421.  
  422.    The maximum region size that can be specified is 65000.
  423. Region sizes remain fixed during execution.
  424.  
  425. 6.4__Details_of_Command-Line_Processing
  426.  
  427.    The processing of command-line arguments normally is important
  428. only in running iconx.
  429.  
  430.    The following rules apply to both:
  431.  
  432.      +  An argument containing white space must be enclosed in
  433.         double quotes ("). For example, "abc def" is a valid
  434.         argument. The quotes are deleted in the string passed to
  435.         iconx.
  436.  
  437.      +  If a quoted argument contains a double quote, the embed-
  438.         ded quote must be preceded by a backslash. For example,
  439.         "abc de\"f" is a valid argument. The outer quotes and the
  440.         backslash are deleted in the string passed to iconx.
  441.  
  442.      +  If a non-quoted argument contains a double quote, the
  443.         embedded quote can be preceded by a backslash or not. For
  444.         example, abc\"d and abc"d are equivalent arguments.
  445.  
  446.      +  To pass a double quote as an argument, precede it with a
  447.         backslash.
  448.  
  449.      +  Wild-card characters are not expanded.
  450.  
  451.      +  Quote-balancing errors are not checked.
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460. IPD131a                       - 7 -                 April 5, 1990
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. 7.__Features_of_OS/2_Icon
  470.  
  471.    OS/2 Icon supports all the features of Version 8 of Icon,
  472. including large-integer arithmetic, with the following exceptions
  473. and additions:
  474.  
  475.      +  There are two additional options for open: "t" and "u".
  476.         The "t" option, which is the default, indicates that the
  477.         file is to be translated into UNIX* format.  All
  478.         carriage-return/line-feed sequences are translated into
  479.         line-feed characters on both input and output.  The "u"
  480.         option indicates that the file is to be untranslated.
  481.         Examples are:
  482.  
  483.                 untranfile := open("test.fil","ru")
  484.                 tranfile := open("test.new","wt")
  485.  
  486.  
  487.         For files opened in the translate mode, the position pro-
  488.         duced by seek may not reflect the actual byte position
  489.         because of the translation of carriage-return/line-feed
  490.         sequences to line-feed characters.
  491.  
  492.      +  Path specifications can be entered using either a / or a
  493.         \. Examples are:
  494.  
  495.                 A:\ICON\TEST.ICN
  496.                 A:/ICON/TEST.ICN
  497.  
  498.  
  499.      +  The following OS/2 device names can be used as file
  500.         names:
  501.  
  502.                 console        CON
  503.                 printer        PRN LST LPT LPT1
  504.                 auxiliary port AUX COM RDR PUN
  505.                 null           NUL NULL
  506.  
  507.         For example,
  508.  
  509.                 prompt := open("CON","w")
  510.  
  511.         causes strings written to prompt to be displayed on the
  512.         console.  Use of a null file name means no file is
  513.         created.
  514.  
  515.  
  516. 8.__Known_Bugs
  517.  
  518.    A list of known bugs in Icon itself is given in [2].  There
  519. are no known bugs that are specific to the OS/2 implementation of
  520. __________________________
  521. *UNIX is a trademark of AT&T Bell Laboratories.
  522.  
  523.  
  524.  
  525.  
  526. IPD131a                       - 8 -                 April 5, 1990
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535. Icon.
  536.  
  537.  
  538. 9.__Reporting_Problems
  539.  
  540.    Problems with Icon should be noted on a trouble report form
  541. (included with the distribution) and sent to
  542.  
  543.         Icon Project
  544.         Department of Computer Science
  545.         Gould-Simpson Building
  546.         The University of Arizona
  547.         Tucson, AZ   85721
  548.         U.S.A.
  549.         (602) 621-4049
  550.         icon-project@cs.arizona.edu     (Internet)
  551.         ... {uunet, allegra, noao}!arizona!icon-project     (uucp)
  552.  
  553.  
  554.  
  555. 10.__Registering_Copies_of_Icon
  556.  
  557.    If you received your copy of Version 8 of Icon directly from
  558. the Icon Project, it has been registered in your name and you
  559. will receive the Icon Newsletter without charge. This Newsletter
  560. contains information about new implementations, updates, program-
  561. ming techniques, and information of general interest about Icon.
  562.  
  563.    If you received your copy of Version 8 of Icon from another
  564. source, please fill out the registration form that is included in
  565. the documents in the distribution) and send it to the Icon Pro-
  566. ject at the address listed above. This will entitle you to a free
  567. subscription to the Icon Newsletter and assure that you receive
  568. information about updates.
  569.  
  570. Acknowledgements
  571.  
  572.    The design and development of the Icon programming language
  573. was supported, in part, by the National Science Foundation under
  574. grants MCS75-01397, MCS79-03890, MCS81-01916, DCR-8320138, DCR-
  575. 8401831, and DCR-8502015.
  576.  
  577.    Many individuals contributed to the design and implementation
  578. of Icon. The principal ones are Cary Coutant, Dave Gudeman, Dave
  579. Hanson, Tim Korb, Bill Mitchell, Kelvin Nilsen, Janalee O'Bagy,
  580. Gregg Townsend, Ken Walker, and Steve Wampler.
  581.  
  582.    The implementation of Icon was adapted to OS/2 by Cheyenne
  583. Wills in Mechanicsburg, Pennsylvania. He also provided some of
  584. the technical material contained in this document.
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592. IPD131a                       - 9 -                 April 5, 1990
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601. References
  602.  
  603.  
  604. 1.   R. E. Griswold, An Overview of Version 8 of the Icon
  605.      Programming Language, The Univ. of Arizona Tech. Rep. 90-6,
  606.      1990.
  607.  
  608. 2.   R. E. Griswold, Version 8 of Icon, The Univ. of Arizona
  609.      Tech. Rep. 90-1, 1990.
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658. IPD131a                      - 10 -                 April 5, 1990
  659.  
  660.  
  661.