home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / i / icon88.zip / DOCS.ZIP / IPD200.DOC next >
Text File  |  1993-01-04  |  15KB  |  529 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                   Version 8.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.8 of Icon runs under OS/2 2.0. It is a 32-bit appli-
  17. cation.  A math co-processor is supported and used if present;
  18. otherwise software emulation is used.
  19.  
  20.    This implementation of Icon is in the public domain and may be
  21. copied and used without restriction.  The Icon Project makes no
  22. warranties of any kind as to the correctness of this material or
  23. its suitability for any application.  The responsibility for the
  24. use of Icon lies entirely with the user.
  25.  
  26.    The basic reference for Version 8 of Icon is the second edi-
  27. tion of the book The Icon Programming Language [1].  This book is
  28. available from the Icon Project at The University of Arizona. It
  29. also can be ordered through any bookstore that handles special
  30. orders.  The new features of Version 8.8 of Icon are described in
  31. an accompanying technical report [2].  Version 8.8 of Icon for
  32. OS/2 supports the graphic capabilities of X-Icon [3].  See that
  33. document for limitations and features specific to OS/2. See also
  34. the file README on the distribution diskette.
  35.  
  36.  
  37. 2.__Installing_OS/2_Icon
  38.  
  39.    The distribution is contained in several files in LHarc (lzh)
  40. format. A copy of lh.exe is included for dearchiving. The distri-
  41. bution files are:
  42.  
  43.         docs.lzh     documents
  44.         icon.lzh     executable binary files
  45.         lh.exe       dearchiving utility
  46.         readme       installation overview and recent notes
  47.         samples.lzh  sample Icon programs and data
  48.  
  49.  
  50.    There are three executable binary files for Version 8.8 of
  51. Icon:
  52.  
  53.         icont.exe   translator
  54.         iconx.exe   text-mode interpreter
  55.         pmiconx.exe PM interpreter
  56.  
  57. These files should be located at a place on your PATH specifica-
  58. tion.
  59.  
  60.    To install the .exe files, set your current directory to the
  61.  
  62.  
  63.  
  64. IPD200b                       - 1 -             December 16, 1992
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. desired place, place the appropriate distribution in a diskette
  74. drive, and dearchive the files there using lh.exe.  For example,
  75. to dearchive the executable binary files using drive A, the fol-
  76. lowing will do:
  77.  
  78.         a:lh x a:icon.lzh
  79.  
  80. The same technique can be used for extracting the remaining
  81. files.
  82.  
  83.  
  84. 3.__Running_OS/2_Icon_-_Basic_Information
  85.  
  86.    As indicated in the preceding section, there are two versions
  87. of the Icon interpreter. iconx is a text-mode version that pro-
  88. vides a command-line interface and handles input and output from
  89. the console.  pmiconx uses PM and emulates the console from a
  90. separate window. pmiconx supports the X-Icon graphics facilities;
  91. iconx does not. Depending on the circumstances, you may wish to
  92. run one version or the other.
  93.  
  94.    Files containing Icon programs must have the extension .icn.
  95. Such files should be plain text files (without line numbers or
  96. other extraneous information).  The icont  translator produces an
  97. ``icode'' file that can be executed by iconx.  For example, an
  98. Icon program in the file prog.icn is translated by
  99.  
  100.         icont prog.icn
  101.  
  102. The result is an icode file with the name prog.icx.  This file
  103. can be run by
  104.  
  105.         iconx prog.icx
  106.  
  107.  
  108. Alternatively, icont can be instructed to execute the icode file
  109. after translation by appending a -x to the command line, as in
  110.  
  111.         icont prog.icn -x
  112.  
  113. Note: The -x option invokes iconx, not pmiconx.
  114.  
  115.    If icont is run with the -x option, the file prog.icx that is
  116. produced can be run subsequently.
  117.  
  118.    The extensions .icn and .icx are optional on command lines.
  119. For example, it is sufficient to use
  120.  
  121.         icont prog
  122.  
  123. and
  124.  
  125.         iconx prog
  126.  
  127.  
  128.  
  129.  
  130. IPD200b                       - 2 -             December 16, 1992
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.    iconx and pmiconx will find an icode file if it is in the
  140. current directory or at place given on your PATH specification.
  141.  
  142.  
  143. 4.__Testing_the_Installation
  144.  
  145.    There are a few programs on the distribution diskette that can
  146. be used for testing the installation and getting a feel for run-
  147. ning Icon:
  148.  
  149.      hello.icn   This program prints the Icon version number,
  150.                  time, and date. Run this test as
  151.  
  152.                          icont hello
  153.                          iconx hello
  154.  
  155.                  Note that this can be done in one step with
  156.  
  157.                          icont hello -x
  158.  
  159.  
  160.      cross.icn   This program prints all the ways that two words
  161.                  intersect in a common character. The file
  162.                  cross.dat contains typical data. Run this test
  163.                  as
  164.  
  165.                          icont cross -x <cross.dat
  166.  
  167.  
  168.      meander.icn This program prints the ``meandering strings''
  169.                  that contain all subsequences of a specified
  170.                  length from a given set of characters. Run this
  171.                  test as
  172.  
  173.                          icont meander -x <meander.dat
  174.  
  175.  
  176.      roman.icn   This program converts Arabic numerals to Roman
  177.                  numerals. Run this test as
  178.  
  179.                          icont roman -x
  180.  
  181.                  and provide some Arabic numbers from your con-
  182.                  sole.
  183.  
  184. If these tests work, your installation is probably correct and
  185. you should have a running version of Icon.
  186.  
  187.  
  188. 5.__More_on_Running_Icon
  189.  
  190.    For simple applications, the instructions for running Icon
  191. given in Section 3 may be adequate. The icont translator supports
  192. a variety of options that may be useful in special situations.
  193.  
  194.  
  195.  
  196. IPD200b                       - 3 -             December 16, 1992
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. There also are several aspects of execution that can be con-
  206. trolled with environment variables.  These are listed here. If
  207. you are new to Icon, you may wish to skip this section on the
  208. first reading but come back to it if you find the need for more
  209. control over the translation and execution of Icon programs.
  210.  
  211. 5.1__Arguments
  212.  
  213.    Arguments can be passed to the Icon program by appending them
  214. to the command line.  Such arguments are passed to the main pro-
  215. cedure as a list of strings.  For example,
  216.  
  217.         iconx prog text.dat log.dat
  218.  
  219. runs the icode file prog.icx, passing its main procedure a list
  220. of two strings, "text.dat" and "log.dat".  The program also can
  221. be translated and run with these arguments with a single command
  222. line by putting the arguments after the -x:
  223.  
  224.         icont prog -x text.dat log.dat
  225.  
  226. These arguments might be the names of files that prog.icn reads
  227. from and writes to. For example, the main procedure might begin
  228. as follows:
  229.  
  230.         procedure main(a)
  231.            in := open(a[1]) | stop("cannot open input file")
  232.            out := open(a[2],"w") | stop("cannot open output file")
  233.                        .
  234.                        .
  235.                        .
  236.  
  237.  
  238. 5.2__More_About_the_Translator
  239.  
  240.    The icont translator can accept several Icon source files at
  241. one time.  When several files are given, they are translated and
  242. combined into a single icode file whose name is derived from the
  243. name of the first file.  For example,
  244.  
  245.         icont prog1 prog2
  246.  
  247. translates the files prog1.icn and prog2.icn and produces one
  248. icode file, prog1.icx.
  249.  
  250.    A name other than the default one for the icode file produced
  251. by icont can be specified by using the -o option, followed by the
  252. desired name. For example,
  253.  
  254.         icont -o probe.icx prog
  255.  
  256. produces the icode file named probe.icx rather than prog.icx.
  257.  
  258.    If the -c option is given to icont, the translator stops
  259.  
  260.  
  261.  
  262. IPD200b                       - 4 -             December 16, 1992
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. before producing an icode file and intermediate ``ucode'' files
  272. with the extensions .u1 and .u2 are left for future use (normally
  273. they are deleted).  For example,
  274.  
  275.         icont -c prog1
  276.  
  277. leaves prog1.u1 and prog1.u2, instead of producing prog1.icx.
  278. These ucode files can be used in a subsequent icont command by
  279. using the .u1 name. This saves translation time for subsequent
  280. uses.  For example,
  281.  
  282.         icont prog2 prog1.u1
  283.  
  284. translates prog2.icn and combines the result with the ucode files
  285. from a previous translation of prog1.icn. Note that only the .u1
  286. name is given; the .u2 name is implied. The extension can be
  287. abbreviated to .u, as in
  288.  
  289.         icont prog2 prog1.u
  290.  
  291. Ucode files also can be added to a program using the link
  292. declaration.
  293.  
  294.    Icon source programs may be read from standard input.  The
  295. argument - signifies the use of standard input as a source file.
  296. In this case, the ucode files are named stdin.u1 and stdin.u2 and
  297. the icode file is named stdin.icx.
  298.  
  299.    The informative messages from the translator can be suppressed
  300. by using the -s option.  Normally, both informative messages and
  301. error messages are sent to standard error output.
  302.  
  303.    The -t option causes &trace to have an initial value of -1
  304. when the icode file is executed.  Normally, &trace has an initial
  305. value of 0.
  306.  
  307.    The option -u causes warning messages to be issued for unde-
  308. clared identifiers in the program.
  309.  
  310. 5.3__Environment_Variables
  311.  
  312.    When an icode file is executed, several environment variables
  313. are examined to determine execution parameters.  The values
  314. assigned to these variables should be numbers.
  315.  
  316.    Environment variables are particularly useful in adjusting
  317. Icon's storage requirements.  Particular care should be taken
  318. when changing default values: unreasonable values may cause Icon
  319. to malfunction.
  320.  
  321.    The following environment variables can be set to adjust
  322. Icon's execution parameters. Their default values are listed in
  323. parentheses after the environment variable name:
  324.  
  325.  
  326.  
  327.  
  328. IPD200b                       - 5 -             December 16, 1992
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.         TRACE (undefined).  This variable initializes the value
  338.      of &trace.  If this variable has a value, it overrides the
  339.      translation-time -t option.
  340.  
  341.         NOERRBUF (undefined).  If this variable is set, &errout
  342.      is not buffered.
  343.  
  344.         STRSIZE (65000). This variable determines the size, in
  345.      bytes, of the initial region in which strings are stored.
  346.      If additional string regions are needed, they may be
  347.      smaller.
  348.  
  349.         BLKSIZE (65000).  This variable determines the size, in
  350.      bytes, of the initial region in which Icon allocates lists,
  351.      tables, and other objects.  If additional block regions are
  352.      needed, they may be smaller.
  353.  
  354.         COEXPSIZE (2000). This variable determines the size, in
  355.      32-bit words, of each co-expression block.
  356.  
  357.         MSTKSIZE (10000). This variable determines the size, in
  358.      words, of the main interpreter stack.
  359.  
  360.  
  361. 6.__Features_of_OS/2_Icon
  362.  
  363.    OS/2 Icon supports all the features of Version 8.8 of Icon,
  364. with the following exceptions and additions:
  365.  
  366.      +  For files opened in the translate mode, the position pro-
  367.         duced by seek() may not reflect the actual byte position
  368.         because of the translation of carriage-return/line-feed
  369.         sequences to line-feed characters.
  370.  
  371.      +  Path specifications can be entered using either a / or a
  372.         \. Examples are:
  373.  
  374.                 A:\ICON\TEST.ICN
  375.                 A:/ICON/TEST.ICN
  376.  
  377.  
  378.      +  The following OS/2 device names can be used as file
  379.         names:
  380.  
  381.                 console        CON
  382.                 printer        PRN LST LPT LPT1
  383.                 auxiliary port AUX COM RDR PUN
  384.                 null           NUL NULL
  385.  
  386.         For example,
  387.  
  388.                 prompt := open("CON", "w")
  389.  
  390.         causes strings written to prompt to be displayed on the
  391.  
  392.  
  393.  
  394. IPD200b                       - 6 -             December 16, 1992
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.         console.  Use of a null file name means no file is
  404.         created.
  405.  
  406.    As mentioned above, pmiconx supports the graphic facilities of
  407. X-Icon. A few features are handled differently under OS/2 than
  408. under other implementations of X-Icon, and there are a few
  409. features that OS/2 does not support. See Appendix C of [3] for
  410. more information on this. In addition to the unsupported features
  411. of X-Icon that are listed in this appendix, OS/2 does not yet
  412. support these features:
  413.  
  414.      +  time stamps on events (&interval)
  415.  
  416.      +  modifier keys (&control, &shift, and &meta)
  417.  
  418.      +  XDefault()
  419.  
  420.  
  421.  
  422. 7.__Reporting_Problems
  423.  
  424.    Problems with Icon should be noted on a trouble report form
  425. (included with the distribution) and sent to
  426.  
  427.         Icon Project
  428.         Department of Computer Science
  429.         Gould-Simpson Building
  430.         The University of Arizona
  431.         Tucson, AZ   85721
  432.         U.S.A.
  433.         (602) 621-8448 (voice)
  434.         (602) 621-4246 (fax)
  435.         icon-project@cs.arizona.edu     (Internet)
  436.         ... uunet!arizona!icon-project     (uucp)
  437.  
  438.  
  439.  
  440. 8.__Registering_Copies_of_Icon
  441.  
  442.    If you received your copy of Icon directly from the Icon Pro-
  443. ject, it has been registered in your name and you will automati-
  444. cally receive the Icon Newsletter.  This newsletter contains
  445. information about new implementations, updates, programming tech-
  446. niques, and information of general interest about Icon.
  447.  
  448.    If you received your copy of Icon from another source, please
  449. fill out the registration form that is included in the distribu-
  450. tion and send it to the Icon Project at the address listed above.
  451. This will assure that you receive the Icon Newsletter and infor-
  452. mation about updates.
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460. IPD200b                       - 7 -             December 16, 1992
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. Acknowledgements
  470.  
  471.    The design and implementation of the Icon programming language
  472. was supported, in part, by grants from the National Science Foun-
  473. dation.
  474.  
  475.    Clint Jeffery, Gregg Townsend, and Ken Walker collaborated
  476. with the author in the development of Version 8.8 of Icon. The
  477. OS/2 implementation was done by Darren Merrill.
  478.  
  479. References
  480.  
  481.  
  482. 1.   R. E. Griswold and M. T. Griswold, The Icon Programming
  483.      Language, Prentice-Hall, Inc., Englewood Cliffs, NJ, second
  484.      edition, 1990.
  485.  
  486. 2.   R. E. Griswold, C. L. Jeffery, G. M. Townsend and K. Walker,
  487.      Version 8.8 of the Icon Programming Language, The Univ. of
  488.      Arizona Icon Project Document IPD210, 1992.
  489.  
  490. 3.   C. L. Jeffery, X-Icon: An Icon Windows Interface; Version 2,
  491.      The Univ. of Arizona Tech. Rep. 92-26, 1992.
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526. IPD200b                       - 8 -             December 16, 1992
  527.  
  528.  
  529.