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