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